Send heartbeat pings for dead man's switch monitoring. Heartbeat alert sources expect periodic pings. If pings stop arriving, alerts fire automatically. Use the ping endpoints to signal that your job or service is still healthy.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/incident-io:incident-io-heartbeat-v2-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
description: '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 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. 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. API keys are global to your incident.io account, and can be managed by anyone
who has the right permissions. We display the user that created the API key,
and the API key will remain valid if that user becomes deactivated. Once you have the key, you should make requests to the API that set the
`Authorization` request header using a "Bearer" authentication scheme:
```
Authorization: Bearer
```
## Rate Limits
The incident.io API enforces rate limits to ensure consistent performance for all users. The default rate limit is 1200 requests/minute per API key. This limit applies to most endpoints across the API. Limits are token buckets that refill continuously rather than resetting on a fixed window boundary. The default
bucket holds 1200 requests and refills at 20 per second, so you can burst up to the full bucket and then sustain
20 requests/second indefinitely. There is no boundary at which your quota resets to full in one step. Some endpoints have lower rate limits, particularly those that interact with external third-party systems that impose
their own limitations. These specific limits vary by endpoint. ### Rate limit headers
Responses to requests authenticated with an API key carry your current allowance, so you can pace yourself rather
than waiting to be throttled:
```
X-RateLimit-Limit: 60, 1200;window=60, 60;window=60
X-RateLimit-Remaining: 59
X-RateLimit-Used: 1
X-RateLimit-Reset: 1785173199
```
| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | The quota that binds this request, followed by every limit that applied and the window it applies over |
| `X-RateLimit-Remaining` | Requests you can make right now against the binding limit |
| `X-RateLimit-Used` | Requests you have spent against it |
| `X-RateLimit-Reset` | Unix timestamp (seconds) at which that limit will be back to full |
More than one limit can apply to a request: your API key''s overall limit, and for some endpoints a lower limit of
their own. `X-RateLimit-Limit` lists all of them, each with its window, so `1200;window=60` means 1200 requests per
minute. Because our limits refill continuously rather than resetting on a boundary, that window is what tells you
the rate you can sustain: 1200 per 60 seconds is 20 requests/second indefinitely. `Remaining`, `Used` and `Reset` describe whichever limit has the least allowance left, since that is the one you
will hit first. `X-RateLimit-Remaining` may lag by a small number of requests under high concurrency, and can move by more than the
requests you made, because limits scoped to your whole organisation are shared with your other API keys. Headers are omitted rather than guessed if we cannot determine your allowance for a request. ### Exceeding a rate limit
When you exceed a rate limit the API responds with `429 Too Many Requests` and a `Retry-After` header giving the
number of seconds to wait:
```
X-RateLimit-Limit: 1200, 1200;window=60
X-RateLimit-Remaining: 0
X-RateLimit-Used: 1200
X-RateLimit-Reset: 1785173199
Retry-After: 1
```
Prefer `Retry-After` over `X-RateLimit-Reset` when deciding how long to back off.'
title: incident.io Heartbeat V2 API
version: 1.0.0
servers:
- url: https://api.incident.io
security:
- BearerAuth: []
tags:
- description: 'Send heartbeat pings for dead man''s switch monitoring.
Heartbeat alert sources expect periodic pings. If pings stop arriving, alerts
fire automatically. Use the ping endpoints to signal that your job or service
is still healthy.'
name: Heartbeat V2
paths:
/v2/heartbeat/{alert_source_config_id}/ping:
get:
description: 'Send a heartbeat ping for the specified alert source.
Records a ping, indicating that the monitored job or service is healthy. The
heartbeat monitor uses these pings to detect missed heartbeats and fire alerts.
Both GET and POST are accepted'
operationId: HeartbeatV2#Ping#1
parameters:
- allowEmptyValue: true
description: Token provided via the token query parameter
example: some-random-string
in: query
name: token
schema:
description: Token provided via the token query parameter
example: some-random-string
type: string
- description: The alert source config this heartbeat ping is for
example: 01GW2G3V0S59R238FAHPDS1R66
in: path
name: alert_source_config_id
required: true
schema:
description: The alert source config this heartbeat ping is for
example: 01GW2G3V0S59R238FAHPDS1R66
type: string
- allowEmptyValue: true
description: Bearer token provided via the Authorization header
example: Bearer some-random-string
in: header
name: authorization
schema:
description: Bearer token provided via the Authorization header
example: Bearer some-random-string
type: string
responses:
'204':
description: No Content response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn''t exist.'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'authentication_error: Authentication failed.'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'resource_forbidden: Access to this resource is forbidden for the authenticated user.'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'not_found: The referenced resource could not be found.'
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'method_not_allowed: The endpoint does not support this operation for the specified resource.'
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'not_acceptable: Requested a media type this endpoint does not support.'
'408':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'request_timeout: The request took too long to process.
client_timeout: The request was cancelled by the client.'
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'conflict: Request conflicted with current state of the resource, likely a concurrent update.'
'412':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'precondition_failed: A required condition hasn''t been met.'
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'payload_too_large: The request payload is too large.'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'validation_error: A required field was not provided, or the provided data was invalid.'
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
rate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later.'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'api_error: Something went wrong and has been reported internally.'
summary: Ping Heartbeat V2
tags:
- Heartbeat V2
x-docs-display-name: Ping
x-docs-group-name: Heartbeat V2
x-operation-id-source: normalized
x-operation-id-original: Heartbeat V2#Ping#1
post:
description: 'Send a heartbeat ping for the specified alert source.
Records a ping, indicating that the monitored job or service is healthy. The
heartbeat monitor uses these pings to detect missed heartbeats and fire alerts.
Both GET and POST are accepted'
operationId: HeartbeatV2#Ping
parameters:
- allowEmptyValue: true
description: Token provided via the token query parameter
example: some-random-string
in: query
name: token
schema:
description: Token provided via the token query parameter
example: some-random-string
type: string
- description: The alert source config this heartbeat ping is for
example: 01GW2G3V0S59R238FAHPDS1R66
in: path
name: alert_source_config_id
required: true
schema:
description: The alert source config this heartbeat ping is for
example: 01GW2G3V0S59R238FAHPDS1R66
type: string
- allowEmptyValue: true
description: Bearer token provided via the Authorization header
example: Bearer some-random-string
in: header
name: authorization
schema:
description: Bearer token provided via the Authorization header
example: Bearer some-random-string
type: string
responses:
'204':
description: No Content response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn''t exist.'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'authentication_error: Authentication failed.'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'resource_forbidden: Access to this resource is forbidden for the authenticated user.'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'not_found: The referenced resource could not be found.'
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'method_not_allowed: The endpoint does not support this operation for the specified resource.'
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'not_acceptable: Requested a media type this endpoint does not support.'
'408':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'request_timeout: The request took too long to process.
client_timeout: The request was cancelled by the client.'
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'conflict: Request conflicted with current state of the resource, likely a concurrent update.'
'412':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'precondition_failed: A required condition hasn''t been met.'
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'payload_too_large: The request payload is too large.'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'validation_error: A required field was not provided, or the provided data was invalid.'
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
rate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later.'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'api_error: Something went wrong and has been reported internally.'
security: []
summary: Ping Heartbeat V2
tags:
- Heartbeat V2
x-docs-display-name: Ping
x-docs-group-name: Heartbeat V2
x-operation-id-source: normalized
x-operation-id-original: Heartbeat V2#Ping
components:
schemas:
ErrorRateLimit:
example:
limit: 100
name: client_ip
remaining: 98
retry_after: '2020-01-01T00:00:00Z'
properties:
limit:
description: The maximum number of requests that the consumer is permitted to make per minute
example: 100
format: int64
type: integer
name:
description: Which rate limit was exceeded
example: client_ip
type: string
remaining:
description: The number of requests remaining in the current rate limit window
example: 98
format: int64
type: integer
retry_after:
description: When the client can retry, as an RFC3339 timestamp in UTC. Prefer the Retry-After response header, which carries the same instant as a number of seconds
example: '2020-01-01T00:00:00Z'
type: string
required:
- name
- limit
- remaining
- retry_after
type: object
ErrorResponse:
example:
debug:
message: 'Something broke: and something else: and something else'
stacktrace:
- thing.go:123
errors:
- code: trial_expired
message: Default incident call link must be a valid URL
metadata:
abc123: abc123
source:
field: default_call_url
pointer: /settings/default_call_url
rate_limit:
limit: 100
name: client_ip
remaining: 98
retry_after: '2020-01-01T00:00:00Z'
request_id: 2T1p0e3j
status: 408
type: invalid_request_error
properties:
debug:
$ref: '#/components/schemas/ErrorDebug'
errors:
description: List of errors that caused this request to fail
example:
- code: trial_expired
message: Default incident call link must be a valid URL
metadata:
abc123: abc123
source:
field: default_call_url
pointer: /settings/default_call_url
items:
$ref: '#/components/schemas/ErrorSingle'
type: array
rate_limit:
$ref: '#/components/schemas/ErrorRateLimit'
request_id:
description: Unique identifier of the request
example: 2T1p0e3j
type: string
status:
description: HTTP status of the response
example: 408
format: int64
type: integer
type:
description: Machine-readable identifier for the general category of error
enum:
- invalid_request_error
- authentication_error
- resource_forbidden
- not_found
- not_acceptable
- method_not_allowed
- request_timeout
- conflict
- precondition_failed
- payload_too_large
- validation_error
- too_many_requests
- api_error
- rate_limit_reached
- client_timeout
example: invalid_request_error
type: string
required:
- type
- status
- request_id
- errors
type: object
ErrorDebug:
example:
message: 'Something broke: and something else: and something else'
stacktrace:
- thing.go:123
properties:
message:
description: Original internal error message
example: 'Something broke: and something else: and something else'
type: string
stacktrace:
description: Stacktrace of the error, if applicable
example:
- thing.go:123
items:
example: thing.go:123
type: string
type: array
required:
- message
- stacktrace
type: object
ErrorSource:
example:
field: default_call_url
pointer: /settings/default_call_url
properties:
field:
description: Field name that is the source of the error
example: default_call_url
type: string
pointer:
description: JSON pointer to the request field that is the source of the error
example: /settings/default_call_url
type: string
required:
- field
- pointer
type: object
ErrorSingle:
example:
code: trial_expired
message: Default incident call link must be a valid URL
metadata:
abc123: abc123
source:
field: default_call_url
pointer: /settings/default_call_url
properties:
code:
description: Machine-readable identifier for this specific error
example: trial_expired
type: string
message:
description: Human readable description of the error
example: Default incident call link must be a valid URL
type: string
metadata:
additionalProperties:
example: abc123
type: string
description: Additional metadata about the error, keyed by a string identifier
example:
abc123: abc123
type: object
source:
$ref: '#/components/schemas/ErrorSource'
required:
- code
- message
type: object
securitySchemes:
BearerAuth:
description: API key from your incident.io dashboard (Settings > API keys)
scheme: bearer
type: http
externalDocs:
description: View our API docs at api-docs.incident.io
url: https://api-docs.incident.io/
x-provenance:
method: harvested
publisher: Incident.io
source: https://api.incident.io/v1/openapiV3.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)