Integrations API

The Integrations API manages the notification destinations on your account: Slack, PagerDuty, Discord, Microsoft Teams, Google Chat, Lark, Opsgenie, Splunk On-Call, Datadog On-Call, Telegram, and custom webhooks. These are the same integrations you configure under Settings → Integrations.

Authentication

The Integrations API requires API key authentication with integration scopes:

integration:read - Required to list integrations (including ?service= / ?label= filters) and list available services
integration:write - Required to create or delete an integration

Create an API key with the appropriate scopes from the API Settings page. SDK Integration keys include both scopes. Session tokens issued to users who cannot manage integrations have integration:read only. For more information about API authentication and scopes, see the API documentation.

Include the key as an HTTP Basic username (leave the password empty):

curl https://cronitor.io/api/integrations \
  -u API_KEY:

Quick Start

List available services

curl https://cronitor.io/api/integrations/services \
  -u API_KEY:

Create a Discord integration

Use a placeholder URL — never commit a real webhook secret.

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "service": "discord",
        "name": "Eng alerts",
        "fields": { "key": "https://discord.com/api/webhooks/EXAMPLE/TOKEN" }
    }' \
    https://cronitor.io/api/integrations

List integrations

curl https://cronitor.io/api/integrations -u API_KEY:

Responses never include secrets. Slack and PagerDuty identifier is always null. Webhook URLs, PagerDuty routing keys, API tokens, and webhook passwords are omitted from metadata.

List Integrations

Endpoint

GET https://cronitor.io/api/integrations

Returns every visible integration on the account whose service is in the current catalogue. Unconnected catalogue services are not included here — use List Available Services.

Query Parameters

service (string) - Restrict results to one service key (for example ?service=discord)
label (string) - Restrict results to this display name (for example ?label=Eng+alerts)
page (integer) - Page number, starting at 1. Default: 1
pageSize (integer) - Results per page. Default: 50

Example

curl "https://cronitor.io/api/integrations?service=discord&pageSize=50" \
  -u API_KEY:

Response

{
  "integrations": [
    {
      "id": "Eng alerts",
      "service": "discord",
      "service_name": "Discord",
      "method": "apikey",
      "name": "Eng alerts",
      "label": "Eng alerts",
      "identifier": "eng-alerts",
      "available": true,
      "metadata": null,
      "created": "2026-09-03T12:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total_integration_count": 1
}

Get Integration

There is no path-key Get. Filter the list by service and label:

curl "https://cronitor.io/api/integrations?service=discord&label=Eng+alerts" \
  -u API_KEY:

200 with the usual list envelope. The integrations array is empty when no visible row matches. Labels are unique per service for visible rows.

Create Integration

Endpoint

POST https://cronitor.io/api/integrations

Creates an API-key integration.

Slack and PagerDuty cannot be created with this endpoint ({"error": "connect_required"}). Start a browser session with POST /api/integrations/connect or connect them from Settings → Integrations.

Telegram cannot be created here either; link the Cronitor bot first ({"error": "link_required", "url": "/docs/using-telegram-with-cronitor"}).

Request Body

service[string] required

Service key. Must be an API-key provider: discord, microsoft-teams, gchat, larksuite, opsgenie, victorops, datadog-on-call, or webhook.

name[string] required

Display name, 1–250 characters after trimming. Blank names are rejected.

identifier[string]

Optional slug, 1–250 characters. Defaults to a slug of name ([^a-zA-Z0-9-] → -, lowercased).

fields[object]

Provider-specific fields. See Create fields. Keys must be a subset of the catalogue fields for that service.

key[string]

Shorthand for fields.key. Ignored when fields.key is also set.

Create fields

Most API-key services take a single key field (the webhook URL, API key, or notification URL). Extra fields are listed in GET /api/integrations/services.

Service	Required `fields`	Optional	Notes
`discord`	`key`		Discord incoming webhook URL
`microsoft-teams`	`key`		Teams incoming webhook URL
`gchat`	`key`		Google Chat incoming webhook URL
`larksuite`	`key`		Lark / Feishu webhook URL
`opsgenie`	`key`		Opsgenie API key
`victorops`	`key`		Splunk On-Call notification URL
`webhook`	`key`	`username`, `password`	Destination URL. Basic-auth extras are stored and never returned
`datadog-on-call`	`webhook_url`, `api_key`, `oncall_team`		Cronitor builds the delivery URL; `api_key` is never returned

Do not send secrets in documentation, tickets, or version control. The examples below use placeholders.

Example

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "service": "opsgenie",
        "name": "Primary",
        "identifier": "primary",
        "fields": { "key": "YOUR_OPSGENIE_API_KEY" }
    }' \
    https://cronitor.io/api/integrations

Custom webhook with optional basic auth:

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "service": "webhook",
        "name": "Internal relay",
        "fields": {
            "key": "https://example.com/hooks/cronitor",
            "username": "relay"
        }
    }' \
    https://cronitor.io/api/integrations

Response

201 with the created Integration Object. Secrets from fields are not echoed back.

