> 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.md). # On-call ## Fetch on-calls > Get list of on-call schedules for a team ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls":{"get":{"summary":"Fetch on-calls","description":"Get list of on-call schedules for a team","tags":["On-call"],"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"}}}}}} ``` ## Create an on-call > Create an on-call schedule.\ > \ > \*\*Common case:\*\* send \`users\` plus a top-level \`rotation\`. Spike creates one\ > primary layer and derives the shift order from the order of \`users\`.\ > \ > \*\*Advanced:\*\* send a \`layers\` array instead to create multiple escalation tiers\ > in one call.\ > \ > The \`x-team-id\` header is REQUIRED and sets which team the on-call belongs to.\ > \ > \---\ > \ > \*\*Custom slots (optional):\*\* restrict when this layer is on-call.\ > \ > \- \`customiseFor: "day"\` with \`fromTime\`/\`toTime\` for a single daily window.\ > \- \`customiseFor: "week"\` with a \`conditions\` array to pick \*\*specific days\*\* (one\ > entry per day window — add as many as you need).\ > \ > Times are \`HH:mm\` (24-hour) in the schedule timezone; days are lowercase names.\ > \ > \`\`\`json\ > {\ > "customiseFor": "week",\ > "conditions": \[\ > { "fromDayOfWeek": "monday", "fromTime": "00:00", "toDayOfWeek": "tuesday", "toTime": "00:00" },\ > { "fromDayOfWeek": "tuesday", "fromTime": "00:00", "toDayOfWeek": "wednesday", "toTime": "00:00" },\ > { "fromDayOfWeek": "wednesday", "fromTime": "00:00", "toDayOfWeek": "thursday", "toTime": "00:00" }\ > ]\ > }\ > \`\`\` ````json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls":{"post":{"summary":"Create an on-call","description":"Create an on-call schedule.\n\n**Common case:** send `users` plus a top-level `rotation`. Spike creates one\nprimary layer and derives the shift order from the order of `users`.\n\n**Advanced:** send a `layers` array instead to create multiple escalation tiers\nin one call.\n\nThe `x-team-id` header is REQUIRED and sets which team the on-call belongs to.\n\n---\n\n**Custom slots (optional):** restrict when this layer is on-call.\n\n- `customiseFor: \"day\"` with `fromTime`/`toTime` for a single daily window.\n- `customiseFor: \"week\"` with a `conditions` array to pick **specific days** (one\n entry per day window — add as many as you need).\n\nTimes are `HH:mm` (24-hour) in the schedule timezone; days are lowercase names.\n\n```json\n {\n \"customiseFor\": \"week\",\n \"conditions\": [\n { \"fromDayOfWeek\": \"monday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"tuesday\", \"toTime\": \"00:00\" },\n { \"fromDayOfWeek\": \"tuesday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"wednesday\", \"toTime\": \"00:00\" },\n { \"fromDayOfWeek\": \"wednesday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"thursday\", \"toTime\": \"00:00\" }\n ]\n }\n```","tags":["On-call"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in the Spike dashboard under Settings → API."},{"name":"x-team-id","in":"header","required":true,"schema":{"type":"string"},"description":"REQUIRED to create an on-call — the id of the team the on-call will belong to. Must be a team in your organisation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"description":"Provide top-level `users` + `rotation` (one primary layer) OR a `layers` array (takes precedence when present).","properties":{"name":{"type":"string","description":"Display name for the on-call."},"users":{"type":"array","minItems":1,"description":"Rotation members for the primary layer, in rotation order.","items":{"type":"string","description":"A user ObjectId from your organisation."}},"rotation":{"type":"object","required":["length","unit"],"description":"How often the rotation moves to the next user.","properties":{"length":{"type":"integer","minimum":1,"description":"How many `unit`s each person is on call before handing off (e.g. 2 with unit days = a 2-day shift)."},"unit":{"type":"string","enum":["minutes","hours","days","weeks","months"],"description":"Time unit for the rotation length. Singular or plural and any case are accepted (day, Days, WEEK) and normalised."},"handoff":{"type":"string","pattern":"^\\d{2}:\\d{2}$","default":"00:00","description":"Time of day the shift hands off, 24-hour HH:mm, interpreted in the schedule timezone. Defaults to 00:00."},"handoffDay":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Day of the week the weekly handoff occurs. Only used when unit is weeks; ignored otherwise."}}},"timezone":{"type":"string","description":"IANA timezone for handoff times (e.g. America/New_York). Defaults to the owner timezone or Etc/UTC."},"desc":{"type":"string","description":"Optional description."},"layers":{"type":"array","description":"Optional explicit layers in priority order; each entry has its own users + rotation.","items":{"type":"object","required":["users","rotation"],"properties":{"users":{"type":"array","minItems":1,"description":"Rotation members for this layer, in order.","items":{"type":"string","description":"A user ObjectId from your organisation."}},"rotation":{"type":"object","required":["length","unit"],"description":"How often the rotation moves to the next user.","properties":{"length":{"type":"integer","minimum":1,"description":"How many `unit`s each person is on call before handing off (e.g. 2 with unit days = a 2-day shift)."},"unit":{"type":"string","enum":["minutes","hours","days","weeks","months"],"description":"Time unit for the rotation length. Singular or plural and any case are accepted (day, Days, WEEK) and normalised."},"handoff":{"type":"string","pattern":"^\\d{2}:\\d{2}$","default":"00:00","description":"Time of day the shift hands off, 24-hour HH:mm, interpreted in the schedule timezone. Defaults to 00:00."},"handoffDay":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Day of the week the weekly handoff occurs. Only used when unit is weeks; ignored otherwise."}}},"desc":{"type":"string","description":"Optional layer description."},"customTimings":{"type":"object","description":"Optional. Restrict WHEN this layer is on-call. Use customiseFor \"day\" for a single daily window (fromTime/toTime), or \"week\" for day-of-week windows (conditions[]). Times are \"HH:mm\" (24-hour) in the schedule timezone; day names are lowercase.","properties":{"customiseFor":{"type":"string","enum":["day","week"],"description":"\"day\" = one daily on-call window; \"week\" = per-day-of-week windows defined in conditions."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window start, HH:mm (used when customiseFor is \"day\")."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window end, HH:mm (used when customiseFor is \"day\")."},"conditions":{"type":"array","description":"Weekly windows (used when customiseFor is \"week\").","items":{"type":"object","properties":{"fromDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window start day."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window start time, HH:mm."},"toDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window end day."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window end time, HH:mm."}}}}}}}}},"customTimings":{"type":"object","description":"Optional. Restrict WHEN this layer is on-call. Use customiseFor \"day\" for a single daily window (fromTime/toTime), or \"week\" for day-of-week windows (conditions[]). Times are \"HH:mm\" (24-hour) in the schedule timezone; day names are lowercase.","properties":{"customiseFor":{"type":"string","enum":["day","week"],"description":"\"day\" = one daily on-call window; \"week\" = per-day-of-week windows defined in conditions."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window start, HH:mm (used when customiseFor is \"day\")."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window end, HH:mm (used when customiseFor is \"day\")."},"conditions":{"type":"array","description":"Weekly windows (used when customiseFor is \"week\").","items":{"type":"object","properties":{"fromDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window start day."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window start time, HH:mm."},"toDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window end day."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window end time, HH:mm."}}}}}}}}}}},"responses":{"201":{"description":"On-call created; the full on-call is returned","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation error (missing name, missing x-team-id, unknown user, or bad rotation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No owner/team could be resolved for this organisation","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 an on-call > Get details about a specific on-call including layers, shifts and users ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls/{oncallId}":{"get":{"summary":"Fetch an on-call","description":"Get details about a specific on-call including layers, shifts and users","tags":["On-call"],"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"},{"name":"from","in":"query","required":true,"schema":{"type":"string"}}],"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"}}}}}} ``` ## Edit an on-call > Update an on-call's top-level properties (name and/or team). Layers are not changed here — use the layer endpoints to edit rotations. Send only the fields you want to change. ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls/{oncallId}":{"put":{"summary":"Edit an on-call","description":"Update an on-call's top-level properties (name and/or team). Layers are not changed here — use the layer endpoints to edit rotations. Send only the fields you want to change.","tags":["On-call"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in the Spike dashboard under Settings → API."},{"name":"x-team-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. Team to scope the request to. Defaults to your organisation's default team when omitted."},{"name":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call ObjectId."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","description":"New display name."},"teamId":{"type":"string","description":"Move the on-call to this team (ObjectId)."}}}}}},"responses":{"200":{"description":"On-call updated; the full on-call is returned","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":"On-call 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"}}}}}} ``` ## Add a layer > Add a new layer (rotation) to an on-call.\ > \ > It's appended after the existing layers as the next escalation tier; shifts are\ > derived from the order of \`users\`. Returns the full updated on-call.\ > \ > \---\ > \ > \*\*Custom timings (optional):\*\* restrict when this layer is on-call.\ > \ > \- \`customiseFor: "day"\` with \`fromTime\`/\`toTime\` for a single daily window.\ > \- \`customiseFor: "week"\` with a \`conditions\` array to pick \*\*specific days\*\* (one\ > entry per day window — add as many as you need).\ > \ > Times are \`HH:mm\` (24-hour) in the schedule timezone; days are lowercase names.\ > \ > \`\`\`json\ > {\ > "customiseFor": "week",\ > "conditions": \[\ > { "fromDayOfWeek": "monday", "fromTime": "00:00", "toDayOfWeek": "tuesday", "toTime": "00:00" },\ > { "fromDayOfWeek": "tuesday", "fromTime": "00:00", "toDayOfWeek": "wednesday", "toTime": "00:00" },\ > { "fromDayOfWeek": "wednesday", "fromTime": "00:00", "toDayOfWeek": "thursday", "toTime": "00:00" }\ > ]\ > }\ > \`\`\` ````json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls/{oncallId}/layers":{"post":{"summary":"Add a layer","description":"Add a new layer (rotation) to an on-call.\n\nIt's appended after the existing layers as the next escalation tier; shifts are\nderived from the order of `users`. Returns the full updated on-call.\n\n---\n\n**Custom timings (optional):** restrict when this layer is on-call.\n\n- `customiseFor: \"day\"` with `fromTime`/`toTime` for a single daily window.\n- `customiseFor: \"week\"` with a `conditions` array to pick **specific days** (one\n entry per day window — add as many as you need).\n\nTimes are `HH:mm` (24-hour) in the schedule timezone; days are lowercase names.\n\n```json\n {\n \"customiseFor\": \"week\",\n \"conditions\": [\n { \"fromDayOfWeek\": \"monday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"tuesday\", \"toTime\": \"00:00\" },\n { \"fromDayOfWeek\": \"tuesday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"wednesday\", \"toTime\": \"00:00\" },\n { \"fromDayOfWeek\": \"wednesday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"thursday\", \"toTime\": \"00:00\" }\n ]\n }\n```","tags":["On-call"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in the Spike dashboard under Settings → API."},{"name":"x-team-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. Team to scope the request to. Defaults to your organisation's default team when omitted."},{"name":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call ObjectId."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["users","rotation"],"properties":{"users":{"type":"array","minItems":1,"description":"Rotation members for this layer, in order.","items":{"type":"string","description":"A user ObjectId from your organisation."}},"rotation":{"type":"object","required":["length","unit"],"description":"How often the rotation moves to the next user.","properties":{"length":{"type":"integer","minimum":1,"description":"How many `unit`s each person is on call before handing off (e.g. 2 with unit days = a 2-day shift)."},"unit":{"type":"string","enum":["minutes","hours","days","weeks","months"],"description":"Time unit for the rotation length. Singular or plural and any case are accepted (day, Days, WEEK) and normalised."},"handoff":{"type":"string","pattern":"^\\d{2}:\\d{2}$","default":"00:00","description":"Time of day the shift hands off, 24-hour HH:mm, interpreted in the schedule timezone. Defaults to 00:00."},"handoffDay":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Day of the week the weekly handoff occurs. Only used when unit is weeks; ignored otherwise."}}},"desc":{"type":"string","description":"Optional layer description."},"customTimings":{"type":"object","description":"Optional. Restrict WHEN this layer is on-call. Use customiseFor \"day\" for a single daily window (fromTime/toTime), or \"week\" for day-of-week windows (conditions[]). Times are \"HH:mm\" (24-hour) in the schedule timezone; day names are lowercase.","properties":{"customiseFor":{"type":"string","enum":["day","week"],"description":"\"day\" = one daily on-call window; \"week\" = per-day-of-week windows defined in conditions."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window start, HH:mm (used when customiseFor is \"day\")."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window end, HH:mm (used when customiseFor is \"day\")."},"conditions":{"type":"array","description":"Weekly windows (used when customiseFor is \"week\").","items":{"type":"object","properties":{"fromDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window start day."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window start time, HH:mm."},"toDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window end day."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window end time, HH:mm."}}}}}}}}}}},"responses":{"201":{"description":"Layer added; the full on-call is returned","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":"On-call 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"}}}}}} ```` ## Edit a layer > Send any subset of \`users\`, \`rotation\`, \`desc\`; omitted fields keep their\ > current values. When you send \`rotation\`, its fields merge onto the current\ > cadence (e.g. send only \`{ "rotation": { "length": 2 } }\` to change just the\ > length). Returns the full updated on-call.\ > \ > \---\ > \ > \*\*Custom slots (optional):\*\* restrict when this layer is on-call.\ > \ > \- \`customiseFor: "day"\` with \`fromTime\`/\`toTime\` for a single daily window.\ > \- \`customiseFor: "week"\` with a \`conditions\` array to pick \*\*specific days\*\* (one\ > entry per day window — add as many as you need).\ > \ > Times are \`HH:mm\` (24-hour) in the schedule timezone; days are lowercase names.\ > \ > \`\`\`json\ > {\ > "customiseFor": "week",\ > "conditions": \[\ > { "fromDayOfWeek": "monday", "fromTime": "00:00", "toDayOfWeek": "tuesday", "toTime": "00:00" },\ > { "fromDayOfWeek": "tuesday", "fromTime": "00:00", "toDayOfWeek": "wednesday", "toTime": "00:00" },\ > { "fromDayOfWeek": "wednesday", "fromTime": "00:00", "toDayOfWeek": "thursday", "toTime": "00:00" }\ > ]\ > }\ > \`\`\` ````json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls/{oncallId}/layers/{layerId}":{"put":{"summary":"Edit a layer","description":"Send any subset of `users`, `rotation`, `desc`; omitted fields keep their\ncurrent values. When you send `rotation`, its fields merge onto the current\ncadence (e.g. send only `{ \"rotation\": { \"length\": 2 } }` to change just the\nlength). Returns the full updated on-call.\n\n---\n\n**Custom slots (optional):** restrict when this layer is on-call.\n\n- `customiseFor: \"day\"` with `fromTime`/`toTime` for a single daily window.\n- `customiseFor: \"week\"` with a `conditions` array to pick **specific days** (one\n entry per day window — add as many as you need).\n\nTimes are `HH:mm` (24-hour) in the schedule timezone; days are lowercase names.\n\n```json\n {\n \"customiseFor\": \"week\",\n \"conditions\": [\n { \"fromDayOfWeek\": \"monday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"tuesday\", \"toTime\": \"00:00\" },\n { \"fromDayOfWeek\": \"tuesday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"wednesday\", \"toTime\": \"00:00\" },\n { \"fromDayOfWeek\": \"wednesday\", \"fromTime\": \"00:00\", \"toDayOfWeek\": \"thursday\", \"toTime\": \"00:00\" }\n ]\n }\n```","tags":["On-call"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in the Spike dashboard under Settings → API."},{"name":"x-team-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. Team to scope the request to. Defaults to your organisation's default team when omitted."},{"name":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call ObjectId."},{"name":"layerId","in":"path","required":true,"schema":{"type":"string"},"description":"The layer ObjectId (from layers[].id)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"users":{"type":"array","minItems":1,"description":"Replacement rotation members, in order (replaces the existing list).","items":{"type":"string","description":"A user ObjectId from your organisation."}},"rotation":{"type":"object","description":"How often the rotation moves to the next user.","properties":{"length":{"type":"integer","minimum":1,"description":"How many `unit`s each person is on call before handing off (e.g. 2 with unit days = a 2-day shift)."},"unit":{"type":"string","enum":["minutes","hours","days","weeks","months"],"description":"Time unit for the rotation length. Singular or plural and any case are accepted (day, Days, WEEK) and normalised."},"handoff":{"type":"string","pattern":"^\\d{2}:\\d{2}$","default":"00:00","description":"Time of day the shift hands off, 24-hour HH:mm, interpreted in the schedule timezone. Defaults to 00:00."},"handoffDay":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Day of the week the weekly handoff occurs. Only used when unit is weeks; ignored otherwise."}}},"desc":{"type":"string","description":"New layer description."},"customTimings":{"type":"object","description":"Optional. Restrict WHEN this layer is on-call. Use customiseFor \"day\" for a single daily window (fromTime/toTime), or \"week\" for day-of-week windows (conditions[]). Times are \"HH:mm\" (24-hour) in the schedule timezone; day names are lowercase.","properties":{"customiseFor":{"type":"string","enum":["day","week"],"description":"\"day\" = one daily on-call window; \"week\" = per-day-of-week windows defined in conditions."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window start, HH:mm (used when customiseFor is \"day\")."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Daily window end, HH:mm (used when customiseFor is \"day\")."},"conditions":{"type":"array","description":"Weekly windows (used when customiseFor is \"week\").","items":{"type":"object","properties":{"fromDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window start day."},"fromTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window start time, HH:mm."},"toDayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"description":"Window end day."},"toTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Window end time, HH:mm."}}}}}}}}}}},"responses":{"200":{"description":"Layer updated; the full on-call is returned","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":"On-call or layer 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"}}}}}} ```` ## Delete a layer > Delete a layer from an on-call. An on-call must always keep at least one layer, so deleting the last remaining layer returns 409. Returns the full updated on-call. ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/on-calls/{oncallId}/layers/{layerId}":{"delete":{"summary":"Delete a layer","description":"Delete a layer from an on-call. An on-call must always keep at least one layer, so deleting the last remaining layer returns 409. Returns the full updated on-call.","tags":["On-call"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key. Find it in the Spike dashboard under Settings → API."},{"name":"x-team-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. Team to scope the request to. Defaults to your organisation's default team when omitted."},{"name":"oncallId","in":"path","required":true,"schema":{"type":"string"},"description":"The on-call ObjectId."},{"name":"layerId","in":"path","required":true,"schema":{"type":"string"},"description":"The layer ObjectId (from layers[].id)."}],"responses":{"200":{"description":"Layer deleted; the full on-call is returned","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"On-call or layer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cannot delete the only remaining layer","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"}}}}}} ``` ## Is a user on-call? > Check whether a personal is currently oncall or not ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/oncalls/am-i-on-call":{"get":{"summary":"Is a user on-call?","description":"Check whether a personal is currently oncall or not","tags":["On-call"],"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":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized","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 upcoming shifts from multiple schedules > Fetch upcoming shifts from multiple schedules ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/oncalls/upcoming-shifts":{"get":{"summary":"Fetch upcoming shifts from multiple schedules","description":"Fetch upcoming shifts from multiple schedules","tags":["On-call"],"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":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized","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 all currently active on-call shifts > Get a list of users who are currently on call ```json {"openapi":"3.1.0","info":{"title":"Spike API","version":"1.0.0"},"tags":[{"name":"On-call"}],"servers":[{"url":"https://api.spike.sh","description":"API server"}],"paths":{"/oncalls/all-active-on-call-shifts":{"get":{"summary":"Fetch all currently active on-call shifts","description":"Get a list of users who are currently on call","tags":["On-call"],"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"}}}}}} ``` --- # 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/on-call.md?ask=&goal= ``` `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.