NAV Navbar
shell
  • Introduction
  • API Endpoint
  • Authentication
  • Rate Limiting
  • Components
  • Incidents
  • Metrics
  • Errors
  • Introduction

    LambStatus provides a simple and powerful REST API, which enables you to:

    API Endpoint

    Your API endpoint is same as your admin page url. By default, it's something like xxxxxxxxxxxxxx.cloudfront.net.

    Authentication

    All the API calls look something like this:

    curl "https://<your_api_endpoint>/api/..."
      -H "x-api-key: <your_api_key>"
    

    Make sure to replace <your_api_endpoint> and <your_api_key>.

    The API uses API keys to allow access to the API. The "Settings" page of your admin page shows you one or more API keys:

    If there is no key, create a new one by clicking the "+" icon and then the "SAVE" button.

    The API expects for the API key to be included in all API requests to the server in a header that looks like the following:

    x-api-key: your_api_key

    Rate Limiting

    Each API token is limited to 10 requests / second.

    Components

    List Components

    curl "https://<your_api_endpoint>/api/v0/components" \
      -H "x-api-key: <your_api_key>"
    

    The above command returns JSON structured like this:

    [
      {
        "componentID": "aKR6rTg0aW2d",
        "name": "Website",
        "description": "",
        "status": "Operational",
        "order": 1509676878
      },
      ...
    ]
    

    This endpoint retrieves all components.

    HTTP Request

    GET https://<your_api_endpoint>/api/v0/components

    Create a New Component

    curl -X POST "https://<your_api_endpoint>/api/v0/components" \
      -d '{"name":"Website", "description":"", "status":"Operational"}' \
      -H "x-api-key: <your_api_key>" -H "Content-Type: application/json"
    

    The above command returns JSON structured like this:

    {
      "componentID": "aKR6rTg0aW2d",
      "name": "Website",
      "description": "",
      "status": "Operational",
      "order": 1509676878
    }
    

    This endpoint creates a new component.

    HTTP Request

    POST https://<your_api_endpoint>/api/v0/components

    Parameters

    Parameter Description
    name The component name
    description The description of the component
    status The current status of the component. Must be one of Operational, Under Maintenance, Degraded Performance, Partial Outage and Major Outage.

    Update the Component

    curl -X PATCH "https://<your_api_endpoint>/api/v0/components/<your_component_id>" \
      -d '{"status":"Major Outage"}' \
      -H "x-api-key: <your_api_key>" -H "Content-Type: application/json"
    

    The above command returns JSON structured like this:

    {
      "componentID": "aKR6rTg0aW2d",
      "name": "Website",
      "description": "",
      "status": "Major Outage",
      "order": 1509676878
    }
    

    This endpoint updates the component.

    HTTP Request

    PATCH https://<your_api_endpoint>/api/v0/components/{componentid}

    Parameters

    Parameter Description
    componentid The component id
    name The component name
    description The description of the component
    status The current status of the component. Must be one of Operational, Under Maintenance, Degraded Performance, Partial Outage and Major Outage.

    Delete the component

    curl -X DELETE "https://<your_api_endpoint>/api/v0/components/<your_component_id>" \
      -H "x-api-key: <your_api_key>"
    

    The above command returns 204 No Content.

    This endpoint deletes the component.

    HTTP Request

    DELETE https://<your_api_endpoint>/api/v0/components/{componentid}

    Parameters

    Parameter Description
    componentid The component id

    Incidents

    List Incidents

    curl "https://<your_api_endpoint>/api/v0/incidents" \
      -H "x-api-key: <your_api_key>"
    

    The above command returns JSON structured like this:

    [
      {
        "incidentID": "aKR6rTg0aW2d",
        "name": "DNS resolution issues",
        "status": "Investigating",
        "createdAt": "2017-11-05T09:04:04.016Z",
        "updatedAt": "2017-11-05T09:04:04.016Z"
      },
      ...
    ]
    

    This endpoint retrieves all incidents.

    HTTP Request

    GET https://<your_api_endpoint>/api/v0/incidents

    Get an incident

    curl "https://<your_api_endpoint>/api/v0/incidents/<your_incident_id>" \
      -H "x-api-key: <your_api_key>"
    

    The above command returns JSON structured like this:

    {
      "incidentID": "aKR6rTg0aW2d",
      "name": "DNS resolution issues",
      "status": "Investigating",
      "createdAt": "2017-11-05T09:20:44.915Z",
      "updatedAt": "2017-11-05T09:20:44.915Z",
      "incidentUpdates": [
        {
          "incidentID": "aKR6rTg0aW2d",
          "incidentUpdateID": "1PGVAHA4ml9X",
          "incidentStatus": "Investigating",
          "message": "We are investigating DNS resolution issues.",
          "createdAt": "2017-11-05T09:20:45.155Z",
          "updatedAt": "2017-11-05T09:20:45.155Z"
        }
      ]
    }
    

    This endpoint retrieves a specified incident with the list of its incident updates.

    HTTP Request

    GET https://<your_api_endpoint>/api/v0/incidents/{incidentid}

    Parameters

    Parameter Description
    incidentid The incident id

    Create a New Incident

    curl -X POST "https://<your_api_endpoint>/api/v0/incidents" \
      -d '{
        "name":"DNS resolution issues",
        "status":"Investigating",
        "message":"We are investigating DNS resolution issues."
      }' \
      -H "x-api-key: <your_api_key>" -H "Content-Type: application/json"
    

    The above command returns JSON structured like this:

    {
      "incidentID": "aKR6rTg0aW2d",
      "name": "DNS resolution issues",
      "status": "Investigating",
      "createdAt": "2017-11-05T09:20:44.915Z",
      "updatedAt": "2017-11-05T09:20:44.915Z",
      "incidentUpdates": [
        {
          "incidentID": "aKR6rTg0aW2d",
          "incidentUpdateID": "1PGVAHA4ml9X",
          "incidentStatus": "Investigating",
          "message": "We are investigating DNS resolution issues.",
          "createdAt": "2017-11-05T09:20:45.155Z",
          "updatedAt": "2017-11-05T09:20:45.155Z"
        }
      ]
    }
    

    This endpoint creates a new incident.

    HTTP Request

    POST https://<your_api_endpoint>/api/v0/incidents

    Parameters

    Parameter Description
    name The incident name
    status The current status of the incident. Must be one of Investigating, Identified, Monitoring and Resolved.
    message The description of the incident's current status

    Update the Incident

    curl -X PATCH "https://<your_api_endpoint>/api/v0/incidents/<your_incident_id>" \
      -d '{
        "status":"Identified",
        "message":"We have migrated to an unaffected DNS provider. Some users may experience problems with cached results as the change propagates."
      }' \
      -H "x-api-key: <your_api_key>" -H "Content-Type: application/json"
    

    The above command returns JSON structured like this:

    {
      "incidentID": "aKR6rTg0aW2d",
      "name": "DNS resolution issues",
      "status": "Identified",
      "createdAt": "2017-11-05T09:20:44.915Z",
      "updatedAt": "2017-11-05T10:33:34.490Z",
      "incidentUpdates": [
        {
          "incidentID": "aKR6rTg0aW2d",
          "incidentUpdateID": "1PGVAHA4ml9X",
          "incidentStatus": "Investigating",
          "message": "We are investigating DNS resolution issues.",
          "createdAt": "2017-11-05T09:20:45.155Z",
          "updatedAt": "2017-11-05T09:20:45.155Z"
        },
        {
          "incidentID": "aKR6rTg0aW2d",
          "incidentUpdateID": "ThFwz6BHTlef",
          "incidentStatus": "Identified",
          "message": "We have migrated to an unaffected DNS provider. Some users may experience problems with cached results as the change propagates.",
          "createdAt": "2017-11-05T10:33:34.684Z",
          "updatedAt": "2017-11-05T10:33:34.684Z"
        }
      ]
    }
    

    This endpoint updates the incident.

    HTTP Request

    PATCH https://<your_api_endpoint>/api/v0/incidents/{incidentid}

    Parameters

    Parameter Description
    incidentid The incident id
    name The incident name
    status The current status of the incident. Must be one of Investigating, Identified, Monitoring and Resolved.
    message The description of the incident's current status

    Delete the incident

    curl -X DELETE "https://<your_api_endpoint>/api/v0/incidents/<your_incident_id>" \
      -H "x-api-key: <your_api_key>"
    

    The above command returns 204 No Content.

    This endpoint deletes the incident.

    HTTP Request

    DELETE https://<your_api_endpoint>/api/v0/incidents/{incidentid}

    Parameters

    Parameter Description
    incidentid The incident id

    Metrics

    Submit data points

    curl -X POST "https://<your_api_endpoint>/api/v0/metrics/data" \
      -d '{
        "<your_metric_id>": [
          {"timestamp": "2017-06-05T00:00:00.000Z", "value": 1},
          {"timestamp": "2017-06-05T00:01:00.000Z", "value": 2}
        ]
      }' \
      -H "x-api-key: <your_api_key>" -H "Content-Type: application/json"
    

    The above command returns JSON structured like this:

    {
      "ARzfSNr5lb3G":[
        {"timestamp": "2017-11-03T00:00:00.000Z", "value": 1},
        {"timestamp": "2017-11-03T00:01:00.000Z", "value": 2}
      ]
    }
    

    The response body is the ACTUAL values saved in the storage. So some data points may be omitted and the second part of a timestamp may be discarded.

    If the metric is "Self" type, you can submit data points via this endpoint. See the wiki to start using the "Self" type metric.

    HTTP Request

    POST https://<your_api_endpoint>/api/v0/metrics/data

    Parameters

    Parameter Description
    <your_metric_id> The metric ID
    timestamp The timestamp of the data point. The second and millisecond parts of the timestamp is discarded. For example, the timestamp 2017-06-05T11:11:11.111Z is saved as 2017-06-05T11:11:00.000Z
    value The data point value.

    Errors

    One or more errors will be returned in the following format:

    {
      "errors": [
        {"message": "message describing condition"},
        ...
      ]
    }
    

    Actionable failure conditions are reported as part of 4xx responses, in a json response body.