> 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

## Fetch list of escalations

> \[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.

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/escalations":{"get":{"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"}}}},"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":"Team ID of the team you are making the request to."}]}}},"components":{"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}}}
```

## 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"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/escalations/{escalationId}":{"get":{"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":"Team ID of the team you are making the request to."},{"name":"escalationId","in":"path","required":true,"schema":{"type":"string"},"description":"escalationId parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}}}
```

## 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"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls/{oncallId}/escalations":{"get":{"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":"Team ID of the team you are making the request to."},{"name":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"oncallId parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}}}
```

## 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": "\<on-call-id>" }\`. The currently on-call user will be notified.\
> \- \`user\`: Reference to a specific user \`{ "id": "\<user-id>" }\`. Use this to always notify a fixed person.\
> \- \`channel\`: (Slack/MS Teams only) The channel to post to \`{ "id": "\<channel-id>", "value": "\<channel-name>", "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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/escalations/create":{"post":{"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\": \"<on-call-id>\" }`. The currently on-call user will be notified.\n- `user`: Reference to a specific user `{ \"id\": \"<user-id>\" }`. Use this to always notify a fixed person.\n- `channel`: (Slack/MS Teams only) The channel to post to `{ \"id\": \"<channel-id>\", \"value\": \"<channel-name>\", \"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"}}}}}}},"delay":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"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":"Team ID of the team you are making the request to."}]}}},"components":{"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}}}
```

## 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/escalations/{escalationId}/update":{"put":{"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":"Team ID of the team you are making the request to."},{"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"}}}}}}},"delay":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"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"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}}}
```

## 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"Escalations"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/escalations/{escalationId}/archive":{"delete":{"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":"Team ID of the team you are making the request to."},{"name":"escalationId","in":"path","required":true,"schema":{"type":"string"},"description":"escalationId parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.spike.sh/spike-api-docs/escalations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.