> 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/on-call-overrides.md).

# On-call Overrides

Temporarily hand an on-call shift to another user. Overrides are Layer documents; the `id` returned by the list endpoint is the Layer `_id` used to remove one.

## GET /on-calls/{oncallId}/overrides

> Get all overrides

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call Overrides","description":"Temporarily hand an on-call shift to another user. Overrides are Layer documents; the `id` returned by the list endpoint is the Layer `_id` used to remove one."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[]}],"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}/overrides":{"get":{"operationId":"getOnCallsByOncallIdOverrides","summary":"Get all overrides","tags":["On-call Overrides"],"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":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call schedule's `_id` (24-char hex ObjectId)."},{"name":"from","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Overrides are Layer documents. `id` on each entry is the Layer `_id` you pass to the remove endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"overrides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The override Layer `_id`. Pass this as `{layerId}` to `DELETE /on-calls/{oncallId}/overrides/{layerId}/remove`."},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"desc":{"type":"string"},"timezone":{"type":"string"},"users":{"type":"array","items":{"type":"string"}},"shifts":{"type":"array","items":{"type":"object"}},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"index":{"type":"number"}}}},"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"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## DELETE /on-calls/{oncallId}/overrides/{layerId}/remove

> Delete an override

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call Overrides","description":"Temporarily hand an on-call shift to another user. Overrides are Layer documents; the `id` returned by the list endpoint is the Layer `_id` used to remove one."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[]}],"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."}}},"paths":{"/on-calls/{oncallId}/overrides/{layerId}/remove":{"delete":{"operationId":"deleteOnCallsByOncallIdOverridesByLayerIdRemove","summary":"Delete an override","tags":["On-call Overrides"],"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":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call schedule's `_id` (24-char hex ObjectId)."},{"name":"layerId","in":"path","required":true,"schema":{"type":"string"},"description":"The override Layer `_id` — this is the `id` field returned by `GET /on-calls/{oncallId}/overrides`, NOT the on-call id."}],"responses":{"200":{"description":"Returns `{ done: true }` — NOT `{ success: true }`.","content":{"application/json":{"schema":{"type":"object","properties":{"done":{"type":"boolean"}}}}}},"401":{"description":"Also returned when the layer does not exist or belongs to another organisation — this endpoint does NOT answer `404` for a missing override.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}}
```

## Add an override

> Add a temporary override to an on-call schedule. Overrides allow you to temporarily assign a different user to cover an on-call shift.\
> \
> All timestamps should be in ISO 8601 format (e.g., \`2025-01-24T00:00:00.000Z\`).<br>

```json
{"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call Overrides","description":"Temporarily hand an on-call shift to another user. Overrides are Layer documents; the `id` returned by the list endpoint is the Layer `_id` used to remove one."}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"security":[{"ApiKeyAuth":[]}],"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}/overrides/add":{"post":{"operationId":"postOnCallsByOncallIdOverridesAdd","summary":"Add an override","description":"Add a temporary override to an on-call schedule. Overrides allow you to temporarily assign a different user to cover an on-call shift.\n\nAll timestamps should be in ISO 8601 format (e.g., `2025-01-24T00:00:00.000Z`).\n","tags":["On-call Overrides"],"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":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call schedule's `_id` (24-char hex ObjectId)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user","start","end"],"description":"API callers send `user`, `start` and `end`. The legacy dashboard form fields (`userId`, `startDate`, `endDate`, `startTime`, `endTime`) are NOT the API contract. `start`/`end` as ISO 8601 are accepted from any caller (API key, OAuth or session).","properties":{"user":{"type":"string","description":"REQUIRED. The User `_id` to hand the shift to — an ObjectId, NOT an email address. A non-ObjectId is rejected with `400`."},"start":{"type":"string","format":"date-time","description":"REQUIRED. ISO 8601 start of the override, interpreted in `timezone`."},"end":{"type":"string","format":"date-time","description":"REQUIRED. ISO 8601 end of the override, interpreted in `timezone`."},"timezone":{"type":"string","description":"Optional IANA timezone. Defaults to the calling user's timezone, then the org default."},"desc":{"type":"string","description":"Optional free-text note."}}}}}},"responses":{"200":{"description":"Returns `{ done: true }` — NOT `{ success: true }`.","content":{"application/json":{"schema":{"type":"object","properties":{"done":{"type":"boolean"}}}}}},"400":{"description":"Either `user` was absent (`{ message: \"User is required\" }`) or it was not a valid ObjectId — an email address, for instance (`{ message: \"user must be a valid user id\" }`).","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```