# On-call API

The Uptizm API has 11 endpoints on this resource, one section each.

## Get who is on call

`GET /on-call/current`

Resolves who is on call right now.

- URL: `https://api.uptizm.com/v1/on-call/current`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:read`
- Tag: On-call
- operationId: `v1.on-call.current`

### Parameters

- `schedule_id` (query, string)

### Response 200

Content type: `application/json`.

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

## List on-call schedules

`GET /on-call/schedules`

The team's schedules, newest first, page-numbered.

- URL: `https://api.uptizm.com/v1/on-call/schedules`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:read`
- Tag: On-call
- operationId: `v1.on-call.schedules.index`

### Response 200

Content type: `application/json`.

- `data` (array of OnCallScheduleResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `timezone` (string, required)
  - `rotations` (array of string, required)
  - `overrides` (array of string, required)
  - `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)
  - `current_page` (integer, min 1, required)
  - `from` (integer or null, min 1, required)
  - `last_page` (integer, min 1, required)
  - `links` (array of object, required): Generated paginator links.
    - `url` (string or null, required)
    - `label` (string, required)
    - `active` (boolean, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, min 0, required): Number of items shown per page.
  - `to` (integer or null, min 1, required): Number of the last item in the slice.
  - `total` (integer, min 0, required): Total number of items being paginated.

### 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 on-call schedule

`POST /on-call/schedules`

Creates a schedule.

- URL: `https://api.uptizm.com/v1/on-call/schedules`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.store`

### Parameters

- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `name` (string, max length 200, required)
- `timezone` (string or null, max length 64)

### Response 201

Content type: `application/json`.

- `data` (OnCallScheduleResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `timezone` (string, required)
  - `rotations` (array of string)
  - `overrides` (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 on-call schedule

`GET /on-call/schedules/{schedule}`

One schedule with its rotation and overrides.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:read`
- Tag: On-call
- operationId: `v1.on-call.schedules.show`

### Parameters

- `schedule` (path, string, required): The schedule ID

### Response 200

Content type: `application/json`.

- `data` (OnCallScheduleResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `timezone` (string, required)
  - `rotations` (array of string, required)
  - `overrides` (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 on-call schedule

`PUT /on-call/schedules/{schedule}`

Updates the schedule.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.update`

### Parameters

- `schedule` (path, string, required): The schedule ID

### Request body

Content type: `application/json`.

- `name` (string, max length 200)
- `timezone` (string or null, max length 64)

### Response 200

Content type: `application/json`.

- `data` (OnCallScheduleResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `timezone` (string, required)
  - `rotations` (array of string)
  - `overrides` (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.
- 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 on-call schedule

`DELETE /on-call/schedules/{schedule}`

Deletes the schedule.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.destroy`

### Parameters

- `schedule` (path, string, required): The schedule 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 a rotation slot

`POST /on-call/schedules/{schedule}/rotations`

Adds a responder slot to the schedule's rotation.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}/rotations`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.rotations.store`

### Parameters

- `schedule` (path, string, required): The schedule ID
- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `user_id` (string, uuid, required)
- `position` (integer, min 0, required)
- `shift_hours` (integer or null, min 1, max 8760)

### Response 201

Content type: `application/json`.

- `data` (OnCallScheduleResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `timezone` (string, required)
  - `rotations` (array of string, required)
  - `overrides` (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 the rotation

`PATCH /on-call/schedules/{schedule}/rotations/reorder`

Sets `position` for the schedule's rotation slots.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}/rotations/reorder`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.rotations.reorder`

### Parameters

- `schedule` (path, string, required): The schedule 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 a rotation slot

`DELETE /on-call/schedules/{schedule}/rotations/{rotation}`

Removes a responder slot from the rotation.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}/rotations/{rotation}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.rotations.destroy`

### Parameters

- `schedule` (path, string, required): The schedule ID
- `rotation` (path, string, required): The rotation 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 override

`POST /on-call/schedules/{schedule}/overrides`

Adds a temporary responder override to the schedule.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}/overrides`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.overrides.store`

### Parameters

- `schedule` (path, string, required): The schedule ID
- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `user_id` (string, uuid, required)
- `starts_at` (string, date-time, required)
- `ends_at` (string, date-time, required)

### Response 201

Content type: `application/json`.

- `data` (OnCallScheduleResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `timezone` (string, required)
  - `rotations` (array of string, required)
  - `overrides` (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

## Remove an override

`DELETE /on-call/schedules/{schedule}/overrides/{override}`

Removes a temporary override.

- URL: `https://api.uptizm.com/v1/on-call/schedules/{schedule}/overrides/{override}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `oncall:write`
- Tag: On-call
- operationId: `v1.on-call.schedules.overrides.destroy`

### Parameters

- `schedule` (path, string, required): The schedule ID
- `override` (path, string, required): The override 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