Status	Body	When
`400`	`{"error": "unknown_service"}`	`service` is not a known key
`400`	`{"error": "connect_required"}`	Slack or PagerDuty — connect from the dashboard
`400`	`{"error": "link_required", "url": "/docs/using-telegram-with-cronitor"}`	Telegram must be linked from the bot
`400`	`{"error": "name_required"}`	Missing or blank `name`
`400`	`{"error": "key_required"}`	Missing `fields.key` (or the Datadog equivalent)
`400`	`{"error": "webhook_url_required"}`	Datadog On-Call is missing `fields.webhook_url`
`400`	`{"error": "webhook_url_invalid"}`	Datadog On-Call webhook URL is not a valid HTTPS intake host
`400`	`{"error": "webhook_url_credentials"}`	Datadog On-Call webhook URL includes credentials
`400`	`{"error": "webhook_url_query"}`	Datadog On-Call webhook URL includes a query or fragment
`400`	`{"error": "api_key_required"}`	Datadog On-Call is missing `fields.api_key`
`400`	`{"error": "oncall_team_required"}`	Datadog On-Call is missing `fields.oncall_team`
`400`	`{"error": "invalid_fields", "fields": ["…"]}`	A field is not in the catalogue for that service
`403`	`{"error": "plan_required"}`	Plan does not allow the service
`403`	`{"error": "forbidden"}`	Caller cannot manage integrations
`400`	`{"identifier": ["identifier must be unique"]}`	Duplicate `identifier` for that service
`400`	`{"name": ["name must be unique"]}`	Duplicate `name` / label for that service (same validation error shape as monitors)
`503`		Account is in read-only mode

Delete Integration

Endpoint

DELETE https://cronitor.io/api/integrations

Soft-deletes the integration (visible=false). Identify the row with service and label query parameters — the same filters as List. By default the request fails if any notification list or monitor still references it.

Query Parameters

service (string, required) - Catalogue service key
label (string, required) - Display name
force (string) - Set force=1 to delete anyway. Cronitor detaches the integration from notification lists and monitors, then hides it.

Example

curl -X DELETE "https://cronitor.io/api/integrations?service=discord&label=Eng+alerts" \
  -u API_KEY:

Force delete:

curl -X DELETE "https://cronitor.io/api/integrations?service=discord&label=Eng+alerts&force=1" \
  -u API_KEY:

Response

200 with {"deleted": true} when the integration is not in use.

If the integration is still in use and force is not set, 409:

{
  "error": "in_use",
  "notification_lists": ["oncall"],
  "monitors": ["important-job"]
}

With force=1:

{
  "deleted": true,
  "detached_from": {
    "notification_lists": ["oncall"],
    "monitors": ["important-job"]
  }
}

404 if no visible row matches service + label. 400 if either query parameter is missing.

List Available Services

Endpoint

GET https://cronitor.io/api/integrations/services

Returns the integration catalogue for this account. available is true when the current plan includes the service. SMS is not part of this catalogue.

Example

curl https://cronitor.io/api/integrations/services \
  -u API_KEY:

Response

{
  "services": [
    {
      "service": "slack",
      "service_name": "Slack",
      "type": "Messaging",
      "method": "oauth",
      "fields": {},
      "available": true
    },
    {
      "service": "webhook",
      "service_name": "Webhook",
      "type": "Messaging",
      "method": "apikey",
      "fields": {
        "key": "URL",
        "username": "Username (optional)",
        "password": "Password (optional)"
      },
      "available": true
    },
    {
      "service": "telegram",
      "service_name": "Telegram",
      "type": "Messaging",
      "method": "link",
      "fields": {
        "type": "Type"
      },
      "available": true
    }
  ]
}

Integration Object

{
  "id": "Eng alerts",
  "service": "discord",
  "service_name": "Discord",
  "method": "apikey",
  "name": "Eng alerts",
  "label": "Eng alerts",
  "identifier": "eng-alerts",
  "available": true,
  "metadata": null,
  "created": "2026-09-03T12:00:00Z"
}

id[string]

Public identity. Same value as label. Unique with service among visible rows. Autoincrement primary keys are never returned.

service[string]

Service key. One of slack, pagerduty, discord, microsoft-teams, gchat, larksuite, opsgenie, victorops, datadog-on-call, webhook, telegram.

service_name[string]

Human-readable provider name (for example Microsoft Teams).

method[string]

How the service is connected: oauth (Slack, PagerDuty), apikey (webhook / token providers), or link (Telegram).

name[string]

Display name shown in the dashboard. Same value as label.

label[string]

Stable name used when attaching this integration to a notification list.

identifier[string]

Customer-supplied slug for API-key services. Always null for Slack and PagerDuty — those destinations are not addressable by a customer-supplied slug.

available[boolean]

true when the current plan includes this service. Existing rows remain listed after a plan downgrade so they can still be deleted (available: false).

metadata[object]

Non-secret provider details (for example username or oncall_team). Keys named api_key, password, webhook_url, or key are never returned. null when empty.

created[timestamp]

ISO-8601 timestamp when the integration was created.

Integrations — dashboard overview and provider guides
Notifications API — attach integrations to notification lists
Cronitor CLI — account resource commands
API Keys — scopes and key types
Using Slack · Using PagerDuty

Authentication

Quick Start

List available services

Create a Discord integration

List integrations

List Integrations

Endpoint

Query Parameters

Example

Response

Get Integration

Create Integration

Endpoint

Request Body

service[string] **required**

name[string] **required**

identifier[string]

fields[object]

key[string]

Create fields

Example

Response

Delete Integration

Endpoint

Query Parameters

Example

Response

List Available Services

Endpoint

Example

Response

Integration Object

id[string]

service[string]

service_name[string]

method[string]

name[string]

label[string]

identifier[string]

available[boolean]

metadata[object]

created[timestamp]

Related

service[string] required

name[string] required