incident.io API
This is the API reference for incident.io. It documents available API endpoints, provides examples of how to use it, and instructions around things like…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
This is the API reference for incident.io.
It documents available API endpoints, provides examples of how to use it, and
instructions around things like authentication and error handling.
The API is hosted at:
- https://api.incident.io/
And you will need to create an API key via your [incident.io
dashboard](https://app.incident.io/settings/api-keys) to make requests.
Making requests
Here are the key concepts required to make requests to the incident.io API.
Authentication
For all requests made to the incident.io API, you'll need an API key.
To create an API key, head to the incident dashboard and visit [API
keys](https://app.incident.io/settings/api-keys). When you create the key,
you'll be able to choose what actions it can take for your account: choose
carefully, as those roles can only be set when you first create the key. We'll
only show you the token once, so make sure you store it somewhere safe.
Once you have the key, you should make requests to the API that set theAuthorization request header using a "Bearer" authentication scheme:
Authorization: BearerErrors
We use standard HTTP response codes to indicate the status or failure of API
requests.
The API response body will be JSON, and contain more detailed information on the
nature of the error.
An example error when a request is made without an API key:
{
"type": "authentication_error",
"status": 401,
"request_id": "8e3cc412-b49d-4957-9073-2c19d2c61804",
"errors": [
{
"code": "missing_authorization_material",
"message": "No authorization material provided in request"
}
]
}Note that the error:
- Contains the HTTP status (
401) - References the type of error (
authentication_error) - Includes a
request_idthat can be provided to incident.io support to help
debug questions with your API request
- Provides a list of individual errors, which go into detail about why the error
occurred
The most common error will be a 422 Validation Error, which is returned when the
request was rejected due to failing validations.
These errors look like this:
{
"type": "validation_error",
"status": 422,
"request_id": "631766c4-4afd-4803-997c-cd700928fa4b",
"errors": [
{
"code": "is_required",
"message": "A severity is required to open an incident",
"source": {
"field": "severity_id"
}
}
]
}This error is caused by not providing a severity identifier, which should be at
the severity_id field of the request payload. Errors like these can be mapped to
forms, should you be integrating with the API from a user-interface.
Compatibility
We won't make breaking changes to existing API services or endpoints, but will
expect integrators to upgrade themselves to the latest API endpoints within 3
months of us deprecating the old service.
We will make changes that are considered backwards compatible, which include:
- Adding new API endpoints and services
- Adding new properties to responses from existing API endpoints
- Reordering properties returned from existing API endpoints
- Adding optional request parameters to existing API endpoints
- Altering the format or length of IDs
- Adding new values to enums
It is important that clients are robust to these changes, to ensure reliable
integrations.
As an example, if you are generating a client using an openapi-generator, ensure
the generated client is configured to support unknown enum values, often
configured via the enumUnknownDefaultCase parameter.
When breaking changes are unavoidable, we'll create a new service version on a
separate path, and run them in parallel.
For example:
- https://api.incident.io/v1/incidents
- https://api.incident.io/v2/incidents
For any questions, email support@incident.io.
Endpoints 88
Actions V1
- GETList Actions V1
/v1/actionsDeprecated. List all actions for an organisation. - GETShow Actions V1
/v1/actions/:idDeprecated. Get a single incident action.
Actions V2
- GETList Actions V2
/v2/actionsList all actions for an organisation. - GETShow Actions V2
/v2/actions/:idGet a single incident action.
Alert Events V2
- POSTCreateHTTP Alert Events V2
/v2/alert_events/http/:alert_source_config_idCreate an alert event using an HTTP source.
Catalog V2
- GETListEntries Catalog V2
/v2/catalog_entries?catalog_type_id=01FCNDV6P870EA6S7TK1DSYDG0List entries for a catalog type. - POSTCreateEntry Catalog V2
/v2/catalog_entriesCreate an entry within the catalog. We support a maximum of 50,000 entries per type. - GETShowEntry Catalog V2
/v2/catalog_entries/:idShow a single catalog entry. - PUTUpdateEntry Catalog V2
/v2/catalog_entries/:idUpdates an existing catalog entry. - DELETEDestroyEntry Catalog V2
/v2/catalog_entries/:idArchives a catalog entry. - GETListResources Catalog V2
/v2/catalog_resourcesList available engine resources for the catalog. A resource represents a type of data that can be held within the catalog, so this endpoint can be used to see… - GETListTypes Catalog V2
/v2/catalog_typesList all catalog types for an organisation, including those synced from external resources. - POSTCreateType Catalog V2
/v2/catalog_typesCreate a catalog type. The schema must be updated using the UpdateTypeSchema endpoint. - GETShowType Catalog V2
/v2/catalog_types/:idShow a single catalog type. - PUTUpdateType Catalog V2
/v2/catalog_types/:idUpdates an existing catalog type. The schema must be updated using the UpdateTypeSchema endpoint. - DELETEDestroyType Catalog V2
/v2/catalog_types/:idArchives a catalog type and associated entries. - POSTUpdateTypeSchema Catalog V2
/v2/catalog_types/:id/actions/update_schemaUpdate an existing catalog types schema, adding or removing attributes. Updating the schema is handled separately from creating and updating types, so that…
Custom Field Options V1
- GETList Custom Field Options V1
/v1/custom_field_options?custom_field_id=01FCNDV6P870EA6S7TK1DSYD5HShow custom field options for a custom field - POSTCreate Custom Field Options V1
/v1/custom_field_optionsCreate a custom field option. If the sort key is not supplied, it'll default to 1000, so the option appears near the end of the list. - GETShow Custom Field Options V1
/v1/custom_field_options/:idGet a single custom field option - PUTUpdate Custom Field Options V1
/v1/custom_field_options/:idUpdate a custom field option - DELETEDelete Custom Field Options V1
/v1/custom_field_options/:idDelete a custom field option
Custom Fields V1
- GETList Custom Fields V1
/v1/custom_fieldsDeprecated. List all custom fields for an organisation. - POSTCreate Custom Fields V1
/v1/custom_fieldsDeprecated. Create a new custom field - GETShow Custom Fields V1
/v1/custom_fields/:idDeprecated. Get a single custom field. - PUTUpdate Custom Fields V1
/v1/custom_fields/:idDeprecated. Update the details of a custom field - DELETEDelete Custom Fields V1
/v1/custom_fields/:idDeprecated. Delete a custom field
Custom Fields V2
- GETList Custom Fields V2
/v2/custom_fieldsList all custom fields for an organisation. - POSTCreate Custom Fields V2
/v2/custom_fieldsCreate a new custom field - GETShow Custom Fields V2
/v2/custom_fields/:idGet a single custom field. - PUTUpdate Custom Fields V2
/v2/custom_fields/:idUpdate the details of a custom field - DELETEDelete Custom Fields V2
/v2/custom_fields/:idDelete a custom field
Follow-ups V2
- GETList Follow-ups V2
/v2/follow_upsList all follow-ups for an organisation. - GETShow Follow-ups V2
/v2/follow_ups/:idGet a single incident follow-up.
Incident Attachments V1
- GETList Incident Attachments V1
/v1/incident_attachmentsList all incident attachements for a given external resource or incident. You must provide either a specific incident ID or a specific external resource type… - POSTCreate Incident Attachments V1
/v1/incident_attachmentsAttaches an external resource to an incident - DELETEDelete Incident Attachments V1
/v1/incident_attachments/:idUnattaches an external resouce from an incident
Incident Memberships V1
- POSTCreate Incident Memberships V1
/v1/incident_membershipsMakes a user a member of a private incident - POSTRevoke Incident Memberships V1
/v1/incident_memberships/actions/revokeRevoke a user's membership of a private incident
Incident Roles V1
- GETList Incident Roles V1
/v1/incident_rolesDeprecated. List all incident roles for an organisation. - POSTCreate Incident Roles V1
/v1/incident_rolesDeprecated. Create a new incident role - GETShow Incident Roles V1
/v1/incident_roles/:idDeprecated. Get a single incident role. - PUTUpdate Incident Roles V1
/v1/incident_roles/:idDeprecated. Update an existing incident role - DELETEDelete Incident Roles V1
/v1/incident_roles/:idDeprecated. Removes an existing role
Incident Roles V2
- GETList Incident Roles V2
/v2/incident_rolesList all incident roles for an organisation. - POSTCreate Incident Roles V2
/v2/incident_rolesCreate a new incident role - GETShow Incident Roles V2
/v2/incident_roles/:idGet a single incident role. - PUTUpdate Incident Roles V2
/v2/incident_roles/:idUpdate an existing incident role - DELETEDelete Incident Roles V2
/v2/incident_roles/:idRemoves an existing role
Incident Statuses V1
- GETList Incident Statuses V1
/v1/incident_statusesList all incident statuses for an organisation. - POSTCreate Incident Statuses V1
/v1/incident_statusesCreate a new incident status - GETShow Incident Statuses V1
/v1/incident_statuses/:idGet a single incident status. - PUTUpdate Incident Statuses V1
/v1/incident_statuses/:idUpdate an existing incident status - DELETEDelete Incident Statuses V1
/v1/incident_statuses/:idDelete an incident status
Incident Timestamps V2
- GETList Incident Timestamps V2
/v2/incident_timestampsList all incident timestamps for an organisation. - GETShow Incident Timestamps V2
/v2/incident_timestamps/:idGet a single incident timestamp.
Incident Types V1
- GETList Incident Types V1
/v1/incident_typesList all incident types for an organisation. - GETShow Incident Types V1
/v1/incident_types/:idGet a single incident type.
Incident Updates V2
- GETList Incident Updates V2
/v2/incident_updatesList all incident updates for an organisation, or for a specific incident.
Incidents V1
- GETList Incidents V1
/v1/incidentsDeprecated. List all incidents for an organisation. - POSTCreate Incidents V1
/v1/incidentsDeprecated. Create a new incident. - GETShow Incidents V1
/v1/incidents/:idDeprecated. Get a single incident.
Incidents V2
- GETList Incidents V2
/v2/incidentsList all incidents for an organisation. This endpoint supports a number of filters, which can help find incidents matching certain criteria. Filters are… - POSTCreate Incidents V2
/v2/incidentsCreate a new incident. Note that if the incident mode is set to "retrospective" then the new incident will not be announced in Slack. - GETShow Incidents V2
/v2/incidents/:idGet a single incident. The ID supplied can be either the incident's full ID, or the numeric part of its reference. For example, to get INC-123, you could use… - POSTEdit Incidents V2
/v2/incidents/:id/actions/editEdit an existing incident. This endpoint allows you to edit the properties of an existing incident: e.g. set the severity or update custom fields. When using…
Managed Resources V2
- POSTCreateManagedResource Managed Resources V2
/v2/managed_resourcesCalled by external providers such as Terraform, this can 'claim' an incident.io resource as being managed externally.
Schedules V2
- GETListScheduleEntries Schedules V2
/v2/schedule_entries?schedule_id=01FDAG4SAP5TYPT98WGR2N7W91Get a list of schedule entries. - GETList Schedules V2
/v2/schedulesList configured schedules. - POSTCreate Schedules V2
/v2/schedulesCreate a new schedule. - GETShow Schedules V2
/v2/schedules/:idGet a single schedule. - PUTUpdate Schedules V2
/v2/schedules/:idUpdate a schedule. - DELETEDestroy Schedules V2
/v2/schedules/:idArchives a single schedule.
Severities V1
- GETList Severities V1
/v1/severitiesList all incident severities for an organisation. - POSTCreate Severities V1
/v1/severitiesCreate a new severity - GETShow Severities V1
/v1/severities/:idGet a single incident severity. - PUTUpdate Severities V1
/v1/severities/:idUpdate an existing severity - DELETEDelete Severities V1
/v1/severities/:idDelete a severity
Users V2
- GETList Users V2
/v2/usersList users for an organisation. - GETShow Users V2
/v2/users/:idGet a single user.
Utilities V1
- GETIdentity Utilities V1
/v1/identityTest if your API key is valid, and which roles it has. - GETOpenAPI Utilities V1
/v1/openapi.jsonGet the OpenAPI (v2) definition. - GETOpenAPIV3 Utilities V1
/v1/openapiV3.jsonGet the OpenAPI (v3) definition.
Workflows V2
- GETListWorkflows Workflows V2
/v2/workflowsList all workflows - POSTCreateWorkflow Workflows V2
/v2/workflowsCreate a new workflow - GETShowWorkflow Workflows V2
/v2/workflows/:idShow a workflow by ID - PUTUpdateWorkflow Workflows V2
/v2/workflows/:idUpdates a workflow - DELETEDestroyWorkflow Workflows V2
/v2/workflows/:idArchives a workflow
API details
- Base URL
https://api.incident.io- Authentication
- None declared in the description
- Operations
- 88 operations on 52 pathsGET 45POST 20DELETE 12PUT 11
15 marked deprecated - Main resources
- Catalog V2 12Schedules V2 6Custom Field Options V1 5Custom Fields V1 5Custom Fields V2 5Incident Roles V1 5Incident Roles V2 5Incident Statuses V1 5Severities V1 5Workflows V2 5
- Response formats
application/json- Description format
- OpenAPI 3.0.3, API version
1.0.0 - Links
- OpenAPI document
How to test the incident.io API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the incident.io API collection, without the publisher's secrets.
- Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
- Send a requestPick an endpoint, for example “List Actions V1” (GET /v1/actions), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the incident.io API?
This is the API reference for incident.io. It documents available API endpoints, provides examples of how to use it, and instructions around things like… It is listed under Developer tools and has 88 endpoints.
Who publishes the incident.io API?
It is listed from incident.io's public API description (an OpenAPI document), not published by incident.io on Swastik Codes. Anyone who controls incident.io can claim the profile by adding a DNS TXT record.
What is the base URL of the incident.io API?
Requests go to https://api.incident.io. Endpoint paths are added to this base URL.
How do I authenticate with the incident.io API?
Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.
How many endpoints does the incident.io API have?
88 operations on 52 paths (45 GET, 20 POST, 12 DELETE, 11 PUT). The largest groups are Catalog V2, Schedules V2, Custom Field Options V1, Custom Fields V1.
Is forking the incident.io API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.