> For the complete documentation index, see [llms.txt](https://docs.spike.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spike.sh/spike-api-docs/escalations.md). # Escalations Create, read, update and archive escalation policies. ## Fetch list of escalations > \[An escalation policy]\() is a simple set of rules to alert the right person at the right time using the right channel such as phone, slack or email. If that person misses out then the incident gets escalated to the next person. ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations","description":"Create, read, update and archive escalation policies."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your organisation's API key. Create one in the Spike dashboard under Settings > API. Sent on every request as the `x-api-key` header."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"},"success":{"type":"boolean","description":"Present on the endpoints whose handlers include it (for example the API-key filter and the public on-call routes). Always `false` on an error."},"valid_api":{"type":"boolean","description":"Present on `401`s produced by the session/API-key filter. `false` means the supplied `x-api-key` was not recognised."},"statusCode":{"type":"number","description":"Echo of the HTTP status, present on a few permission errors."}}}}},"paths":{"/escalations":{"get":{"operationId":"getEscalations","summary":"Fetch list of escalations","description":"[An escalation policy](https://docs.spike.sh/escalations/introduction-to-escalations) is a simple set of rules to alert the right person at the right time using the right channel such as phone, slack or email. If that person misses out then the incident gets escalated to the next person.","tags":["Escalations"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"totalEscalations":{"type":"number"},"escalations":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"teams":{"type":"array","items":{"type":"string"}},"org":{"type":"string"}}}},"pagination":{"type":"object","description":"Pagination envelope produced by `lib/pagination.js`.","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"total":{"type":"number"},"perPage":{"type":"number"},"skip":{"type":"number"},"pages":{"type":"array","items":{"type":"number"}},"showingFrom":{"type":"number"},"showingTill":{"type":"number"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in your Spike dashboard under Settings > API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"The team's `_id` — a 24-character hex ObjectId, NOT the short `uid` slug. Read it from `GET /teams/get-all-teams`."}]}}}} ``` ## Get escalation policy details > Get details of an escalation policy. Includes escalation policy name, description, and escalation rules. ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations","description":"Create, read, update and archive escalation policies."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your organisation's API key. Create one in the Spike dashboard under Settings > API. Sent on every request as the `x-api-key` header."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"},"success":{"type":"boolean","description":"Present on the endpoints whose handlers include it (for example the API-key filter and the public on-call routes). Always `false` on an error."},"valid_api":{"type":"boolean","description":"Present on `401`s produced by the session/API-key filter. `false` means the supplied `x-api-key` was not recognised."},"statusCode":{"type":"number","description":"Echo of the HTTP status, present on a few permission errors."}}}}},"paths":{"/escalations/{escalationId}":{"get":{"operationId":"getEscalationsByEscalationId","summary":"Get escalation policy details","description":"Get details of an escalation policy. Includes escalation policy name, description, and escalation rules.","tags":["Escalations"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in your Spike dashboard under Settings > API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"The team's `_id` — a 24-character hex ObjectId, NOT the short `uid` slug. Read it from `GET /teams/get-all-teams`."},{"name":"escalationId","in":"path","required":true,"schema":{"type":"string"},"description":"escalationId parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"escalation":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"teams":{"type":"array","items":{"type":"string"}},"org":{"type":"string"}}},"integrations":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"token":{"type":"string","description":"The integration reference used by `POST /incidents/create` (as `integrationWebhook`) and by `GET|DELETE /integrations/{token}`. Never use the `_id`."},"webhookUrl":{"type":"string"},"service":{"type":"string"},"escalation":{"type":"string"},"teams":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}}},"isPinned":{"type":"boolean"},"alertRules":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` ## Fetch escalations using an on-call > Get a list of escalation policies that reference a specific on-call schedule. Useful for understanding which escalations will be affected if you modify or delete an on-call schedule. ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations","description":"Create, read, update and archive escalation policies."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your organisation's API key. Create one in the Spike dashboard under Settings > API. Sent on every request as the `x-api-key` header."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"},"success":{"type":"boolean","description":"Present on the endpoints whose handlers include it (for example the API-key filter and the public on-call routes). Always `false` on an error."},"valid_api":{"type":"boolean","description":"Present on `401`s produced by the session/API-key filter. `false` means the supplied `x-api-key` was not recognised."},"statusCode":{"type":"number","description":"Echo of the HTTP status, present on a few permission errors."}}}}},"paths":{"/on-calls/{oncallId}/escalations":{"get":{"operationId":"getOnCallsByOncallIdEscalations","summary":"Fetch escalations using an on-call","description":"Get a list of escalation policies that reference a specific on-call schedule. Useful for understanding which escalations will be affected if you modify or delete an on-call schedule.","tags":["Escalations"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in your Spike dashboard under Settings > API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"The team's `_id` — a 24-character hex ObjectId, NOT the short `uid` slug. Read it from `GET /teams/get-all-teams`."},{"name":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"oncallId parameter"}],"responses":{"200":{"description":"A bare JSON array of the escalation policies that reference this on-call.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"teams":{"type":"array","items":{"type":"string"}},"org":{"type":"string"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The on-call does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"oncall_found":{"type":"boolean"}}}}}}}}}}} ``` ## Create an escalation policy > Create a new escalation policy for a team. An escalation policy defines \*\*who\*\* gets notified, \*\*how\*\* (via which channel), and the \*\*delay between steps\*\*.\ > \ > \*\*Request Body:\*\*\ > \- \`name\` (required): A descriptive name for the escalation policy.\ > \- \`escalation\` (required): An array of steps. Each step is an array of notification rules that fire in parallel. Steps are executed sequentially — Step 2 fires only if Step 1 is not acknowledged within its interval.\ > \- \`delay\` (optional): Delay in minutes before the first step begins (default: \`0\`).\ > \ > \*\*Notification rule fields:\*\*\ > \- \`interval\`: Time in minutes to wait before escalating to the next step. Only required in the first step.\ > \- \`via\`: The notification channel — one of \`email\`, \`sms\`, \`phone\`, \`whatsapp\`, \`push-notification\`, \`slack\`, \`telegram\`, or \`ms-teams\`.\ > \- \`oncall\`: Reference to an on-call schedule \`{ "id": "\" }\`. The currently on-call user will be notified.\ > \- \`user\`: Reference to a specific user \`{ "id": "\" }\`. Use this to always notify a fixed person.\ > \- \`channel\`: (Slack/MS Teams only) The channel to post to \`{ "id": "\", "value": "\", "isPrivate": "false" }\`.\ > \- \`mention\`: (Slack only) Mention config \`{ "id": "false", "value": "No mention" }\`.\ > \ > \> \*\*Tip:\*\* Use \`oncall\` to route alerts to whoever is currently on-call, or \`user\` to always alert a specific person.
```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations","description":"Create, read, update and archive escalation policies."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your organisation's API key. Create one in the Spike dashboard under Settings > API. Sent on every request as the `x-api-key` header."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"},"success":{"type":"boolean","description":"Present on the endpoints whose handlers include it (for example the API-key filter and the public on-call routes). Always `false` on an error."},"valid_api":{"type":"boolean","description":"Present on `401`s produced by the session/API-key filter. `false` means the supplied `x-api-key` was not recognised."},"statusCode":{"type":"number","description":"Echo of the HTTP status, present on a few permission errors."}}}}},"paths":{"/escalations/create":{"post":{"operationId":"postEscalationsCreate","summary":"Create an escalation policy","description":"Create a new escalation policy for a team. An escalation policy defines **who** gets notified, **how** (via which channel), and the **delay between steps**.\n\n**Request Body:**\n- `name` (required): A descriptive name for the escalation policy.\n- `escalation` (required): An array of steps. Each step is an array of notification rules that fire in parallel. Steps are executed sequentially — Step 2 fires only if Step 1 is not acknowledged within its interval.\n- `delay` (optional): Delay in minutes before the first step begins (default: `0`).\n\n**Notification rule fields:**\n- `interval`: Time in minutes to wait before escalating to the next step. Only required in the first step.\n- `via`: The notification channel — one of `email`, `sms`, `phone`, `whatsapp`, `push-notification`, `slack`, `telegram`, or `ms-teams`.\n- `oncall`: Reference to an on-call schedule `{ \"id\": \"\" }`. The currently on-call user will be notified.\n- `user`: Reference to a specific user `{ \"id\": \"\" }`. Use this to always notify a fixed person.\n- `channel`: (Slack/MS Teams only) The channel to post to `{ \"id\": \"\", \"value\": \"\", \"isPrivate\": \"false\" }`.\n- `mention`: (Slack only) Mention config `{ \"id\": \"false\", \"value\": \"No mention\" }`.\n\n> **Tip:** Use `oncall` to route alerts to whoever is currently on-call, or `user` to always alert a specific person.\n","tags":["Escalations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"escalation":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"interval":{"type":"string"},"via":{"type":"string"},"oncall":{"type":"object","properties":{"id":{"type":"string"}}},"user":{"type":"object","description":"Notify a fixed person. `id` is the User `_id` (from `GET /users`).","properties":{"id":{"type":"string"}}},"channel":{"type":"object","description":"Slack / MS Teams only — the channel to post into.","properties":{"id":{"type":"string"},"value":{"type":"string"},"isPrivate":{"type":"string"}}},"mention":{"type":"object","description":"Slack only — mention configuration.","properties":{"id":{"type":"string"},"value":{"type":"string"}}}}}}},"delay":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"teams":{"type":"array","items":{"type":"string"}},"org":{"type":"string"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in your Spike dashboard under Settings > API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"The team's `_id` — a 24-character hex ObjectId, NOT the short `uid` slug. Read it from `GET /teams/get-all-teams`."}]}}}} ``` ## Update an escalation policy > Update an existing escalation policy by its ID. Pass the escalation policy \`\_id\` in the URL and provide the full updated policy in the request body.\ > \ > You must send the \*\*complete escalation structure\*\* — partial updates are not supported. The existing policy will be fully replaced with the provided data.\ > \ > \*\*Request Body:\*\*\ > \- \`name\` (required): Updated name for the escalation policy.\ > \- \`escalation\` (required): The full array of escalation steps (same format as Create).\ > \- \`delay\` (optional): Delay in minutes before the first step (default: \`0\`).\ > \ > See the \*Create an escalation policy\* endpoint for detailed field descriptions and notification channel options.
```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations","description":"Create, read, update and archive escalation policies."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your organisation's API key. Create one in the Spike dashboard under Settings > API. Sent on every request as the `x-api-key` header."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"},"success":{"type":"boolean","description":"Present on the endpoints whose handlers include it (for example the API-key filter and the public on-call routes). Always `false` on an error."},"valid_api":{"type":"boolean","description":"Present on `401`s produced by the session/API-key filter. `false` means the supplied `x-api-key` was not recognised."},"statusCode":{"type":"number","description":"Echo of the HTTP status, present on a few permission errors."}}}}},"paths":{"/escalations/{escalationId}/update":{"put":{"operationId":"putEscalationsByEscalationIdUpdate","summary":"Update an escalation policy","description":"Update an existing escalation policy by its ID. Pass the escalation policy `_id` in the URL and provide the full updated policy in the request body.\n\nYou must send the **complete escalation structure** — partial updates are not supported. The existing policy will be fully replaced with the provided data.\n\n**Request Body:**\n- `name` (required): Updated name for the escalation policy.\n- `escalation` (required): The full array of escalation steps (same format as Create).\n- `delay` (optional): Delay in minutes before the first step (default: `0`).\n\nSee the *Create an escalation policy* endpoint for detailed field descriptions and notification channel options.\n","tags":["Escalations"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in your Spike dashboard under Settings > API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"The team's `_id` — a 24-character hex ObjectId, NOT the short `uid` slug. Read it from `GET /teams/get-all-teams`."},{"name":"escalationId","in":"path","required":true,"schema":{"type":"string"},"description":"escalationId parameter"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"escalation":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"interval":{"type":"string"},"via":{"type":"string"},"oncall":{"type":"object","properties":{"id":{"type":"string"}}},"user":{"type":"object","description":"Notify a fixed person. `id` is the User `_id` (from `GET /users`).","properties":{"id":{"type":"string"}}},"channel":{"type":"object","description":"Slack / MS Teams only — the channel to post into.","properties":{"id":{"type":"string"},"value":{"type":"string"},"isPrivate":{"type":"string"}}},"mention":{"type":"object","description":"Slack only — mention configuration.","properties":{"id":{"type":"string"},"value":{"type":"string"}}}}}}},"delay":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"teams":{"type":"array","items":{"type":"string"}},"org":{"type":"string"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` ## Archive an escalation policy > Archive (soft-delete) an escalation policy by its ID. Archived escalation policies will no longer be active and won't appear in the default escalation list.\ > \ > \*\*Important:\*\* Before archiving, make sure no active integrations are using this escalation policy. Archiving an in-use policy may result in incidents not being escalated properly.\ > \ > Pass the escalation policy \`\_id\` as a path parameter. No request body is required.
```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations","description":"Create, read, update and archive escalation policies."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your organisation's API key. Create one in the Spike dashboard under Settings > API. Sent on every request as the `x-api-key` header."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"},"success":{"type":"boolean","description":"Present on the endpoints whose handlers include it (for example the API-key filter and the public on-call routes). Always `false` on an error."},"valid_api":{"type":"boolean","description":"Present on `401`s produced by the session/API-key filter. `false` means the supplied `x-api-key` was not recognised."},"statusCode":{"type":"number","description":"Echo of the HTTP status, present on a few permission errors."}}}}},"paths":{"/escalations/{escalationId}/archive":{"delete":{"operationId":"deleteEscalationsByEscalationIdArchive","summary":"Archive an escalation policy","description":"Archive (soft-delete) an escalation policy by its ID. Archived escalation policies will no longer be active and won't appear in the default escalation list.\n\n**Important:** Before archiving, make sure no active integrations are using this escalation policy. Archiving an in-use policy may result in incidents not being escalated properly.\n\nPass the escalation policy `_id` as a path parameter. No request body is required.\n","tags":["Escalations"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in your Spike dashboard under Settings > API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"The team's `_id` — a 24-character hex ObjectId, NOT the short `uid` slug. Read it from `GET /teams/get-all-teams`."},{"name":"escalationId","in":"path","required":true,"schema":{"type":"string"},"description":"escalationId parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"archive":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```