# Escalation API The Uptizm API has 8 endpoints on this resource, one section each. ## List escalation policies `GET /escalation-policies` The team's escalation policies, newest first, cursor-paginated. - URL: `https://api.uptizm.com/v1/escalation-policies` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:read` - Tag: Escalation - operationId: `v1.escalation-policies.index` ### Parameters - `per_page` (query, integer, min 1, max 200): Page size, clamped to 1 and the endpoint's maximum (200 on most lists). - `cursor` (query, string): The `meta.next_cursor` of the previous page. ### Response 200 Content type: `application/json`. - `data` (array of EscalationPolicyResource, required) - `id` (string, required) - `team_id` (string, required) - `name` (string, required) - `repeat_last_step` (boolean, required): Emitted on every read, list included: the editor seeds both switches from the roster it already holds, so gating these behind the detail response would make an edit form open with the flags off and then silently save them off. - `is_default` (boolean, required) - `steps` (array of string) - `created_at` (string or null, required) - `updated_at` (string or null, required) - `links` (object, required) - `first` (string or null, required) - `last` (string or null, required) - `prev` (string or null, required) - `next` (string or null, required) - `meta` (object, required) - `path` (string or null, required): Base path for paginator generated URLs. - `per_page` (integer, min 0, required): Number of items shown per page. - `next_cursor` (string or null, required): The "cursor" that points to the next set of items. - `prev_cursor` (string or null, required): The "cursor" that points to the previous set of items. ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Create an escalation policy `POST /escalation-policies` Creates a policy. - URL: `https://api.uptizm.com/v1/escalation-policies` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:write` - Tag: Escalation - operationId: `v1.escalation-policies.store` ### Parameters - `Idempotency-Key` (header, string): Any unique string per logical request. ### Request body Content type: `application/json`. - `name` (string, max length 200, required) - `repeat_last_step` (boolean): Both are optional and both default to false in the schema, so a client that predates them (or simply omits them) creates exactly the policy it created before. - `is_default` (boolean) ### Response 201 Content type: `application/json`. - `data` (EscalationPolicyResource, required) - `id` (string, required) - `team_id` (string, required) - `name` (string, required) - `repeat_last_step` (boolean, required): Emitted on every read, list included: the editor seeds both switches from the roster it already holds, so gating these behind the detail response would make an edit form open with the flags off and then silently save them off. - `is_default` (boolean, required) - `steps` (array of string) - `created_at` (string or null, required) - `updated_at` (string or null, required) ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 422: Validation error - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Get an escalation policy `GET /escalation-policies/{policy}` One policy with its ordered steps. - URL: `https://api.uptizm.com/v1/escalation-policies/{policy}` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:read` - Tag: Escalation - operationId: `v1.escalation-policies.show` ### Parameters - `policy` (path, string, required): The policy ID ### Response 200 Content type: `application/json`. - `data` (EscalationPolicyResource and object, required) - `id` (string, required) - `team_id` (string, required) - `name` (string, required) - `repeat_last_step` (boolean, required): Emitted on every read, list included: the editor seeds both switches from the roster it already holds, so gating these behind the detail response would make an edit form open with the flags off and then silently save them off. - `is_default` (boolean, required) - `steps` (array of string, required) - `created_at` (string or null, required) - `updated_at` (string or null, required) ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 404: Not found - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Update an escalation policy `PUT /escalation-policies/{policy}` Updates the policy. - URL: `https://api.uptizm.com/v1/escalation-policies/{policy}` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:write` - Tag: Escalation - operationId: `v1.escalation-policies.update` ### Parameters - `policy` (path, string, required): The policy ID ### Request body Content type: `application/json`. - `name` (string, max length 200) - `repeat_last_step` (boolean): Omitting either leaves it as it was: this is a PATCH-shaped update, so an editor that only renames a policy must not silently clear its paging flags. - `is_default` (boolean) ### Response 200 Content type: `application/json`. - `data` (EscalationPolicyResource and object, required) - `id` (string, required) - `team_id` (string, required) - `name` (string, required) - `repeat_last_step` (boolean, required): Emitted on every read, list included: the editor seeds both switches from the roster it already holds, so gating these behind the detail response would make an edit form open with the flags off and then silently save them off. - `is_default` (boolean, required) - `steps` (array of string, required) - `created_at` (string or null, required) - `updated_at` (string or null, required) ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 404: Not found - 422: Validation error - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Delete an escalation policy `DELETE /escalation-policies/{policy}` Deletes the policy. - URL: `https://api.uptizm.com/v1/escalation-policies/{policy}` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:write` - Tag: Escalation - operationId: `v1.escalation-policies.destroy` ### Parameters - `policy` (path, string, required): The policy ID ### Response 204 No body. ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 404: Not found - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Add an escalation step `POST /escalation-policies/{policy}/steps` Adds a step to the policy's paging chain. - URL: `https://api.uptizm.com/v1/escalation-policies/{policy}/steps` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:write` - Tag: Escalation - operationId: `v1.escalation-policies.steps.store` ### Parameters - `policy` (path, string, required): The policy ID - `Idempotency-Key` (header, string): Any unique string per logical request. ### Request body Content type: `application/json`. - `position` (integer, min 0, required) - `delay_minutes` (integer, min 0, required) - `target_type` (EscalationTargetType: string, one of `"on_call"`, `"user"`, required): Who an escalation step pages: the on-call responder (`on_call`) or a user (`user`). - `target_id` (string or null, uuid) ### Response 201 Content type: `application/json`. - `data` (EscalationPolicyResource and object, required) - `id` (string, required) - `team_id` (string, required) - `name` (string, required) - `repeat_last_step` (boolean, required): Emitted on every read, list included: the editor seeds both switches from the roster it already holds, so gating these behind the detail response would make an edit form open with the flags off and then silently save them off. - `is_default` (boolean, required) - `steps` (array of string, required) - `created_at` (string or null, required) - `updated_at` (string or null, required) ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 404: Not found - 422: Validation error - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Reorder escalation steps `PATCH /escalation-policies/{policy}/steps/reorder` Sets `position` for the policy's steps. - URL: `https://api.uptizm.com/v1/escalation-policies/{policy}/steps/reorder` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:write` - Tag: Escalation - operationId: `v1.escalation-policies.steps.reorder` ### Parameters - `policy` (path, string, required): The policy ID ### Request body Content type: `application/json`. - `order` (array of object, required) - `id` (string, required) - `position` (integer, min 0, required) ### Response 204 No body. ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 404: Not found - 422: Validation error - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md ## Remove an escalation step `DELETE /escalation-policies/{policy}/steps/{step}` Removes a step from the policy. - URL: `https://api.uptizm.com/v1/escalation-policies/{policy}/steps/{step}` - Auth: `Authorization: Bearer upz_...` - Required ability (`x-required-ability`): `oncall:write` - Tag: Escalation - operationId: `v1.escalation-policies.steps.destroy` ### Parameters - `policy` (path, string, required): The policy ID - `step` (path, string, required): The step ID ### Response 204 No body. ### Errors - 401: Unauthenticated - 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team. - 404: Not found - 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds. Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md