# 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"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. You can find this in your Spike dashboard under Settings > API."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}},"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"}}}}}}}}}
```

## 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"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. You can find this in your Spike dashboard under Settings > API."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}},"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":"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"}}}}}}}}}
```

## 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"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. You can find this in your Spike dashboard under Settings > API."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}},"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":"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"}}}}}}}}}
```

## 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"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. You can find this in your Spike dashboard under Settings > API."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}},"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"}}}}}}}}}
```

## 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"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. You can find this in your Spike dashboard under Settings > API."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}},"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":"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"}}}}}}}}}
```

## 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"}],"security":[{"ApiKeyAuth":[],"TeamIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. You can find this in your Spike dashboard under Settings > API."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message describing the problem"},"error":{"type":"string","description":"Error type or code"}}}}},"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":"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"}}}}}}}}}
```


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.