# Introduction

Welcome to the IsDown API developer documentation.

IsDown is a status page aggregator & outage monitoring tool for all your business-critical dependencies. Get a health dashboard with all your external services. Instant notifications on outages. All in one place.

To get started with developing against the [IsDown](https://isdown.app) API, you first need an IsDown account. You can [Sign In](https://isdown.app/users/sign_in) or [Create your new account here](https://isdown.app/users/sign_up).


# Quick Start

{% hint style="info" %}
**Good to know:** You will need an API Key for every endpoint available. IsDown API is only available in the Enterprise plan. 
{% endhint %}

### Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an authorization Error.

You can create an API Key in your Account Settings.

### Create API Key

1. Go to <https://isdown.app>;
2. Sign in or create your account;
3. Go to the [Account Settings](https://isdown.app/settings) by clicking in the profile menu (top right);
4. Choose a name for the API Key and click "Create your API Key"
5. **The key will only be available right after you create it**. Save the API Key in a place where you want to recover it later (e.g., password manager), if needed.

<figure><img src="/files/70pfN5oFU5Nzd40FbqeJ" alt=""><figcaption><p>API Key form in Account Settings</p></figcaption></figure>

### How to use API Key

Every request to the API needs to be authenticated. To authenticate your requests you will need to send a `Authorization` header in your requests with this format.&#x20;

```
Authorization: Bearer {API_KEY}
```

### Postman Collection

If you are a Postman user, download the collection with all existing endpoints, and import it in your account.

{% file src="/files/2JfbckcmNKkfsGpM4cr3" %}
IsDown API Postman Collection
{% endfile %}


# 3rd-Party Monitors

3rd-party monitors keep track of outages in all external vendors from AWS, GitHub, Zoom, and over +3850 more.

These monitors provide critical insights into the performance, uptime, and any outages that may occur with these services. This enables businesses to react swiftly to issues, minimizing downtime and maintaining service reliability. Organizations can utilize this data to analyze trends, forecast potential risks, and ensure contingency plans are in place.


# Get List of All Services Available

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/services`

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK List of all the services" %}

```json
{
    "data": [
        {
            "id": "1",
            "type": "service",
            "attributes": {
                "name": "AWS",
                "urlname": "aws",
                "isdown_url": "https://isdown.app/integrations/aws"
            }
        },
        {
            "id": "55",
            "type": "service",
            "attributes": {
                "name": "Apple Developer",
                "urlname": "apple-developer",
                "isdown_url": "https://isdown.app/integrations/apple-developer"
            }
        },
        ...
    ]
n
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The status of the services can be '`ok`', '`minor`', '`major`', and '`maintenance`'. It depends on the severity of the incidents and their impact on the service.
{% endhint %}

{% hint style="info" %}
Try our demo services to see the examples' responses depending on the status. Here's the list of different demo services available for you to test.\
\
**'demo-service'**  - This service changes the status every 5 minutes, cycling between 'ok' and 'minor' or 'major'.\
**'demo-service-ok'** - This service is always operational. \
**'demo-service-minor'** - This service is always going through a minor outage.\
**'demo-service-major'** - This service is constantly going through a major outage.
{% endhint %}


# Get Outages from 3rd-party Monitors

The Incidents endpoint is used to get the outages that happen in service in the last month. Depending on your plan, you will have access via API to all the services available or just the services you monitor.

## Get outages information of a service for the last 30 days

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/services/{service_name}/incidents`

#### Path Parameters

| Name                                            | Type   | Description                                                                                                                                                 |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service\_name<mark style="color:red;">\*</mark> | String | Parameterize name for the service. Get the service\_name from the url of a service. E.g., <https://isdown.app/services/digitalocean> it's **digitalocean.** |

#### Query Parameters

| Name                   | Type   | Description                                                  |
| ---------------------- | ------ | ------------------------------------------------------------ |
| include\_user\_reports | String | If 'true' it will return incidents created from user reports |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "data": [
        {
            "id": "1",
            "type": "incident",
            "attributes": {
                "url": null,
                "title": "Users reports spike",
                "description": null,
                "status": "minor",
                "resolved": false,
                "created_at": "2023-05-23T17:08:12.942Z",
                "resolved_at": null,
                "service": "AWS",
                "user_generated": true
                "components": []
            }
        },
        {
            "id": "2",
            "type": "incident",
            "attributes": {
                "url": null,
                "title": "Data discrepancy Issue",
                "description": "We are investigating data discrepancy issues with Billing Console. Customers using Cost Explorer, Cost and Usage Report, Saving Plans and Reservations Utilization and Coverage Reports consoles may experience data staleness. We are actively working towards resolution and we expect to be able to provide an update by 7:30 AM PDT.",
                "status": "minor",
                "resolved": true,
                "created_at": "2023-08-14T13:39:00.000Z",
                "resolved_at": "2023-08-14T18:38:22.338Z",
                "service": "AWS",
                "user_generated": false,
                "components": [
                    "AWS Billing Console"
                ]
            }
        },
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Get status and outage information of a service

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/services/{service_name}`

#### Path Parameters

| Name                                            | Type   | Description                                                                                                                                                 |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service\_name<mark style="color:red;">\*</mark> | String | Parameterize name for the service. Get the service\_name from the url of a service. E.g., <https://isdown.app/services/digitalocean> it's **digitalocean.** |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK When status is OK" %}

```json
{
    "data": {
        "id": "10000",
        "type": "service",
        "attributes": {
            "name": "Demo Service",
            "status": "ok",
            "status_page_url": "https://status.demo-service.com/",
            "isdown_url": "https://isdown.app/integrations/demo-service"
        }
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}

{% tab title="200: OK When status is any other than OK" %}

```json
{
    "data": {
        "id": "10000",
        "type": "service",
        "attributes": {
            "name": "Demo Service",
            "status": "major",
            "status_page_url": "https://status.demo-service.com/",
            "ongoing_incidents": {
                "data": [
                    {
                        "id": "10001",
                        "type": "incident",
                        "attributes": {
                            "url": "https://status.demo-service.com/incidents/10000",
                            "title": "Demo Incident 2",
                            "status": "minor",
                            "resolved": false,
                            "created_at": "2022-09-13T06:56:45.523+01:00",
                            "description": "This is a demo incident 2",
                            "resolved_at": "2022-09-13T07:26:45.523+01:00"
                        }
                    }
                ]
            },
            "isdown_url": "https://isdown.app/integrations/demo-service"
        }
    }
}
```

{% endtab %}
{% endtabs %}


# Add 3rd-party Monitor to Board

<mark style="color:orange;">`POST`</mark> `https://isdown.app/api/v2/boards/{board_id}/services/{service_urlname}`

#### Path Parameters

| Name                                               | Type   | Description                                                                                                                                                 |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service\_urlname<mark style="color:red;">\*</mark> | String | Parameterize name for the service. Get the service\_name from the url of a service. E.g., <https://isdown.app/services/digitalocean> it's **digitalocean.** |
| board\_id<mark style="color:red;">\*</mark>        | String | Board Id. Get the identifier for the board in the settings screen.                                                                                          |

#### Body Parameters

| Name | Type           | Description                                                                                                          |
| ---- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| tags | Array\<String> | Optional. Tags to attach to this service on this board. Whitespace is trimmed; blanks and duplicates are dropped. \| |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK When status is OK" %}

```json
{
    "data": {
        "id": "383",
        "type": "service",
        "attributes": {
            "name": "unpkg",
            "status": "ok",
            "status_page_url": null,
            "severity_from_provider": false,
            "isdown_url": "https://isdown.app/status/unpkg"
        },
        "tags": [ "tag1", "tag2" ]
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}

{% tab title="422: When service already exists in the board" %}

```json
{
    "errors": [
        {
            "status": 422,
            "title": "Unprocessable entity",
            "detail": "Service already added to board"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Update 3rd-party Monitor in Board

<mark style="color:orange;">`PATCH`</mark> `https://isdown.app/api/v2/boards/{board_id}/services/{service_urlname}`

#### Path Parameters

| Name                                               | Type   | Description                                                                                                                                                 |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service\_urlname<mark style="color:red;">\*</mark> | String | Parameterize name for the service. Get the service\_name from the url of a service. E.g., <https://isdown.app/services/digitalocean> it's **digitalocean.** |
| board\_id<mark style="color:red;">\*</mark>        | String | Board Id. Get the identifier for the board in the settings screen.                                                                                          |

#### Body Parameters

| Name | Type           | Description                                                                                                                                                |
| ---- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tags | Array\<String> | Optional. Tags to attach to this service on this board. If no tags param is sent nothing happens. If you need to reset it you need to send an empty array. |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK When status is OK" %}

```json
{
    "data": {
        "id": "383",
        "type": "service",
        "attributes": {
            "name": "unpkg",
            "status": "ok",
            "status_page_url": null,
            "severity_from_provider": false,
            "isdown_url": "https://isdown.app/status/unpkg"
        },
        "tags": [ "tag1", "tag2" ]
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}

{% tab title="422: When service already exists in the board" %}

```json
{
    "errors": [
        {
            "status": 422,
            "title": "Unprocessable entity",
            "detail": "Service already added to board"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Remove 3rd-party Monitor from Board

<mark style="color:red;">`DELETE`</mark> `https://isdown.app/api/v2/boards/{board_id}/services/{service_urlname}`

#### Path Parameters

| Name                                               | Type   | Description                                                                                                                                                 |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service\_urlname<mark style="color:red;">\*</mark> | String | Parameterize name for the service. Get the service\_name from the url of a service. E.g., <https://isdown.app/services/digitalocean> it's **digitalocean.** |
| board\_id<mark style="color:red;">\*</mark>        | String | Board Id. Get the identifier for the board in the settings screen.                                                                                          |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK When status is OK" %}

```json
{
    "message": "Service removed from board"
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}

{% tab title="422: When service already exists in the board" %}

```json
{
    "errors": [
        {
            "status": 422,
            "title": "Unprocessable entity",
            "detail": "Service not in board"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Custom Monitors

The Custom Monitor endpoint is used to get the current status of all custom monitors in your account.&#x20;

A Custom Monitor is used to monitor all the pieces of your infrastructure ( websites, API's, and others).


# Get List of your Custom Monitors

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/custom_monitors`

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK List of all the services" %}

```json
{
    "data": [
        {
            "id": "1",
            "type": "custom_monitor",
            "attributes": {
                "name": "IsDown",
                "status": "ok",
                "url": "https://isdown.app",
                "probe_type": "ping",
                "created_at": "2024-08-16T16:36:25.952Z",
                "updated_at": "2024-09-09T11:32:13.647Z",
                "ongoing_incidents": {
                    "data": []
                }
            }
        },
        {
            "id": "2",
            "type": "custom_monitor",
            "attributes": {
                "name": "IsDown Keyword",
                "status": "down",
                "url": "https://isdown.app",
                "probe_type": "keyword",
                "created_at": "2024-08-16T16:36:25.952Z",
                "updated_at": "2024-09-09T11:32:13.647Z",
                "ongoing_incidents": {
                    "data": [
                        {
                            "id": "2",
                            "type": "custom_monitor_incident",
                            "attributes": {
                                "description": "Down in Europe, North America with HTTP status code 500",
                                "created_at": "2024-09-09T10:08:11.500Z",
                                "resolved_at": null,
                                "updated_at": "2024-09-09T11:32:13.647Z",
                                "resolved": false
                            }
                        }
                    ]
                }
            }
        },
        ...
    ]
n
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}

{% tab title="200: OK When status is any other than OK" %}

```json
{
    "data": [
        {
            "id": "1",
            "type": "custom_monitor",
            "attributes": {
                "name": "IsDown",
                "status": "ok",
                "url": "https://isdown.app",
                "probe_type": "ping",
                "created_at": "2024-08-16T16:36:25.952Z",
                "updated_at": "2024-09-09T11:32:13.647Z",
                "ongoing_incidents": {
                    "data": []
                }
            }
        },
        ...
    ]
n
```

{% endtab %}
{% endtabs %}


# Get Outages from Custom Monitors

The Incidents endpoint is used to get the outages in the custom monitor for the last month.&#x20;

## Get outages of a custom monitor for the last 30 days

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/custom_monitors/{custom_monitor_id}/incidents`

#### Path Parameters

| Name                                                  | Type    | Description                                                                                                                                 |
| ----------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| custom\_monitor\_id<mark style="color:red;">\*</mark> | Integer | ID for the custom monitor. Get the id from the url of the custom monitor. E.g., <https://isdown.app/all-company/monitors/105> it's **105.** |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "data": [
        {
            "id": "9878",
            "type": "custom_monitor_incident",
            "attributes": {
                "description": "Down in North America, Asia with HTTP status code 504",
                "created_at": "2024-08-17T17:22:44.670Z",
                "resolved_at": "2024-08-17T17:23:19.808Z",
                "updated_at": "2024-08-17T17:22:44.670Z",
                "resolved": true,
                "custom_monitor_url": "https://isdown.app/all-company/monitors/1"
            }
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Incidents

The Incidents API allows you to list ( all services ) and create, update, and delete incidents (on your custom services). Incidents on third-party services monitored by IsDown are read-only.

### Incident object

| Field                | Type           | Description                                                |
| -------------------- | -------------- | ---------------------------------------------------------- |
| `id`                 | string         | Unique incident ID                                         |
| `title`              | string         | Incident title                                             |
| `description`        | string         | Latest description / initial description                   |
| `status`             | string         | `minor` or `major`                                         |
| `resolved`           | boolean        | Whether the incident is resolved                           |
| `created_at`         | string         | ISO 8601 timestamp                                         |
| `resolved_at`        | string \| null | ISO 8601 timestamp, or `null` if ongoing                   |
| `updated_at`         | string         | ISO 8601 timestamp of last update                          |
| `service`            | string         | Service name                                               |
| `service_urlname`    | string         | Service URL slug                                           |
| `service_status_url` | string         | URL of the service's own status page                       |
| `user_generated`     | boolean        | Whether this was a user-reported incident                  |
| `components`         | array          | Affected component names                                   |
| `updates`            | array          | Ordered list of incident updates (see below)               |
| `isdown_url`         | string \| null | Link to the incident on IsDown. `null` for custom services |

#### Update object

Each item in the `updates` array:

| Field         | Type   | Description                                                    |
| ------------- | ------ | -------------------------------------------------------------- |
| `status`      | string | One of `investigating`, `identified`, `monitoring`, `resolved` |
| `created_at`  | string | ISO 8601 timestamp                                             |
| `description` | string | Update message                                                 |

***

### Error responses

All errors follow the same format:

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Unprocessable Entity",
      "detail": "Status must be 'minor' or 'major'"
    }
  ]
}
```


# Get an incident

Returns a single incident by its ID. You can access incidents for services your company owns or has connected.

<mark style="color:$primary;">`GET`</mark> `https://isdown.app/api/v2/incidents/:id`

### Path parameters

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `id`      | integer | Yes      | The incident ID |

### Example request

```bash
curl https://api.isdown.app/api/v2/incidents/98765 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```bash
{
  "data": {
    "id": "98765",
    "type": "incidents",
    "attributes": {
      "url": "https://www.githubstatus.com/incidents/abc123",
      "title": "Actions and Packages degraded performance",
      "description": "We are investigating reports of degraded performance.",
      "status": "minor",
      "resolved": true,
      "created_at": "2024-03-15T10:00:00.000Z",
      "resolved_at": "2024-03-15T12:30:00.000Z",
      "updated_at": "2024-03-15T12:30:00.000Z",
      "service_id": 42,
      "service": "GitHub",
      "service_status_url": "https://www.githubstatus.com",
      "service_urlname": "github",
      "user_generated": false,
      "severity_from_provider": "minor",
      "components": ["Actions", "Packages"],
      "updates": [
        {
          "status": "investigating",
          "created_at": "2024-03-15T10:00:00.000Z",
          "description": "We are investigating reports of degraded performance."
        }
      ],
      "isdown_url": "https://isdown.app/status/github/incidents/abc123-actions-and-packages-degraded-performance"
    }
  }
}
```


# Get incidents from all services (or just one)

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/incidents`

{% hint style="info" %}
**Note:** This endpoint is only available for Enterprise customers.
{% endhint %}

#### Path Parameters

| Name          | Type   | Description                                                                                                                                                 |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service\_name | String | Parameterize name for the service. Get the service\_name from the url of a service. E.g., <https://isdown.app/services/digitalocean> it's **digitalocean.** |
| from          | String | Send a date in the format %Y/%m/%d. It will send incidents created from this date.                                                                          |
| to            | String | Send a date in the format %Y/%m/%d. It will send incidents created until this date.                                                                         |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "data": [
        {
            "id": "1",
            "type": "incident",
            "attributes": {
                "url": null,
                "title": "Users reports spike",
                "description": null,
                "status": "minor",
                "resolved": false,
                "created_at": "2023-05-23T17:08:12.942Z",
                "resolved_at": null,
                "service": "AWS",
                "user_generated": true
                "components": []
            }
        },
        {
            "id": "2",
            "type": "incident",
            "attributes": {
                "url": null,
                "title": "Data discrepancy Issue",
                "description": "We are investigating data discrepancy issues with Billing Console. Customers using Cost Explorer, Cost and Usage Report, Saving Plans and Reservations Utilization and Coverage Reports consoles may experience data staleness. We are actively working towards resolution and we expect to be able to provide an update by 7:30 AM PDT.",
                "status": "minor",
                "resolved": true,
                "created_at": "2023-08-14T13:39:00.000Z",
                "resolved_at": "2023-08-14T18:38:22.338Z",
                "service": "AWS",
                "user_generated": false,
                "components": [
                    "AWS Billing Console"
                ]
            }
        },
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found When we don't find the resource" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity If the request params are not valid" %}

{% endtab %}
{% endtabs %}


# Create an incident

Creates a new incident on a custom service. Only works with services you created in IsDown — not third-party services.

<mark style="color:blue;">`POST`</mark> `https://isdown.app/api/v2/incidents`

### Request body

| Parameter          | Type    | Required | Description                                                                             |
| ------------------ | ------- | -------- | --------------------------------------------------------------------------------------- |
| `service_id`       | integer | Yes      | The numeric ID of the custom service                                                    |
| `title`            | string  | Yes      | Short title describing the incident                                                     |
| `status`           | string  | No       | `minor` or `major`. Defaults to `minor`                                                 |
| `description`      | string  | No       | Initial update message. Defaults to empty string                                        |
| `resolution_stage` | string  | No       | `investigating`, `identified`, `monitoring`, or `resolved`. Defaults to `investigating` |

### Example request

```bash
curl -X POST https://api.isdown.app/api/v2/incidents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 1234,
    "title": "API response times elevated",
    "status": "minor",
    "description": "We are seeing elevated response times on our API.",
    "resolution_stage": "investigating"
  }'
```

### Example Response

```bash
{
  "data": {
    "id": "55001",
    "type": "incidents",
    "attributes": {
      "url": null,
      "title": "API response times elevated",
      "description": "We are seeing elevated response times on our API.",
      "status": "minor",
      "resolved": false,
      "created_at": "2024-03-15T10:00:00.000Z",
      "resolved_at": null,
      "updated_at": "2024-03-15T10:00:00.000Z",
      "service_id": 1234,
      "service": "My API",
      "service_status_url": null,
      "service_urlname": "my-api",
      "user_generated": false,
      "severity_from_provider": null,
      "components": [],
      "updates": [
        {
          "status": "investigating",
          "created_at": "2024-03-15T10:00:00.000Z",
          "description": "We are seeing elevated response times on our API."
        }
      ],
      "isdown_url": null
    }
  }
}
```

#### Notes

* Creating an incident automatically updates the service status on any linked status pages
* Subscribers to your status page will be notified according to your notification settings
* Setting resolution\_stage to resolved immediately marks the incident as resolved


# Update an incident

Adds an update to an ongoing incident, and optionally changes its title or status. You can also resolve an incident by setting \`resolution\_stage\` to \`resolved\`.

Only works with incidents on custom services your company owns.

<mark style="color:$primary;">`PATCH`</mark> `https://isdown.app/api/v2/incidents/:id`

### Path parameters

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `id`      | integer | Yes      | The incident ID |

### Request body

All parameters are optional, but to post a new update you must provide both `description` and `resolution_stage` together.

| Parameter          | Type   | Required | Description                                                                        |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------- |
| `title`            | string | No       | Updated incident title                                                             |
| `status`           | string | No       | `minor` or `major`                                                                 |
| `description`      | string | No\*     | Update message. Requires `resolution_stage`                                        |
| `resolution_stage` | string | No\*     | `investigating`, `identified`, `monitoring`, or `resolved`. Requires `description` |

### Example request — post an update

```bash
curl -X PATCH https://api.isdown.app/api/v2/incidents/55001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "We have identified the root cause and are deploying a fix.",
    "resolution_stage": "identified",
    "status": "minor"
  }'
```

### Example request — resolve an incident

```bash
curl -X PATCH https://api.isdown.app/api/v2/incidents/55001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "The issue has been resolved. Response times are back to normal.",
    "resolution_stage": "resolved"
  }'
```

### Example response

```bash
{
  "data": {
    "id": "55001",
    "type": "incidents",
    "attributes": {
      "title": "API response times elevated",
      "description": "We have identified the root cause and are deploying a fix.",
      "status": "minor",
      "resolved": false,
      "created_at": "2024-03-15T10:00:00.000Z",
      "resolved_at": null,
      "updated_at": "2024-03-15T10:15:00.000Z",
      "service_id": 1234,
      "service": "My API",
      "updates": [
        {
          "status": "investigating",
          "created_at": "2024-03-15T10:00:00.000Z",
          "description": "We are seeing elevated response times on our API."
        },
        {
          "status": "identified",
          "created_at": "2024-03-15T10:15:00.000Z",
          "description": "We have identified the root cause and are deploying a fix."
        }
      ],
      "isdown_url": null
    }
  }
}
```


# Delete an incident

Permanently deletes an incident. Only works with incidents on custom services your company owns.

<mark style="color:$danger;">`DELETE`</mark> `https://isdown.app/api/v2/incidents/:id`

### Path parameters

| Parameter | Type    | Required | Description     |
| --------- | ------- | -------- | --------------- |
| `id`      | integer | Yes      | The incident ID |

### Example request

```bash
curl -X DELETE https://api.isdown.app/api/v2/incidents/55001 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Notes

* Deleting an incident updates the service status on any linked status pages
* This action cannot be undone


# Boards

A Board is where you aggregate all the third-party Monitors, Custom Monitors, and Notifications for a specific team or stakeholders who might be interested in a specific view of your systems.

Everyone knows that different teams in your company have different needs for 3rd-party monitors.&#x20;


# Create Board

<mark style="color:orange;">`POST`</mark> `https://isdown.app/api/v2/boards`

#### Path Parameters

| Name                                   | Type   | Description       |
| -------------------------------------- | ------ | ----------------- |
| name<mark style="color:red;">\*</mark> | String | Name of the board |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK When status is OK" %}

```json
{
    "data": {
        "id": "XXXXX-XXXX-XXXX-XXXXXXXX",
        "type": "board",
        "attributes": {
            "name": "Test Board via API",
            "urlname": "test-board-via-api",
            "services": []
        }
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="422: When service already exists in the board" %}

```json
{
    "errors": [
        {
            "status": 422,
            "title": "Unprocessable entity",
            "detail": "Board limit reached for your plan"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Get List of your Boards

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/boards`

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK List of all the services" %}

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "board",
      "attributes": {
        "name": "Demo Board",
        "urlname": "demo-board",
        "services": [
          { "name": "Slack",         "urlname": "slack",  "tags": [] },
          { "name": "Stripe",        "urlname": "stripe",  "tags": [] },
          { "name": "Google Cloud",  "urlname": "google-cloud",  "tags": [] }
        ]
      }
    },
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": "board",
      "attributes": {
        "name": "Sample Board",
        "urlname": "sample-board",
        "services": [
          { "name": "AWS",           "urlname": "aws",  "tags": [] },
          { "name": "Azure",         "urlname": "azure",  "tags": [] },
          { "name": "Cloudflare",    "urlname": "cloudflare",  "tags": [] }
        ]
      }
    }
  ]
}

```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="200: OK When status is any other than OK" %}

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "board",
      "attributes": {
        "urlname": "demo-board",
        "services": [
          { "name": "Slack",         "urlname": "slack" },
          { "name": "Stripe",        "urlname": "stripe" },
          { "name": "Google Cloud",  "urlname": "google-cloud" }
        ]
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Get Board

<mark style="color:blue;">`GET`</mark> `https://isdown.app/api/v2/boards/{board_id}`

#### Path Parameters

| Name                                        | Type   | Description                                                        |
| ------------------------------------------- | ------ | ------------------------------------------------------------------ |
| board\_id<mark style="color:red;">\*</mark> | String | Board Id. Get the identifier for the board in the settings screen. |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK When status is any other than OK" %}

```json
{
    "data": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "board",
        "attributes": {
            "name": "Critical Vendors",
            "urlname": "critical-vendors",
            "services": [
                {
                    "name": "Zendesk",
                    "urlname": "zendesk",
                    "tags": ["tag1", "tag2"]
                },
                {
                    "name": "Vercel",
                    "urlname": "vercel",
                    "tags": []
                },
                {
                    "name": "Slack",
                    "urlname": "slack",
                    "tags": ["tag1", "tag2"]
                },
                {
                    "name": "Azure DevOps",
                    "urlname": "azure-devops",
                    "tags": []
                },
                {
                    "name": "Google Workspace",
                    "urlname": "google-workspace",
                    "tags": []
                },
                {
                    "name": "Azure",
                    "urlname": "azure",
                    "tags": []
                },
                {
                    "name": "Cloudflare",
                    "urlname": "cloudflare",
                    "tags": []
                }
            ]
        }
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized When authorization is missing or is invalid" %}

```json
{
    "errors": [
        {
            "status": 401,
            "title": "Unauthorized access",
            "detail": "You are not authorized to access this resource"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Board Not Found" %}

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Resource not found",
            "detail": "The resource you are looking for does not exist"
        }
    ]
}
```

{% endtab %}
{% endtabs %}