{"openapi":"3.1.0","info":{"title":"Kazee Spaces API","version":"0.1.0","description":"Everything a person can do in Kazee Spaces (tasks, spaces, docs, calendar, files and more) as plain HTTPS calls that answer in JSON.\n\n**Sign in.** Send `Authorization: Bearer <token>` with every call. The token comes from Kazee sign-in, and each call lists the permission it needs.\n\n**Lists.** Most list calls take `limit` and `skip` and answer with the matching items plus a `total`, so you can page through them. Each call lists its own paging inputs.\n\n**IDs and dates.** IDs are 24-character strings. Dates are ISO 8601 in UTC, e.g. `2026-10-20T09:00:00.000Z`.\n\n**Errors.** A call that fails answers with a 4xx or 5xx status and `{ \"error\": \"what went wrong\" }`.\n\n**For bots.** This page is built from the Spaces code itself. The raw file is at `/api/swagger`.\n\n## Live updates\n\nSpaces pushes changes to open apps over [Socket.IO](https://socket.io/docs/v4/) (version 4), so a screen can update without asking again.\n\n### Connect\n\nConnect a Socket.IO client to `https://api.spaces.kazee.africa` with path `/socket.io`, and give the same Kazee sign-in token the calls take as `auth: { token }` (a `token` query value or an `Authorization: Bearer <token>` header also works). Outside systems' app logins cannot connect. Spaces checks the token again while you stay connected and closes the connection once it is no longer valid.\n\n```js\nconst socket = io(\"https://api.spaces.kazee.africa\", { path: \"/socket.io\", auth: { token } });\nsocket.on(\"connected\", ({ userId }) => socket.emit(\"room:join\", { roomId: `space:${spaceId}` }, (err) => err && console.warn(err.message)));\nsocket.on(\"task:updated\", ({ task }) => render(task));\n```\n\nYou get `connected` first, and `user:online` / `user:offline` for everyone in your organisation without joining anything. For everything else, join a room with `room:join`:\n\n- `space:<spaceId>`: tasks, comments and pipelines in that space. You need to be able to see the space: its members, or anyone in the organisation when it is public.\n- `pipeline-agent:<sessionId>` or `strategy-agent:<sessionId>`: an AI assistant chat you started.\n- Your notifications come without joining a room.\n- Wiki pages, sheets and documents have their own join events (`doc:join`, `univer:join`). Joining needs what opening it takes: for a page, being able to see its space (and a member of it when the wiki is private); for a sheet or document, being able to see its space or having it shared with you. Sending changes (`doc:update`, `univer:update`, `univer:operation`, or a sync message that carries changes) needs what saving it takes: a contributor of the space for a page; an editor of the space, or an editor it was shared with, for a sheet or document, and never while its space is archived. Every other event needs you to have joined first.\n\nA refused join answers on the acknowledgement with `{ code: \"FORBIDDEN\", message }`. Rejoin your rooms after a reconnect.\n\n### Events Spaces sends\n\n#### Connection\n\n- **`connected`**: The connection is signed in and ready. Sent to the new connection only.\n  - `userId`: Your user ID\n  - `socketId`: ID of this connection\n- **`pong`**: Answer to ping. Sent to the connection that sent ping.\n  - No payload\n- **`error`**: A room could not be joined or left because of a server fault (a refused join answers on the acknowledgement only). Sent to the connection whose room:join or room:leave failed on the server.\n  - `code`: INTERNAL_ERROR\n  - `message`: What went wrong\n  - `action`: room:join or room:leave\n- **`room:joined`**: You are in the room and will get its events. Sent to the connection that joined.\n  - `roomId`: The room\n- **`room:left`**: You left the room. Sent to the connection that left.\n  - `roomId`: The room\n\n#### Presence\n\n- **`user:online`**: Someone opened their first connection. Sent to everyone connected in your organisation.\n  - `userId`: ID of the person\n- **`user:offline`**: Someone closed their last connection. Sent to everyone connected in your organisation.\n  - `userId`: ID of the person\n  - `lastSeen`: When, ISO 8601\n\n#### Tasks\n\n- **`task:created`**: A task appeared in the space: created, restored, moved in, or unarchived in bulk. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `task`: The task, as the task calls return it\n  - `spaceId`: ID of the task's space\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n- **`task:updated`**: A task in the space changed: details, status, assignees, or a bulk change. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `task`: The task, as the task calls return it\n  - `spaceId`: ID of the task's space\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n- **`task:deleted`**: A task left the space: archived (one or in bulk) or moved to another space. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `taskId`: ID of the task\n  - `spaceId`: ID of the space it left\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n\n#### Comments\n\n- **`comment:created`**: A comment was posted on something in the space. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `comment`: The new comment, as the comment calls return it\n  - `targetType`: What it is on: task, wiki_page, pipeline, pipeline_record or event\n  - `targetId`: ID of that item\n  - `spaceId`: ID of the space\n  - `timestamp`: When it was sent, ISO 8601\n- **`comment:reaction`**: Someone added or removed an emoji reaction on a comment. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `commentId`: ID of the comment\n  - `targetType`: What the comment is on\n  - `targetId`: ID of that item\n  - `spaceId`: ID of the space\n  - `reactions`: The comment's reactions now\n  - `actorId`: ID of the person who reacted\n  - `emoji`: The emoji\n  - `action`: added or removed\n  - `timestamp`: When it was sent, ISO 8601\n- **`comment:seen`**: Someone marked comments as seen. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `targetType`: What the comments are on\n  - `targetId`: ID of that item\n  - `spaceId`: ID of the space\n  - `commentIds`: IDs of the comments marked\n  - `userId`: ID of the person who saw them\n  - `seenAt`: When, ISO 8601\n  - `timestamp`: When it was sent, ISO 8601\n- **`comment:typing`**: Someone started or stopped typing a comment (send comment:typing to share your own). Sent to everyone else in the space's room (`space:<spaceId>`).\n  - `targetType`: What they are commenting on; task when not given\n  - `targetId`: ID of that item\n  - `spaceId`: ID of the space\n  - `userId`: ID of the person typing, from their sign-in\n  - `userName`: Their name\n  - `isTyping`: true while typing, false when they stop\n  - `timestamp`: When it was sent, ISO 8601\n\n#### Pipelines\n\n- **`pipeline:record_created`**: A record was added to a pipeline (also by duplicating one). Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `record`: The record, as the record calls return it\n  - `pipelineId`: ID of the record's pipeline\n  - `spaceId`: ID of the pipeline's space\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n- **`pipeline:record_updated`**: A record's details changed. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `record`: The record, as the record calls return it\n  - `pipelineId`: ID of the record's pipeline\n  - `spaceId`: ID of the pipeline's space\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n- **`pipeline:record_moved`**: A record moved to another stage. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `record`: The record, as the record calls return it\n  - `pipelineId`: ID of the record's pipeline\n  - `spaceId`: ID of the pipeline's space\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n  - `fromStageId`: The stage it left\n  - `toStageId`: The stage it is in now\n- **`pipeline:record_archived`**: A record was archived. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `recordId`: ID of the record\n  - `pipelineId`: ID of its pipeline\n  - `spaceId`: ID of the pipeline's space\n  - `userId`: ID of the person who archived it\n  - `timestamp`: When it was sent, ISO 8601\n- **`pipeline:updated`**: A pipeline's setup changed: its automations, or a new setup from a blueprint or the AI assistant. Sent to everyone who joined the space's room, `space:<spaceId>`.\n  - `pipeline`: The pipeline's whole setup\n  - `spaceId`: ID of its space\n  - `userId`: ID of the person who made the change\n  - `timestamp`: When it was sent, ISO 8601\n\n#### Notifications\n\n- **`notification`**: A new notification for you. Sent to each of the recipient's own connections.\n  - `id`: ID of the notification\n  - `type`: What kind, e.g. task_assigned or event_reminders\n  - `title`: Its title\n  - `content`: Its text\n  - `targetType`: What it is about, e.g. task, event or pipeline_record\n  - `targetId`: ID of that item\n  - `spaceId`: ID of the space, when there is one\n  - `actorId`: ID of the person (or system) that caused it\n  - `actorName`: Their name\n  - `deepLink`: Where to open it in the app, when there is a link\n  - `data`: Extra details for that kind, when there are any\n  - `timestamp`: When it was sent, ISO 8601\n  - `read`: Always false\n\n#### AI assistants\n\n- **`pipeline-agent:event`**: One step of a pipeline assistant turn, streamed while it runs (sendPipelineAgentMessage answers 202 at once); type applied comes after applyPipelineAgentDraft. Sent to the pipeline assistant chat's room (`pipeline-agent:<sessionId>`), open to the chat's owner.\n  - `type`: What happened: message_start, text_delta, tool_call, tool_result, draft_updated, migration_plan_updated, applied, message_end, done or error\n  - `iteration`: message_start: which round of the turn this is, from 1\n  - `delta`: text_delta: the next piece of the assistant's reply\n  - `toolCall`: tool_call: the tool the assistant is calling, with its arguments\n  - `toolCallId`, `name`, `ok`, `result`, `error`: tool_result: which call it answers, the tool, whether it worked, and its result or error\n  - `blueprint`, `valid`, `errors`: draft_updated: the draft pipeline setup, whether it is valid, and its problems\n  - `plan`: migration_plan_updated: what happens to the records in stages the draft changes\n  - `pipelineId`: applied: the draft was applied to this pipeline\n  - `message`: message_end: the assistant's whole message\n  - `reason`: done: why the turn ended: stop, max_iterations, cancelled or timeout\n  - `error`, `code`, `provider`: error: what went wrong; code AI_NOT_CONFIGURED when the organisation has no AI key set up\n- **`strategy-agent:event`**: One step of a strategy assistant turn, streamed while it runs (sendStrategyAgentMessage answers 202 at once). Sent to the strategy assistant chat's room (`strategy-agent:<sessionId>`), open to the chat's owner.\n  - `type`: What happened: message_start, text_delta, tool_call, tool_result, strategy_updated, message_end, done or error\n  - `iteration`: message_start: which round of the turn this is, from 1\n  - `delta`: text_delta: the next piece of the assistant's reply\n  - `toolCall`: tool_call: the tool the assistant is calling, with its arguments\n  - `toolCallId`, `name`, `ok`, `result`, `error`: tool_result: which call it answers, the tool, whether it worked, and its result or error\n  - `strategy`: strategy_updated: the strategy as the assistant left it\n  - `message`: message_end: the assistant's whole message\n  - `reason`: done: why the turn ended: stop, max_iterations, cancelled or timeout\n  - `error`, `code`, `provider`: error: what went wrong; code AI_NOT_CONFIGURED when the organisation has no AI key set up\n\n#### Editing a wiki page together\n\n- **`doc:sync`**: A Y.js sync message for the page. Sent to the connection that joined or synced, or the others editing the page.\n  - `documentId`: ID of the page\n  - `message`: The Y.js sync message, as a list of bytes\n- **`doc:update`**: Someone changed the page. Sent to the others editing the page (`doc:<documentId>`).\n  - `documentId`: ID of the page\n  - `update`: The Y.js update, as a list of bytes\n- **`doc:awareness`**: Someone's cursor or selection moved. Sent to the others editing the page (`doc:<documentId>`).\n  - `documentId`: ID of the page\n  - `userId`: ID of the person\n  - `socketId`: ID of that person's connection\n  - `awareness`: Their cursor and selection state, as their editor sent it\n- **`doc:user:joined`**: Someone opened the page for editing. Sent to the others editing the page (`doc:<documentId>`).\n  - `documentId`: ID of the page\n  - `userId`: ID of the person\n  - `socketId`: ID of that person's connection\n- **`doc:user:left`**: Someone closed the page. Sent to the others editing the page (`doc:<documentId>`).\n  - `documentId`: ID of the page\n  - `userId`: ID of the person\n  - `socketId`: ID of that person's connection\n\n#### Editing a sheet or document together\n\n- **`univer:sync`**: A Y.js sync message for the sheet or document. Sent to the connection that joined or synced, or the others editing it.\n  - `documentId`: ID of the sheet or document\n  - `message`: The Y.js sync message, as a list of bytes\n- **`univer:update`**: Someone changed the sheet or document. Sent to the others editing it (`univer:<documentId>`).\n  - `documentId`: ID of the sheet or document\n  - `update`: The Y.js update, as a list of bytes\n  - `userId`: ID of the person who changed it\n- **`univer:users`**: Who is editing it now. Sent to the connection that just joined.\n  - `documentId`: ID of the sheet or document\n  - `users`: Each person editing: socketId, userId, userName, color, and isCurrentUser for you\n- **`univer:user:joined`**: Someone opened it for editing. Sent to the others editing it (`univer:<documentId>`).\n  - `documentId`: ID of the sheet or document\n  - `userId`: ID of the person\n  - `userName`: Their name\n  - `socketId`: ID of that person's connection\n  - `color`: Their cursor colour\n- **`univer:user:left`**: Someone closed it or lost their connection. Sent to the others editing it (`univer:<documentId>`).\n  - `documentId`: ID of the sheet or document\n  - `userId`: ID of the person\n  - `socketId`: ID of that person's connection\n- **`univer:cursor`**: Someone's cursor moved. Sent to the others editing it (`univer:<documentId>`).\n  - `documentId`: ID of the sheet or document\n  - `userId`: ID of the person\n  - `userName`: Their name\n  - `socketId`: ID of that person's connection\n  - `cursor`: Where it is (position, selection, sheetId or slideId, row, column) and its color\n- **`univer:selection`**: Someone selected cells, slide elements or text. Sent to the others editing it (`univer:<documentId>`).\n  - `documentId`: ID of the sheet or document\n  - `userId`: ID of the person\n  - `userName`: Their name\n  - `socketId`: ID of that person's connection\n  - `color`: Their cursor colour\n  - `selection`: What is selected: sheetId or slideId with a range or ranges of cells, elementIds or a textRange\n- **`univer:operation`**: Someone ran an editor command, passed on as they sent it. Sent to the others editing it (`univer:<documentId>`).\n  - `documentId`: ID of the sheet or document\n  - `userId`: ID of the person\n  - `operation`: The command (id, type, params, timestamp)\n\n### Events you send\n\nEach takes an optional acknowledgement callback, called with nothing when it worked or with `{ code, message, action }`.\n\n#### Connection\n\n- **`ping`**: Check the connection; Spaces answers pong.\n  - No payload\n- **`room:join`**: Join a room to get its events. `space:<spaceId>` needs you to be able to see the space (its members, or anyone in the organisation when it is public); `pipeline-agent:<sessionId>` and `strategy-agent:<sessionId>` are for the chat's owner; `user:<userId>` is your own. Any other room is refused with code FORBIDDEN on the acknowledgement.\n  - `roomId`: The room, e.g. space:6650a1b2c3d4e5f6a7b8c9d0\n- **`room:leave`**: Stop getting a room's events.\n  - `roomId`: The room\n- **`data:subscribe`**: Subscribe to a data channel named after a room you may join. Nothing is sent on data channels today, so join the room instead.\n  - `channel`: A room name, e.g. `space:<spaceId>`\n  - `filters`: Optional; kept but not used\n- **`data:unsubscribe`**: End a data channel subscription.\n  - `channel`: The channel\n\n#### Comments\n\n- **`comment:typing`**: Tell the others in a space that you are typing a comment; Spaces passes it on as comment:typing with your name. Nothing is saved.\n  - `spaceId`: ID of the space whose room you joined\n  - `targetType`: What you are commenting on; task when left out\n  - `targetId`: ID of that item\n  - `isTyping`: true while typing, false when you stop\n\n#### Editing a wiki page together\n\n- **`doc:join`**: Start editing a page: you get doc:sync and the others get doc:user:joined.\n  - `documentId`: ID of the page\n- **`doc:leave`**: Stop editing a page.\n  - `documentId`: ID of the page\n- **`doc:sync`**: Send a Y.js sync message.\n  - `documentId`: ID of the page\n  - `message`: The Y.js sync message, as a list of bytes\n- **`doc:update`**: Send a change to the page.\n  - `documentId`: ID of the page\n  - `update`: The Y.js update, as a list of bytes\n- **`doc:awareness`**: Share your cursor and selection.\n  - `documentId`: ID of the page\n  - `awareness`: Your editor's awareness state\n\n#### Editing a sheet or document together\n\n- **`univer:join`**: Start editing a sheet or document: you get univer:sync and univer:users, the others univer:user:joined.\n  - `documentId`: ID of the sheet or document\n  - `documentType`: Optional, only used in the server's log\n- **`univer:leave`**: Stop editing it.\n  - `documentId`: ID of the sheet or document\n- **`univer:sync`**: Send a Y.js sync message.\n  - `documentId`: ID of the sheet or document\n  - `message`: The Y.js sync message, as a list of bytes\n- **`univer:update`**: Send a change.\n  - `documentId`: ID of the sheet or document\n  - `update`: The Y.js update, as a list of bytes\n- **`univer:cursor`**: Share your cursor.\n  - `documentId`: ID of the sheet or document\n  - `cursor`: Where it is (position, selection, sheetId or slideId, row, column)\n- **`univer:selection`**: Share your selection.\n  - `documentId`: ID of the sheet or document\n  - `selection`: sheetId or slideId with a range of cells, or elementIds\n- **`univer:operation`**: Pass an editor command on to the others.\n  - `documentId`: ID of the sheet or document\n  - `operation`: The command (id, type, params, timestamp)"},"tags":[{"name":"Spaces","description":"Spaces, their members, folders and items."},{"name":"Tasks","description":"Personal and space tasks, subtasks, assignees, followers and files."},{"name":"Docs","description":"Wiki collections and pages."},{"name":"Sheets & documents","description":"Spreadsheets, documents and slides inside a space."},{"name":"Calendar","description":"Events and time blocks."},{"name":"Files","description":"Drive files and download links."},{"name":"Comments","description":"Comments and comment threads."},{"name":"Messages & calls","description":"Emails, text messages and phone calls sent from your connected accounts."},{"name":"Pipelines","description":"Pipelines, stages and records."},{"name":"Strategies","description":"Strategies and goals."},{"name":"Search","description":"One search across spaces, tasks, pipelines and docs."},{"name":"Notifications","description":"A person's notifications."},{"name":"Saved views","description":"Saved filters and layouts."},{"name":"People","description":"People and the organisation."},{"name":"Activity","description":"Who did what, and when."},{"name":"Settings","description":"Organisation settings and connections to other systems."}],"paths":{"/org/currency":{"get":{"tags":["People"],"summary":"Get my organisation's currency","description":"Gets your organisation's currency as set in iNet Central when the organisation was created. Spreadsheets take their default currency symbol from it.\n\n**Permission:** `spaces.read` (View spaces).","operationId":"getOrgCurrency","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"object","properties":{"code":{"type":"string","description":"ISO 4217 code, e.g. UGX or KES"},"symbol":{"type":"string","description":"Symbol to show, e.g. USh"},"minorUnits":{"type":"integer","description":"Digits after the decimal point: 0 for UGX, 2 for KES"}},"description":"The currency set for your organisation in iNet Central"}}},"example":{"currency":{"code":"UGX","symbol":"USh","minorUnits":0}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"iNet Central could not tell the currency; currency is then null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.read"]}],"x-required-scopes":["spaces.read"]}},"/spaces":{"get":{"tags":["Spaces"],"summary":"List my spaces","description":"Lists every space you can open: the ones you are a member of and every public space in the organisation. Archived spaces are left out. All of them come in one reply, most recently changed first.\n\n**Permission:** `spaces.read` (View spaces).","operationId":"listSpaces","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"spaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; absent until the room is first made, e.g. when someone first opens the space's chat"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"description":"The spaces you can open, most recently changed first"}}},"example":{"spaces":[{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","role":"editor","joinedAt":"2026-09-03T10:15:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"chatId":"6a9f3d02b7e4a20f1c5d8e59","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-14T12:02:00.000Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.read"]}],"x-required-scopes":["spaces.read"]},"post":{"tags":["Spaces"],"summary":"Create a space","description":"Creates a space with you as its owner and only member, and answers with status 201. The space starts with one task list, called Tasks, in its sidebar.\n\n**Permission:** `spaces.create` (Create spaces).","operationId":"createSpace","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"Colour as a hex code. Defaults to #3b82f6","examples":["#3b82f6"]},"description":{"type":"string","description":"What the space is for","examples":["Invoices, budgets and the month-end close."]},"icon":{"type":"string","description":"An emoji or icon name","examples":["💼"]},"name":{"type":"string","description":"Name of the space","examples":["Finance"]},"visibility":{"type":"string","enum":["public","private"],"description":"private (the default): only members can open it. public: anyone in the organisation can open it","examples":["private"]}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"space":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"space":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z"}}}}},"400":{"description":"name is empty, or visibility is not public or private","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.create"]}],"x-required-scopes":["spaces.create"]}},"/spaces/{spaceId}":{"get":{"tags":["Spaces"],"summary":"Get a space","description":"Gets one space with its members. You can open it if you are a member or it is public; an archived space is not found.\n\n**Permission:** `spaces.read` (View spaces).","operationId":"getSpace","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"space":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; absent until the room is first made, e.g. when someone first opens the space's chat"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"space":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","role":"editor","joinedAt":"2026-09-03T10:15:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"chatId":"6a9f3d02b7e4a20f1c5d8e59","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-14T12:02:00.000Z"}}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID, it is archived, or it is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.read"]}],"x-required-scopes":["spaces.read"]},"put":{"tags":["Spaces"],"summary":"Update a space","description":"Changes a space's name, description, icon, colour or visibility; inputs you leave out stay as they are. Needs the editor role or higher in the space; an archived space cannot be changed. An empty name, colour or visibility is ignored, while an empty description or icon clears it.\n\n**Permission:** `spaces.update` (Update spaces).","operationId":"updateSpace","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"New colour as a hex code","examples":["#10b981"]},"description":{"type":"string","description":"New description; an empty text clears it","examples":["Invoices, budgets, payroll and the month-end close."]},"icon":{"type":"string","description":"New emoji or icon name; an empty text clears it","examples":["💼"]},"name":{"type":"string","description":"New name","examples":["Finance"]},"visibility":{"type":"string","enum":["public","private"],"description":"private: only members can open it. public: anyone in the organisation can open it","examples":["public"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"space":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; absent until the room is first made, e.g. when someone first opens the space's chat"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"space":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets, payroll and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","role":"editor","joinedAt":"2026-09-03T10:15:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"chatId":"6a9f3d02b7e4a20f1c5d8e59","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:00:00.000Z"}}}}},"400":{"description":"spaceId is not a valid ID, name is only spaces, or visibility is not public or private","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.update"]}],"x-required-scopes":["spaces.update"]},"delete":{"tags":["Spaces"],"summary":"Archive a space","description":"Archives a space together with its calendar events and tasks; it then no longer shows in lists. Only the space's owner may do it. Kazee meetings on those events are cancelled and the space's Kazee Chat room, if it has one, is archived, while its sidebar items, wikis, sheets and pipelines are left as they are. There is no call to bring an archived space back.\n\n**Permission:** `spaces.delete` (Delete spaces).","operationId":"archiveSpace","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"archivedEvents":{"type":"integer","description":"How many of the space's calendar events were archived with it"},"archivedTasks":{"type":"integer","description":"How many of the space's tasks were archived with it"}}},"example":{"success":true,"archivedEvents":3,"archivedTasks":42}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.delete"]}],"x-required-scopes":["spaces.delete"]}},"/spaces/{spaceId}/members":{"get":{"tags":["Spaces"],"summary":"List a space's members","description":"Lists a space's members with their name, email and role, sorted by name. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.members.read` (View space members).","operationId":"listSpaceMembers","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Most members to return. Defaults to 500; more than 1,000 is cut to 1,000","example":100},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Only members whose name or email contains this text, ignoring case. Members with no user record drop out","example":"brian"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"name":{"type":"string","description":"Full name; when it is not stored, first and last name, else the start of the email, else User"},"email":{"type":"string","description":"Email address"}},"description":"Their name and email; null when there is no user record for them. profilePicture is there too when their record has one"},"role":{"type":"string","description":"owner, editor, contributor or viewer"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"The members, sorted by name"},"count":{"type":"integer","description":"How many members this reply holds, after search and limit"}}},"example":{"members":[{"userId":"66f1b2c3d4e5f60718293a4b","user":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","name":"Amina Otieno","email":"amina.otieno@example.com"},"role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","user":{"id":"66f1b2c3d4e5f60718293a5c","firstName":"Brian","lastName":"Mwangi","name":"Brian Mwangi","email":"brian.mwangi@example.com"},"role":"editor","joinedAt":"2026-09-03T10:15:00.000Z"}],"count":2}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The space is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.members.read"]}],"x-required-scopes":["spaces.members.read"]},"post":{"tags":["Spaces"],"summary":"Add someone to a space","description":"Adds a person to a space, found by userId or by email, with the viewer role unless you give another. Needs the editor role or higher in the space, and the owner role to add another owner; not in an archived space. If the space has a Kazee Chat room, they are added to it too.\n\n**Permission:** `spaces.members.create` (Add space members).","operationId":"addSpaceMember","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email of the person to add, used when userId is not given. It is looked up in lower case, and the person must already have a user record in the organisation","examples":["grace.wanjiru@example.com"]},"role":{"type":"string","enum":["owner","editor","contributor","viewer"],"default":"viewer","description":"Their role in the space. Only an owner may give the owner role","examples":["viewer"]},"userId":{"type":"string","description":"User ID of the person to add; give this or email. Wins when both are given","examples":["66f1b2c3d4e5f60718293a6d"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"space":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; absent until the room is first made, e.g. when someone first opens the space's chat"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"space":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","role":"editor","joinedAt":"2026-09-03T10:15:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a6d","role":"viewer","joinedAt":"2026-10-15T09:30:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"chatId":"6a9f3d02b7e4a20f1c5d8e59","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:30:00.000Z"}}}}},"400":{"description":"Neither userId nor email was given, spaceId or userId is not a valid ID, the person is already a member, or role is not one of the four roles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space, or role is owner and you are not an owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No person with that userId or email, or no space with that ID (or it is archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.members.create"]}],"x-required-scopes":["spaces.members.create"]}},"/spaces/{spaceId}/apps":{"get":{"tags":["Spaces"],"summary":"List a space's apps","description":"Lists the apps added to a space: outside systems' app logins that may read, or also add, edit and move, the space's pipeline records as themselves. Apps are not members: they are never counted, assigned or notified. Open to the space's members, whatever their role.\n\n**Permission:** `spaces.members.read` (View space members).","operationId":"listSpaceApps","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success"},"apps":{"type":"array","items":{"type":"object","properties":{"integrationId":{"type":"string","description":"ID of the app login in Central"},"principalId":{"type":"string","description":"The app's own user ID; records it adds or changes show this user"},"name":{"type":"string","description":"The app login's name, as set in Central"},"role":{"type":"string","description":"viewer (reads pipeline records) or contributor (also adds, edits and moves them)"},"addedBy":{"type":"string","description":"User ID of the owner who added it; null if not known"},"addedAt":{"type":"string","format":"date-time","description":"When it was added; null if not known"}}},"description":"The apps added to the space, oldest first"}}},"example":{"success":true,"apps":[{"integrationId":"6ad1a0b1c2d3e4f5a6b7c801","principalId":"6ad1a0b1c2d3e4f5a6b7c802","name":"Zoho Books sync","role":"contributor","addedBy":"66f1b2c3d4e5f60718293a4b","addedAt":"2026-10-15T08:30:00.000Z"}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"App logins cannot call this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you are a member of, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.members.read"]}],"x-required-scopes":["spaces.members.read"]},"post":{"tags":["Spaces"],"summary":"Add an app to a space","description":"The space's owner adds an app login (from listAvailableSpaceApps) as viewer, which reads the space's pipeline records, or contributor, which also adds, edits and moves them. Central must allow what the role needs. Adding an app that is already there updates its role and name. The app gets its own user in Spaces, so records it changes show its name. A space can have at most 20 apps. Answers with all the space's apps.\n\n**Permission:** `spaces.members.create` (Add space members).","operationId":"addSpaceApp","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string","description":"ID of the app login in Central (integrationId from listAvailableSpaceApps)","examples":["6ad1a0b1c2d3e4f5a6b7c801"]},"role":{"type":"string","enum":["viewer","contributor"],"default":"contributor","description":"viewer (read records) or contributor (also add, edit and move them). Defaults to contributor","examples":["contributor"]}},"required":["integrationId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success"},"apps":{"type":"array","items":{"type":"object","properties":{"integrationId":{"type":"string","description":"ID of the app login in Central"},"principalId":{"type":"string","description":"The app's own user ID; records it adds or changes show this user"},"name":{"type":"string","description":"The app login's name, as set in Central"},"role":{"type":"string","description":"viewer (reads pipeline records) or contributor (also adds, edits and moves them)"},"addedBy":{"type":"string","description":"User ID of the owner who added it; null if not known"},"addedAt":{"type":"string","format":"date-time","description":"When it was added; null if not known"}}},"description":"The apps added to the space, oldest first"}}},"example":{"success":true,"apps":[{"integrationId":"6ad1a0b1c2d3e4f5a6b7c801","principalId":"6ad1a0b1c2d3e4f5a6b7c802","name":"Zoho Books sync","role":"contributor","addedBy":"66f1b2c3d4e5f60718293a4b","addedAt":"2026-10-15T08:30:00.000Z"}]}}}},"400":{"description":"spaceId or integrationId is not a valid ID, or role is not viewer or contributor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner, the caller is an app login, or Spaces is not installed for the organization in Central","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you are a member of (or it is archived), or no such app login for Spaces in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The space already has 20 apps; the app login is switched off in Central; Central does not let it read records, or only lets it read when role is contributor; or its ID belongs to a person in Spaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Central answered without the app's user ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Central could not be reached; try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.members.create"]}],"x-required-scopes":["spaces.members.create"]}},"/spaces/{spaceId}/apps/available":{"get":{"tags":["Spaces"],"summary":"List apps a space could add","description":"Lists the organization's app logins that are allowed into Spaces in Central, with the most each may be given in this space and whether it is already added. Only the space's owner may call it.\n\n**Permission:** `spaces.members.create` (Add space members).","operationId":"listAvailableSpaceApps","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success"},"apps":{"type":"array","items":{"type":"object","properties":{"integrationId":{"type":"string","description":"ID of the app login in Central; give it to addSpaceApp"},"name":{"type":"string","description":"Its name in Central"},"description":{"type":"string","description":"Its description in Central"},"enabled":{"type":"boolean","description":"false when it is switched off in Central; it cannot be added then"},"maxRole":{"type":"string","description":"The most it can be given here: contributor (read, add, edit and move records), viewer (read only), or null when Central lets it do nothing with records"},"added":{"type":"boolean","description":"true when it is already added to this space"}}},"description":"The organization's app logins that Central allows into Spaces"}}},"example":{"success":true,"apps":[{"integrationId":"6ad1a0b1c2d3e4f5a6b7c801","name":"Zoho Books sync","description":"Copies paid invoices into the Finance pipeline","enabled":true,"maxRole":"contributor","added":true},{"integrationId":"6ad1a0b1c2d3e4f5a6b7c803","name":"Website enquiries","description":"Reads leads to show their status on the website","enabled":true,"maxRole":"viewer","added":false}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner, the caller is an app login, or Spaces is not installed for the organization in Central","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you are a member of, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Central could not be reached; try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.members.create"]}],"x-required-scopes":["spaces.members.create"]}},"/spaces/{spaceId}/archived-stats":{"get":{"tags":["Spaces"],"summary":"Count a space's archived content","description":"Counts the archived wikis, wiki pages and tasks in a space, for example before deleting them for good. Open to the space's members, whatever their role; on a public space, people who are not members get 403.\n\n**Permission:** `spaces.read` (View spaces).","operationId":"getArchivedContentStats","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"archivedWikis":{"type":"integer","description":"Archived wikis in the space"},"archivedWikiPages":{"type":"integer","description":"Archived wiki pages in the space"},"archivedTasks":{"type":"integer","description":"Archived tasks in the space"},"totalArchived":{"type":"integer","description":"The three added up"}}},"example":{"archivedWikis":1,"archivedWikiPages":6,"archivedTasks":14,"totalArchived":21}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.read"]}],"x-required-scopes":["spaces.read"]}},"/tasks":{"get":{"tags":["Tasks"],"summary":"List my tasks","description":"Lists tasks assigned to you or created by you, a page at a time, most recently changed first. Inputs narrow it the way the My Tasks tabs, saved views and board columns do, and withCounts and withGroupCounts add totals.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"listTasks","parameters":[{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true lists only archived tasks; false (the default) only tasks that are not archived"},{"name":"column","in":"query","required":false,"schema":{"type":"string"},"description":"With groupBy: only the tasks in this one board column, so each column pages on its own. status: a status. priority: low, medium (also tasks with no priority), high or critical, counting only tasks not completed, or done for completed ones. space: a space ID, or __personal__ for tasks with no space. dueDate: inbox (not completed; no due date, or due after weekEnd), overdue, today, this_week (due from tomorrowStart up to weekEnd) or done; overdue, today and this_week need todayStart and tomorrowStart. A column it does not know is ignored","example":"in_progress"},{"name":"excludeSubtasks","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Hide subtasks, except those assigned to you"},{"name":"fieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Saved-view filters as a JSON object in a string: field name -> condition. Fields: status, priority, title, tags, assignees, creatorId, spaceId, taskListId, dueDate, createdAt, updatedAt; others are ignored. A condition is { operator, value } or { operator, values }, with operator is (the default), is_not, contains, greater_than, less_than, is_empty or is_not_empty; { from, to } instead matches an inclusive range. A plain value means \"is\", a list means \"is any of\"","example":"{\"priority\":{\"operator\":\"is\",\"values\":[\"high\",\"critical\"]},\"dueDate\":{\"from\":\"2026-10-01T00:00:00.000Z\",\"to\":\"2026-10-31T23:59:59.999Z\"}}"},{"name":"groupBy","in":"query","required":false,"schema":{"type":"string","enum":["status","priority","dueDate","space"]},"description":"Board grouping, for column and withGroupCounts; on its own it changes nothing","example":"status"},{"name":"includeCreated","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"true also lists tasks you created for other people; false lists only tasks assigned to you. Ignored when ownership is mine"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most tasks to return","example":50},{"name":"ownership","in":"query","required":false,"schema":{"type":"string","enum":["mine"]},"description":"mine: tasks assigned to you, plus tasks you created that nobody is assigned to (tasks you created for others drop out). Overrides includeCreated","example":"mine"},{"name":"priorities","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated priorities; a task matches if it has any of them","example":"critical,high"},{"name":"priority","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high","critical"]},"description":"Only tasks with this priority; ignored when priorities is given","example":"high"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Words to look for in the title or description; a task matches if it has any of them as a whole word","example":"invoice"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many tasks to skip, for paging","example":0},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["dueDate","createdAt","updatedAt","title","orderIndex"]},"description":"Sort by this field. Without it: earliest due first on the today, overdue and upcoming tabs, otherwise most recently changed first","example":"dueDate"},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"desc sorts from the largest or latest down; anything else sorts upwards","example":"asc"},{"name":"spaceId","in":"query","required":false,"schema":{"type":"string"},"description":"Only tasks in this space, or none for personal tasks (no space)","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","in_progress","completed","cancelled"]},"description":"Only tasks with this status; wins over the status a tab implies","example":"open"},{"name":"tab","in":"query","required":false,"schema":{"type":"string","enum":["active","today","overdue","upcoming","completed"]},"description":"A My Tasks tab. active: not completed (cancelled tasks included). completed: completed. overdue: not completed and due before todayStart. today: not completed and due before tomorrowStart or with no due date, so overdue tasks too. upcoming: not completed and due from tomorrowStart on or with no due date. A tab whose date input is missing is ignored","example":"today"},{"name":"todayStart","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the user's today in their time zone, as an exact time. Needed by the overdue tab and count and by the dueDate board columns","example":"2026-10-14T21:00:00.000Z"},{"name":"tomorrowStart","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the user's tomorrow in their time zone. Needed by the today and upcoming tabs and counts and by the dueDate board columns","example":"2026-10-15T21:00:00.000Z"},{"name":"weekEnd","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Last moment of the user's week, in their time zone. Used only when groupBy is dueDate: this_week runs up to it and inbox takes tasks due after it","example":"2026-10-18T20:59:59.999Z"},{"name":"withCounts","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Also return counts: totals for each My Tasks tab"},{"name":"withGroupCounts","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"With groupBy: also return groupCounts, the number of tasks in each column with the same filters"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"number","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"type":"string","description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"subtaskCount":{"type":"integer","description":"How many subtasks it has, not counting archived ones (list calls only)"},"subtaskCompletedCount":{"type":"integer","description":"How many of those are completed (list calls only)"},"parentTask":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"description":"Only on a subtask: its parent's id and title"}}}},"total":{"type":"integer","description":"How many tasks match the filters, over all pages"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Most items in this page"},"skip":{"type":"integer","description":"How many items were skipped before this page"},"hasMore":{"type":"boolean","description":"Whether another page follows"}}},"counts":{"type":"object","properties":{"active":{"type":"integer","description":"Tasks not completed (cancelled ones count here)"},"today":{"type":"integer","description":"Not completed and due before tomorrowStart, or with no due date; 0 without tomorrowStart"},"overdue":{"type":"integer","description":"Not completed and due before todayStart; 0 without todayStart"},"upcoming":{"type":"integer","description":"Not completed and due from tomorrowStart on, or with no due date; 0 without tomorrowStart"},"completed":{"type":"integer","description":"Completed tasks"},"archived":{"type":"integer","description":"Archived tasks"}},"description":"Only when withCounts is true: totals for the My Tasks tabs. They always count tasks assigned to you or created by you with nobody assigned, and apply no other input except todayStart, tomorrowStart and excludeSubtasks. Archived tasks count only under archived"},"groupCounts":{"type":"object","properties":{"open":{"type":"integer"},"in_progress":{"type":"integer"},"completed":{"type":"integer"},"cancelled":{"type":"integer"}},"description":"Only when withGroupCounts is true and groupBy is set: how many tasks match the filters in each board column (column itself is not applied). Keys: for status, each status; for priority, each priority, with tasks that have none under medium and completed tasks counted too (there is no done key); for space, each space ID, or __personal__; for dueDate, always inbox, overdue, today, this_week and done. Apart from dueDate, a column with no tasks has no key"}}},"example":{"tasks":[{"id":"6ad0a051d5c26de56de949b2","title":"Attach the signed delivery note","description":"Scan the delivery note the client signed.","status":"open","priority":"medium","dueDate":"2026-10-17T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a5c","assignees":["66f1b2c3d4e5f60718293a4b"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a0b4d5c26de56de949d3","estimatedHours":0.5,"actualHours":0.25,"isTimeBlocked":false,"parentTaskId":"6ad0a044d5c26de56de949a8","orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"delivery-note-signed-7b2e4f90.pdf","originalName":"delivery-note-signed.pdf","fileSize":96256,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a051d5c26de56de949b2/7b2e4f90-1c3a-4d5e-8f60-2a9b7c4d3e18-delivery-note-signed.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T10:05:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:30:00.000Z","updatedAt":"2026-10-15T10:05:00.000Z","subtaskCount":0,"subtaskCompletedCount":0,"parentTask":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice"}},{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","subtaskCount":2,"subtaskCompletedCount":1}],"total":121,"pagination":{"limit":50,"skip":0,"hasMore":true},"counts":{"active":24,"today":6,"overdue":2,"upcoming":19,"completed":97,"archived":7},"groupCounts":{"open":14,"in_progress":8,"completed":97,"cancelled":2}}}}},"400":{"description":"spaceId is not a valid ID (or none), or fieldFilters gives assignees, creatorId, spaceId or taskListId a value that is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]},"post":{"tags":["Tasks"],"summary":"Create a task","description":"Creates a task, personal or in a space, and answers with status 201. In a space you need the contributor role or higher, and people watching the space see the task appear live. You and every assignee start following it.\n\n**Permission:** `spaces.tasks.create` (Create tasks).","operationId":"createTask","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people to assign (a JSON array in a string also works). For a space task, each must be able to see the space","examples":[["66f1b2c3d4e5f60718293a5c"]]},"description":{"type":"string","description":"Longer notes, up to 50,000 characters","examples":["Email the invoice to the client with the delivery note."]},"dueDate":{"type":"string","format":"date-time","description":"When it is due","examples":["2026-10-20T09:00:00.000Z"]},"parentTaskId":{"type":"string","description":"Parent task, to make this a subtask. The subtask does not take the parent's space or list, so pass spaceId (and taskListId) too","examples":["6ad0a044d5c26de56de949a8"]},"priority":{"type":"string","enum":["low","medium","high","critical"],"default":"medium","description":"How urgent it is","examples":["high"]},"spaceId":{"type":"string","description":"Space to put it in; leave out for a personal task","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"tags":{"type":"array","items":{"type":"string"},"description":"Labels: at most 50, each up to 100 characters (a JSON array in a string also works)","examples":[["billing"]]},"taskListId":{"type":"string","description":"Task list of the space to put it in. Without it, the task goes in the space's first list (made if the space has none). Ignored for a personal task","examples":["6a9f3c5eb7e4a20f1c5d8e47"]},"title":{"type":"string","description":"What needs doing, up to 500 characters","examples":["Send the October invoice"]}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","description":"Files attached to the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"open","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"isTimeBlocked":false,"parentTaskId":null,"orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[],"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z"}}}}},"400":{"description":"A text is too long, priority is unknown, an ID or dueDate is not valid, assignees or tags is not a list, an assignee does not exist or cannot see the space, there are over 50 tags or a tag over 100 characters, or taskListId is not a task list of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you can see, or the parent task does not exist or is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.create"]}],"x-required-scopes":["spaces.tasks.create"]}},"/tasks/by-planning-state":{"get":{"tags":["Tasks"],"summary":"List my tasks grouped by due date","description":"Lists every task you are assigned to or created that is not archived, subtasks included, grouped by due date and most recently changed first. Today and this week (which ends on Sunday) follow the server's clock, not your time zone. There is no paging: all of them come back at once.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"listTasksByPlanningState","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"inbox":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"description":"Not completed or cancelled, with no due date or due after this week"},"overdue":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","description":"Labels on the task"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"description":"Not completed or cancelled, and due before today"},"today":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","description":"Labels on the task"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"description":"Not completed or cancelled, and due today"},"thisWeek":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","description":"Labels on the task"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"description":"Not completed or cancelled, and due after today up to the end of Sunday"},"completed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"completedAt":{"type":"string","format":"date-time","description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","description":"Labels on the task"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"description":"Completed or cancelled"}}},"example":{"inbox":[{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}],"overdue":[{"id":"6ad0a071d5c26de56de949c1","title":"Reply to the auditor's questions","status":"open","priority":"high","dueDate":"2026-10-13T09:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":[],"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}],"today":[{"id":"6ad0a07ed5c26de56de949c7","title":"Call the courier about the late parcel","status":"open","priority":"high","dueDate":"2026-10-15T12:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":[],"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}],"thisWeek":[{"id":"6ad0a08bd5c26de56de949cd","title":"Book the venue for the team lunch","status":"open","priority":"medium","dueDate":"2026-10-17T09:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":[],"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}],"completed":[{"id":"6ad0a098d5c26de56de949d1","title":"Send the September invoice","status":"completed","priority":"high","dueDate":"2026-09-30T09:00:00.000Z","completedAt":"2026-09-30T14:10:00.000Z","creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":[],"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]}},"/tasks/{taskId}/subtasks":{"get":{"tags":["Tasks"],"summary":"List subtasks","description":"Lists a task's subtasks that are not archived, by position and then newest first. Each subtask's assignees come back as people (id, name, email) rather than IDs. Open to the parent task's creator, its assignees and anyone who can see its space.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"listSubtasks","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the parent task","example":"6ad0a044d5c26de56de949a8"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most subtasks to return","example":50},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many subtasks to skip, for paging","example":0}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Person ID"}}},"description":"The people it is assigned to, as people rather than IDs"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"number","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"type":"string","description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}},"total":{"type":"integer","description":"How many subtasks it has that are not archived"}}},"example":{"tasks":[{"id":"6ad0a051d5c26de56de949b2","title":"Attach the signed delivery note","description":"Scan the delivery note the client signed.","status":"open","priority":"medium","dueDate":"2026-10-17T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a5c","assignees":[{"firstName":"Amina","lastName":"Wanjiru","email":"amina.wanjiru@example.com","id":"66f1b2c3d4e5f60718293a4b"}],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","tags":["billing"],"chatId":"6ad0a0b4d5c26de56de949d3","estimatedHours":0.5,"actualHours":0.25,"isTimeBlocked":false,"parentTaskId":"6ad0a044d5c26de56de949a8","orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"delivery-note-signed-7b2e4f90.pdf","originalName":"delivery-note-signed.pdf","fileSize":96256,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a051d5c26de56de949b2/7b2e4f90-1c3a-4d5e-8f60-2a9b7c4d3e18-delivery-note-signed.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T10:05:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:30:00.000Z","updatedAt":"2026-10-15T10:05:00.000Z"}],"total":2}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You did not create the parent task, are not assigned to it and cannot see its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]}},"/tasks/{taskId}":{"get":{"tags":["Tasks"],"summary":"Get a task","description":"Gets one task, archived or not, with how many subtasks it has and, for a subtask, its parent's title. You can open it if you created it, are assigned to it, follow it, or can see its space (as a member, or anyone for a public space).\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"getTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a051d5c26de56de949b2"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"number","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"type":"string","description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"subtaskCount":{"type":"integer","description":"How many subtasks it has, not counting archived ones"},"parentTask":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"description":"Only on a subtask: its parent's id and title"}}}}},"example":{"task":{"id":"6ad0a051d5c26de56de949b2","title":"Attach the signed delivery note","description":"Scan the delivery note the client signed.","status":"open","priority":"medium","dueDate":"2026-10-17T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a5c","assignees":["66f1b2c3d4e5f60718293a4b"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a0b4d5c26de56de949d3","estimatedHours":0.5,"actualHours":0.25,"isTimeBlocked":false,"parentTaskId":"6ad0a044d5c26de56de949a8","orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"delivery-note-signed-7b2e4f90.pdf","originalName":"delivery-note-signed.pdf","fileSize":96256,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a051d5c26de56de949b2/7b2e4f90-1c3a-4d5e-8f60-2a9b7c4d3e18-delivery-note-signed.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T10:05:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:30:00.000Z","updatedAt":"2026-10-15T10:05:00.000Z","subtaskCount":0,"parentTask":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice"}}}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You did not create it, are not assigned to it, do not follow it and cannot see its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]},"put":{"tags":["Tasks"],"summary":"Update a task","description":"Changes a task's details; only the inputs you send change, and status and assignees have their own calls. Its creator, its assignees and members of its space with the contributor role or higher can do this. People watching the space see the change live.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"updateTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualHours":{"type":"number","description":"Effort spent so far in hours, 0 or more; null clears it","examples":[1.5]},"description":{"type":"string","description":"New notes, up to 50,000 characters; an empty string clears them","examples":["Email the invoice to the client with the delivery note."]},"dueDate":{"type":"string","format":"date-time","description":"New due date; null or an empty string clears it. If the task has a planner slot on another day and you send no timeBlockStart or timeBlockEnd, the slot moves to the new day at the same time","examples":["2026-10-20T09:00:00.000Z"]},"estimatedHours":{"type":"number","description":"Expected effort in hours, 0 or more; null clears it","examples":[2]},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner","examples":[true]},"parentTaskId":{"type":"string","description":"Parent task, to make it a subtask; null or an empty string makes it a top-level task again. A task cannot become its own parent or a subtask of its own subtasks"},"priority":{"type":"string","enum":["low","medium","high","critical"],"description":"New priority","examples":["critical"]},"tags":{"type":"array","items":{"type":"string"},"description":"New labels, replacing the old ones: at most 50, each up to 100 characters (a JSON array in a string also works). null, an empty string or [] clears them","examples":[["billing","urgent"]]},"taskListId":{"type":"string","description":"Task list to move it to, together with its subtasks. For a space task it must be a list of that space, and null or an empty string puts it back in the space's first list; for a personal task null or an empty string clears it","examples":["6a9f3c5eb7e4a20f1c5d8e47"]},"timeBlockEnd":{"type":"string","format":"date-time","description":"End of its planner slot; null or an empty string clears it","examples":["2026-10-16T08:30:00.000Z"]},"timeBlockStart":{"type":"string","format":"date-time","description":"Start of its planner slot; null or an empty string clears it","examples":["2026-10-16T07:00:00.000Z"]},"title":{"type":"string","description":"New title, up to 500 characters; an empty one is ignored","examples":["Send the October invoice"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"timeBlockStart":{"type":"string","format":"date-time","description":"Start of its planner slot, once it has one"},"timeBlockEnd":{"type":"string","format":"date-time","description":"End of its planner slot"},"timeBlockDuration":{"type":"integer","description":"Length of the slot in minutes; null unless it has both a start and an end"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":true,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","timeBlockStart":"2026-10-16T07:00:00.000Z","timeBlockEnd":"2026-10-16T08:30:00.000Z","timeBlockDuration":90}}}}},"400":{"description":"An ID is not valid, a text is too long, priority is unknown, hours are negative or not numbers, tags are not a list of short labels, taskListId is not a list of the task's space, or parentTaskId would make the task its own parent or ancestor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not its creator or an assignee, nor a member of its space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]},"delete":{"tags":["Tasks"],"summary":"Archive a task","description":"Archives a task and its subtasks; they drop out of task lists, and restoreTask brings them back. Only organisation admins (the Admin or SuperAdmin role) can archive; others should mark the task completed or cancelled instead. People watching the space see it disappear live.\n\n**Permission:** `spaces.tasks.delete` (Delete tasks).","operationId":"archiveTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task to archive","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin, or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is already archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.delete"]}],"x-required-scopes":["spaces.tasks.delete"]}},"/tasks/{taskId}/comments":{"get":{"tags":["Tasks"],"summary":"Get a task's comment chat","description":"Returns the ID of the task's chat room in Kazee Chat, and creates the room on the first call; its messages are then read and sent through Kazee Chat, not Spaces. For the comments shown on a task in Spaces, use the comment calls instead: GET /comments/task/{taskId} (listComments) lists them and POST /comments with targetType task (createComment) posts one. A new room holds the task's creator, its assignees and, for a task in a space, the space's members. Open to the task's creator, its assignees and anyone who can see its space.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"getTaskCommentChat","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat"},"taskId":{"type":"string","description":"The task's ID, as you sent it"},"taskTitle":{"type":"string","description":"The task's title"}}},"example":{"chatId":"6ad0a09ed5c26de56de949c0","taskId":"6ad0a044d5c26de56de949a8","taskTitle":"Send the October invoice"}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator, its assignees and people who can see its space (its members, or anyone if it is public) can open its chat. Can also mean the chat has yet to be made and you signed in with a Kazee sign-in token, which Kazee Chat cannot take yet (sign in with your password)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]}},"/tasks/{taskId}/attachments/{fileKey}":{"get":{"tags":["Tasks"],"summary":"Get a download link for a file","description":"Returns a download link for a file attached to the task. The link works without sign-in for one hour, and is to the organisation's own file store, or to the older shared one when the file is only there. Open to the task's creator, its assignees and anyone who can see its space.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"getTaskAttachmentUrl","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"},{"name":"fileKey","in":"path","required":true,"schema":{"type":"string"},"description":"Key of the file: its minioKey in the task's attachments. The key contains slashes, so URL-encode it (each / as %2F)","example":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Download link for the file; anyone who has it can download the file until it expires"},"expiresIn":{"type":"integer","description":"Seconds until the link stops working (always 3600, one hour)"}}},"example":{"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T092500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=8c2f4e1a9b7d3c5e6f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6","expiresIn":3600}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator, its assignees and people who can see its space (its members, or anyone if it is public) can get a link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID (or it is archived), or the task has no file with that key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The file is not in the organisation's own file store, and the older shared store is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]},"delete":{"tags":["Tasks"],"summary":"Delete a file from a task","description":"Removes a file from the task and deletes the stored file for good, from the organisation's own file store, or from the older shared one when the file is only there. Open to the task's creator, its assignees and members of its space with the editor or owner role.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"deleteTaskAttachment","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"},{"name":"fileKey","in":"path","required":true,"schema":{"type":"string"},"description":"Key of the file: its minioKey in the task's attachments. The key contains slashes, so URL-encode it (each / as %2F)","example":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator, its assignees and editors or owners of its space can delete its files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID (or it is archived), or the task has no file with that key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The file is not in the organisation's own file store and the older shared store is not available right now, so the file was left as it was","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/followers":{"get":{"tags":["Tasks"],"summary":"List a task's followers","description":"Lists the IDs of everyone who follows a task. Open to the task's creator, its assignees and anyone who can see its space.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"listTaskFollowers","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"followers":{"type":"array","items":{"type":"string"},"description":"IDs of the people who follow the task"},"count":{"type":"integer","description":"How many people follow it"}}},"example":{"followers":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"],"count":2}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator, its assignees and people who can see its space (its members, or anyone if it is public) can list its followers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]}},"/tasks/{taskId}/following":{"get":{"tags":["Tasks"],"summary":"Check whether I follow a task","description":"Tells you whether you follow a task. It does not look the task up or check that you can see it, so an unknown task ID answers false.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"getTaskFollowStatus","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"following":{"type":"boolean","description":"Whether you follow the task"}}},"example":{"following":true}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]}},"/spaces/{spaceId}/tasks":{"get":{"tags":["Tasks"],"summary":"List a space's tasks","description":"Lists the tasks in a space, a page at a time, by position and then most recently changed. Anyone who can see the space can list them: its members, or everyone for a public space. If the space has no task list yet, this creates one named Tasks.\n\n**Permission:** `spaces.tasks.read` (View tasks).","operationId":"listSpaceTasks","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true lists only archived tasks; false (the default) only tasks that are not archived"},{"name":"assigneeId","in":"query","required":false,"schema":{"type":"string"},"description":"Only tasks assigned to this person","example":"66f1b2c3d4e5f60718293a5c"},{"name":"column","in":"query","required":false,"schema":{"type":"string"},"description":"With groupBy: only the tasks in this one board column, so each column pages on its own. status: a status. priority: low, medium (also tasks with no priority), high or critical, counting only tasks not completed, or done for completed ones. space: a space ID, or __personal__ for tasks with no space. dueDate: inbox (not completed; no due date, or due after weekEnd), overdue, today, this_week (due from tomorrowStart up to weekEnd) or done; overdue, today and this_week need todayStart and tomorrowStart. A column it does not know is ignored","example":"in_progress"},{"name":"excludeSubtasks","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Hide all subtasks"},{"name":"fieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Saved-view filters as a JSON object in a string: field name -> condition. Fields: status, priority, title, tags, assignees, creatorId, spaceId, taskListId, dueDate, createdAt, updatedAt; others are ignored. A condition is { operator, value } or { operator, values }, with operator is (the default), is_not, contains, greater_than, less_than, is_empty or is_not_empty; { from, to } instead matches an inclusive range. A plain value means \"is\", a list means \"is any of\"","example":"{\"priority\":{\"operator\":\"is\",\"values\":[\"high\",\"critical\"]},\"dueDate\":{\"from\":\"2026-10-01T00:00:00.000Z\",\"to\":\"2026-10-31T23:59:59.999Z\"}}"},{"name":"groupBy","in":"query","required":false,"schema":{"type":"string","enum":["status","priority","dueDate","space"]},"description":"Board grouping, for column and withGroupCounts; on its own it changes nothing","example":"status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most tasks to return","example":50},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Words to look for in the title or description; a task matches if it has any of them as a whole word","example":"invoice"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many tasks to skip, for paging","example":0},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["dueDate","createdAt","updatedAt","title","orderIndex"]},"description":"Sort by this field. Without it: by position (orderIndex), then most recently changed first","example":"dueDate"},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"desc sorts from the largest or latest down; anything else sorts upwards","example":"asc"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","in_progress","completed","cancelled"]},"description":"Only tasks with this status","example":"open"},{"name":"taskListId","in":"query","required":false,"schema":{"type":"string"},"description":"Only tasks in this task list. For the space's first list (defaultTaskListId) this includes tasks with no list","example":"6a9f3c5eb7e4a20f1c5d8e47"},{"name":"todayStart","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the user's today in their time zone, as an exact time. Used only by the dueDate board columns","example":"2026-10-14T21:00:00.000Z"},{"name":"tomorrowStart","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the user's tomorrow in their time zone. Used only by the dueDate board columns","example":"2026-10-15T21:00:00.000Z"},{"name":"weekEnd","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Last moment of the user's week, in their time zone. Used only when groupBy is dueDate: this_week runs up to it and inbox takes tasks due after it","example":"2026-10-18T20:59:59.999Z"},{"name":"withGroupCounts","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"With groupBy: also return groupCounts, the number of tasks in each column with the same filters"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"subtaskCount":{"type":"integer","description":"How many subtasks it has, not counting archived ones (list calls only)"},"subtaskCompletedCount":{"type":"integer","description":"How many of those are completed (list calls only)"}}}},"total":{"type":"integer","description":"How many tasks match the filters, over all pages"},"defaultTaskListId":{"type":"string","description":"ID of the space's first task list (made by this call if the space had none); tasks with no list belong to it"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Most items in this page"},"skip":{"type":"integer","description":"How many items were skipped before this page"},"hasMore":{"type":"boolean","description":"Whether another page follows"}}},"groupCounts":{"type":"object","properties":{"open":{"type":"integer"},"in_progress":{"type":"integer"},"completed":{"type":"integer"},"cancelled":{"type":"integer"}},"description":"Only when withGroupCounts is true and groupBy is set: how many tasks match the filters in each board column (column itself is not applied). Keys: for status, each status; for priority, each priority, with tasks that have none under medium and completed tasks counted too (there is no done key); for space, each space ID, or __personal__; for dueDate, always inbox, overdue, today, this_week and done. Apart from dueDate, a column with no tasks has no key"}}},"example":{"tasks":[{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","subtaskCount":2,"subtaskCompletedCount":1}],"total":73,"defaultTaskListId":"6a9f3c5eb7e4a20f1c5d8e47","pagination":{"limit":50,"skip":0,"hasMore":true},"groupCounts":{"open":21,"in_progress":9,"completed":40,"cancelled":3}}}}},"400":{"description":"spaceId, assigneeId or taskListId is not a valid ID, or fieldFilters gives assignees, creatorId, spaceId or taskListId a value that is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID, it is archived, or it is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.read"]}],"x-required-scopes":["spaces.tasks.read"]}},"/spaces/{spaceId}/pipelines":{"get":{"tags":["Pipelines"],"summary":"List a space's pipelines","description":"Lists the pipelines in a space, each with its whole setup (stages, transitions, custom fields, automations, settings) but no records. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"listPipelines","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipelines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}}},"description":"The space's pipelines that are not archived, most recently changed first"}}},"example":{"pipelines":[{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID that you can see (you are not a member and it is not public), or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]},"post":{"tags":["Pipelines"],"summary":"Create a pipeline","description":"Creates a pipeline in a space and answers with status 201. Needs the editor or owner role in the space. Stages, custom fields and settings can be given now or added later; it starts with no transitions, automations or custom buttons.\n\n**Permission:** `spaces.pipelines.create` (Create pipelines).","operationId":"createPipeline","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conditionFields":{"type":"array","items":{"type":"object"},"description":"Older list of fields conditions can use, each { path, label, type, options }; kept as config.conditionFields unless config has its own. A JSON array in a string also works","examples":[[{"path":"amount","label":"Amount","type":"number"}]]},"config":{"type":"object","description":"Board settings, shaped like the reply's config; keys left out take their defaults. A JSON object in a string also works","examples":[{"defaultStageId":"received","requireTransitions":true}]},"description":{"type":"string","description":"What the pipeline is for","examples":["Bills from suppliers, from arrival to payment."]},"fieldDefinitions":{"type":"array","items":{"type":"object"},"description":"Custom fields, each shaped like the reply's fieldDefinitions items: id, name, label and fieldType are required. A JSON array in a string also works","examples":[[{"id":"supplier","name":"supplier","label":"Supplier","fieldType":"text","isRequired":true},{"id":"amount","name":"amount","label":"Amount","fieldType":"currency","currencyCode":"KES"}]]},"name":{"type":"string","description":"Pipeline name","examples":["Supplier invoices"]},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"}}},"description":"Its stages, in board order. Each needs an id you choose (e.g. received) and a name; color defaults to grey (#6b7280), orderNum to its place in the list, isDefault to false. A JSON array in a string also works","examples":[[{"id":"received","name":"Received","color":"#6b7280","isDefault":true},{"id":"approved","name":"Approved","color":"#3b82f6"},{"id":"paid","name":"Paid","color":"#22c55e"}]]},"templateId":{"type":"string","description":"ID of the starter template the pipeline was made from, kept on it as templateId","examples":["crm-sales"]}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"}}},"description":"Its stages (the board columns); sort by orderNum for board order. Keys some items also have: positionX (where the stage sits across the workflow editor; absent until positions are saved); positionY (where the stage sits down the workflow editor; absent until positions are saved)"},"transitions":{"type":"array","description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings. It may also have: cardSubtitleField (ID of the custom field shown under the card title, if any); cardBadgeField (ID of the custom field shown as the card badge, if any)"},"enabledEmailAccountIds":{"type":"array","description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The new pipeline"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false}],"transitions":[],"customButtons":[],"automations":[],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"defaultStageId":"received","requireTransitions":true,"enableSLA":false,"stageSLAs":[],"stageRollups":[],"conditionFields":[]},"enabledEmailAccountIds":[],"emailEnabled":true,"smsEnabled":true,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-02T07:30:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"spaceId is not a valid ID, a list or object input is not valid JSON, or the pipeline fails the model's checks (e.g. a stage with no id or name, an unknown fieldType)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.create"]}],"x-required-scopes":["spaces.pipelines.create"]}},"/pipelines/schema":{"get":{"tags":["Pipelines"],"summary":"Get what a blueprint can contain","description":"Lists what pipelines are built from: custom field types, action types with their config keys, condition operators, automation triggers, column total functions, the functions custom code can call, and template placeholders. It answers the same for everyone and reads no data.\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"getPipelineSchema","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"object","properties":{"fieldTypes":{"type":"array","items":{"type":"string"},"description":"Custom field types"},"actionTypes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Action type"},"description":{"type":"string","description":"What it does"},"configSchema":{"type":"object","properties":{"actionType":{"type":"string"},"description":{"type":"string"},"requiredKeys":{"type":"array"},"optionalKeys":{"type":"array","items":{"type":"string"}},"configShape":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}}},"description":"Its config: requiredKeys, optionalKeys, and configShape (each key's meaning)"}}},"description":"Action types transitions, automations and custom buttons can run"},"conditionOperators":{"type":"array","items":{"type":"string"},"description":"Operators a condition can use"},"automationTriggers":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Event name"},"description":{"type":"string","description":"When it happens"}}},"description":"Events an automation can run on; some also have configKeys, the keys trigger.config takes to narrow them"},"rollupFunctions":{"type":"array","items":{"type":"string"},"description":"Functions a column total can use"},"sandboxApiFunctions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"signature":{"type":"string"},"description":{"type":"string"}}},"description":"Functions custom code can call: name, signature, description"},"templateVariables":{"type":"array","items":{"type":"string"},"description":"Placeholders message templates can use"},"stageMigrationModes":{"type":"array","items":{"type":"object","properties":{"mode":{"type":"string"},"description":{"type":"string"}}},"description":"How the Pipeline AI chat can deal with records on stages it removes: mode and description"}},"description":"The building blocks of a pipeline; the same for everyone"}}},"example":{"schema":{"fieldTypes":["text","textarea","number","date","datetime","select","multiselect","checkbox","email","phone","url","currency","user","multiuser","rating","color","attachment"],"actionTypes":[{"type":"email","description":"Send templated email notification to users","configSchema":{"actionType":"email","description":"Send email notification","requiredKeys":[],"optionalKeys":["to","subject","template"],"configShape":{"to":"'assignees' | 'creator' | string[] (user IDs) — who the email goes to; an action without it emails the record's assignees.","subject":"string — email subject. Supports {{record.title}}, {{pipeline.name}}, etc.","template":"string — email body template. Supports {{record.title}}, {{record.stageName}}, {{pipeline.name}}, {{transition.name}}"}}},{"type":"webhook","description":"Send HTTP webhook with record/pipeline data","configSchema":{"actionType":"webhook","description":"Send HTTP webhook","requiredKeys":["url"],"optionalKeys":["method","headers","includeFields"],"configShape":{"url":"string — webhook URL (required)","method":"'POST' | 'PUT' | 'PATCH' (default: POST)","headers":"Record<string, string> — custom HTTP headers","includeFields":"boolean — include record.fieldValues in payload"}}},{"type":"assign","description":"Auto-assign users to the record","configSchema":{"actionType":"assign","description":"Auto-assign users","requiredKeys":[],"optionalKeys":["strategy","userIds","userPool","fieldId","fieldMappings","fallbackUserId","replaceExisting"],"configShape":{"strategy":"'static' | 'round_robin' | 'load_balanced' | 'field_based' (default: static)","userIds":"string[] — user IDs for static strategy","userPool":"string[] — user IDs for round_robin or load_balanced","fieldId":"string — field ID for field_based strategy","fieldMappings":"Array<{ fieldValue: string, userIds: string[] }> — for field_based","fallbackUserId":"string — fallback for field_based when no mapping matches","replaceExisting":"boolean — replace existing assignees (default: false, adds to existing)"}}},{"type":"update_field","description":"Auto-set a field value on the record","configSchema":{"actionType":"update_field","description":"Update record field value","requiredKeys":["fieldId"],"optionalKeys":["value","useCurrentDate"],"configShape":{"fieldId":"string — field definition ID (required)","value":"any — the value to set","useCurrentDate":"boolean — set to current ISO date instead of value"}}},{"type":"create_task","description":"Auto-create a linked task in the same space","configSchema":{"actionType":"create_task","description":"Create linked task","requiredKeys":["title"],"optionalKeys":["assignToRecordAssignees","priority","tags"],"configShape":{"title":"string — task title. Supports {{record.title}}, {{pipeline.name}} (required)","assignToRecordAssignees":"boolean — assign task to the record's assignees","priority":"'low' | 'medium' | 'high' | 'critical' (default: medium)","tags":"string[] — tags for the task"}}},{"type":"notify","description":"Send in-app notification to users","configSchema":{"actionType":"notify","description":"In-app notification","requiredKeys":[],"optionalKeys":["to","message"],"configShape":{"to":"'assignees' | 'creator' | 'followers' | string[] (user IDs)","message":"string — notification message. Supports {{record.title}}, {{record.stageName}}, {{pipeline.name}}, {{transition.name}}"}}},{"type":"kazee_chat","description":"Send a message to a Kazee Chat room or user DMs","configSchema":{"actionType":"kazee_chat","description":"Kazee Chat message","requiredKeys":["to"],"optionalKeys":["chatId","message"],"configShape":{"to":"'chat' | 'assignees' | 'creator' (required)","chatId":"string — required when to='chat'. The chat room ID.","message":"string — message template. Supports {{record.title}}, {{record.stageName}}, {{pipeline.name}}, {{transition.name}}"}}},{"type":"code","description":"Execute custom TypeScript/JavaScript in an isolated sandbox","configSchema":{"actionType":"code","description":"Custom code execution","requiredKeys":["sourceCode"],"optionalKeys":["timeout","memoryLimit","functionId"],"configShape":{"sourceCode":"string — TypeScript/JavaScript source code (required unless functionId is supplied)","functionId":"string — id of a saved reusable code function in the org's function library. When set, the executor loads that function's compiled code at run time and sourceCode is ignored.","timeout":"number — execution timeout in ms (default: 5000, max: 30000)","memoryLimit":"number — memory limit in MB (default: 64, max: 128)"}}},{"type":"sms","description":"Send a templated SMS through the org's configured SMS provider (or the CELCOM_* env fallback) when the transition / automation fires.","configSchema":{"actionType":"sms","description":"Send SMS","requiredKeys":["to","message"],"optionalKeys":["recordPhoneFieldId","toCustom"],"configShape":{"to":"'assignees' | 'creator' | 'record_field' | 'custom' — who the SMS goes to. Blueprints must set it; an action saved without it texts the record's assignees.","recordPhoneFieldId":"string — required when to='record_field'. Field id whose value holds the recipient's phone number.","toCustom":"string — required when to='custom'. Comma-separated list of E.164 numbers.","message":"string — SMS body. Supports {{record.title}}, {{record.stageName}}, {{record.priority}}, {{pipeline.name}}, {{transition.name}}, {{user.name}}, {{record.fields.<fieldId>}}."}}}],"conditionOperators":["eq","neq","gt","gte","lt","lte","contains","notContains","startsWith","endsWith","exists","notExists","in","notIn","isEmpty","isNotEmpty"],"automationTriggers":[{"event":"record_created","description":"When a new record is created"},{"event":"record_updated","description":"When a record is updated"},{"event":"field_changed","description":"When a specific field value changes","configKeys":["fieldId"]},{"event":"stage_entered","description":"When a record enters a specific stage","configKeys":["stageId"]},{"event":"stage_exited","description":"When a record leaves a specific stage","configKeys":["stageId"]},{"event":"assignee_changed","description":"When record assignees change"},{"event":"priority_changed","description":"When record priority changes"},{"event":"due_date_passed","description":"When the record's due date has passed"},{"event":"record_archived","description":"When a record is archived"}],"rollupFunctions":["count","sum","avg","min","max"],"sandboxApiFunctions":[{"name":"setField","signature":"setField(name: string, value: any): void","description":"Queue a field update on the current record. Pass the field's name (the camelCase identifier shown in the Pipeline Fields panel) — it resolves to the canonical id server-side. Applied after the action completes successfully."},{"name":"setFieldOn","signature":"setFieldOn(recordId: string, fieldName: string, value: any): void","description":"Queue a field update on a different record (looked up by id). The field name is resolved against the target record's pipeline. Useful for syncing parent/related records."},{"name":"notify","signature":"notify(userId: string, message: string): Promise<void>","description":"Queue an in-app notification to the given user."},{"name":"sendEmail","signature":"sendEmail(to: string, subject: string, body: string): Promise<void>","description":"Queue a transactional email to a single recipient. Body may be HTML or plain text."},{"name":"sendChatMessage","signature":"sendChatMessage(chatId: string, message: string): Promise<void>","description":"Queue a Kazee Chat message into a chat room or DM thread by chatId."},{"name":"sendSms","signature":"sendSms(phone: string, message: string): Promise<void>","description":"Send an SMS via the org's configured SMS provider (Settings → Integrations → SMS) or the deployment-level CELCOM_* env fallback. Local numbers are normalised to E.164 using the org's default country code. Errors are logged as warnings and do NOT throw — other side effects continue. Requires the org to have an SMS provider saved (or env fallback) before any messages will actually leave the platform."},{"name":"initiateCall","signature":"initiateCall(callee: string, opts?: { autoAnswer?: boolean }): Promise<void>","description":"Originate a click-to-call from the executing user's mapped Yeastar PBX extension to callee (a phone number or internal extension). The PBX rings the user first, then bridges to callee. Requires (a) the org admin to have connected Yeastar in Settings → Integrations → Yeastar PBX and (b) the executing user (ctx.user) to be mapped to a PBX extension on the same screen. autoAnswer (default true) controls whether the caller's SIP/Linkus endpoint auto-answers. The caller is ALWAYS the executing user's extension — user code can never spoof the caller. Failures are logged as warnings; they do NOT throw."},{"name":"http","signature":"http(url: string, options?: { method?: string; body?: any; headers?: Record<string, string> }): Promise<{ status: number; data: any }>","description":"Make an outbound HTTP request. Limited to 3 requests per execution and 5s per call. Private/loopback IP ranges are blocked."},{"name":"queryRecords","signature":"queryRecords(pipelineId: string, filter?: { stageId?: string; assignee?: string }): Promise<RemoteRecord[]>","description":"Query records from any pipeline in this organisation (read-only, capped at 100 rows). Each returned record exposes a sugar method `.setField(name, value)` that queues a write back to that record (same semantics as setFieldOn)."},{"name":"getRecord","signature":"getRecord(recordId: string): Promise<RemoteRecord | null>","description":"Fetch a single pipeline record by id. Returns null if not found. Returned object exposes `.setField(name, value)` to queue updates on that record."},{"name":"getTask","signature":"getTask(taskId: string): Promise<{ id: string; title: string; status: string } | null>","description":"Fetch a task by id (read-only)."},{"name":"log","signature":"log(message: string): void","description":"Write a message to the execution log (visible in the Console tab). Capped at 50 entries per execution."}],"templateVariables":["{{record.title}}","{{record.stageName}}","{{record.priority}}","{{pipeline.name}}","{{transition.name}}","{{automation.name}}","{{triggerEvent}}"],"stageMigrationModes":[{"mode":"move","description":"Move all non-archived records from a stage that is being removed to another stage that still exists in the new blueprint. Use the propose_stage_migration tool to schedule this before applying the blueprint."},{"mode":"archive","description":"Archive all non-archived records on a stage being removed (sets isArchived=true and stamps transitionHistory). Use when records should not live on any stage after the change."}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]}},"/pipelines/{pipelineId}":{"get":{"tags":["Pipelines"],"summary":"Get a pipeline and its board","description":"Gets a pipeline's whole setup and, unless includeRecords is false, its board: the records that match the filters grouped by stage, with counts. Give perStageLimit to page the board (the next cards of a column come from listPipelineStageRecords); without it every matching record comes back. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"getPipeline","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists only archived records; otherwise only records that are not archived. Ignored when includeArchived is true. true, 1 and yes count as true"},{"name":"assigneeId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records assigned to this person (a user ID). For several, a JSON array in a string; a record matches if any of them is assigned","example":"66f1b2c3d4e5f60718293a5c"},{"name":"createdAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"createdAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"},{"name":"customFieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Same as fieldFilters; used only when fieldFilters is not given","example":"{\"category\":{\"operator\":\"is_not\",\"value\":\"services\"}}"},{"name":"dueDateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"dueDateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or before this time. A date on its own means its first moment (midnight UTC), so give the end of the day to include it","example":"2026-10-31T23:59:59.999Z"},{"name":"fieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Custom field filters as a JSON object in a string (an object in a JSON body also works): field ID -> condition. A plain value means \"is\" (a date such as 2026-10-01 matches that whole day), a list means \"is any of\". Otherwise { operator, value } or { operator, values }, with operator is (the default), is_not, contains (text, ignoring case), greater_than, less_than, is_empty or is_not_empty; { from, to } matches an inclusive range. Dates in text compare as dates and numbers in text as numbers. Text that is not valid JSON is ignored","example":"{\"category\":\"connectivity\",\"amount\":{\"from\":100000,\"to\":500000}}"},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true lists archived records together with the others. true, 1 and yes count as true"},{"name":"includeRecords","in":"query","required":false,"schema":{"type":"boolean"},"description":"false (or the text false) returns only pipeline and stagesWithTransitions: no records, counts, rollups or tags","example":true},{"name":"perStageLimit","in":"query","required":false,"schema":{"type":"integer"},"description":"Cards per column, 1 to 500 (more counts as 500). Turns on board paging, which also adds stageRollups and tagOptions. Without it, or with 0 or text, every matching record comes back","example":25},{"name":"priority","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this priority: none, low, medium, high or critical. For several, a JSON array in a string","example":"high"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Text to look for anywhere in the title, ignoring case","example":"safaricom"},{"name":"stageId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records in this stage. For several, a JSON array in a string, e.g. [\"received\",\"approved\"]; a record matches any of them","example":"approved"},{"name":"stageLimits","in":"query","required":false,"schema":{"type":"string"},"description":"With perStageLimit: how deep to load columns someone had paged into, as a JSON object in a string (an object in a JSON body also works): stage ID (\"null\" for no stage) -> cards, each up to 1000. A column gets the larger of this and perStageLimit","example":"{\"received\":75}"},{"name":"tags","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this tag. For several, a JSON array in a string; a record matches if it has any of them","example":"connectivity"},{"name":"updatedAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"updatedAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it belongs to: its id, name, color and icon"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline's whole setup"},"stagesWithTransitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"},"transitionsFrom":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"},"fromStage":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"}},"description":"This stage: id, name, color, orderNum"},"toStage":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"},"positionX":{"type":"integer"},"positionY":{"type":"integer"}},"description":"The stage it leads to, in full; { id, name: Unknown, color, orderNum: 999 } if that stage is gone"}}},"description":"Active transitions a record in this stage can take: its own, plus global ones that list this stage in fromStageIds"},"transitionsTo":{"type":"array","description":"Active transitions that lead into this stage, each { id, name, fromStageId }"}}},"description":"The pipeline's stages in board order, each with the active transitions out of it and into it"},"recordsByStage":{"type":"object","properties":{"received":{"type":"array","items":{"type":"object","properties":{"pipelineId":{"type":"string"},"spaceId":{"type":"string"},"stageId":{"type":"string"},"stageName":{"type":"string"},"stageEnteredAt":{"type":"string","format":"date-time"},"title":{"type":"string"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}}},"priority":{"type":"string"},"dueDate":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"po-number":{"type":"string"}}},"displaySubtitle":{"type":"string"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}}},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"orderIndex":{"type":"integer"},"isArchived":{"type":"boolean"},"organizationId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"id":{"type":"string"}}},"description":"Cards in the stage with ID received (one key per stage)"},"approved":{"type":"array","items":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who added it: id, firstName, lastName, email"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}}},"description":"Cards in the stage with ID approved"}},"description":"Unless includeRecords is false: the records that match the filters, keyed by stage ID (\"null\" for records with no stage). With perStageLimit: the first cards of each column that has any, newest first, without description, transitionHistory, checklist, linkedItems and attachments. Without it: every matching record in full, by orderIndex and then newest first"},"stageCounts":{"type":"object","properties":{"received":{"type":"integer"},"approved":{"type":"integer"}},"description":"Unless includeRecords is false: how many records match the filters in each stage, over all of them (not just the cards sent), keyed like recordsByStage; stages with none are left out"},"stageRollups":{"type":"object","properties":{"received":{"type":"array","items":{"type":"integer"}},"approved":{"type":"array","items":{"type":"integer"}}},"description":"Only with perStageLimit: for each stage, the value of each config.stageRollups entry over every matching record, in that order; null when the column has no number for it"},"tagOptions":{"type":"array","items":{"type":"string"},"description":"Only with perStageLimit: every tag on the pipeline's records, sorted, for a tag filter. It follows archived and includeArchived but no other filter"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"},"stagesWithTransitions":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120,"transitionsFrom":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true,"fromStage":{"id":"received","name":"Received","color":"#6b7280","orderNum":0},"toStage":{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120}}],"transitionsTo":[]},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120,"transitionsFrom":[{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true,"fromStage":{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1},"toStage":{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}}],"transitionsTo":[{"id":"approve","name":"Approve","fromStageId":"received"}]},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120,"transitionsFrom":[],"transitionsTo":[{"id":"mark-paid","name":"Mark paid","fromStageId":"approved"}]}],"recordsByStage":{"received":[{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"received","stageName":"Received","stageEnteredAt":"2026-10-15T07:40:00.000Z","title":"Liquid Intelligent Technologies, router spares","assignees":[{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"}],"priority":"medium","dueDate":"2026-11-05T09:00:00.000Z","tags":["equipment"],"fieldValues":{"supplier":"Liquid Intelligent Technologies","amount":96000,"category":"equipment","po-number":"PO-2291"},"displaySubtitle":"KES 96,000","displayBadge":{"label":"Due","value":"5 Nov","color":"#6b7280"},"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T07:40:00.000Z","updatedAt":"2026-10-15T07:40:00.000Z","id":"6ad1c4c9f4b2e81d9c7a5e2b"}],"approved":[{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"externalRef":{"type":"books_bill","id":"BILL-00412"},"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}]},"stageCounts":{"received":12,"approved":5},"stageRollups":{"received":[2214000],"approved":[922500]},"tagOptions":["connectivity","equipment","monthly"]}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]},"put":{"tags":["Pipelines"],"summary":"Update a pipeline's settings","description":"Changes a pipeline's name, description, board settings or messaging options; inputs you leave out stay as they are. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipeline","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"callEnabled":{"type":"boolean","description":"false hides calling from the pipeline's records. Only a JSON true or false counts","examples":[true]},"config":{"type":"object","description":"Board settings to change, shaped like the reply's config: each key you send replaces that key (a list such as stageSLAs is replaced whole), the rest stay. A JSON object in a string also works","examples":[{"cardBadgeField":"amount","stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}]}]},"description":{"type":"string","description":"New description; empty text clears it","examples":["Bills from suppliers, from arrival to payment."]},"emailEnabled":{"type":"boolean","description":"false hides sending email from the pipeline's records. Only a JSON true or false counts: text such as \"false\" is ignored","examples":[true]},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; an empty list allows any of them. Only a real list counts (not a JSON string); items that are not text are dropped and spaces trimmed","examples":[["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"]]},"name":{"type":"string","description":"New name; empty is ignored","examples":["Supplier invoices"]},"smsEnabled":{"type":"boolean","description":"false hides sending texts from the pipeline's records. Only a JSON true or false counts","examples":[false]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline after the change"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, config is not valid JSON, or the settings fail the model's checks (e.g. text where a number belongs)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]},"delete":{"tags":["Pipelines"],"summary":"Archive a pipeline","description":"Archives a pipeline: it drops out of lists, and most calls on it answer 404 from then on. Its records are left as they are, and no call brings it back. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.delete` (Delete pipelines).","operationId":"archivePipeline","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is already archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.delete"]}],"x-required-scopes":["spaces.pipelines.delete"]}},"/pipelines/{pipelineId}/records":{"get":{"tags":["Pipelines"],"summary":"List a pipeline's records","description":"Lists the records of a pipeline that match the filters, a page at a time, with their assignees and creator looked up. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"listPipelineRecords","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true lists only archived records; otherwise only records that are not archived. Ignored when includeArchived is true. true, 1 and yes count as true"},{"name":"assigneeId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records assigned to this person (a user ID). For several, a JSON array in a string; a record matches if any of them is assigned","example":"66f1b2c3d4e5f60718293a5c"},{"name":"createdAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"createdAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"},{"name":"customFieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Same as fieldFilters; used only when fieldFilters is not given","example":"{\"category\":{\"operator\":\"is_not\",\"value\":\"services\"}}"},{"name":"dueDateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"dueDateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or before this time. A date on its own means its first moment (midnight UTC), so give the end of the day to include it","example":"2026-10-31T23:59:59.999Z"},{"name":"fieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Custom field filters as a JSON object in a string (an object in a JSON body also works): field ID -> condition. A plain value means \"is\" (a date such as 2026-10-01 matches that whole day), a list means \"is any of\". Otherwise { operator, value } or { operator, values }, with operator is (the default), is_not, contains (text, ignoring case), greater_than, less_than, is_empty or is_not_empty; { from, to } matches an inclusive range. Dates in text compare as dates and numbers in text as numbers. Text that is not valid JSON is ignored","example":"{\"category\":\"connectivity\",\"amount\":{\"from\":100000,\"to\":500000}}"},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists archived records together with the others. true, 1 and yes count as true"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100},"description":"Most records to return, 1 to 500 (more counts as 500); 0 or text counts as 100","example":50},{"name":"priority","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this priority: none, low, medium, high or critical. For several, a JSON array in a string","example":"high"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Text to look for anywhere in the title, ignoring case","example":"safaricom"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many records to skip, for paging","example":0},{"name":"stageId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records in this stage. For several, a JSON array in a string, e.g. [\"received\",\"approved\"]; a record matches any of them","example":"approved"},{"name":"tags","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this tag. For several, a JSON array in a string; a record matches if it has any of them","example":"connectivity"},{"name":"updatedAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"updatedAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","items":{"type":"object","properties":{"transitionId":{"type":"string","description":"ID of the transition"},"transitionName":{"type":"string","description":"Its name at the time"},"fromStageId":{"type":"string","description":"Stage it left"},"fromStageName":{"type":"string","description":"Name of that stage"},"toStageId":{"type":"string","description":"Stage it entered"},"toStageName":{"type":"string","description":"Name of that stage"},"fieldValues":{"type":"object","properties":{"amount":{"type":"integer"}},"description":"Custom field values sent with the move"},"notes":{"type":"string","description":"Note given with the move"},"executedBy":{"type":"string","description":"ID of who moved it"},"executedAt":{"type":"string","format":"date-time","description":"When"}}},"description":"Every transition it went through, oldest first"},"checklist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"isCompleted":{"type":"boolean"},"completedBy":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"orderNum":{"type":"integer"}}},"description":"Checklist items: id, text, isCompleted, completedBy (user ID), completedAt, orderNum"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who added it: id, firstName, lastName, email"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}}},"description":"The records that match the filters, in full, by orderIndex and then newest first"},"total":{"type":"integer","description":"How many records match the filters, over all pages"}}},"example":{"records":[{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[{"transitionId":"approve","transitionName":"Approve","fromStageId":"received","fromStageName":"Received","toStageId":"approved","toStageName":"Approved","fieldValues":{"amount":184500},"notes":"Matches PO-2291; approved by the finance lead.","executedBy":"66f1b2c3d4e5f60718293a4b","executedAt":"2026-10-14T11:05:00.000Z"}],"checklist":[{"id":"match-po","text":"Match against the purchase order","isCompleted":true,"completedBy":"66f1b2c3d4e5f60718293a4b","completedAt":"2026-10-14T10:58:00.000Z","orderNum":0}],"externalRef":{"type":"books_bill","id":"BILL-00412"},"linkedItems":[],"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}],"total":17}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]},"post":{"tags":["Pipelines"],"summary":"Add a record to a pipeline","description":"Adds a record to a pipeline and answers with status 201. Needs the contributor role or higher in the pipeline's space. Without stageId it starts in config.defaultStageId, else the stage marked isDefault, else the first stage. It shows in the space's activity, people viewing the pipeline see it appear, and record_created and stage_entered automations run in the background.\n\n**Permission:** `spaces.pipelineRecords.create` (Add pipeline records).","operationId":"addPipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignees":{"type":"array","items":{"type":"string"},"description":"User IDs of the people to assign. A JSON array in a string also works","examples":[["66f1b2c3d4e5f60718293a5c"]]},"description":{"type":"string","description":"Longer notes on the record","examples":["100 Mbps dedicated link for the Westlands office, October."]},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card","examples":["https://example.com/logos/safaricom-business.png"]},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{},"color":{"type":"string"}},"description":"Badge on its card: { label, value, color }; value shows instead of label when set. A JSON object in a string also works","examples":[{"label":"Due","value":"31 Oct","color":"#f59e0b"}]},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card","examples":["KES 184,500"]},"dueDate":{"type":"string","format":"date-time","description":"When it is due","examples":["2026-10-31T09:00:00.000Z"]},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: { type, id }. A JSON object in a string also works","examples":[{"type":"books_bill","id":"BILL-00412"}]},"fieldValues":{"type":"object","description":"Custom field values: field ID -> value. Values for fields hidden by their dependsOn are dropped, then each is checked: a required field you send may not be empty, a field required while it shows must be filled, numbers and currency keep to min and max, ratings to their range (0 to 5 by default), select and multiselect values must be among the options, text must match its pattern, and email, phone (3 to 15 digits) and url values must look right. A JSON object in a string also works","examples":[{"supplier":"Safaricom Business","amount":184500,"category":"connectivity"}]},"priority":{"type":"string","enum":["none","low","medium","high","critical"],"description":"Defaults to none","examples":["high"]},"stageId":{"type":"string","description":"ID of the stage to start in; it must be one of the pipeline's stages","examples":["received"]},"startDate":{"type":"string","format":"date-time","description":"When work starts","examples":["2026-10-01T06:00:00.000Z"]},"tags":{"type":"array","items":{"type":"string"},"description":"Labels for the record. A JSON array in a string also works","examples":[["connectivity","monthly"]]},"title":{"type":"string","description":"Record title","examples":["Safaricom Business, October bandwidth"]}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"record":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people assigned to it"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","description":"Empty: a new record has been through no transitions"},"checklist":{"type":"array","description":"Empty: a new record has no checklist"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"string","description":"ID of who added it (you)"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}},"description":"The new record"}}},"example":{"record":{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"received","stageName":"Received","stageEnteredAt":"2026-10-13T08:12:00.000Z","title":"Safaricom Business, October bandwidth","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":["66f1b2c3d4e5f60718293a5c"],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[],"checklist":[],"externalRef":{"type":"books_bill","id":"BILL-00412"},"linkedItems":[],"createdBy":"66f1b2c3d4e5f60718293a4b","orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-13T08:12:00.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}}}}},"400":{"description":"pipelineId is not a valid ID, stageId is not one of the pipeline's stages, a custom field value fails its checks (the error names the field), a list or object input is not valid JSON, or the record fails the model's checks (e.g. an unknown priority)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the contributor role or higher in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.create"]}],"x-required-scopes":["spaces.pipelineRecords.create"]}},"/pipelines/{pipelineId}/records/{recordId}":{"get":{"tags":["Pipelines"],"summary":"Get a pipeline record","description":"Gets one record in full, with its assignees, its creator and whoever made each move looked up. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"getPipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"record":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","items":{"type":"object","properties":{"transitionId":{"type":"string","description":"ID of the transition"},"transitionName":{"type":"string","description":"Its name at the time"},"fromStageId":{"type":"string","description":"Stage it left"},"fromStageName":{"type":"string","description":"Name of that stage"},"toStageId":{"type":"string","description":"Stage it entered"},"toStageName":{"type":"string","description":"Name of that stage"},"fieldValues":{"type":"object","properties":{"amount":{"type":"integer"}},"description":"Custom field values sent with the move"},"notes":{"type":"string","description":"Note given with the move"},"executedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who moved it: id, firstName, lastName, email"},"executedAt":{"type":"string","format":"date-time","description":"When"}}},"description":"Every transition it went through, oldest first"},"checklist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"isCompleted":{"type":"boolean"},"completedBy":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"orderNum":{"type":"integer"}}},"description":"Checklist items: id, text, isCompleted, completedBy (user ID), completedAt, orderNum"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who added it: id, firstName, lastName, email"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}},"description":"The record in full"}}},"example":{"record":{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[{"transitionId":"approve","transitionName":"Approve","fromStageId":"received","fromStageName":"Received","toStageId":"approved","toStageName":"Approved","fieldValues":{"amount":184500},"notes":"Matches PO-2291; approved by the finance lead.","executedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"executedAt":"2026-10-14T11:05:00.000Z"}],"checklist":[{"id":"match-po","text":"Match against the purchase order","isCompleted":true,"completedBy":"66f1b2c3d4e5f60718293a4b","completedAt":"2026-10-14T10:58:00.000Z","orderNum":0}],"externalRef":{"type":"books_bill","id":"BILL-00412"},"linkedItems":[],"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}}}}},"400":{"description":"pipelineId or recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it (or the record is archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]},"put":{"tags":["Pipelines"],"summary":"Update a pipeline record","description":"Changes a record; inputs you leave out stay as they are. To move it to another stage, use movePipelineRecord. Needs the contributor role or higher in the pipeline's space. People viewing the pipeline see the change, and automations run in the background: record_updated always, field_changed for each custom field that changed, assignee_changed and priority_changed when those changed.\n\n**Permission:** `spaces.pipelineRecords.update` (Update pipeline records).","operationId":"updatePipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"assignees":{"type":"array","items":{"type":"string"},"description":"Replaces the assignees: user IDs. A JSON array in a string also works; anything that is not a list clears them","examples":[["66f1b2c3d4e5f60718293a5c"]]},"checklist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"isCompleted":{"type":"boolean"},"completedBy":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"orderNum":{"type":"integer"}}},"description":"Replaces the whole checklist: each item needs an id and text. A JSON array in a string also works","examples":[[{"id":"match-po","text":"Match against the purchase order","isCompleted":true,"completedBy":"66f1b2c3d4e5f60718293a4b","completedAt":"2026-10-14T10:58:00.000Z","orderNum":0}]]},"description":{"type":"string","description":"New notes","examples":["100 Mbps dedicated link for the Westlands office, October."]},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card","examples":["https://example.com/logos/safaricom-business.png"]},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{},"color":{"type":"string"}},"description":"Badge on its card: { label, value, color }; value shows instead of label when set. A JSON object in a string also works","examples":[{"label":"Due","value":"31 Oct","color":"#f59e0b"}]},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card","examples":["KES 184,500"]},"dueDate":{"type":"string","format":"date-time","description":"New due date; empty clears it","examples":["2026-10-31T09:00:00.000Z"]},"fieldValues":{"type":"object","description":"Custom field values to change: field ID -> value; fields you leave out keep their values. Values for fields that end up hidden by their dependsOn are dropped, and the result is checked as in addPipelineRecord, except that a field required while it shows may stay empty. A JSON object in a string also works","examples":[{"supplier":"Safaricom Business","amount":184500,"category":"connectivity"}]},"priority":{"type":"string","enum":["none","low","medium","high","critical"],"description":"Record priority","examples":["high"]},"startDate":{"type":"string","format":"date-time","description":"New start date; empty clears it","examples":["2026-10-01T06:00:00.000Z"]},"tags":{"type":"array","items":{"type":"string"},"description":"Replaces the tags. A JSON array in a string also works","examples":[["connectivity","monthly"]]},"title":{"type":"string","description":"New title","examples":["Safaricom Business, October bandwidth"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"record":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","items":{"type":"object","properties":{"transitionId":{"type":"string","description":"ID of the transition"},"transitionName":{"type":"string","description":"Its name at the time"},"fromStageId":{"type":"string","description":"Stage it left"},"fromStageName":{"type":"string","description":"Name of that stage"},"toStageId":{"type":"string","description":"Stage it entered"},"toStageName":{"type":"string","description":"Name of that stage"},"fieldValues":{"type":"object","properties":{"amount":{"type":"integer"}},"description":"Custom field values sent with the move"},"notes":{"type":"string","description":"Note given with the move"},"executedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who moved it: id, firstName, lastName, email"},"executedAt":{"type":"string","format":"date-time","description":"When"}}},"description":"Every transition it went through, oldest first"},"checklist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"isCompleted":{"type":"boolean"},"completedBy":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"orderNum":{"type":"integer"}}},"description":"Checklist items: id, text, isCompleted, completedBy (user ID), completedAt, orderNum"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who added it: id, firstName, lastName, email"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}},"description":"The record after the change, with people looked up"}}},"example":{"record":{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[{"transitionId":"approve","transitionName":"Approve","fromStageId":"received","fromStageName":"Received","toStageId":"approved","toStageName":"Approved","fieldValues":{"amount":184500},"notes":"Matches PO-2291; approved by the finance lead.","executedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"executedAt":"2026-10-14T11:05:00.000Z"}],"checklist":[{"id":"match-po","text":"Match against the purchase order","isCompleted":true,"completedBy":"66f1b2c3d4e5f60718293a4b","completedAt":"2026-10-14T10:58:00.000Z","orderNum":0}],"externalRef":{"type":"books_bill","id":"BILL-00412"},"linkedItems":[],"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}}}}},"400":{"description":"pipelineId or recordId is not a valid ID, a custom field value fails its checks (the error names the field), a list or object input is not valid JSON, or the record fails the model's checks (e.g. an unknown priority)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the contributor role or higher in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it (or the record is archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.update"]}],"x-required-scopes":["spaces.pipelineRecords.update"]},"delete":{"tags":["Pipelines"],"summary":"Archive a record","description":"Archives a record, so it leaves the board and record lists. Needs the editor or owner role in the pipeline's space (adding and changing records needs only contributor). It shows in the space's activity, people viewing the pipeline see it go, and record_archived automations run in the background. A record that is already archived is archived again; updateManyPipelineRecords with isArchived false brings records back.\n\n**Permission:** `spaces.pipelineRecords.update` (Update pipeline records).","operationId":"archivePipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"pipelineId or recordId is not a valid ID, or the record could not be saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.update"]}],"x-required-scopes":["spaces.pipelineRecords.update"]}},"/pipelines/{pipelineId}/records/{recordId}/attachment-url":{"get":{"tags":["Pipelines"],"summary":"Get a download link for a record file","description":"Gets a download link, good for an hour, for a file in one of a record's attachment fields. The link is to the organisation's own file store, or to the older shared one when the file is only there. Open to the space's members, and to anyone when the space is public. Works on archived records too.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"getPipelineRecordAttachmentUrl","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"},{"name":"minioKey","in":"query","required":true,"schema":{"type":"string"},"description":"Key of the file: the minioKey of a file in one of the record's attachment fields (in fieldValues). It contains slashes, so URL-encode it","example":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Link that downloads the file without signing in, until it runs out"},"expiresIn":{"type":"integer","description":"Seconds the link works for: always 3600"}}},"example":{"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T092500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4be1c07d9a2f3e5b6c8d0a1f2e3d4c5b6a7980f1e2d3c4b5a69788f0e1d2c3b4","expiresIn":3600}}}},"400":{"description":"pipelineId or recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), no record with that ID in it, or no file with that key in the record's custom fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipelines/{pipelineId}/records/{recordId}/followers":{"get":{"tags":["Pipelines"],"summary":"List a record's followers","description":"Lists the IDs of everyone who follows a record. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"listPipelineRecordFollowers","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"followers":{"type":"array","items":{"type":"string"},"description":"User IDs of the people who follow the record"}}},"example":{"followers":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]}}}},"400":{"description":"pipelineId or recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it (or the record is archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipelines/{pipelineId}/records/{recordId}/following":{"get":{"tags":["Pipelines"],"summary":"Check whether I follow a record","description":"Tells you whether you follow a record. It does not look the pipeline or record up, so an unknown record answers false.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"getPipelineRecordFollowStatus","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline; not checked","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"isFollowing":{"type":"boolean","description":"Whether you follow the record"}}},"example":{"isFollowing":true}}}},"400":{"description":"recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipelines/{pipelineId}/stats":{"get":{"tags":["Pipelines"],"summary":"Get a pipeline's stats","description":"Counts a pipeline's records: per stage, with the average time spent there so far, and in total. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"getPipelineStats","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"stageStats":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Stage ID; null for records with no stage"},"count":{"type":"integer","description":"Records in the stage that are not archived"},"avgTimeInStage":{"type":"integer","description":"Average time those records have been in the stage so far, in milliseconds"}}},"description":"One entry per stage that holds records that are not archived"},"totalRecords":{"type":"integer","description":"Records that are not archived"},"archivedRecords":{"type":"integer","description":"Archived records"},"overdueRecords":{"type":"integer","description":"Records that are not archived and whose due date has passed, in any stage"}}},"example":{"stageStats":[{"_id":"received","count":12,"avgTimeInStage":97200000},{"_id":"approved","count":5,"avgTimeInStage":43200000}],"totalRecords":17,"archivedRecords":3,"overdueRecords":2}}}},"400":{"description":"pipelineId is not a valid ID, or the counts could not be made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipelines/{pipelineId}/stage-counts":{"get":{"tags":["Pipelines"],"summary":"Count records in each stage","description":"Counts the records that match the filters in each stage. It takes the same filters as getPipeline and listPipelineRecords, so the numbers match theirs. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"getPipelineStageCounts","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists only archived records; otherwise only records that are not archived. Ignored when includeArchived is true. true, 1 and yes count as true"},{"name":"assigneeId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records assigned to this person (a user ID). For several, a JSON array in a string; a record matches if any of them is assigned","example":"66f1b2c3d4e5f60718293a5c"},{"name":"createdAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"createdAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"},{"name":"customFieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Same as fieldFilters; used only when fieldFilters is not given","example":"{\"category\":{\"operator\":\"is_not\",\"value\":\"services\"}}"},{"name":"dueDateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"dueDateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or before this time. A date on its own means its first moment (midnight UTC), so give the end of the day to include it","example":"2026-10-31T23:59:59.999Z"},{"name":"fieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Custom field filters as a JSON object in a string (an object in a JSON body also works): field ID -> condition. A plain value means \"is\" (a date such as 2026-10-01 matches that whole day), a list means \"is any of\". Otherwise { operator, value } or { operator, values }, with operator is (the default), is_not, contains (text, ignoring case), greater_than, less_than, is_empty or is_not_empty; { from, to } matches an inclusive range. Dates in text compare as dates and numbers in text as numbers. Text that is not valid JSON is ignored","example":"{\"category\":\"connectivity\",\"amount\":{\"from\":100000,\"to\":500000}}"},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists archived records together with the others. true, 1 and yes count as true"},{"name":"priority","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this priority: none, low, medium, high or critical. For several, a JSON array in a string","example":"high"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Text to look for anywhere in the title, ignoring case","example":"safaricom"},{"name":"stageId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records in this stage. For several, a JSON array in a string, e.g. [\"received\",\"approved\"]; a record matches any of them","example":"approved"},{"name":"tags","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this tag. For several, a JSON array in a string; a record matches if it has any of them","example":"connectivity"},{"name":"updatedAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"updatedAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"byStage":{"type":"object","properties":{"received":{"type":"integer"},"approved":{"type":"integer"}},"description":"Stage ID (\"null\" for no stage) -> how many records match the filters; stages with none are left out"},"total":{"type":"integer","description":"Sum of byStage"}}},"example":{"byStage":{"received":12,"approved":5},"total":17}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipelines/{pipelineId}/columns/{column}/records":{"get":{"tags":["Pipelines"],"summary":"List one board column's records","description":"Gets the next page of one board column: its cards after skip, newest first, and the column's total. It takes the same filters as getPipeline, so its pages carry on from the board's first page. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"listPipelineStageRecords","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"column","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the stage, or \"null\" for records with no stage. A stageId filter, if given, applies as well","example":"approved"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists only archived records; otherwise only records that are not archived. Ignored when includeArchived is true. true, 1 and yes count as true"},{"name":"assigneeId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records assigned to this person (a user ID). For several, a JSON array in a string; a record matches if any of them is assigned","example":"66f1b2c3d4e5f60718293a5c"},{"name":"createdAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"createdAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records added at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"},{"name":"customFieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Same as fieldFilters; used only when fieldFilters is not given","example":"{\"category\":{\"operator\":\"is_not\",\"value\":\"services\"}}"},{"name":"dueDateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"dueDateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records due at or before this time. A date on its own means its first moment (midnight UTC), so give the end of the day to include it","example":"2026-10-31T23:59:59.999Z"},{"name":"fieldFilters","in":"query","required":false,"schema":{"type":"string"},"description":"Custom field filters as a JSON object in a string (an object in a JSON body also works): field ID -> condition. A plain value means \"is\" (a date such as 2026-10-01 matches that whole day), a list means \"is any of\". Otherwise { operator, value } or { operator, values }, with operator is (the default), is_not, contains (text, ignoring case), greater_than, less_than, is_empty or is_not_empty; { from, to } matches an inclusive range. Dates in text compare as dates and numbers in text as numbers. Text that is not valid JSON is ignored","example":"{\"category\":\"connectivity\",\"amount\":{\"from\":100000,\"to\":500000}}"},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true lists archived records together with the others. true, 1 and yes count as true"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most cards to return, 1 to 500 (more counts as 500); 0 or text counts as 50","example":25},{"name":"priority","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this priority: none, low, medium, high or critical. For several, a JSON array in a string","example":"high"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Text to look for anywhere in the title, ignoring case","example":"safaricom"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many of the column's cards to skip, for paging","example":25},{"name":"stageId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records in this stage. For several, a JSON array in a string, e.g. [\"received\",\"approved\"]; a record matches any of them","example":"approved"},{"name":"tags","in":"query","required":false,"schema":{"type":"string"},"description":"Only records with this tag. For several, a JSON array in a string; a record matches if it has any of them","example":"connectivity"},{"name":"updatedAtFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or after this time; ignored if it is not a date","example":"2026-10-01T00:00:00.000Z"},{"name":"updatedAtTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only records changed at or before this time (a date on its own means midnight UTC)","example":"2026-10-31T23:59:59.999Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who added it: id, firstName, lastName, email"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}}},"description":"The column's cards after skip, newest first (the board's order), shaped like getPipeline's paged cards: no description, transitionHistory, checklist, linkedItems or attachments"},"total":{"type":"integer","description":"How many records match the filters in this column, over all pages"}}},"example":{"records":[{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"externalRef":{"type":"books_bill","id":"BILL-00412"},"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}],"total":5}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]}},"/pipelines/{pipelineId}/execution-logs":{"get":{"tags":["Pipelines"],"summary":"List a pipeline's action runs","description":"Lists each time a pipeline's transition or automation actions ran, with how every action went, newest first, a page at a time. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"listPipelineExecutionLogs","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":"50"},"description":"Most runs to return, up to 100; 0 or text counts as 50","example":50},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":"0"},"description":"How many runs to skip, for paging","example":0},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["success","partial_failure","failure"]},"description":"Only runs with this outcome","example":"partial_failure"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"logs":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Log ID"},"pipelineId":{"type":"string","description":"ID of the pipeline"},"recordId":{"type":"string","description":"ID of the record the actions ran on"},"recordTitle":{"type":"string","description":"Title of that record at the time"},"source":{"type":"string","description":"transition, automation or custom_button: what ran the actions"},"sourceId":{"type":"string","description":"ID of that transition or automation; for a custom button, custom_button:<button ID>"},"sourceName":{"type":"string","description":"Its name"},"triggerEvent":{"type":"string","description":"For automations: the event that set it off; custom_button for custom buttons; absent for transitions"},"status":{"type":"string","description":"success (every action worked), failure (none did) or partial_failure"},"actionResults":{"type":"array","items":{"type":"object","properties":{"actionType":{"type":"string","description":"Type of the action"},"actionName":{"type":"string","description":"The action's config.description, or its type"},"success":{"type":"boolean","description":"Whether it worked"},"logs":{"type":"array","description":"Lines a code action logged"},"sideEffects":{"type":"array","description":"What a code action asked for (notifications, emails, field writes)"},"duration":{"type":"integer","description":"How long it took, in milliseconds"}}},"description":"One entry per action, in run order. Keys some items also have: error (why it failed; absent when it worked)"},"totalDuration":{"type":"integer","description":"How long all the actions took, in milliseconds"},"executedBy":{"type":"string","description":"ID of the person whose change set it off"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it ran"},"updatedAt":{"type":"string","format":"date-time","description":"Same as createdAt"},"__v":{"type":"integer","description":"Internal version counter"}}},"description":"Runs of the pipeline's transition and automation actions, newest first"},"total":{"type":"integer","description":"How many runs match, over all pages"}}},"example":{"logs":[{"_id":"6ad1c6e1f4b2e81d9c7a5e55","pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","recordId":"6ad1c4b2f4b2e81d9c7a5e17","recordTitle":"Safaricom Business, October bandwidth","source":"automation","sourceId":"assign-payer-on-approval","sourceName":"Assign a payer","triggerEvent":"stage_entered","status":"success","actionResults":[{"actionType":"assign","actionName":"assign","success":true,"logs":[],"sideEffects":[],"duration":38}],"totalDuration":52,"executedBy":"66f1b2c3d4e5f60718293a4b","organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T11:05:01.000Z","updatedAt":"2026-10-14T11:05:01.000Z","__v":0},{"_id":"6ad1c6f7f4b2e81d9c7a5e63","pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","recordId":"6ad1c4b2f4b2e81d9c7a5e17","recordTitle":"Safaricom Business, October bandwidth","source":"transition","sourceId":"approve","sourceName":"Approve","status":"partial_failure","actionResults":[{"actionType":"notify","actionName":"notify","success":true,"logs":[],"sideEffects":[],"duration":21},{"actionType":"webhook","actionName":"webhook","success":false,"error":"Request failed with status code 502","logs":[],"sideEffects":[],"duration":5012}],"totalDuration":5040,"executedBy":"66f1b2c3d4e5f60718293a4b","organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T11:05:00.000Z","updatedAt":"2026-10-14T11:05:00.000Z","__v":0}],"total":214}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipelines/{pipelineId}/blueprint":{"get":{"tags":["Pipelines"],"summary":"Export a pipeline as a blueprint","description":"Gives a pipeline's whole setup as one blueprint, leaving out values that are the defaults, ready for updatePipelineFromBlueprint or createPipelineFromBlueprint. Custom buttons, editor positions and messaging options are not included. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"exportPipelineBlueprint","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"blueprint":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"}}},"description":"Stages: id, name, color, orderNum, and isDefault when set"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"fromStageId":{"type":"string"},"toStageId":{"type":"string"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}}}}}},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fieldPath":{"type":"string"},"fieldLabel":{"type":"string"},"operator":{"type":"string"},"value":{"type":"integer"}}}},"requiredFieldIds":{"type":"array","items":{"type":"string"}},"requireComment":{"type":"boolean"},"commentPrompt":{"type":"string"}}},"description":"Transitions, each as the pipeline holds it, leaving out values that are the defaults"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"trigger":{"type":"object","properties":{"event":{"type":"string"},"config":{"type":"object","properties":{"stageId":{"type":"string"}}}}},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fieldPath":{"type":"string"},"fieldLabel":{"type":"string"},"operator":{"type":"string"}}}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}}}}}}}},"description":"Automations, leaving out values that are the defaults"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"fieldType":{"type":"string"},"sectionId":{"type":"string"},"isRequired":{"type":"boolean"},"placeholder":{"type":"string"},"showOnCard":{"type":"boolean"}}},"description":"Custom fields, leaving out values that are the defaults"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"description":"Field sections: id, name, and orderNum when not 0"},"config":{"type":"object","properties":{"cardSubtitleField":{"type":"string"},"cardBadgeField":{"type":"string"},"defaultStageId":{"type":"string"},"requireTransitions":{"type":"boolean"},"enableSLA":{"type":"boolean"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}}},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}}}},"description":"Board settings that differ from the defaults (requireTransitions is always there)"}},"description":"The pipeline's setup in one document"}}},"example":{"blueprint":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","config":{"to":"creator","message":"{{record.title}} was approved"}},{"id":"approve-webhook","actionType":"webhook","config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note"},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","config":{"to":"assignees","message":"{{record.title}} is paid"}}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty"}],"requiredFieldIds":["payment-ref"]}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty"}],"actions":[{"id":"assign-payer","actionType":"assign","config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]}}]}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","fieldType":"text","sectionId":"invoice","isRequired":true,"placeholder":"Who sent the invoice","showOnCard":true},{"id":"amount","name":"amount","label":"Amount","fieldType":"currency","sectionId":"invoice","isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0}},{"id":"category","name":"category","label":"Category","fieldType":"select","sectionId":"invoice","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"defaultValue":"services","orderNum":2},{"id":"po-number","name":"poNumber","label":"PO number","fieldType":"text","sectionId":"invoice","placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","fieldType":"attachment","sectionId":"invoice","colSpan":6,"orderNum":4},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","fieldType":"text","sectionId":"payment","placeholder":"Bank reference","orderNum":5}],"fieldSections":[{"id":"invoice","name":"Invoice"},{"id":"payment","name":"Payment","orderNum":1}],"config":{"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}]}}}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]}},"/my/records":{"get":{"tags":["Pipelines"],"summary":"List records assigned to me","description":"Lists the records assigned to you in the active pipelines of every active space you own or belong to, most recently changed first, a page at a time. The pipelines and spaces they can belong to come with them, for grouping.\n\n**Permission:** `spaces.pipelineRecords.read` (View pipeline records).","operationId":"listMyRecords","parameters":[{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true (or the text true) also lists archived records"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200},"description":"Most records to return, 1 to 500 (more counts as 500); 0 or text counts as 200","example":50},{"name":"pipelineId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records in this pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"priority","in":"query","required":false,"schema":{"type":"string","enum":["none","low","medium","high","critical"]},"description":"Only records with this priority","example":"high"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many records to skip, for paging","example":0},{"name":"spaceId","in":"query","required":false,"schema":{"type":"string"},"description":"Only records in this space's pipelines; a space you do not own or belong to gives no records and no pipelines","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","items":{"type":"object","properties":{"transitionId":{"type":"string","description":"ID of the transition"},"transitionName":{"type":"string","description":"Its name at the time"},"fromStageId":{"type":"string","description":"Stage it left"},"fromStageName":{"type":"string","description":"Name of that stage"},"toStageId":{"type":"string","description":"Stage it entered"},"toStageName":{"type":"string","description":"Name of that stage"},"fieldValues":{"type":"object","properties":{"amount":{"type":"integer"}},"description":"Custom field values sent with the move"},"notes":{"type":"string","description":"Note given with the move"},"executedBy":{"type":"string","description":"ID of who moved it"},"executedAt":{"type":"string","format":"date-time","description":"When"}}},"description":"Every transition it went through, oldest first"},"checklist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"isCompleted":{"type":"boolean"},"completedBy":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"orderNum":{"type":"integer"}}},"description":"Checklist items: id, text, isCompleted, completedBy (user ID), completedAt, orderNum"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"string","description":"ID of who added it"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}}},"description":"Records assigned to you, most recently changed first"},"pipelines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pipeline ID"},"name":{"type":"string","description":"Pipeline name"},"spaceId":{"type":"string","description":"ID of its space"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"}}},"description":"Its stages: id, name, color, orderNum"}}},"description":"Active pipelines of your spaces (only spaceId's when given, none if it is not one of yours), narrowed by pipelineId, whether or not they hold records for you"},"spaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Space name"},"color":{"type":"string","description":"Space colour as a hex code"},"icon":{"type":"string","description":"Space icon (an emoji)"}}},"description":"Every active space you own or belong to"},"total":{"type":"integer","description":"How many records match, over all pages"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Most items in this page"},"skip":{"type":"integer","description":"How many items were skipped before this page"},"hasMore":{"type":"boolean","description":"Whether another page follows"}}}}},"example":{"records":[{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[{"transitionId":"approve","transitionName":"Approve","fromStageId":"received","fromStageName":"Received","toStageId":"approved","toStageName":"Approved","fieldValues":{"amount":184500},"notes":"Matches PO-2291; approved by the finance lead.","executedBy":"66f1b2c3d4e5f60718293a4b","executedAt":"2026-10-14T11:05:00.000Z"}],"checklist":[{"id":"match-po","text":"Match against the purchase order","isCompleted":true,"completedBy":"66f1b2c3d4e5f60718293a4b","completedAt":"2026-10-14T10:58:00.000Z","orderNum":0}],"externalRef":{"type":"books_bill","id":"BILL-00412"},"linkedItems":[],"createdBy":"66f1b2c3d4e5f60718293a4b","orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}],"pipelines":[{"id":"6ad1c3a0f4b2e81d9c7a5e01","name":"Supplier invoices","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2}]}],"spaces":[{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"}],"total":9,"pagination":{"limit":200,"skip":0,"hasMore":false}}}}},"400":{"description":"pipelineId or spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.read"]}],"x-required-scopes":["spaces.pipelineRecords.read"]}},"/pipeline-agent/sessions":{"get":{"tags":["Pipelines"],"summary":"List my Pipeline AI chats in a space","description":"Lists your own Pipeline AI chats in a space, most recently changed first, without their transcripts. It returns nothing for other people's chats.\n\n**Permission:** `spaces.agents.read` (View agent sessions).","operationId":"listPipelineAgentSessions","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Most chats to return, 1 to 50. Defaults to 10","example":10},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["create","edit"]},"description":"Only chats in this mode; any other value is ignored","example":"edit"},{"name":"pipelineId","in":"query","required":false,"schema":{"type":"string"},"description":"Only chats about this pipeline: edit chats for it, and the create chat that made it","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"spaceId","in":"query","required":true,"schema":{"type":"string"},"description":"Space whose chats to list","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Chat ID; also names its live room, pipeline-agent:<id>"},"mode":{"type":"string","description":"create (design a new pipeline) or edit (change pipelineId)"},"provider":{"type":"string","description":"AI provider: openai or anthropic"},"model":{"type":"string","description":"Model the provider runs"},"status":{"type":"string","description":"idle, running (a reply is being written; one silent for 10 minutes no longer blocks new messages), cancelled, applied or failed"},"pipelineId":{"type":"string","description":"Pipeline it changes (edit mode), or the one it created once applied; null otherwise"},"spaceId":{"type":"string","description":"ID of the space it works in"},"createdAt":{"type":"string","format":"date-time","description":"When the chat started"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed; chats are removed 7 days after this"},"appliedPipelineId":{"description":"ID of the pipeline the draft was applied to, or null"},"appliedAt":{"description":"When it was applied, or null"},"draftIsValid":{"type":"boolean","description":"Whether the draft passes the checks, so it can be applied"},"hasDraft":{"type":"boolean","description":"Whether the assistant has proposed a draft"},"messageCount":{"type":"integer","description":"How many messages the transcript has, tool messages included"},"lastUserMessage":{"type":"string","description":"First 120 characters of your last message, or null"}}}}}},"example":{"sessions":[{"id":"6ad1c2e0f3a4b5c6d7e8f907","mode":"edit","provider":"anthropic","model":"claude-sonnet-5-5","status":"idle","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","spaceId":"6a9f3c21b7e4a20f1c5d8e41","createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:01:14.000Z","appliedPipelineId":null,"appliedAt":null,"draftIsValid":true,"hasDraft":true,"messageCount":4,"lastUserMessage":"Drop the Negotiation stage and move its deals to Quoted."},{"id":"6ad1c2e0f3a4b5c6d7e8f908","mode":"create","provider":"anthropic","model":"claude-sonnet-5-5","status":"applied","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","spaceId":"6a9f3c21b7e4a20f1c5d8e41","createdAt":"2026-09-02T07:10:00.000Z","updatedAt":"2026-09-02T07:30:00.000Z","appliedPipelineId":"6ad1c2e0f3a4b5c6d7e8f901","appliedAt":"2026-09-02T07:30:00.000Z","draftIsValid":true,"hasDraft":true,"messageCount":9,"lastUserMessage":"Make a sales pipeline with Lead, Quoted, Negotiation and Won."}]}}}},"400":{"description":"spaceId or pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.read"]}],"x-required-scopes":["spaces.agents.read"]},"post":{"tags":["Pipelines"],"summary":"Start a Pipeline AI chat","description":"Starts a chat with the Pipeline AI assistant in a space, to design a new pipeline (create mode) or change one (edit mode), and answers with status 201. Needs the editor role or higher in the space, which must not be archived, and the organisation needs an API key for the AI provider. Only you can see and use the chat; it is removed 7 days after its last change.\n\n**Permission:** `spaces.agents.create` (Start agent sessions).","operationId":"startPipelineAgentSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["create","edit"],"default":"create","description":"create designs a new pipeline; edit changes pipelineId. Any other value counts as create","examples":["edit"]},"model":{"type":"string","description":"Model name, passed to the provider as given. Defaults to the server's default model for the provider","examples":["claude-sonnet-5-5"]},"pipelineId":{"type":"string","description":"Pipeline to change, in spaceId; needed in edit mode, ignored in create mode","examples":["6ad1c2e0f3a4b5c6d7e8f901"]},"provider":{"type":"string","enum":["openai","anthropic"],"description":"AI provider, in any letter case. Without it, or with another value, the organisation's default provider is used (openai if none is set)","examples":["anthropic"]},"spaceId":{"type":"string","description":"Space the pipeline is in, or will be made in","examples":["6a9f3c21b7e4a20f1c5d8e41"]}},"required":["spaceId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string","description":"Chat ID; also names its live room, pipeline-agent:<id>"},"userId":{"type":"string","description":"ID of the person who started it; only they can use it"},"spaceId":{"type":"string","description":"ID of the space it works in"},"pipelineId":{"type":"string","description":"Pipeline it changes (edit mode), or the one it created once applied; null otherwise"},"mode":{"type":"string","description":"create (design a new pipeline) or edit (change pipelineId)"},"provider":{"type":"string","description":"AI provider: openai or anthropic"},"model":{"type":"string","description":"Model the provider runs"},"status":{"type":"string","description":"idle, running (a reply is being written; one silent for 10 minutes no longer blocks new messages), cancelled, applied or failed"},"lastError":{"description":"Why the last reply failed, or null"},"messages":{"type":"array","description":"The transcript, oldest first. Assistant messages that called tools also have toolCalls (id, name, arguments), and tool messages have toolResults (toolCallId, name, result, isError) instead of content"},"draftBlueprint":{"description":"The pipeline the assistant proposes (name, description, stages, transitions, automations, fieldDefinitions, fieldSections, config), or null before it proposes one"},"draftIsValid":{"type":"boolean","description":"Whether the draft passes the checks, so it can be applied"},"draftValidationErrors":{"type":"array","description":"Why the draft is not valid"},"stageMigrations":{"type":"array","description":"Edit mode: what happens to records on stages the draft removes"},"appliedPipelineId":{"description":"ID of the pipeline the draft was applied to, or null"},"appliedAt":{"description":"When it was applied, or null"},"createdAt":{"type":"string","format":"date-time","description":"When the chat started"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed; chats are removed 7 days after this"}}},"availableProviders":{"type":"array","items":{"type":"string"},"description":"AI providers the organisation has an API key for: openai, anthropic or both"}}},"example":{"session":{"id":"6ad1c2e0f3a4b5c6d7e8f907","userId":"66f1b2c3d4e5f60718293a4b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","mode":"edit","provider":"anthropic","model":"claude-sonnet-5-5","status":"idle","lastError":null,"messages":[],"draftBlueprint":null,"draftIsValid":false,"draftValidationErrors":[],"stageMigrations":[],"appliedPipelineId":null,"appliedAt":null,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z"},"availableProviders":["openai","anthropic"]}}}},"400":{"description":"spaceId or pipelineId is not a valid ID, mode is edit without pipelineId, or the organisation has no API key for the provider (code AI_NOT_CONFIGURED; the reply also has provider and availableProviders)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID (or it is archived), or in edit mode no pipeline with that ID in the space, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.create"]}],"x-required-scopes":["spaces.agents.create"]}},"/pipeline-agent/sessions/{sessionId}":{"get":{"tags":["Pipelines"],"summary":"Get a Pipeline AI chat","description":"Gets one of your Pipeline AI chats with its whole transcript, the current draft and the stage migration plan. Only the person who started the chat may open it.\n\n**Permission:** `spaces.agents.read` (View agent sessions).","operationId":"getPipelineAgentSession","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the Pipeline AI chat","example":"6ad1c2e0f3a4b5c6d7e8f907"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string","description":"Chat ID; also names its live room, pipeline-agent:<id>"},"userId":{"type":"string","description":"ID of the person who started it; only they can use it"},"spaceId":{"type":"string","description":"ID of the space it works in"},"pipelineId":{"type":"string","description":"Pipeline it changes (edit mode), or the one it created once applied; null otherwise"},"mode":{"type":"string","description":"create (design a new pipeline) or edit (change pipelineId)"},"provider":{"type":"string","description":"AI provider: openai or anthropic"},"model":{"type":"string","description":"Model the provider runs"},"status":{"type":"string","description":"idle, running (a reply is being written; one silent for 10 minutes no longer blocks new messages), cancelled, applied or failed"},"lastError":{"description":"Why the last reply failed, or null"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","description":"user, assistant or tool (results of the assistant's tool calls)"},"content":{"type":"string","description":"The text; null on tool messages"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"}}},"description":"The transcript, oldest first. Assistant messages that called tools also have toolCalls (id, name, arguments), and tool messages have toolResults (toolCallId, name, result, isError) instead of content"},"draftBlueprint":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"}}}},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"fromStageId":{"type":"string"},"toStageId":{"type":"string"},"requiredFieldIds":{"type":"array","items":{"type":"string"}},"actions":{"type":"array"}}}},"automations":{"type":"array"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"fieldType":{"type":"string"},"currencyCode":{"type":"string"},"isRequired":{"type":"boolean"},"showOnCard":{"type":"boolean"}}}},"fieldSections":{"type":"array"},"config":{"type":"object","properties":{"defaultStageId":{"type":"string"},"requireTransitions":{"type":"boolean"}}}},"description":"The pipeline the assistant proposes (name, description, stages, transitions, automations, fieldDefinitions, fieldSections, config), or null before it proposes one"},"draftIsValid":{"type":"boolean","description":"Whether the draft passes the checks, so it can be applied"},"draftValidationErrors":{"type":"array","description":"Why the draft is not valid"},"stageMigrations":{"type":"array","items":{"type":"object","properties":{"fromStageId":{"type":"string","description":"Stage being removed"},"fromStageName":{"type":"string","description":"Its name"},"toStageId":{"type":"string","description":"Stage its records move to (mode move)"},"toStageName":{"type":"string","description":"That stage's name"},"mode":{"type":"string","description":"move or archive"},"recordCountAtPlanning":{"type":"integer","description":"How many active records it had when planned"},"note":{"type":"string","description":"Note saved in each moved record's history"}}},"description":"Edit mode: what happens to records on stages the draft removes"},"appliedPipelineId":{"description":"ID of the pipeline the draft was applied to, or null"},"appliedAt":{"description":"When it was applied, or null"},"createdAt":{"type":"string","format":"date-time","description":"When the chat started"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed; chats are removed 7 days after this"}}}}},"example":{"session":{"id":"6ad1c2e0f3a4b5c6d7e8f907","userId":"66f1b2c3d4e5f60718293a4b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","mode":"edit","provider":"anthropic","model":"claude-sonnet-5-5","status":"idle","lastError":null,"messages":[{"role":"user","content":"Drop the Negotiation stage and move its deals to Quoted.","createdAt":"2026-10-15T08:01:00.000Z"},{"role":"assistant","content":"I will move the 3 deals in Negotiation to Quoted, then remove the stage.","toolCalls":[{"id":"toolu_01","name":"propose_stage_migration","arguments":{"migrations":[{"fromStageId":"negotiation","toStageId":"quoted","mode":"move"}]}},{"id":"toolu_02","name":"propose_blueprint","arguments":{"blueprint":{"name":"Sales","description":"Deals from first contact to signed contract","stages":[{"id":"lead","name":"Lead","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"quoted","name":"Quoted","color":"#3b82f6","orderNum":1,"isDefault":false},{"id":"won","name":"Won","color":"#22c55e","orderNum":2,"isDefault":false}],"transitions":[{"id":"lead-to-quoted","name":"Send quote","fromStageId":"lead","toStageId":"quoted","requiredFieldIds":["dealAmount"],"actions":[]}],"automations":[],"fieldDefinitions":[{"id":"dealAmount","name":"dealAmount","label":"Deal amount","fieldType":"currency","currencyCode":"KES","isRequired":true,"showOnCard":true}],"fieldSections":[],"config":{"defaultStageId":"lead","requireTransitions":true}}}}],"createdAt":"2026-10-15T08:01:09.000Z"},{"role":"tool","content":null,"toolResults":[{"toolCallId":"toolu_01","name":"propose_stage_migration","result":{"plan":[{"fromStageId":"negotiation","fromStageName":"Negotiation","toStageId":"quoted","toStageName":"Quoted","mode":"move","recordCountAtPlanning":3,"note":"Negotiation merged into Quoted"}],"warnings":[],"totalRecords":3},"isError":false},{"toolCallId":"toolu_02","name":"propose_blueprint","result":{"valid":true,"errors":[],"summary":{"name":"Sales","stageCount":3,"stageNames":["Lead","Quoted","Won"],"transitionCount":1,"automationCount":0,"fieldCount":1}},"isError":false}],"createdAt":"2026-10-15T08:01:10.000Z"},{"role":"assistant","content":"The draft is ready: Lead, Quoted and Won. Apply it when you are happy.","createdAt":"2026-10-15T08:01:14.000Z"}],"draftBlueprint":{"name":"Sales","description":"Deals from first contact to signed contract","stages":[{"id":"lead","name":"Lead","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"quoted","name":"Quoted","color":"#3b82f6","orderNum":1,"isDefault":false},{"id":"won","name":"Won","color":"#22c55e","orderNum":2,"isDefault":false}],"transitions":[{"id":"lead-to-quoted","name":"Send quote","fromStageId":"lead","toStageId":"quoted","requiredFieldIds":["dealAmount"],"actions":[]}],"automations":[],"fieldDefinitions":[{"id":"dealAmount","name":"dealAmount","label":"Deal amount","fieldType":"currency","currencyCode":"KES","isRequired":true,"showOnCard":true}],"fieldSections":[],"config":{"defaultStageId":"lead","requireTransitions":true}},"draftIsValid":true,"draftValidationErrors":[],"stageMigrations":[{"fromStageId":"negotiation","fromStageName":"Negotiation","toStageId":"quoted","toStageName":"Quoted","mode":"move","recordCountAtPlanning":3,"note":"Negotiation merged into Quoted"}],"appliedPipelineId":null,"appliedAt":null,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:01:14.000Z"}}}}},"400":{"description":"sessionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID; chats are removed 7 days after their last change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.read"]}],"x-required-scopes":["spaces.agents.read"]}},"/strategy-agent/sessions":{"get":{"tags":["Strategies"],"summary":"List your strategy assistant chats","description":"Lists your own strategy assistant chats about one strategy, most recently changed first, each with its message count and your last message. Other people's chats are never listed, and an unknown strategy gives an empty list. Chats are deleted 7 days after their last change.\n\n**Permission:** `spaces.agents.read` (View agent sessions).","operationId":"listStrategyAgentSessions","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50},"description":"Most chats to return, up to 50 (more is cut to 50). Defaults to 10, also for 0 or a value that is not a number","example":10},{"name":"strategyId","in":"query","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Chat (session) ID"},"provider":{"type":"string","description":"AI provider: openai or anthropic"},"model":{"type":"string","description":"AI model in use"},"status":{"type":"string","description":"idle, running, cancelled or failed: running while a reply is being worked out (one silent for 10 minutes no longer blocks new messages), failed after an error"},"strategyId":{"type":"string","description":"ID of the strategy it works on"},"spaceId":{"type":"string","description":"ID of the strategy's space"},"createdAt":{"type":"string","format":"date-time","description":"When the chat was started"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed; the chat is deleted 7 days after this"},"messageCount":{"type":"integer","description":"How many messages the transcript holds, the AI's and tool messages included"},"lastUserMessage":{"type":"string","description":"Your last message, cut to 120 characters; null before you send one"}}},"description":"Your chats about the strategy, most recently changed first"}}},"example":{"sessions":[{"id":"6ad1c4b04f3b8a1d2c7e5f42","provider":"anthropic","model":"claude-sonnet-5-5","status":"idle","strategyId":"6ad1c2e04f3b8a1d2c7e5f10","spaceId":"6a9f3c21b7e4a20f1c5d8e41","createdAt":"2026-10-15T09:29:40.000Z","updatedAt":"2026-10-15T09:30:07.000Z","messageCount":4,"lastUserMessage":"Add a pillar for network reliability"},{"id":"6ad1b8e24f3b8a1d2c7e5e90","provider":"openai","model":"gpt-4.1","status":"idle","strategyId":"6ad1c2e04f3b8a1d2c7e5f10","spaceId":"6a9f3c21b7e4a20f1c5d8e41","createdAt":"2026-10-13T14:02:11.000Z","updatedAt":"2026-10-13T14:06:48.000Z","messageCount":9,"lastUserMessage":"Which of our objectives has no key results yet?"}]}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.read"]}],"x-required-scopes":["spaces.agents.read"]},"post":{"tags":["Strategies"],"summary":"Start a strategy assistant chat","description":"Starts a chat with the AI strategy assistant about one strategy and answers with status 201; send it messages with sendStrategyAgentMessage. Needs the editor role or higher in the strategy's space, which must not be archived, and an API key for the AI provider in the organisation's AI settings. The chat is yours alone and is deleted 7 days after its last change.\n\n**Permission:** `spaces.agents.create` (Start agent sessions).","operationId":"startStrategyAgentSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"AI model to use. Leave out for the provider's default model (claude-sonnet-5-5 or gpt-4.1 unless the server sets others). The name is not checked here; a model the provider does not have makes the first reply fail","examples":["claude-sonnet-5-5"]},"provider":{"type":"string","enum":["openai","anthropic"],"description":"AI provider to use (any letter case). Leave out, or send anything else, for the organisation's default provider (openai if none is set)","examples":["anthropic"]},"strategyId":{"type":"string","description":"ID of the strategy to work on","examples":["6ad1c2e04f3b8a1d2c7e5f10"]}},"required":["strategyId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string","description":"Chat (session) ID"},"userId":{"type":"string","description":"ID of the person who started it; only they can use it"},"spaceId":{"type":"string","description":"ID of the strategy's space"},"strategyId":{"type":"string","description":"ID of the strategy it works on"},"provider":{"type":"string","description":"AI provider: openai or anthropic"},"model":{"type":"string","description":"AI model in use"},"status":{"type":"string","description":"idle, running, cancelled or failed: running while a reply is being worked out (one silent for 10 minutes no longer blocks new messages), failed after an error"},"lastError":{"description":"What went wrong in the last failed reply; null when none"},"messages":{"type":"array","description":"Always empty: the chat has just started"},"createdAt":{"type":"string","format":"date-time","description":"When the chat was started"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed; the chat is deleted 7 days after this"}}},"availableProviders":{"type":"array","items":{"type":"string"},"description":"The AI providers the organisation has an API key for"}}},"example":{"session":{"id":"6ad1c4b04f3b8a1d2c7e5f42","userId":"66f1b2c3d4e5f60718293a4b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","strategyId":"6ad1c2e04f3b8a1d2c7e5f10","provider":"anthropic","model":"claude-sonnet-5-5","status":"idle","lastError":null,"messages":[],"createdAt":"2026-10-15T09:29:40.000Z","updatedAt":"2026-10-15T09:29:40.000Z"},"availableProviders":["openai","anthropic"]}}}},"400":{"description":"strategyId is not a valid ID, or the AI provider to use has no API key set up for the organisation; the reply then also has code AI_NOT_CONFIGURED, provider and availableProviders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.create"]}],"x-required-scopes":["spaces.agents.create"]}},"/strategy-agent/sessions/{sessionId}":{"get":{"tags":["Strategies"],"summary":"Get a strategy assistant chat","description":"Gets one of your strategy assistant chats with its whole transcript, including the changes the assistant made to the strategy and what each returned. Only the person who started the chat can open it.\n\n**Permission:** `spaces.agents.read` (View agent sessions).","operationId":"getStrategyAgentSession","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the chat (session)","example":"6ad1c4b04f3b8a1d2c7e5f42"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string","description":"Chat (session) ID"},"userId":{"type":"string","description":"ID of the person who started it; only they can use it"},"spaceId":{"type":"string","description":"ID of the strategy's space"},"strategyId":{"type":"string","description":"ID of the strategy it works on"},"provider":{"type":"string","description":"AI provider: openai or anthropic"},"model":{"type":"string","description":"AI model in use"},"status":{"type":"string","description":"idle, running, cancelled or failed: running while a reply is being worked out (one silent for 10 minutes no longer blocks new messages), failed after an error"},"lastError":{"description":"What went wrong in the last failed reply; null when none"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","description":"user (your messages), assistant (the AI's), or tool (results of the changes it made)"},"content":{"type":"string","description":"The text; null when there is none (tool messages, or an assistant step with only tool calls)"},"createdAt":{"type":"string","format":"date-time","description":"When the message was added"}}},"description":"The transcript, oldest first. An assistant message that made changes to the strategy also has toolCalls, a list of { id, name, arguments }: which change (e.g. add_pillar, add_objective, set_vision, set_phase) with the values the AI passed. The tool message after it has toolResults, a list of { toolCallId, name, result, isError }: what each change returned, or { error } in result when it failed"},"createdAt":{"type":"string","format":"date-time","description":"When the chat was started"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed; the chat is deleted 7 days after this"}}}}},"example":{"session":{"id":"6ad1c4b04f3b8a1d2c7e5f42","userId":"66f1b2c3d4e5f60718293a4b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","strategyId":"6ad1c2e04f3b8a1d2c7e5f10","provider":"anthropic","model":"claude-sonnet-5-5","status":"idle","lastError":null,"messages":[{"role":"user","content":"Add a pillar for network reliability","createdAt":"2026-10-15T09:30:00.000Z"},{"role":"assistant","content":"I'll add that pillar now.","toolCalls":[{"id":"toolu_01HxQ7rV3pKz8mWnD2sYbE5c","name":"add_pillar","arguments":{"name":"Network reliability","description":"Keep business links up","color":"#10b981"}}],"createdAt":"2026-10-15T09:30:04.000Z"},{"role":"tool","content":null,"toolResults":[{"toolCallId":"toolu_01HxQ7rV3pKz8mWnD2sYbE5c","name":"add_pillar","result":{"id":"1792143004512-a8k3p","name":"Network reliability"},"isError":false}],"createdAt":"2026-10-15T09:30:05.000Z"},{"role":"assistant","content":"Done: the strategy now has a Network reliability pillar. Shall I add an objective under it?","createdAt":"2026-10-15T09:30:07.000Z"}],"createdAt":"2026-10-15T09:29:40.000Z","updatedAt":"2026-10-15T09:30:07.000Z"}}}}},"400":{"description":"sessionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID (chats are deleted 7 days after their last change)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.read"]}],"x-required-scopes":["spaces.agents.read"]}},"/spaces/{spaceId}/items":{"get":{"tags":["Spaces"],"summary":"List a space's sidebar items","description":"Lists what is in a space's sidebar: folders, task lists, pipelines, wikis, sheets, documents and more, leaving out archived items, and the entries of private wikis for anyone who is not a member of the space. By default the reply is a tree; flat gives one list instead. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.spaceItems.read` (View space items).","operationId":"listSpaceItems","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"flat","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true answers with one flat list instead of the tree"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Item ID again (the tree shape carries both _id and id)"},"id":{"type":"string","description":"Item ID"},"spaceId":{"type":"string","description":"ID of the space it is in"},"itemType":{"type":"string","description":"What it is: folder, calendar, pipeline, wiki, document, tasks, spreadsheet, presentation, custom, analytics, strategy, drive. tasks is a task list"},"name":{"type":"string","description":"Name shown in the sidebar"},"icon":{"type":"string","description":"An emoji or icon name; each type has its own default, e.g. 📁 for a folder"},"parentId":{"description":"ID of the folder it sits in; null at the top level"},"orderNum":{"type":"integer","description":"Position among the items in the same folder; 0 comes first"},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"metadata":{"description":"Extra settings some item types keep, e.g. the dashboard an analytics item shows; null when none"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"__v":{"type":"integer","description":"Internal revision counter"},"children":{"type":"array","description":"Only in the tree: the items inside this folder, in the same shape; empty for anything else"}}},"description":"The tree: top-level items in sidebar order, each folder holding its own items in children. With flat, every item in one list, by folder and then position, without _id and children"}}},"example":{"items":[{"_id":"6a9f3c5eb7e4a20f1c5d8e47","id":"6a9f3c5eb7e4a20f1c5d8e47","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"tasks","name":"This month","icon":"✏️","parentId":null,"orderNum":0,"isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-09-01T07:30:00.000Z","__v":0,"children":[]},{"_id":"6a9f3c71b7e4a20f1c5d8e4c","id":"6a9f3c71b7e4a20f1c5d8e4c","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"folder","name":"Budgets","icon":"📁","parentId":null,"orderNum":1,"isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-02T09:00:00.000Z","updatedAt":"2026-10-01T06:45:00.000Z","color":"#f59e0b","__v":0,"children":[{"_id":"6ad0a0c7d5c26de56de949e1","id":"6ad0a0c7d5c26de56de949e1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"spreadsheet","name":"October budget","icon":"📊","parentId":"6a9f3c71b7e4a20f1c5d8e4c","orderNum":0,"targetId":"6ad0a0d2d5c26de56de949e6","targetType":"UniverDocument","isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T08:10:00.000Z","__v":0,"children":[]}]}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID, it is archived, or it is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.read"]}],"x-required-scopes":["spaces.spaceItems.read"]},"post":{"tags":["Spaces"],"summary":"Create a sidebar item","description":"Adds an item to a space's sidebar, at the end of its folder, and answers with status 201. It only makes the sidebar entry: to make the pipeline, wiki, strategy, sheet or document it opens as well, use createSpaceItemWithTarget. Needs the editor role or higher in the space; an archived space takes no new items.\n\n**Permission:** `spaces.spaceItems.create` (Create space items).","operationId":"createSpaceItem","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"Colour as a hex code","examples":["#8b5cf6"]},"icon":{"type":"string","description":"An emoji or icon name. Defaults to the type's own, e.g. 📁 for a folder","examples":["📈"]},"itemType":{"type":"string","enum":["folder","calendar","pipeline","wiki","document","tasks","spreadsheet","presentation","custom","analytics","strategy","drive"],"description":"What the item is; tasks is a task list","examples":["analytics"]},"metadata":{"type":"object","description":"Extra settings for the item, e.g. the dashboardId an analytics item shows. A JSON object in a string also works","examples":[{"dashboardId":12}]},"name":{"type":"string","description":"Name shown in the sidebar","examples":["Cash flow"]},"parentId":{"type":"string","description":"ID of a folder in this space to put it in; leave out for the top level","examples":["6a9f3c71b7e4a20f1c5d8e4c"]},"targetId":{"type":"string","description":"ID of the thing the item opens, e.g. a pipeline, wiki or sheet. It is not checked","examples":["6ad0a0d2d5c26de56de949e6"]},"targetType":{"type":"string","enum":["Pipeline","Wiki","WikiPage","UniverDocument","Strategy"],"description":"Kind of thing targetId points to; UniverDocument is a sheet or document","examples":["UniverDocument"]}},"required":["itemType","name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"spaceId":{"type":"string","description":"ID of the space it is in"},"itemType":{"type":"string","description":"What it is: folder, calendar, pipeline, wiki, document, tasks, spreadsheet, presentation, custom, analytics, strategy, drive. tasks is a task list"},"name":{"type":"string","description":"Name shown in the sidebar"},"icon":{"type":"string","description":"An emoji or icon name; each type has its own default, e.g. 📁 for a folder"},"parentId":{"type":"string","description":"ID of the folder it sits in; null at the top level"},"orderNum":{"type":"integer","description":"Position among the items in the same folder; 0 comes first"},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"metadata":{"type":"object","properties":{"dashboardId":{"type":"integer"}},"description":"Extra settings some item types keep, e.g. the dashboard an analytics item shows; null when none"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"color":{"type":"string","description":"Colour as a hex code; absent when none was chosen"}}}}},"example":{"item":{"id":"6ad0a10bd5c26de56de94a02","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"analytics","name":"Cash flow","icon":"📈","parentId":"6a9f3c71b7e4a20f1c5d8e4c","orderNum":1,"isExpanded":true,"isArchived":false,"metadata":{"dashboardId":12},"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:40:00.000Z","updatedAt":"2026-10-15T09:40:00.000Z","color":"#8b5cf6"}}}}},"400":{"description":"spaceId or parentId is not a valid ID, parentId is not a folder in this space, itemType or targetType is not one of the known values, or metadata is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.create"]}],"x-required-scopes":["spaces.spaceItems.create"]}},"/events":{"get":{"tags":["Calendar"],"summary":"List my events","description":"Lists the events you organise or are invited to, personal and in every space, earliest first. Without both startDate and endDate it lists at most 500 events, the ones that start latest (a repeating event counts by its first occurrence). With expandOccurrences each occurrence is its own row, and only occurrences you are invited to are listed, leaving out spaces you can no longer see.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"listUserEvents","parameters":[{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of the range","example":"2026-10-26T00:00:00.000Z"},{"name":"expandOccurrences","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists each occurrence in the range as its own dated row (with its own Kazee call) and adds occurrenceContract. It needs startDate and endDate, at most 92 days apart, with at most 500 events in the range, and a person's sign-in (not a service token)","example":true},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the range. With endDate, only events that touch the range are listed (repeating events with an occurrence in it too); without both, at most 500 events are: the ones that start latest, so upcoming events come before old ones","example":"2026-10-19T00:00:00.000Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string","description":"The organizer's first name"},"lastName":{"type":"string","description":"The organizer's last name"},"email":{"type":"string","description":"The organizer's email address"},"id":{"type":"string","description":"The organizer's user ID"}},"description":"The organizer"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string","description":"The invited person's first name"},"lastName":{"type":"string","description":"The invited person's last name"},"email":{"type":"string","description":"The invited person's email address"},"id":{"type":"string","description":"The invited person's user ID"}},"description":"The invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"string"},"description":"IDs of the tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}}},"description":"Events, earliest first. Without expandOccurrences a repeating event is one item with its rule, except a series the server plans, which comes as dated rows like the second item (row fields are explained on getEventOccurrenceCall). With expandOccurrences every item is a dated row and has _id but no id"},"occurrenceContract":{"type":"integer","description":"Only with expandOccurrences: always 1, meaning every item is a dated occurrence row"}}},"example":{"events":[{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":{"firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com","id":"66f1b2c3d4e5f60718293a4b"},"attendees":[{"userId":{"firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com","id":"66f1b2c3d4e5f60718293a5c"},"status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":["6ad0a044d5c26de56de949a8"],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}},{"_id":"6ad1c0b8d5c26de56de94a1c_rec_2026-10-22T06:30:00.000Z","title":"Finance team stand-up","description":"What moved yesterday and what is blocked.","startDate":"2026-10-22T06:30:00.000Z","endDate":"2026-10-22T06:45:00.000Z","allDay":false,"timeZone":"Africa/Kampala","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c102e8b37a1d2c9f5b27","meeting":{"provider":"kazee","meetingId":"6ad1c102e8b37a1d2c9f5b27","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c102e8b37a1d2c9f5b27","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","managesAttendees":false,"occurrenceStartsAt":"2026-10-22T06:30:00.000Z","syncedAt":"2026-10-15T06:31:10.000Z"},"spaceId":{"_id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"creatorId":{"_id":"66f1b2c3d4e5f60718293a4b","firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com"},"attendees":[{"userId":{"_id":"66f1b2c3d4e5f60718293a5c","firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com"},"status":"accepted","respondedAt":"2026-10-01T10:00:00.000Z"}],"color":"#22c55e","category":"meeting","recurrence":null,"reminders":[5],"recurrenceExceptions":[],"linkedTasks":[{"_id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","status":"in_progress"}],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"occurrenceManaged":true,"createdAt":"2026-10-01T09:00:00.000Z","updatedAt":"2026-10-14T16:20:00.000Z","__v":3,"eventId":"6ad1c0b8d5c26de56de94a1c","seriesId":"6ad1c0b8d5c26de56de94a1c","occurrenceId":"6ad1c0b8d5c26de56de94a1c:2026-10-22T06:30:00.000Z","originalStartDate":"2026-10-22T06:30:00.000Z","isOccurrence":true,"isRecurring":true,"revision":"2026-10-14T16:20:00.000Z","version":3,"seriesVersion":3,"eventUrl":"https://spaces.kazee.africa/calendar?event=6ad1c0b8d5c26de56de94a1c&occurrence=2026-10-22T06%3A30%3A00.000Z","meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T06:31:10.000Z","retryable":false},"parentEventId":null,"id":"6ad1c0b8d5c26de56de94a1c_rec_2026-10-22T06:30:00.000Z"}],"occurrenceContract":1}}}},"400":{"description":"The range is not valid for expandOccurrences (both dates, end after start, at most 92 days), or it holds too many events or occurrences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"expandOccurrences was asked with a service token instead of a person's sign-in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]},"post":{"tags":["Calendar"],"summary":"Create an event","description":"Creates a calendar event, personal or in a space, and answers with status 201; in a space you need the contributor role or higher, and an archived space takes no new events. Everyone invited except you gets an invitation notification. meetingProvider kazee sets up a Kazee call for the organizer and attendees: if Kazee Chat cannot be reached the event is still made and meetingReadiness shows the call as pending, but when Kazee Chat refuses a call asked for in a conversation the event is withdrawn and the answer carries Kazee Chat's status and reason. jitsiMeeting gives the event its own video room instead.\n\n**Permission:** `spaces.calendar.create` (Create events).","operationId":"createEvent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allDay":{"type":"boolean","default":false,"description":"Whether it takes the whole day"},"attendees":{"type":"array","items":{"type":"string"},"description":"IDs of the people to invite (a JSON array in a string also works): up to 500, each an active person in your organisation. For a Kazee call in a space, each must be a member of the space","examples":[["66f1b2c3d4e5f60718293a5c"]]},"category":{"type":"string","enum":["meeting","deadline","milestone","reminder","other"],"description":"Kind of event; a new event defaults to meeting","examples":["meeting"]},"color":{"type":"string","description":"Colour shown on the calendar; a new event defaults to #3b82f6","examples":["#22c55e"]},"conversationId":{"type":"string","description":"Kazee Chat conversation to hold the call in, so the call and its card stay there for everyone in it. Only with meetingProvider kazee; for a space event it must be the space's own conversation","examples":["6ad1c11ae8b37a1d2c9f5b30"]},"description":{"type":"string","description":"Longer notes","examples":["Go through the October invoices and the cash forecast."]},"endDate":{"type":"string","format":"date-time","description":"When it ends","examples":["2026-10-21T08:00:00.000Z"]},"jitsiMeeting":{"type":"boolean","default":false,"description":"true gives the event its own video room and puts its link in meetingUrl; join it with getEventCallToken. Ignored with meetingProvider kazee"},"location":{"type":"string","description":"Where it takes place","examples":["Board room, 3rd floor"]},"meetingProvider":{"type":"string","enum":["kazee","jitsi"],"description":"kazee sets up a Kazee call in Kazee Chat for the organizer and attendees (a space event's call is in the space's conversation); jitsi is the same as jitsiMeeting true. Other values add no call","examples":["kazee"]},"meetingUrl":{"type":"string","description":"Link to a call held elsewhere, kept as the event's join link; replaced when jitsiMeeting or a Kazee call gives it one","examples":["https://meet.google.com/abc-defg-hij"]},"recurrence":{"type":"object","properties":{"type":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"interval":{"type":"integer","minimum":1},"endDate":{"type":"string","format":"date-time"},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"monthlyPattern":{"type":"string","enum":["dayOfMonth","dayOfWeek"]},"weekOfMonth":{"type":"array","items":{"type":"integer","minimum":1,"maximum":5}},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6}},"description":"How it repeats (a JSON object in a string also works): type, interval (every how many days, weeks, months or years; default 1), endDate (last day), daysOfWeek (0 is Sunday) for weekly, and for monthly either monthlyPattern dayOfMonth or monthlyPattern dayOfWeek with weekOfMonth (1 to 5) and dayOfWeek","examples":[{"type":"weekly","interval":1,"daysOfWeek":[1,3]}]},"reminders":{"type":"array","items":{"type":"integer","minimum":0},"description":"Minutes before the start to remind attendees; 0 is at the start (a JSON array in a string also works). Defaults to [15, 0]","examples":[[15,0]]},"spaceId":{"type":"string","description":"Space to put it in; leave out for a personal event","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"startDate":{"type":"string","format":"date-time","description":"When it starts","examples":["2026-10-21T07:00:00.000Z"]},"timeZone":{"type":"string","description":"IANA time zone it is planned in, e.g. Africa/Kampala","examples":["Africa/Kampala"]},"title":{"type":"string","description":"What the event is","examples":["October finance review"]}},"required":["endDate","startDate","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"string","description":"ID of the organizer (firstName, lastName, email are not filled in here)"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","description":"Tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The new event, with its space filled in and people as IDs"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","attendees":[{"userId":"66f1b2c3d4e5f60718293a5c","status":"pending"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":[],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:02.000Z","id":"6ad1c0a2d5c26de56de94a10","version":1,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"spaceId is not a valid ID; endDate is before startDate; a repeating event lasts longer than the gap between its repeats; timeZone is not a valid IANA zone; conversationId is not an ID, comes without meetingProvider kazee, or is not the space's own conversation; an attendee is not an active person in your organisation, or there are over 500; a Kazee call in a space invites someone who is not a member; or a field is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.create"]}],"x-required-scopes":["spaces.calendar.create"]}},"/events/{eventId}":{"get":{"tags":["Calendar"],"summary":"Get an event","description":"Gets one event with its space, organizer, attendees and linked tasks. A space event is open to anyone who can see the space; a personal event to its organizer and attendees. With occurrence it answers that one occurrence of a repeating event, with its own Kazee call. A repeating series with Kazee calls asked for without occurrence comes with an empty meetingUrl, meeting { provider: kazee, status: pending } and metadata.undatedSeries.next naming the next occurrence to open (null when none is due within 62 days).\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"getEvent","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event; for a repeating event, the series","example":"6ad1c0a2d5c26de56de94a10"},{"name":"occurrence","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Original start of one occurrence of a repeating event: originalStartDate from a list row","example":"2026-10-22T06:30:00.000Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string","description":"The organizer's first name"},"lastName":{"type":"string","description":"The organizer's last name"},"email":{"type":"string","description":"The organizer's email address"},"id":{"type":"string","description":"The organizer's user ID"}},"description":"The organizer"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string","description":"The invited person's first name"},"lastName":{"type":"string","description":"The invited person's last name"},"email":{"type":"string","description":"The invited person's email address"},"id":{"type":"string","description":"The invited person's user ID"}},"description":"The invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title of the task"},"status":{"type":"string","description":"Status of the task"},"id":{"type":"string","description":"Task ID"}}},"description":"Tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The event. With occurrence, that one dated occurrence instead, shaped as getEventOccurrenceCall shows it"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":{"firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com","id":"66f1b2c3d4e5f60718293a4b"},"attendees":[{"userId":{"firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com","id":"66f1b2c3d4e5f60718293a5c"},"status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":[{"title":"Send the October invoice","status":"in_progress","id":"6ad0a044d5c26de56de949a8"}],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"eventId is not a valid ID, occurrence is not a valid date, or the series has over 500 changed occurrences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the event's space, or it is a personal event you neither organise nor are invited to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation (or it was deleted), or that occurrence no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]},"put":{"tags":["Calendar"],"summary":"Update an event","description":"Changes an event; only the fields you send change. Open to its organizer and to space members with the contributor role or higher, but only the organizer or a space editor may change attendees. For a repeating event, editScope picks one occurrence (this), it and the ones after it (following) or every upcoming one (all); earlier occurrences keep their history. The Kazee call follows the edit (set up, moved or removed in Kazee Chat); if Chat cannot be reached the edit is still saved and meetingReadiness shows what is still owed.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"updateEvent","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event; for a repeating event, the series (or the stored change of one occurrence)","example":"6ad1c0a2d5c26de56de94a10"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"attendees":{"type":"array","items":{"type":"string"},"description":"IDs of everyone to invite, replacing the list (a JSON array in a string also works); people already invited keep their reply. Up to 500, each an active person in your organisation, and members of the space for a Kazee call in a space","examples":[["66f1b2c3d4e5f60718293a5c"]]},"category":{"type":"string","enum":["meeting","deadline","milestone","reminder","other"],"description":"Kind of event; a new event defaults to meeting","examples":["meeting"]},"color":{"type":"string","description":"Colour shown on the calendar; a new event defaults to #3b82f6","examples":["#22c55e"]},"description":{"type":"string","description":"Longer notes","examples":["Go through the October invoices and the cash forecast."]},"editScope":{"type":"string","enum":["this","following","all","series"],"description":"Which occurrences of a repeating event change: this (the one at occurrenceDate), following (that one and the ones after it) or all and series (every occurrence from the next upcoming one). Needed for a series the server plans; ignored for an event that does not repeat","examples":["this"]},"endDate":{"type":"string","format":"date-time","description":"When it ends","examples":["2026-10-21T08:00:00.000Z"]},"expectedRevision":{"type":"integer","description":"The event's version as you last read it; if it has changed since, the edit is refused with 409","examples":[2]},"jitsiMeeting":{"type":"boolean","description":"true gives the event its own video room (join it with getEventCallToken); false removes the room, and meetingUrl, if sent, becomes the link"},"location":{"type":"string","description":"Where it takes place","examples":["Board room, 3rd floor"]},"meetingProvider":{"type":"string","enum":["kazee","jitsi","external","none"],"description":"kazee adds a Kazee call; any other value removes the Kazee call. When editing occurrences of a repeating event (any editScope) only these four are accepted, and jitsi turns on the event's own video room","examples":["kazee"]},"meetingUrl":{"type":"string","description":"Link to a call held elsewhere, set as the event's join link","examples":["https://meet.google.com/abc-defg-hij"]},"occurrenceDate":{"type":"string","format":"date-time","description":"With editScope this or following: original start of the occurrence to change (originalStartDate from a list row). Midnight UTC of a day also works when the series has one occurrence that day","examples":["2026-10-22T06:30:00.000Z"]},"recurrence":{"type":"object","properties":{"type":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"interval":{"type":"integer","minimum":1},"endDate":{"type":"string","format":"date-time"},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"monthlyPattern":{"type":"string","enum":["dayOfMonth","dayOfWeek"]},"weekOfMonth":{"type":"array","items":{"type":"integer","minimum":1,"maximum":5}},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6}},"description":"How it repeats (a JSON object in a string also works): type, interval (every how many days, weeks, months or years; default 1), endDate (last day), daysOfWeek (0 is Sunday) for weekly, and for monthly either monthlyPattern dayOfMonth or monthlyPattern dayOfWeek with weekOfMonth (1 to 5) and dayOfWeek. With editScope following, all or series, the interval is 1 to 366 and null stops the repeating from there","examples":[{"type":"weekly","interval":1,"daysOfWeek":[1,3]}]},"reminders":{"type":"array","items":{"type":"integer","minimum":0},"description":"Minutes before the start to remind attendees; 0 is at the start (a JSON array in a string also works). When editing occurrences of a repeating event (any editScope): at most 10, each up to 40320 (four weeks)","examples":[[15,0]]},"startDate":{"type":"string","format":"date-time","description":"When it starts","examples":["2026-10-21T07:00:00.000Z"]},"timeZone":{"type":"string","description":"IANA time zone it is planned in, e.g. Africa/Kampala","examples":["Africa/Kampala"]},"title":{"type":"string","description":"What the event is; up to 200 characters when editing occurrences of a repeating event (any editScope)","examples":["October finance review"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string","description":"The organizer's first name"},"lastName":{"type":"string","description":"The organizer's last name"},"email":{"type":"string","description":"The organizer's email address"},"id":{"type":"string","description":"The organizer's user ID"}},"description":"The organizer"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string","description":"The invited person's first name"},"lastName":{"type":"string","description":"The invited person's last name"},"email":{"type":"string","description":"The invited person's email address"},"id":{"type":"string","description":"The invited person's user ID"}},"description":"The invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title of the task"},"status":{"type":"string","description":"Status of the task"},"id":{"type":"string","description":"Task ID"}}},"description":"Tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The event after the change. For editScope this it is the stored change of that one occurrence; for following, all or series it is the series, with its space and people as IDs. For a call made in Kazee Chat (in organisations where Chat keeps those calls) it is the event before the change, which shows once Chat confirms it"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":{"firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com","id":"66f1b2c3d4e5f60718293a4b"},"attendees":[{"userId":{"firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com","id":"66f1b2c3d4e5f60718293a5c"},"status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":[{"title":"Send the October invoice","status":"in_progress","id":"6ad0a044d5c26de56de949a8"}],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"eventId is not a valid ID; timeZone, attendees, editScope, expectedRevision or another field is not valid (recurrence or reminders that is not valid JSON too); a repeating event lasts longer than the gap between its repeats; an attendee is not an active person in your organisation (or, for a Kazee call in a space, not a member); or a series the server plans came without editScope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the organizer or a space member with the contributor role or higher; only the organizer or a space editor may change attendees; or the event is kept by Kazee People and is read-only here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The event changed since expectedRevision, the occurrence cannot be changed (it has started, was cancelled or is not an occurrence of the series), the series would last longer than the gap between its repeats, or Kazee Chat refused a change to a call made in Chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The call was made in Kazee Chat and Kazee Chat could not be reached to change it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]},"delete":{"tags":["Calendar"],"summary":"Cancel an event","description":"Cancels an event: it leaves every calendar together with the changes stored for its single occurrences, and its Kazee calls are cancelled in Kazee Chat (retried later if Chat cannot be reached). Open to the organizer and to space members with the editor role or higher. For a repeating event, deleteScope this cancels one upcoming occurrence and following cancels it and the ones after it; earlier occurrences keep their history. The event is archived rather than erased, but no call brings it back.\n\n**Permission:** `spaces.calendar.delete` (Delete events).","operationId":"cancelEvent","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event; for a repeating event, the series","example":"6ad1c0a2d5c26de56de94a10"},{"name":"deleteScope","in":"query","required":false,"schema":{"type":"string","enum":["this","following","all","series"]},"description":"For a repeating event: this (the occurrence at occurrenceDate), following (that one and the ones after it), or all and series (the whole event, as when it is left out). Ignored for an event that does not repeat","example":"this"},{"name":"occurrenceDate","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"With deleteScope this or following: original start of the occurrence (originalStartDate from a list row). Midnight UTC of a day also works when the series has one occurrence that day","example":"2026-10-22T06:30:00.000Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"eventId is not a valid ID, or deleteScope is not this, following, all or series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the event's organizer or a space member with the editor role or higher, or the event is kept by Kazee People and is read-only here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation, or it was already cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The occurrence cannot be cancelled (it has started, is not an occurrence of the series, or the series changed), or Kazee Chat refused to cancel a call made in Chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The call was made in Kazee Chat and Kazee Chat could not be reached to change it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.delete"]}],"x-required-scopes":["spaces.calendar.delete"]}},"/events/{eventId}/jitsi-token":{"get":{"tags":["Calendar"],"summary":"Get a pass to join an event's call","description":"Signs you into the meeting call of an event that has its own video room, answering a pass with your name, email and photo for that room. The organizer joins as moderator. Open to anyone who can see the event's space, or for a personal event to its organizer and attendees.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"getEventCallToken","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event","example":"6ad1c0a2d5c26de56de94a10"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Signed pass that lets you into the call, valid for 24 hours; it makes the organizer a moderator"},"roomName":{"type":"string","description":"The event's call room: spaces-<event ID>"},"domain":{"type":"string","description":"Call server; the room is at https://<domain>/<roomName>"}}},"example":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250ZXh0Ijp7InVzZXIiOnsiaWQiOiI2NmYxYjJjM2Q0ZTVmNjA3MTgyOTNhNWMiLCJuYW1lIjoiRGFuaWVsIE9rZWxsbyJ9fSwicm9vbSI6InNwYWNlcy02YWQxYzBhMmQ1YzI2ZGU1NmRlOTRhMTAiLCJtb2RlcmF0b3IiOmZhbHNlfQ.4Qy0b1mK8nZt2rVwX9sLcP3aJfE7uH5dGiOqT6yNkBw","roomName":"spaces-6ad1c0a2d5c26de56de94a10","domain":"meet.inet.africa"}}}},"400":{"description":"eventId is not a valid ID, or the event has no video room of its own (it was not made with jitsiMeeting); a Kazee call is joined with meeting.joinUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the event's space, or it is a personal event you neither organise nor are invited to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation, or it was cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]}},"/spaces/{spaceId}/events":{"get":{"tags":["Calendar"],"summary":"List a space's events","description":"Lists a space's events, earliest first, with their organizer, attendees and linked tasks. Open to anyone who can see the space (its members, or anyone if it is public). Without both startDate and endDate it lists at most 500 events, the ones that start latest (a repeating event counts by its first occurrence). With expandOccurrences each occurrence of a repeating event is its own row, ready to show on a calendar.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"listSpaceEvents","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of the range","example":"2026-10-26T00:00:00.000Z"},{"name":"expandOccurrences","in":"query","required":false,"schema":{"type":"boolean"},"description":"true lists each occurrence in the range as its own dated row (with its own Kazee call) and adds occurrenceContract. It needs startDate and endDate, at most 92 days apart, with at most 500 events in the range, and a person's sign-in (not a service token)","example":true},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of the range. With endDate, only events that touch the range are listed (repeating events with an occurrence in it too); without both, at most 500 events are: the ones that start latest, so upcoming events come before old ones","example":"2026-10-19T00:00:00.000Z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"string","description":"ID of the space it belongs to; absent for a personal event"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string","description":"The organizer's first name"},"lastName":{"type":"string","description":"The organizer's last name"},"email":{"type":"string","description":"The organizer's email address"},"id":{"type":"string","description":"The organizer's user ID"}},"description":"The organizer"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string","description":"The invited person's first name"},"lastName":{"type":"string","description":"The invited person's last name"},"email":{"type":"string","description":"The invited person's email address"},"id":{"type":"string","description":"The invited person's user ID"}},"description":"The invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title of the task"},"status":{"type":"string","description":"Status of the task"},"id":{"type":"string","description":"Task ID"}}},"description":"Tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}}},"description":"Events, earliest first. Without expandOccurrences a repeating event is one item with its rule, except a series the server plans, which comes as dated rows like the second item (row fields are explained on getEventOccurrenceCall). With expandOccurrences every item is a dated row and has _id but no id"},"occurrenceContract":{"type":"integer","description":"Only with expandOccurrences: always 1, meaning every item is a dated occurrence row"}}},"example":{"events":[{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com","id":"66f1b2c3d4e5f60718293a4b"},"attendees":[{"userId":{"firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com","id":"66f1b2c3d4e5f60718293a5c"},"status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":[{"title":"Send the October invoice","status":"in_progress","id":"6ad0a044d5c26de56de949a8"}],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}},{"_id":"6ad1c0b8d5c26de56de94a1c_rec_2026-10-22T06:30:00.000Z","title":"Finance team stand-up","description":"What moved yesterday and what is blocked.","startDate":"2026-10-22T06:30:00.000Z","endDate":"2026-10-22T06:45:00.000Z","allDay":false,"timeZone":"Africa/Kampala","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c102e8b37a1d2c9f5b27","meeting":{"provider":"kazee","meetingId":"6ad1c102e8b37a1d2c9f5b27","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c102e8b37a1d2c9f5b27","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","managesAttendees":false,"occurrenceStartsAt":"2026-10-22T06:30:00.000Z","syncedAt":"2026-10-15T06:31:10.000Z"},"spaceId":{"_id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"creatorId":{"_id":"66f1b2c3d4e5f60718293a4b","firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com"},"attendees":[{"userId":{"_id":"66f1b2c3d4e5f60718293a5c","firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com"},"status":"accepted","respondedAt":"2026-10-01T10:00:00.000Z"}],"color":"#22c55e","category":"meeting","recurrence":null,"reminders":[5],"recurrenceExceptions":[],"linkedTasks":[{"_id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","status":"in_progress"}],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"occurrenceManaged":true,"createdAt":"2026-10-01T09:00:00.000Z","updatedAt":"2026-10-14T16:20:00.000Z","__v":3,"eventId":"6ad1c0b8d5c26de56de94a1c","seriesId":"6ad1c0b8d5c26de56de94a1c","occurrenceId":"6ad1c0b8d5c26de56de94a1c:2026-10-22T06:30:00.000Z","originalStartDate":"2026-10-22T06:30:00.000Z","isOccurrence":true,"isRecurring":true,"revision":"2026-10-14T16:20:00.000Z","version":3,"seriesVersion":3,"eventUrl":"https://spaces.kazee.africa/calendar?event=6ad1c0b8d5c26de56de94a1c&occurrence=2026-10-22T06%3A30%3A00.000Z","meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T06:31:10.000Z","retryable":false},"parentEventId":null,"id":"6ad1c0b8d5c26de56de94a1c_rec_2026-10-22T06:30:00.000Z"}],"occurrenceContract":1}}}},"400":{"description":"spaceId is not a valid ID. The range is not valid for expandOccurrences (both dates, end after start, at most 92 days), or it holds too many events or occurrences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"expandOccurrences was asked with a service token instead of a person's sign-in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]},"post":{"tags":["Calendar"],"summary":"Create an event","description":"Creates a calendar event, personal or in a space, and answers with status 201; in a space you need the contributor role or higher, and an archived space takes no new events. Everyone invited except you gets an invitation notification. meetingProvider kazee sets up a Kazee call for the organizer and attendees: if Kazee Chat cannot be reached the event is still made and meetingReadiness shows the call as pending, but when Kazee Chat refuses a call asked for in a conversation the event is withdrawn and the answer carries Kazee Chat's status and reason. jitsiMeeting gives the event its own video room instead.\n\n**Permission:** `spaces.calendar.create` (Create events).","operationId":"createEvent_2","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Space to put it in; leave out for a personal event","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allDay":{"type":"boolean","default":false,"description":"Whether it takes the whole day"},"attendees":{"type":"array","items":{"type":"string"},"description":"IDs of the people to invite (a JSON array in a string also works): up to 500, each an active person in your organisation. For a Kazee call in a space, each must be a member of the space","examples":[["66f1b2c3d4e5f60718293a5c"]]},"category":{"type":"string","enum":["meeting","deadline","milestone","reminder","other"],"description":"Kind of event; a new event defaults to meeting","examples":["meeting"]},"color":{"type":"string","description":"Colour shown on the calendar; a new event defaults to #3b82f6","examples":["#22c55e"]},"conversationId":{"type":"string","description":"Kazee Chat conversation to hold the call in, so the call and its card stay there for everyone in it. Only with meetingProvider kazee; for a space event it must be the space's own conversation","examples":["6ad1c11ae8b37a1d2c9f5b30"]},"description":{"type":"string","description":"Longer notes","examples":["Go through the October invoices and the cash forecast."]},"endDate":{"type":"string","format":"date-time","description":"When it ends","examples":["2026-10-21T08:00:00.000Z"]},"jitsiMeeting":{"type":"boolean","default":false,"description":"true gives the event its own video room and puts its link in meetingUrl; join it with getEventCallToken. Ignored with meetingProvider kazee"},"location":{"type":"string","description":"Where it takes place","examples":["Board room, 3rd floor"]},"meetingProvider":{"type":"string","enum":["kazee","jitsi"],"description":"kazee sets up a Kazee call in Kazee Chat for the organizer and attendees (a space event's call is in the space's conversation); jitsi is the same as jitsiMeeting true. Other values add no call","examples":["kazee"]},"meetingUrl":{"type":"string","description":"Link to a call held elsewhere, kept as the event's join link; replaced when jitsiMeeting or a Kazee call gives it one","examples":["https://meet.google.com/abc-defg-hij"]},"recurrence":{"type":"object","properties":{"type":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"interval":{"type":"integer","minimum":1},"endDate":{"type":"string","format":"date-time"},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"monthlyPattern":{"type":"string","enum":["dayOfMonth","dayOfWeek"]},"weekOfMonth":{"type":"array","items":{"type":"integer","minimum":1,"maximum":5}},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6}},"description":"How it repeats (a JSON object in a string also works): type, interval (every how many days, weeks, months or years; default 1), endDate (last day), daysOfWeek (0 is Sunday) for weekly, and for monthly either monthlyPattern dayOfMonth or monthlyPattern dayOfWeek with weekOfMonth (1 to 5) and dayOfWeek","examples":[{"type":"weekly","interval":1,"daysOfWeek":[1,3]}]},"reminders":{"type":"array","items":{"type":"integer","minimum":0},"description":"Minutes before the start to remind attendees; 0 is at the start (a JSON array in a string also works). Defaults to [15, 0]","examples":[[15,0]]},"startDate":{"type":"string","format":"date-time","description":"When it starts","examples":["2026-10-21T07:00:00.000Z"]},"timeZone":{"type":"string","description":"IANA time zone it is planned in, e.g. Africa/Kampala","examples":["Africa/Kampala"]},"title":{"type":"string","description":"What the event is","examples":["October finance review"]}},"required":["endDate","startDate","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"string","description":"ID of the organizer (firstName, lastName, email are not filled in here)"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","description":"Tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The new event, with its space filled in and people as IDs"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","attendees":[{"userId":"66f1b2c3d4e5f60718293a5c","status":"pending"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":[],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:02.000Z","id":"6ad1c0a2d5c26de56de94a10","version":1,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"spaceId is not a valid ID; endDate is before startDate; a repeating event lasts longer than the gap between its repeats; timeZone is not a valid IANA zone; conversationId is not an ID, comes without meetingProvider kazee, or is not the space's own conversation; an attendee is not an active person in your organisation, or there are over 500; a Kazee call in a space invites someone who is not a member; or a field is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.create"]}],"x-required-scopes":["spaces.calendar.create"]}},"/time-blocks":{"get":{"tags":["Calendar"],"summary":"List my time blocks","description":"Lists your time blocks (the bands like Focus or Meetings drawn behind calendar events), and with spaceIds also the blocks shared to those of the spaces you can see (their members, or anyone if public), with their owners; spaces you cannot see are skipped. Blocks that are not active are left out.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"listTimeBlocks","parameters":[{"name":"spaceIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Also list the blocks shared to these spaces (comma-separated IDs in a string also work)","example":["6a9f3c21b7e4a20f1c5d8e41"]}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"timeBlocks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Name of the block, e.g. Deep work"},"blockType":{"type":"string","description":"Kind of block: focus, meetings, admin, personal, break, custom"},"color":{"type":"string","description":"Colour shown on the calendar"},"startTime":{"type":"string","description":"Start time of day, HH:mm"},"endTime":{"type":"string","description":"End time of day, HH:mm"},"recurrence":{"type":"object","properties":{"daysOfWeek":{"type":"array","items":{"type":"integer"},"description":"Weekdays it repeats on, 0 (Sunday) to 6; empty for a one-off block"}},"description":"When a repeating block comes back"},"userId":{"type":"object","properties":{"firstName":{"type":"string","description":"The owner's first name"},"lastName":{"type":"string","description":"The owner's last name"},"email":{"type":"string","description":"The owner's email address"},"id":{"type":"string","description":"The owner's user ID"}},"description":"The person whose block it is"},"spaceId":{"type":"string","description":"ID of the space it is shared to; absent when it is not shared"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether it is shown; lists leave out blocks that are not"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Time block ID"}}},"description":"Time blocks that are shown, earliest time of day first"}}},"example":{"timeBlocks":[{"title":"Deep work","blockType":"focus","color":"#3b82f6","startTime":"09:00","endTime":"11:00","recurrence":{"daysOfWeek":[1,2,3,4,5]},"userId":{"firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com","id":"66f1b2c3d4e5f60718293a4b"},"spaceId":"6a9f3c21b7e4a20f1c5d8e41","organizationId":"66a4b275003d1b495212b5aa","isActive":true,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z","id":"6ad1c2b0d5c26de56de94a40"}]}}}},"400":{"description":"spaceIds holds a value that is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]},"post":{"tags":["Calendar"],"summary":"Create a time block","description":"Creates a time block of yours, for one day (date) or repeating on weekdays (recurrence), and answers with status 201. Sharing it to a space needs you to see the space.\n\n**Permission:** `spaces.calendar.create` (Create events).","operationId":"createTimeBlock","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blockType":{"type":"string","enum":["focus","meetings","admin","personal","break","custom"],"description":"Kind of block; defaults to focus","examples":["focus"]},"color":{"type":"string","description":"Colour shown on the calendar; defaults to #3b82f6","examples":["#3b82f6"]},"date":{"type":"string","format":"date-time","description":"Day of a one-off block; leave out for a repeating block","examples":["2026-10-20T00:00:00.000Z"]},"endTime":{"type":"string","description":"End time of day, HH:mm","examples":["11:00"]},"recurrence":{"type":"object","properties":{"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}}},"description":"For a repeating block: { daysOfWeek } with 0 for Sunday to 6 (a JSON object in a string also works). Ignored when date is given","examples":[{"daysOfWeek":[1,2,3,4,5]}]},"spaceId":{"type":"string","description":"Space to share the block to","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"startTime":{"type":"string","description":"Start time of day, HH:mm","examples":["09:00"]},"title":{"type":"string","description":"Name of the block","examples":["Deep work"]}},"required":["endTime","startTime","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"timeBlock":{"type":"object","properties":{"title":{"type":"string","description":"Name of the block, e.g. Deep work"},"blockType":{"type":"string","description":"Kind of block: focus, meetings, admin, personal, break, custom"},"color":{"type":"string","description":"Colour shown on the calendar"},"startTime":{"type":"string","description":"Start time of day, HH:mm"},"endTime":{"type":"string","description":"End time of day, HH:mm"},"recurrence":{"type":"object","properties":{"daysOfWeek":{"type":"array","items":{"type":"integer"},"description":"Weekdays it repeats on, 0 (Sunday) to 6; empty for a one-off block"}},"description":"When a repeating block comes back"},"userId":{"type":"string","description":"ID of the person whose block it is"},"spaceId":{"type":"string","description":"ID of the space it is shared to; absent when it is not shared"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether it is shown; lists leave out blocks that are not"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Time block ID"}},"description":"The new time block"}}},"example":{"timeBlock":{"title":"Deep work","blockType":"focus","color":"#3b82f6","startTime":"09:00","endTime":"11:00","recurrence":{"daysOfWeek":[1,2,3,4,5]},"userId":"66f1b2c3d4e5f60718293a4b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","organizationId":"66a4b275003d1b495212b5aa","isActive":true,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z","id":"6ad1c2b0d5c26de56de94a40"}}}}},"400":{"description":"spaceId is not a valid ID, or recurrence is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID that you can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.create"]}],"x-required-scopes":["spaces.calendar.create"]}},"/spaces/{spaceId}/time-blocks":{"get":{"tags":["Calendar"],"summary":"List a space's time blocks","description":"Lists the active time blocks members have shared to a space, with their owners. Open to anyone who can see the space (its members, or anyone if it is public).\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"listSpaceTimeBlocks","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"timeBlocks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Name of the block, e.g. Deep work"},"blockType":{"type":"string","description":"Kind of block: focus, meetings, admin, personal, break, custom"},"color":{"type":"string","description":"Colour shown on the calendar"},"startTime":{"type":"string","description":"Start time of day, HH:mm"},"endTime":{"type":"string","description":"End time of day, HH:mm"},"recurrence":{"type":"object","properties":{"daysOfWeek":{"type":"array","items":{"type":"integer"},"description":"Weekdays it repeats on, 0 (Sunday) to 6; empty for a one-off block"}},"description":"When a repeating block comes back"},"userId":{"type":"object","properties":{"firstName":{"type":"string","description":"The owner's first name"},"lastName":{"type":"string","description":"The owner's last name"},"email":{"type":"string","description":"The owner's email address"},"id":{"type":"string","description":"The owner's user ID"}},"description":"The person whose block it is"},"spaceId":{"type":"string","description":"ID of the space it is shared to; absent when it is not shared"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether it is shown; lists leave out blocks that are not"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Time block ID"}}},"description":"Time blocks shared to the space that are shown, earliest time of day first"}}},"example":{"timeBlocks":[{"title":"Deep work","blockType":"focus","color":"#3b82f6","startTime":"09:00","endTime":"11:00","recurrence":{"daysOfWeek":[1,2,3,4,5]},"userId":{"firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com","id":"66f1b2c3d4e5f60718293a4b"},"spaceId":"6a9f3c21b7e4a20f1c5d8e41","organizationId":"66a4b275003d1b495212b5aa","isActive":true,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z","id":"6ad1c2b0d5c26de56de94a40"}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID that you can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]}},"/activities":{"get":{"tags":["Activity"],"summary":"List my activity feed","description":"Lists what you did anywhere in the organisation, plus what anyone did in the spaces you are a member of (archived spaces left out), newest first.\n\n**Permission:** `spaces.activity.read` (View activity feeds).","operationId":"listUserActivities","parameters":[{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only entries from before this time, for paging: pass the createdAt of the last entry you have. A date that cannot be read answers 400","example":"2026-10-15T09:41:00.000Z"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most entries to return; there is no upper limit","example":50}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"type":"object","properties":{"actorId":{"type":"object","properties":{"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who did it"},"action":{"type":"string","description":"What they did, e.g. task_created, task_updated, task_completed, task_assigned, comment_added, record_stage_changed, wiki_page_updated, event_rsvp, member_added, file_uploaded, email_sent or call_missed"},"targetType":{"type":"string","description":"What it was done to: task, space, pipeline, pipeline_record, wiki_page, event, comment or user"},"targetId":{"type":"string","description":"ID of that item"},"targetTitle":{"type":"string","description":"Its title at the time"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"details":{"type":"object","properties":{"commentId":{"type":"string"},"preview":{"type":"string"},"isReply":{"type":"boolean"}},"description":"What changed; its fields depend on the action (a comment gives commentId, preview and isReply)"},"isPublic":{"type":"boolean","description":"Always true here: only public entries are listed"},"organizationId":{"type":"string","description":"ID of the organisation"},"metadata":{"type":"object","properties":{},"description":"Extra data"},"createdAt":{"type":"string","format":"date-time","description":"When it happened"},"updatedAt":{"type":"string","format":"date-time","description":"When the entry last changed"},"id":{"type":"string","description":"Activity ID"}}},"description":"Activity entries, newest first"}}},"example":{"activities":[{"actorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"action":"comment_added","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","spaceId":"6a9f3c21b7e4a20f1c5d8e41","details":{"commentId":"6ad0a3c2d5c26de56de94a10","preview":"Sent the invoice to the client this morning. Photo of the signed delivery note attached.","isReply":false},"isPublic":true,"organizationId":"66a4b275003d1b495212b5aa","metadata":{},"createdAt":"2026-10-15T09:41:00.000Z","updatedAt":"2026-10-15T09:41:00.000Z","id":"6ad0a3c3d5c26de56de94a13"}]}}}},"400":{"description":"before is not a date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.activity.read"]}],"x-required-scopes":["spaces.activity.read"]}},"/activities/target":{"get":{"tags":["Activity"],"summary":"List an item's history","description":"Lists what happened to one task, wiki page, event, space, pipeline or pipeline record, newest first. A task, page or space-held event is open to anyone who can see its space (its members, or anyone if it is public), except a page of a private wiki: only the space's members; a personal task to its creator and assignees; a personal event to its creator and attendees. A pipeline or record follows getPipeline and getPipelineRecord: open to anyone who can see the pipeline's space, while neither the pipeline nor the record is archived. A pipeline's history holds its stage changes and comments; a record's holds it being added, moved and archived, its comments, and its emails, texts and calls.\n\n**Permission:** `spaces.activity.read` (View activity feeds).","operationId":"listTargetActivities","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"Most entries to return; there is no upper limit","example":20},{"name":"targetId","in":"query","required":true,"schema":{"type":"string"},"description":"ID of that task, wiki page, event, space, pipeline or pipeline record","example":"6ad0a044d5c26de56de949a8"},{"name":"targetType","in":"query","required":true,"schema":{"type":"string","enum":["task","wiki_page","event","space","pipeline","pipeline_record"]},"description":"What kind of item; any other value answers 403","example":"task"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"type":"object","properties":{"actorId":{"type":"object","properties":{"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who did it"},"action":{"type":"string","description":"What they did, e.g. task_created, task_updated, task_completed, task_assigned, comment_added, record_stage_changed, wiki_page_updated, event_rsvp, member_added, file_uploaded, email_sent or call_missed"},"targetType":{"type":"string","description":"What it was done to: task, space, pipeline, pipeline_record, wiki_page, event, comment or user"},"targetId":{"type":"string","description":"ID of that item"},"targetTitle":{"type":"string","description":"Its title at the time"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"details":{"type":"object","properties":{"commentId":{"type":"string"},"preview":{"type":"string"},"isReply":{"type":"boolean"}},"description":"What changed; its fields depend on the action (a comment gives commentId, preview and isReply)"},"isPublic":{"type":"boolean","description":"Always true here: only public entries are listed"},"organizationId":{"type":"string","description":"ID of the organisation"},"metadata":{"type":"object","properties":{},"description":"Extra data"},"createdAt":{"type":"string","format":"date-time","description":"When it happened"},"updatedAt":{"type":"string","format":"date-time","description":"When the entry last changed"},"id":{"type":"string","description":"Activity ID"}}},"description":"Activity entries, newest first"}}},"example":{"activities":[{"actorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"action":"comment_added","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","spaceId":"6a9f3c21b7e4a20f1c5d8e41","details":{"commentId":"6ad0a3c2d5c26de56de94a10","preview":"Sent the invoice to the client this morning. Photo of the signed delivery note attached.","isReply":false},"isPublic":true,"organizationId":"66a4b275003d1b495212b5aa","metadata":{},"createdAt":"2026-10-15T09:41:00.000Z","updatedAt":"2026-10-15T09:41:00.000Z","id":"6ad0a3c3d5c26de56de94a13"}]}}}},"400":{"description":"targetId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not see the item (see above), it does not exist (or is archived, for a pipeline or record), or targetType is not one listed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.activity.read"]}],"x-required-scopes":["spaces.activity.read"]}},"/spaces/{spaceId}/activities":{"get":{"tags":["Activity"],"summary":"List a space's activity","description":"Lists what happened in a space, newest first. Open to its members, and to anyone in the organisation when the space is public; the pages of its private wikis are then left out for those who are not members.\n\n**Permission:** `spaces.activity.read` (View activity feeds).","operationId":"listSpaceActivities","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only entries from before this time, for paging: pass the createdAt of the last entry you have. A date that cannot be read answers 400","example":"2026-10-15T09:41:00.000Z"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most entries to return; there is no upper limit","example":50}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"type":"object","properties":{"actorId":{"type":"object","properties":{"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who did it"},"action":{"type":"string","description":"What they did, e.g. task_created, task_updated, task_completed, task_assigned, comment_added, record_stage_changed, wiki_page_updated, event_rsvp, member_added, file_uploaded, email_sent or call_missed"},"targetType":{"type":"string","description":"What it was done to: task, space, pipeline, pipeline_record, wiki_page, event, comment or user"},"targetId":{"type":"string","description":"ID of that item"},"targetTitle":{"type":"string","description":"Its title at the time"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"details":{"type":"object","properties":{"commentId":{"type":"string"},"preview":{"type":"string"},"isReply":{"type":"boolean"}},"description":"What changed; its fields depend on the action (a comment gives commentId, preview and isReply)"},"isPublic":{"type":"boolean","description":"Always true here: only public entries are listed"},"organizationId":{"type":"string","description":"ID of the organisation"},"metadata":{"type":"object","properties":{},"description":"Extra data"},"createdAt":{"type":"string","format":"date-time","description":"When it happened"},"updatedAt":{"type":"string","format":"date-time","description":"When the entry last changed"},"id":{"type":"string","description":"Activity ID"}}},"description":"Activity entries, newest first"}}},"example":{"activities":[{"actorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"action":"comment_added","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","spaceId":"6a9f3c21b7e4a20f1c5d8e41","details":{"commentId":"6ad0a3c2d5c26de56de94a10","preview":"Sent the invoice to the client this morning. Photo of the signed delivery note attached.","isReply":false},"isPublic":true,"organizationId":"66a4b275003d1b495212b5aa","metadata":{},"createdAt":"2026-10-15T09:41:00.000Z","updatedAt":"2026-10-15T09:41:00.000Z","id":"6ad0a3c3d5c26de56de94a13"}]}}}},"400":{"description":"spaceId is not a valid ID, or before is not a date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID that you can see: it does not exist, is archived, or is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.activity.read"]}],"x-required-scopes":["spaces.activity.read"]}},"/users":{"get":{"tags":["People"],"summary":"List people in my organisation","description":"Lists the people in your organisation who are not disabled, for people pickers. search narrows the list; there is no paging, so at most 500 people come back.\n\n**Permission:** `spaces.users.read` (View users).","operationId":"listUsers","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200},"description":"Most people to return; over 500 counts as 500, and a value that is not a positive number gives 200","example":50},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Text to find in the first name, last name, full name or email, ignoring case. It is matched as written, so characters like ( or + are plain characters","example":"namu"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"name":{"type":"string","description":"Full name; made from the first and last name when none is stored"},"email":{"type":"string","description":"Email address"},"profilePicture":{"type":"string","description":"Link to their photo; for people with none stored it is fetched from Kazee Chat, and absent when there is none"},"role":{"type":"string","description":"Their role in the organisation, from iNet Central, e.g. user"}}},"description":"People in your organisation who are not disabled, sorted by first name, last name, then email"},"count":{"type":"integer","description":"How many people are in this answer"}}},"example":{"users":[{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Grace","lastName":"Namutebi","name":"Grace Namutebi","email":"grace.namutebi@example.com","profilePicture":"https://chat.kazee.africa/media/profiles/66f1b2c3d4e5f60718293a4b.jpg","role":"user"}],"count":1}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.read"]}],"x-required-scopes":["spaces.users.read"]}},"/users/sidebar-preferences":{"get":{"tags":["People"],"summary":"Get my sidebar layout","description":"Gets how you arranged spaces in your sidebar: starred spaces, their order and your own groups. Someone who never changed it gets empty lists.\n\n**Permission:** `spaces.users.read` (View users).","operationId":"getSidebarPreferences","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"sidebarPreferences":{"type":"object","properties":{"starredSpaceIds":{"type":"array","items":{"type":"string"},"description":"IDs of the spaces you starred"},"spaceOrder":{"type":"array","items":{"type":"string"},"description":"Space IDs in the order you put them"},"spaceGroups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The group's ID, chosen by the app that made it"},"name":{"type":"string","description":"The group's name"},"spaceIds":{"type":"array","items":{"type":"string"},"description":"IDs of the spaces in the group"},"collapsed":{"type":"boolean","description":"Whether the group is folded shut"}}},"description":"Your own groups of spaces"}},"description":"How you arranged the spaces in your sidebar; empty lists until you change anything"}}},"example":{"sidebarPreferences":{"starredSpaceIds":["6a9f3c21b7e4a20f1c5d8e41"],"spaceOrder":["6a9f3c21b7e4a20f1c5d8e41","6a9f3c21b7e4a20f1c5d8e52"],"spaceGroups":[{"id":"group-finance","name":"Finance and admin","spaceIds":["6a9f3c21b7e4a20f1c5d8e41","6a9f3c21b7e4a20f1c5d8e52"],"collapsed":false}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.read"]}],"x-required-scopes":["spaces.users.read"]},"put":{"tags":["People"],"summary":"Update my sidebar layout","description":"Saves how you arranged spaces in your sidebar. Each list you send replaces the stored one; lists you leave out stay as they are. The IDs are stored as given, without checking the spaces.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"updateSidebarPreferences","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"spaceGroups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"spaceIds":{"type":"array","items":{"type":"string"}},"collapsed":{"type":"boolean"}}},"description":"Your groups of spaces, replacing the list: each { id, name, spaceIds, collapsed }, where id is any text your app chooses and collapsed defaults to false","examples":[[{"id":"group-finance","name":"Finance and admin","spaceIds":["6a9f3c21b7e4a20f1c5d8e41","6a9f3c21b7e4a20f1c5d8e52"],"collapsed":false}]]},"spaceOrder":{"type":"array","items":{"type":"string"},"description":"Space IDs in the order you want them, replacing the list","examples":[["6a9f3c21b7e4a20f1c5d8e41","6a9f3c21b7e4a20f1c5d8e52"]]},"starredSpaceIds":{"type":"array","items":{"type":"string"},"description":"IDs of the spaces you starred, replacing the list","examples":[["6a9f3c21b7e4a20f1c5d8e41"]]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"sidebarPreferences":{"type":"object","properties":{"starredSpaceIds":{"type":"array","items":{"type":"string"},"description":"IDs of the spaces you starred"},"spaceOrder":{"type":"array","items":{"type":"string"},"description":"Space IDs in the order you put them"},"spaceGroups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The group's ID, chosen by the app that made it"},"name":{"type":"string","description":"The group's name"},"spaceIds":{"type":"array","items":{"type":"string"},"description":"IDs of the spaces in the group"},"collapsed":{"type":"boolean","description":"Whether the group is folded shut"}}},"description":"Your own groups of spaces"}},"description":"Your sidebar layout after the change"}}},"example":{"sidebarPreferences":{"starredSpaceIds":["6a9f3c21b7e4a20f1c5d8e41"],"spaceOrder":["6a9f3c21b7e4a20f1c5d8e41","6a9f3c21b7e4a20f1c5d8e52"],"spaceGroups":[{"id":"group-finance","name":"Finance and admin","spaceIds":["6a9f3c21b7e4a20f1c5d8e41","6a9f3c21b7e4a20f1c5d8e52"],"collapsed":false}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]}},"/users/{userId}":{"get":{"tags":["People"],"summary":"Get a person","description":"Gets one person in your organisation by ID, disabled people included. The photo is only the one stored in Spaces; unlike listUsers it is not fetched from Kazee Chat.\n\n**Permission:** `spaces.users.read` (View users).","operationId":"getUser","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the person","example":"66f1b2c3d4e5f60718293a4b"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"name":{"type":"string","description":"Full name; made from the first and last name when none is stored"},"email":{"type":"string","description":"Email address"},"profilePicture":{"type":"string","description":"Link to their photo as stored in Spaces; absent when there is none"},"role":{"type":"string","description":"Their role in the organisation, from iNet Central, e.g. user"}},"description":"The person"}}},"example":{"user":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Grace","lastName":"Namutebi","name":"Grace Namutebi","email":"grace.namutebi@example.com","profilePicture":"https://chat.kazee.africa/media/profiles/66f1b2c3d4e5f60718293a4b.jpg","role":"user"}}}}},"400":{"description":"userId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No person with that ID in your organisation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.read"]}],"x-required-scopes":["spaces.users.read"]}},"/views":{"get":{"tags":["Saved views"],"summary":"List my saved views","description":"Lists your own saved views for one screen: My Tasks, one space's tasks, or one pipeline board. Nobody else's views are included.\n\n**Permission:** `spaces.users.read` (View users).","operationId":"listSavedViews","parameters":[{"name":"context","in":"query","required":true,"schema":{"type":"string","enum":["my-tasks","space-tasks","pipeline"]},"description":"The screen: my-tasks (your My Tasks page), space-tasks (a space's tasks) or pipeline (a pipeline board)","example":"space-tasks"},{"name":"contextId","in":"query","required":false,"schema":{"type":"string"},"description":"ID of the space for space-tasks, or of the pipeline for pipeline; leave out for my-tasks. An empty text or null also mean none. It is not checked","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"views":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"View ID"},"organizationId":{"type":"string","description":"ID of the organisation"},"userId":{"type":"string","description":"User ID of the owner; views are personal"},"context":{"type":"string","description":"The screen it belongs to: my-tasks, space-tasks or pipeline"},"contextId":{"type":"string","description":"ID of the space (space-tasks) or pipeline (pipeline); null for my-tasks"},"name":{"type":"string","description":"Name of the view"},"filters":{"type":"object","properties":{"priority":{"type":"object","properties":{"operator":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"dueDate":{"type":"object","properties":{"preset":{"type":"string"}}}},"description":"Filter conditions by field, as they were saved; absent when there are none"},"search":{"type":"string","description":"Search text; empty when none"},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string"}},"description":"Sort field and direction (asc or desc); absent when not set"},"display":{"type":"object","properties":{"viewMode":{"type":"string"},"groupBy":{"type":"string"},"compactView":{"type":"boolean"}},"description":"How the screen shows it (viewMode, groupBy, compactView); absent when not set"},"isDefault":{"type":"boolean","description":"Whether it opens by default on that screen"},"order":{"type":"integer","description":"Position among your views on that screen; lower comes first"},"visibility":{"type":"string","description":"Always private for now: only you see it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"View ID (same as _id)"}}},"description":"Your saved views on that screen, in your order, then oldest first"}}},"example":{"views":[{"_id":"6ad0a0f4d5c26de56de949f8","organizationId":"66a4b275003d1b495212b5aa","userId":"66f1b2c3d4e5f60718293a4b","context":"space-tasks","contextId":"6a9f3c21b7e4a20f1c5d8e41","name":"Overdue criticals","filters":{"priority":{"operator":"is","values":["critical"]},"dueDate":{"preset":"last_7_days"}},"search":"","sort":{"field":"dueDate","direction":"asc"},"display":{"viewMode":"board","groupBy":"status","compactView":false},"isDefault":false,"order":2,"visibility":"private","createdAt":"2026-10-10T07:20:00.000Z","updatedAt":"2026-10-14T15:45:00.000Z","id":"6ad0a0f4d5c26de56de949f8"}]}}}},"400":{"description":"context is not my-tasks, space-tasks or pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.read"]}],"x-required-scopes":["spaces.users.read"]},"post":{"tags":["Saved views"],"summary":"Create a saved view","description":"Saves a view of a screen (its filters, search, sort and layout) for you alone. It goes after your other views there, and you can keep up to 50 per screen. With isDefault true it becomes the view that opens by default, in place of the old default.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"createSavedView","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"context":{"type":"string","enum":["my-tasks","space-tasks","pipeline"],"description":"The screen: my-tasks (your My Tasks page), space-tasks (a space's tasks) or pipeline (a pipeline board)","examples":["space-tasks"]},"contextId":{"type":"string","description":"ID of the space for space-tasks, or of the pipeline for pipeline; leave out for my-tasks. An empty text or null also mean none. It is not checked","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"display":{"type":"object","properties":{"viewMode":{"type":"string"},"groupBy":{"type":"string"},"compactView":{"type":"boolean"}},"description":"How the screen shows the view: viewMode, groupBy and compactView, as the apps use them. A JSON object in a string also works","examples":[{"viewMode":"board","groupBy":"status","compactView":false}]},"filters":{"type":"object","description":"Filter conditions by field, stored as given: field -> { operator, value } or { operator, values }, or { from, to } for a range. A date range may hold a preset such as last_7_days instead, which the apps work out when they apply the view. A JSON object in a string also works","examples":[{"priority":{"operator":"is","values":["critical"]},"dueDate":{"preset":"last_7_days"}}]},"isDefault":{"type":"boolean","description":"true makes it the view that opens by default on that screen, in place of the old default. The text \"true\" also works","examples":[false]},"name":{"type":"string","maxLength":80,"description":"Name of the view, up to 80 characters; spaces at either end are trimmed","examples":["Overdue criticals"]},"search":{"type":"string","description":"Search text to keep with the view","examples":["invoice"]},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"description":"Sort field and direction (asc or desc; asc when left out). A JSON object in a string also works","examples":[{"field":"dueDate","direction":"asc"}]}},"required":["context","name"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"object","properties":{"_id":{"type":"string","description":"View ID"},"organizationId":{"type":"string","description":"ID of the organisation"},"userId":{"type":"string","description":"User ID of the owner; views are personal"},"context":{"type":"string","description":"The screen it belongs to: my-tasks, space-tasks or pipeline"},"contextId":{"type":"string","description":"ID of the space (space-tasks) or pipeline (pipeline); null for my-tasks"},"name":{"type":"string","description":"Name of the view"},"filters":{"type":"object","properties":{"priority":{"type":"object","properties":{"operator":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"dueDate":{"type":"object","properties":{"preset":{"type":"string"}}}},"description":"Filter conditions by field, as they were saved; absent when there are none"},"search":{"type":"string","description":"Search text; empty when none"},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string"}},"description":"Sort field and direction (asc or desc); absent when not set"},"display":{"type":"object","properties":{"viewMode":{"type":"string"},"groupBy":{"type":"string"},"compactView":{"type":"boolean"}},"description":"How the screen shows it (viewMode, groupBy, compactView); absent when not set"},"isDefault":{"type":"boolean","description":"Whether it opens by default on that screen"},"order":{"type":"integer","description":"Position among your views on that screen; lower comes first"},"visibility":{"type":"string","description":"Always private for now: only you see it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"View ID (same as _id)"}}}}},"example":{"view":{"_id":"6ad0a0f4d5c26de56de949f8","organizationId":"66a4b275003d1b495212b5aa","userId":"66f1b2c3d4e5f60718293a4b","context":"space-tasks","contextId":"6a9f3c21b7e4a20f1c5d8e41","name":"Overdue criticals","filters":{"priority":{"operator":"is","values":["critical"]},"dueDate":{"preset":"last_7_days"}},"search":"","sort":{"field":"dueDate","direction":"asc"},"display":{"viewMode":"board","groupBy":"status","compactView":false},"isDefault":false,"order":2,"visibility":"private","createdAt":"2026-10-10T07:20:00.000Z","updatedAt":"2026-10-10T07:20:00.000Z","id":"6ad0a0f4d5c26de56de949f8"}}}}},"400":{"description":"context is not one of the three screens, name is empty or longer than 80 characters, sort.direction is not asc or desc, or you already have 50 views on that screen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]}},"/spaces/{spaceId}/wikis":{"get":{"tags":["Docs"],"summary":"List a space's wikis","description":"Lists the wikis in a space that are not archived, most recently active first, each with its page templates. Open to members of the space, and to anyone if the space is public; private wikis are listed only for the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"listWikis","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"wikis":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the wiki, up to 100 characters"},"description":{"type":"string","description":"What the wiki is for, up to 500 characters; absent when not set"},"slug":{"type":"string","description":"The name in lower case, with a dash for each run of other characters, or 8 random letters and digits when the name has no letter a-z or digit; unique in the space. Archiving adds -archived- and a time to it, freeing the name"},"icon":{"type":"string","description":"Emoji shown with the wiki; 📚 unless set"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"visibility":{"type":"string","description":"public, private or members. private: only the space's members (any role) see the wiki, its pages and their comments. members and public: anyone who can see the space"},"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"What the template is for; may be empty"},"icon":{"type":"string","description":"Emoji shown with the template"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The body a page made from it starts with. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Absent when the template is blank"},"_id":{"type":"string","description":"Template ID; pass it as templateId to make a page from it"}}},"description":"Page templates for new pages in this wiki. A new wiki starts with Blank Page, Meeting Notes, How-To Guide and FAQ"},"settings":{"type":"object","properties":{"allowComments":{"type":"boolean","description":"Whether people may comment on its pages; createWikiComment refuses when false"},"allowPublicAccess":{"type":"boolean","description":"Stored only; nothing reads it yet"},"defaultPageStatus":{"type":"string","description":"draft or published: the status new pages start with, made one by one or imported"}},"description":"The wiki's settings"},"pageCount":{"type":"integer","description":"How many of its pages are not archived, as last counted when a page was made, archived, deleted or imported"},"lastActivityAt":{"type":"string","format":"date-time","description":"When a page in it was last made or edited; when it was made until then"},"isArchived":{"type":"boolean","description":"Always false here: archived wikis are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, page count and activity time included"},"id":{"type":"string","description":"Wiki ID"}}},"description":"The space's wikis that are not archived, most recently active first; private ones only if you are a member of the space"}}},"example":{"wikis":[{"name":"Staff handbook","description":"How we work: leave, expenses and onboarding.","slug":"staff-handbook","icon":"📚","coverImage":"https://images.example.com/covers/handbook.jpg","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"visibility":"members","templates":[{"name":"Meeting Notes","description":"Template for meeting notes","icon":"📝","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Meeting Notes"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Attendees"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Agenda"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Action Items"}]},{"type":"taskList","content":[{"type":"taskItem","attrs":{"checked":false},"content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f3"},{"name":"How-To Guide","description":"Step-by-step instructions","icon":"📖","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"How to [Task Name]"}]},{"type":"paragraph","content":[{"type":"text","text":"Brief description of what this guide covers."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Prerequisites"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Steps"}]},{"type":"orderedList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f4"},{"name":"FAQ","description":"Frequently asked questions","icon":"❓","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Frequently Asked Questions"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Question 1?"}]},{"type":"paragraph","content":[{"type":"text","text":"Answer to question 1."}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f5"},{"name":"Policy page","description":"A policy with who it covers and how to apply it","icon":"📜","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Who this covers"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to apply it"}]},{"type":"paragraph"}]},"_id":"6ad1b0d8e4f5a6b7c8d9e0f9"}],"settings":{"allowComments":true,"allowPublicAccess":false,"defaultPageStatus":"published"},"pageCount":12,"lastActivityAt":"2026-10-15T09:20:00.000Z","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","id":"6ad1b0c2e4f5a6b7c8d9e0f1"}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID, it is archived, or you cannot see it (you are not a member and it is not public)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]},"post":{"tags":["Docs"],"summary":"Create a wiki","description":"Creates a wiki in a space and answers with status 201. Needs the editor role in the space. The wiki starts with four page templates: Blank Page, Meeting Notes, How-To Guide and FAQ. It is not added to the space's list of items.\n\n**Permission:** `spaces.wiki.create` (Create wikis).","operationId":"createWiki","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space to put it in","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coverImage":{"type":"string","description":"Address of a cover picture","examples":["https://images.example.com/covers/handbook.jpg"]},"description":{"type":"string","description":"What the wiki is for, up to 500 characters","examples":["How we work: leave, expenses and onboarding."]},"icon":{"type":"string","description":"Emoji for the wiki. Defaults to 📚","examples":["📚"]},"name":{"type":"string","description":"Name of the wiki, up to 100 characters. Its slug (lower case, with dashes; 8 random letters and digits when the name has no letter a-z or digit) must be unique in the space","examples":["Staff handbook"]},"visibility":{"type":"string","enum":["public","private","members"],"description":"private: only the space's members (any role) can see the wiki, its pages and their comments. members and public: anyone who can see the space (its members, or anyone if the space is public). Defaults to members","examples":["members"]}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"wiki":{"type":"object","properties":{"name":{"type":"string","description":"Name of the wiki, up to 100 characters"},"description":{"type":"string","description":"What the wiki is for, up to 500 characters; absent when not set"},"slug":{"type":"string","description":"The name in lower case, with a dash for each run of other characters, or 8 random letters and digits when the name has no letter a-z or digit; unique in the space. Archiving adds -archived- and a time to it, freeing the name"},"icon":{"type":"string","description":"Emoji shown with the wiki; 📚 unless set"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"visibility":{"type":"string","description":"public, private or members. private: only the space's members (any role) see the wiki, its pages and their comments. members and public: anyone who can see the space"},"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"What the template is for; may be empty"},"icon":{"type":"string","description":"Emoji shown with the template"},"_id":{"type":"string","description":"Template ID; pass it as templateId to make a page from it"}}},"description":"The four page templates every new wiki starts with: Blank Page, Meeting Notes, How-To Guide and FAQ. Each has _id, name, description and icon, and all but Blank Page have content (the body a page made from it starts with)"},"settings":{"type":"object","properties":{"allowComments":{"type":"boolean","description":"Whether people may comment on its pages; createWikiComment refuses when false"},"allowPublicAccess":{"type":"boolean","description":"Stored only; nothing reads it yet"},"defaultPageStatus":{"type":"string","description":"draft or published: the status new pages start with, made one by one or imported"}},"description":"The wiki's settings"},"pageCount":{"type":"integer","description":"How many of its pages are not archived: 0 for a new wiki"},"lastActivityAt":{"type":"string","format":"date-time","description":"When a page in it was last made or edited; when it was made until then"},"isArchived":{"type":"boolean","description":"Always false here: archived wikis are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, page count and activity time included"},"id":{"type":"string","description":"Wiki ID"}}}}},"example":{"wiki":{"name":"Staff handbook","description":"How we work: leave, expenses and onboarding.","slug":"staff-handbook","icon":"📚","coverImage":"https://images.example.com/covers/handbook.jpg","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"visibility":"members","templates":[{"name":"Blank Page","description":"Start with a blank page","icon":"📄","_id":"6ad1b0c2e4f5a6b7c8d9e0f2"},{"name":"Meeting Notes","description":"Template for meeting notes","icon":"📝","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Meeting Notes"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Attendees"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Agenda"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Action Items"}]},{"type":"taskList","content":[{"type":"taskItem","attrs":{"checked":false},"content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f3"},{"name":"How-To Guide","description":"Step-by-step instructions","icon":"📖","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"How to [Task Name]"}]},{"type":"paragraph","content":[{"type":"text","text":"Brief description of what this guide covers."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Prerequisites"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Steps"}]},{"type":"orderedList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f4"},{"name":"FAQ","description":"Frequently asked questions","icon":"❓","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Frequently Asked Questions"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Question 1?"}]},{"type":"paragraph","content":[{"type":"text","text":"Answer to question 1."}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f5"}],"settings":{"allowComments":true,"allowPublicAccess":false,"defaultPageStatus":"published"},"pageCount":0,"lastActivityAt":"2026-10-15T08:00:00.000Z","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z","id":"6ad1b0c2e4f5a6b7c8d9e0f1"}}}}},"400":{"description":"spaceId is not a valid ID, a wiki in the space already has a name that gives the same slug, the name is over 100 characters or the description over 500, or visibility is not public, private or members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the space with the editor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.create"]}],"x-required-scopes":["spaces.wiki.create"]}},"/wikis/{wikiId}":{"get":{"tags":["Docs"],"summary":"Get a wiki","description":"Gets one wiki with its five most recently changed pages and a fresh count of its pages. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"getWiki","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"},{"name":"slug","in":"query","required":false,"schema":{"type":"string"},"description":"Not used on this route; read only with spaceId when no wikiId is given","example":"staff-handbook"},{"name":"spaceId","in":"query","required":false,"schema":{"type":"string"},"description":"Not used on this route, where the wiki ID in the path always wins. Read only when no wikiId is given: with slug, finds the wiki by its slug in this space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"wiki":{"type":"object","properties":{"name":{"type":"string","description":"Name of the wiki, up to 100 characters"},"description":{"type":"string","description":"What the wiki is for, up to 500 characters; absent when not set"},"slug":{"type":"string","description":"The name in lower case, with a dash for each run of other characters, or 8 random letters and digits when the name has no letter a-z or digit; unique in the space. Archiving adds -archived- and a time to it, freeing the name"},"icon":{"type":"string","description":"Emoji shown with the wiki; 📚 unless set"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"visibility":{"type":"string","description":"public, private or members. private: only the space's members (any role) see the wiki, its pages and their comments. members and public: anyone who can see the space"},"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"What the template is for; may be empty"},"icon":{"type":"string","description":"Emoji shown with the template"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The body a page made from it starts with. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Absent when the template is blank"},"_id":{"type":"string","description":"Template ID; pass it as templateId to make a page from it"}}},"description":"Page templates for new pages in this wiki. A new wiki starts with Blank Page, Meeting Notes, How-To Guide and FAQ"},"settings":{"type":"object","properties":{"allowComments":{"type":"boolean","description":"Whether people may comment on its pages; createWikiComment refuses when false"},"allowPublicAccess":{"type":"boolean","description":"Stored only; nothing reads it yet"},"defaultPageStatus":{"type":"string","description":"draft or published: the status new pages start with, made one by one or imported"}},"description":"The wiki's settings"},"pageCount":{"type":"integer","description":"How many of its pages are not archived, as last counted when a page was made, archived, deleted or imported"},"lastActivityAt":{"type":"string","format":"date-time","description":"When a page in it was last made or edited; when it was made until then"},"isArchived":{"type":"boolean","description":"Always false here: archived wikis are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, page count and activity time included"},"id":{"type":"string","description":"Wiki ID"}}},"recentPages":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The page's slug"},"icon":{"type":"string","description":"Emoji shown with the page"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content: id, firstName, lastName and email; null if that person is no longer on record"},"updatedAt":{"type":"string","format":"date-time","description":"When the page last changed"},"id":{"type":"string","description":"Page ID"}}},"description":"Its five most recently changed pages that are not archived, latest first"},"pageCount":{"type":"integer","description":"How many of its pages are not archived, counted now"}}},"example":{"wiki":{"name":"Staff handbook","description":"How we work: leave, expenses and onboarding.","slug":"staff-handbook","icon":"📚","coverImage":"https://images.example.com/covers/handbook.jpg","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"visibility":"members","templates":[{"name":"Meeting Notes","description":"Template for meeting notes","icon":"📝","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Meeting Notes"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Attendees"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Agenda"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Action Items"}]},{"type":"taskList","content":[{"type":"taskItem","attrs":{"checked":false},"content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f3"},{"name":"How-To Guide","description":"Step-by-step instructions","icon":"📖","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"How to [Task Name]"}]},{"type":"paragraph","content":[{"type":"text","text":"Brief description of what this guide covers."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Prerequisites"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Steps"}]},{"type":"orderedList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f4"},{"name":"FAQ","description":"Frequently asked questions","icon":"❓","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Frequently Asked Questions"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Question 1?"}]},{"type":"paragraph","content":[{"type":"text","text":"Answer to question 1."}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f5"},{"name":"Policy page","description":"A policy with who it covers and how to apply it","icon":"📜","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Who this covers"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to apply it"}]},{"type":"paragraph"}]},"_id":"6ad1b0d8e4f5a6b7c8d9e0f9"}],"settings":{"allowComments":true,"allowPublicAccess":false,"defaultPageStatus":"published"},"pageCount":12,"lastActivityAt":"2026-10-15T09:20:00.000Z","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","id":"6ad1b0c2e4f5a6b7c8d9e0f1"},"recentPages":[{"title":"Leave policy","slug":"leave-policy","icon":"🌴","lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"updatedAt":"2026-10-15T09:20:00.000Z","id":"6ad1b11ce4f5a6b7c8d9e10c"}],"pageCount":12}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the wiki's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]},"put":{"tags":["Docs"],"summary":"Update a wiki","description":"Changes a wiki's details; only the inputs you send change. Needs the editor role in its space. A new name also changes the wiki's slug, and settings is merged into the current settings.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"updateWiki","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"coverImage":{"type":"string","description":"Address of a cover picture","examples":["https://images.example.com/covers/handbook.jpg"]},"description":{"type":"string","description":"What the wiki is for, up to 500 characters","examples":["How we work: leave, expenses and onboarding."]},"icon":{"type":"string","description":"Emoji for the wiki","examples":["📚"]},"name":{"type":"string","description":"New name, up to 100 characters; its slug changes with it and must stay unique in the space","examples":["Staff handbook"]},"settings":{"type":"object","properties":{"allowComments":{"type":"boolean"},"allowPublicAccess":{"type":"boolean"},"defaultPageStatus":{"type":"string","enum":["draft","published"]}},"description":"Settings to change; keys you leave out keep their value. allowComments false stops new comments on its pages. defaultPageStatus is the status new pages start with. allowPublicAccess is stored only: nothing reads it yet","examples":[{"allowComments":false}]},"visibility":{"type":"string","enum":["public","private","members"],"description":"private: only the space's members (any role) can see the wiki, its pages and their comments. members and public: anyone who can see the space (its members, or anyone if the space is public)","examples":["members"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"wiki":{"type":"object","properties":{"name":{"type":"string","description":"Name of the wiki, up to 100 characters"},"description":{"type":"string","description":"What the wiki is for, up to 500 characters; absent when not set"},"slug":{"type":"string","description":"The name in lower case, with a dash for each run of other characters, or 8 random letters and digits when the name has no letter a-z or digit; unique in the space. Archiving adds -archived- and a time to it, freeing the name"},"icon":{"type":"string","description":"Emoji shown with the wiki; 📚 unless set"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"visibility":{"type":"string","description":"public, private or members. private: only the space's members (any role) see the wiki, its pages and their comments. members and public: anyone who can see the space"},"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"What the template is for; may be empty"},"icon":{"type":"string","description":"Emoji shown with the template"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The body a page made from it starts with. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Absent when the template is blank"},"_id":{"type":"string","description":"Template ID; pass it as templateId to make a page from it"}}},"description":"Page templates for new pages in this wiki. A new wiki starts with Blank Page, Meeting Notes, How-To Guide and FAQ"},"settings":{"type":"object","properties":{"allowComments":{"type":"boolean","description":"Whether people may comment on its pages; createWikiComment refuses when false"},"allowPublicAccess":{"type":"boolean","description":"Stored only; nothing reads it yet"},"defaultPageStatus":{"type":"string","description":"draft or published: the status new pages start with, made one by one or imported"}},"description":"The wiki's settings"},"pageCount":{"type":"integer","description":"How many of its pages are not archived, as last counted when a page was made, archived, deleted or imported"},"lastActivityAt":{"type":"string","format":"date-time","description":"When a page in it was last made or edited; when it was made until then"},"isArchived":{"type":"boolean","description":"Always false here: archived wikis are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, page count and activity time included"},"id":{"type":"string","description":"Wiki ID"}}}}},"example":{"wiki":{"name":"Staff handbook","description":"How we work: leave, expenses and onboarding.","slug":"staff-handbook","icon":"📚","coverImage":"https://images.example.com/covers/handbook.jpg","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"visibility":"members","templates":[{"name":"Meeting Notes","description":"Template for meeting notes","icon":"📝","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Meeting Notes"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Attendees"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Agenda"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Action Items"}]},{"type":"taskList","content":[{"type":"taskItem","attrs":{"checked":false},"content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f3"},{"name":"How-To Guide","description":"Step-by-step instructions","icon":"📖","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"How to [Task Name]"}]},{"type":"paragraph","content":[{"type":"text","text":"Brief description of what this guide covers."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Prerequisites"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Steps"}]},{"type":"orderedList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f4"},{"name":"FAQ","description":"Frequently asked questions","icon":"❓","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Frequently Asked Questions"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Question 1?"}]},{"type":"paragraph","content":[{"type":"text","text":"Answer to question 1."}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f5"},{"name":"Policy page","description":"A policy with who it covers and how to apply it","icon":"📜","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Who this covers"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to apply it"}]},{"type":"paragraph"}]},"_id":"6ad1b0d8e4f5a6b7c8d9e0f9"}],"settings":{"allowComments":true,"allowPublicAccess":false,"defaultPageStatus":"published"},"pageCount":12,"lastActivityAt":"2026-10-15T09:20:00.000Z","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","id":"6ad1b0c2e4f5a6b7c8d9e0f1"}}}}},"400":{"description":"wikiId is not a valid ID, another wiki in the space already has a name that gives the same slug, the new name is empty, a text is too long, or visibility or settings.defaultPageStatus is not one it accepts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the wiki's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]},"delete":{"tags":["Docs"],"summary":"Archive or delete a wiki","description":"Archives a wiki and all its pages, or with permanent deletes it for good. Archiving needs the editor role in its space and hides the wiki and its pages; there is no call to bring them back yet. Archiving adds -archived- and a time to the slugs of the wiki and its pages, so a new wiki or page can take their names. Deleting for good needs the owner role, works on an archived wiki too, and also removes all its pages, every comment on them and the wiki's entry in the space's list of items.\n\n**Permission:** `spaces.wiki.delete` (Archive wikis).","operationId":"deleteWiki","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"},{"name":"permanent","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true (or 1) deletes the wiki for good instead of archiving it; false, 0 or leaving it out archives it"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"permanent":{"type":"boolean","description":"true when the wiki was deleted for good, false when it was archived"},"archivedPagesCount":{"type":"integer","description":"How many of its pages were archived with it. When deleting for good, deletedPagesCount (how many pages were removed) comes instead"}}},"example":{"success":true,"permanent":false,"archivedPagesCount":12}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Archiving needs the editor role in the wiki's space, deleting for good the owner role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or you are archiving a wiki that is already archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.delete"]}],"x-required-scopes":["spaces.wiki.delete"]}},"/wikis/{wikiId}/templates":{"get":{"tags":["Docs"],"summary":"List a wiki's page templates","description":"Lists a wiki's page templates, in the order they were added; a new wiki has Blank Page, Meeting Notes, How-To Guide and FAQ. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"listWikiTemplates","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"What the template is for; may be empty"},"icon":{"type":"string","description":"Emoji shown with the template"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The body a page made from it starts with. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Absent when the template is blank"},"_id":{"type":"string","description":"Template ID; pass it as templateId to make a page from it"}}},"description":"The wiki's page templates, in the order they were added"}}},"example":{"templates":[{"name":"Meeting Notes","description":"Template for meeting notes","icon":"📝","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Meeting Notes"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Attendees"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Agenda"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Action Items"}]},{"type":"taskList","content":[{"type":"taskItem","attrs":{"checked":false},"content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f3"},{"name":"How-To Guide","description":"Step-by-step instructions","icon":"📖","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"How to [Task Name]"}]},{"type":"paragraph","content":[{"type":"text","text":"Brief description of what this guide covers."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Prerequisites"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Steps"}]},{"type":"orderedList","content":[{"type":"listItem","content":[{"type":"paragraph"}]}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f4"},{"name":"FAQ","description":"Frequently asked questions","icon":"❓","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Frequently Asked Questions"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"text","text":"Question 1?"}]},{"type":"paragraph","content":[{"type":"text","text":"Answer to question 1."}]}]},"_id":"6ad1b0c2e4f5a6b7c8d9e0f5"},{"name":"Policy page","description":"A policy with who it covers and how to apply it","icon":"📜","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Who this covers"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to apply it"}]},{"type":"paragraph"}]},"_id":"6ad1b0d8e4f5a6b7c8d9e0f9"}]}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the wiki's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]},"post":{"tags":["Docs"],"summary":"Add a page template to a wiki","description":"Adds a page template to a wiki and answers with status 201. Needs the editor role in its space. New pages start from it when createWikiPage gets its _id as templateId.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"addWikiTemplate","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"object","description":"The body pages made from it start with. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text","examples":[{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Who this covers"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to apply it"}]},{"type":"paragraph"}]}]},"description":{"type":"string","description":"What the template is for. Defaults to empty","examples":["A policy with who it covers and how to apply it"]},"icon":{"type":"string","description":"Emoji for the template. Defaults to 📄","examples":["📜"]},"name":{"type":"string","description":"Template name","examples":["Policy page"]}},"required":["content","name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"What the template is for; may be empty"},"icon":{"type":"string","description":"Emoji shown with the template"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The body a page made from it starts with. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Absent when the template is blank"},"_id":{"type":"string","description":"Template ID; pass it as templateId to make a page from it"}}}}},"example":{"template":{"name":"Policy page","description":"A policy with who it covers and how to apply it","icon":"📜","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Who this covers"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to apply it"}]},{"type":"paragraph"}]},"_id":"6ad1b0d8e4f5a6b7c8d9e0f9"}}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the wiki's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]}},"/wikis/{wikiId}/search":{"get":{"tags":["Docs"],"summary":"Search a wiki's pages","description":"Finds pages in a wiki whose title or text hold the words you give, best match first, at most 20; archived pages are left out. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"searchWiki","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"},{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Words to look for. A page matches if it has any of them, in any English form (leave finds leaves); put a phrase in double quotes to require it, or a minus before a word to leave out pages that have it","example":"leave policy"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The page's slug"},"icon":{"type":"string","description":"Emoji shown with the page"},"contentText":{"type":"string","description":"The page's whole text without formatting"},"updatedAt":{"type":"string","format":"date-time","description":"When the page last changed"},"id":{"type":"string","description":"Page ID"}}},"description":"Matching pages that are not archived, best match first, at most 20"}}},"example":{"results":[{"title":"Leave policy","slug":"leave-policy","icon":"🌴","contentText":"How to ask for leave Ask your manager at least two weeks ahead, then log it in People. See Public holidays for the days everyone gets off.","updatedAt":"2026-10-15T09:20:00.000Z","id":"6ad1b11ce4f5a6b7c8d9e10c"}]}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the wiki's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]}},"/wikis/{wikiId}/pages":{"get":{"tags":["Docs"],"summary":"List a wiki's pages","description":"Lists one level of a wiki's pages with their full content: the top-level pages, or with parentId the pages directly under that page. Archived pages are left out. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"listWikiPages","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"},{"name":"parentId","in":"query","required":false,"schema":{"type":"string"},"description":"ID of a page, to list the pages directly under it; leave out for the top-level pages","example":"6ad1b10ae4f5a6b7c8d9e101"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the linking page"},"title":{"type":"string","description":"Its title when the link was recorded"}}},"description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds (at most 50)"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}},"description":"One level of pages that are not archived, in their set order, then by title"}}},"example":{"pages":[{"title":"People and HR","slug":"people-and-hr","icon":"🧑‍💼","content":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Leave, pay and who to ask."}]}]},"contentText":"Leave, pay and who to ask.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"status":"published","backlinks":[{"pageId":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist"}],"outgoingLinks":["6ad1b11ce4f5a6b7c8d9e10c"],"linkedTasks":[],"coverImage":"https://images.example.com/covers/team.jpg","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[{"userId":"66f1b2c3d4e5f60718293a4b","viewedAt":"2026-10-13T07:45:00.000Z","viewCount":9}],"totalViews":9,"createdAt":"2026-09-01T07:40:00.000Z","updatedAt":"2026-09-20T12:10:00.000Z","revision":1,"id":"6ad1b10ae4f5a6b7c8d9e101","versionCount":2,"viewerCount":1}]}}}},"400":{"description":"wikiId or parentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No wiki with that ID, it is archived, or you cannot see it: you cannot see its space (you are not a member and it is not public, or it is archived), or it is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]},"post":{"tags":["Docs"],"summary":"Create a page","description":"Creates a page in a wiki and answers with status 201. Needs the contributor role in the wiki's space. Its first content goes in its version history, the wiki's page count and activity time are updated, and the page shows in the space's activity. A page titled exactly Untitled keeps that title and gets a short code in its slug (untitled-mgs3k2a1), so there can be many. A new page starts with the wiki's settings.defaultPageStatus (published unless changed).\n\n**Permission:** `spaces.wiki.create` (Create wikis).","operationId":"createWikiPage","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"object","description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Defaults to the template's content when templateId is given, else one empty paragraph","examples":[{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Send receipts within 30 days of spending."}]}]}]},"icon":{"type":"string","description":"Emoji for the page. Defaults to 📄","examples":["🧾"]},"parentId":{"type":"string","description":"ID of the page to put it under, in the same wiki; leave out for the top level","examples":["6ad1b10ae4f5a6b7c8d9e101"]},"templateId":{"type":"string","description":"_id of one of the wiki's templates to take the content from. Used only when content is left out; an ID the wiki has no template for is ignored","examples":["6ad1b0c2e4f5a6b7c8d9e0f3"]},"title":{"type":"string","description":"Page title. Its slug (lower case, with dashes; 8 random letters and digits when the title has no letter a-z or digit) must be unique in the wiki. Exactly Untitled stays the title; its slug gets a short code (untitled-mgs3k2a1)","examples":["Expense claims"]}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"parentId":{"type":"string","description":"ID of the page it sits under; absent on a top-level page"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds: 1 for a new page"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}}}},"example":{"page":{"title":"Expense claims","slug":"expense-claims","icon":"🧾","content":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Send receipts within 30 days of spending."}]}]},"contentText":"Send receipts within 30 days of spending.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"parentId":"6ad1b10ae4f5a6b7c8d9e101","orderIndex":0,"status":"published","backlinks":[],"outgoingLinks":[],"linkedTasks":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[],"totalViews":0,"createdAt":"2026-10-15T10:30:00.000Z","updatedAt":"2026-10-15T10:30:00.000Z","revision":0,"id":"6ad1b190e4f5a6b7c8d9e180","versionCount":1,"viewerCount":0}}}}},"400":{"description":"wikiId or parentId is not a valid ID, the parent page is in another wiki, or another page in the wiki has a title that gives the same slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the wiki's space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, it is archived, its space no longer exists or is archived, or the parent page does not exist or is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.create"]}],"x-required-scopes":["spaces.wiki.create"]}},"/wikis/{wikiId}/pages/tree":{"get":{"tags":["Docs"],"summary":"Get a wiki's page tree","description":"Gets all of a wiki's pages that are not archived as a tree of titles: the top-level pages, each with the pages under it. A page whose parent is archived or gone shows at the top level. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"getWikiPageTree","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"tree":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Page ID"},"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The page's slug"},"icon":{"type":"string","description":"Emoji shown with the page"},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"icon":{"type":"string"},"children":{"type":"array"}}},"description":"The pages directly under it, in the same shape and order"}}},"description":"The top-level pages, in their set order, then by title"}}},"example":{"tree":[{"id":"6ad1b10ae4f5a6b7c8d9e101","title":"People and HR","slug":"people-and-hr","icon":"🧑‍💼","children":[{"id":"6ad1b190e4f5a6b7c8d9e180","title":"Expense claims","slug":"expense-claims","icon":"🧾","children":[]},{"id":"6ad1b11ce4f5a6b7c8d9e10c","title":"Leave policy","slug":"leave-policy","icon":"🌴","children":[]}]},{"id":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist","slug":"onboarding-checklist","icon":"✅","children":[]}]}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No wiki with that ID, it is archived, or you cannot see it: you cannot see its space (you are not a member and it is not public, or it is archived), or it is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]}},"/wiki/pages/{pageId}":{"get":{"tags":["Docs"],"summary":"Get a page","description":"Gets one page with its full content and the pages that link to it. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members. It does not count as a view: markWikiPageViewed does that.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"getWikiPage","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"},{"name":"includeBacklinks","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Whether to fill backlinks; false (or 0) leaves it empty"},{"name":"slug","in":"query","required":false,"schema":{"type":"string"},"description":"Not used on this route; read only with wikiId when no pageId is given","example":"leave-policy"},{"name":"wikiId","in":"query","required":false,"schema":{"type":"string"},"description":"Not used on this route, where the page ID in the path always wins. Read only when no pageId is given: with slug, finds the page by its slug in this wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"parentId":{"type":"string","description":"ID of the page it sits under; absent on a top-level page"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the linking page"},"title":{"type":"string","description":"Its title when the link was recorded"}}},"description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds (at most 50)"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}},"backlinks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The page's slug"},"icon":{"type":"string","description":"Emoji shown with the page"},"id":{"type":"string","description":"Page ID"}}},"description":"The pages that link to this one and are not archived; pages of a private wiki only if you are a member of the space"}}},"example":{"page":{"title":"Leave policy","slug":"leave-policy","icon":"🌴","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager at least two weeks ahead, then log it in People."}]},{"type":"paragraph","content":[{"type":"text","text":"See Public holidays for the days everyone gets off."}]}]},"contentText":"How to ask for leave Ask your manager at least two weeks ahead, then log it in People. See Public holidays for the days everyone gets off.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"parentId":"6ad1b10ae4f5a6b7c8d9e101","orderIndex":1,"status":"published","backlinks":[{"pageId":"6ad1b10ae4f5a6b7c8d9e101","title":"People and HR"},{"pageId":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist"}],"outgoingLinks":["6ad1b12ee4f5a6b7c8d9e11e"],"linkedTasks":[],"coverImage":"https://images.example.com/covers/beach.jpg","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[{"userId":"66f1b2c3d4e5f60718293a5c","viewedAt":"2026-10-15T09:25:00.000Z","viewCount":5},{"userId":"66f1b2c3d4e5f60718293a4b","viewedAt":"2026-10-14T13:02:00.000Z","viewCount":2}],"totalViews":7,"createdAt":"2026-09-02T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","revision":6,"id":"6ad1b11ce4f5a6b7c8d9e10c","versionCount":4,"viewerCount":2},"backlinks":[{"title":"People and HR","slug":"people-and-hr","icon":"🧑‍💼","id":"6ad1b10ae4f5a6b7c8d9e101"},{"title":"Onboarding checklist","slug":"onboarding-checklist","icon":"✅","id":"6ad1b134e4f5a6b7c8d9e124"}]}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the page's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]},"put":{"tags":["Docs"],"summary":"Update a page","description":"Changes a page; only the inputs you send change. Needs the contributor role in its space. When the content changes, the page's revision goes up by one, the new content is saved in the version history as a copy with you, the time and the summary (the last 50 copies are kept), and you become its last editor. With autosave, an autosave updates the newest copy instead of adding one when that copy is also your autosave and was started less than 10 minutes ago, so one person's autosaves make one version per 10 minutes. Send baseRevision (the revision of the page you loaded or last saved) to refuse the save with 409 when someone changed the content since; without it the save always goes through. A new title also changes its slug. The wiki's activity time is updated and the change shows in the space's activity.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"updateWikiPage","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"autosave":{"type":"boolean","description":"true when the editor saves on its own as you type: within 10 minutes your autosaves go into one version instead of one each. Leave out (or false) for a save someone asked for, which always adds a version","examples":[false]},"baseRevision":{"type":"integer","description":"The page's revision when you loaded it or last saved it. When the content has changed since, nothing is saved and the answer is 409. Leave out to save whatever changed in between","examples":[5]},"content":{"type":"object","description":"New page body. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text. Content equal to the current content adds nothing to the history","examples":[{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager at least two weeks ahead, then log it in People."}]},{"type":"paragraph","content":[{"type":"text","text":"See Public holidays for the days everyone gets off."}]}]}]},"coverImage":{"type":"string","description":"Address of a cover picture","examples":["https://images.example.com/covers/beach.jpg"]},"icon":{"type":"string","description":"Emoji for the page","examples":["🌴"]},"status":{"type":"string","enum":["draft","published","archived"],"description":"A label for the page. archived does not hide it: archiveWikiPage does that","examples":["draft"]},"summary":{"type":"string","description":"A note on this edit, used only when the content changes. It is stored with the copy of the new content. Defaults to Content update, or Autosave with autosave","examples":["Added the two-week rule"]},"title":{"type":"string","description":"New title. Its slug changes with it and must stay unique in the wiki","examples":["Leave policy"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"parentId":{"type":"string","description":"ID of the page it sits under; absent on a top-level page"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the linking page"},"title":{"type":"string","description":"Its title when the link was recorded"}}},"description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds (at most 50)"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}}}},"example":{"page":{"title":"Leave policy","slug":"leave-policy","icon":"🌴","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager at least two weeks ahead, then log it in People."}]},{"type":"paragraph","content":[{"type":"text","text":"See Public holidays for the days everyone gets off."}]}]},"contentText":"How to ask for leave Ask your manager at least two weeks ahead, then log it in People. See Public holidays for the days everyone gets off.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"parentId":"6ad1b10ae4f5a6b7c8d9e101","orderIndex":1,"status":"published","backlinks":[{"pageId":"6ad1b10ae4f5a6b7c8d9e101","title":"People and HR"},{"pageId":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist"}],"outgoingLinks":["6ad1b12ee4f5a6b7c8d9e11e"],"linkedTasks":[],"coverImage":"https://images.example.com/covers/beach.jpg","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[{"userId":"66f1b2c3d4e5f60718293a5c","viewedAt":"2026-10-15T09:25:00.000Z","viewCount":5},{"userId":"66f1b2c3d4e5f60718293a4b","viewedAt":"2026-10-14T13:02:00.000Z","viewCount":2}],"totalViews":7,"createdAt":"2026-09-02T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","revision":6,"id":"6ad1b11ce4f5a6b7c8d9e10c","versionCount":4,"viewerCount":2}}}}},"400":{"description":"pageId is not a valid ID, another page in the wiki has a title that gives the same slug, status is not draft, published or archived, or baseRevision is not a whole number of 0 or more","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the contributor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"baseRevision was sent and the page's content has changed since that revision (someone else saved, or a version was restored): nothing is saved. Get the page again to see the changes and its revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]},"delete":{"tags":["Docs"],"summary":"Archive a page","description":"Archives a page and every page under it, at any depth: they drop out of the wiki, and their slugs are freed for new pages. Needs the editor role in its space. listArchivedWikiPages lists them and restoreWikiPage brings the page back with the pages archived with it; deleteWikiPage and deleteArchivedWikiPages delete them for good. The wiki's page count is updated and the archiving shows in the space's activity.\n\n**Permission:** `spaces.wiki.delete` (Archive wikis).","operationId":"archiveWikiPage","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the editor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.delete"]}],"x-required-scopes":["spaces.wiki.delete"]}},"/wiki/pages/{pageId}/versions":{"get":{"tags":["Docs"],"summary":"List a page's versions","description":"Lists the saved copies of a page's content, newest first. The first copy is the content the page was made with; after that, each change of content (a restore too) saves the new content with its editor, time and note, so the newest copy is the page as it is now; one person's autosaves within 10 minutes share one copy, and the last 50 copies are kept. Copies saved by earlier versions of Spaces stay as they were: each holds the content from just before an edit, with that edit's note. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"listWikiPageVersions","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"Most copies to return, newest first","example":20}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Version ID, for getWikiPageVersion and restoreWikiPageVersion"},"editedBy":{"type":"string","description":"ID of the person who wrote this content"},"editedAt":{"type":"string","format":"date-time","description":"When this content was saved: when the page was made for the first copy, else when the edit or restore saved it"},"summary":{"type":"string","description":"Initial creation on the first copy, Restored from version <id> on a restore, else the summary sent with the edit that saved this content (Content update when none, Autosave for an autosave). Copies saved by earlier versions of Spaces hold the summary of the edit after them instead"},"autosave":{"type":"boolean","description":"true when the editor saved it on its own (updateWikiPage autosave): it holds that person's autosaves of up to 10 minutes, and editedAt is the last of them"},"editor":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote this content: id, firstName, lastName and email; null if that person is no longer on record"}}},"description":"Saved copies of the page's content, newest first, without the content itself"}}},"example":{"versions":[{"id":"6ad1b150e4f5a6b7c8d9e140","editedBy":"66f1b2c3d4e5f60718293a4b","editedAt":"2026-10-10T11:00:00.000Z","summary":"Added the two-week rule","autosave":false,"editor":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"}},{"id":"6ad1b13fe4f5a6b7c8d9e12f","editedBy":"66f1b2c3d4e5f60718293a4b","editedAt":"2026-09-02T08:00:00.000Z","summary":"Initial creation","autosave":false,"editor":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"}}]}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the page's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]}},"/wiki/pages/{pageId}/versions/{versionId}":{"get":{"tags":["Docs"],"summary":"Get a version of a page","description":"Gets one saved copy of a page's content from its version history. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"getWikiPageVersion","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the saved copy, from listWikiPageVersions","example":"6ad1b13fe4f5a6b7c8d9e12f"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"object","properties":{"id":{"type":"string","description":"Version ID, for getWikiPageVersion and restoreWikiPageVersion"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The content this copy holds. The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"editedBy":{"type":"string","description":"ID of the person who wrote this content"},"editedAt":{"type":"string","format":"date-time","description":"When this content was saved: when the page was made for the first copy, else when the edit or restore saved it"},"summary":{"type":"string","description":"Initial creation on the first copy, Restored from version <id> on a restore, else the summary sent with the edit that saved this content (Content update when none, Autosave for an autosave). Copies saved by earlier versions of Spaces hold the summary of the edit after them instead"}}}}},"example":{"version":{"id":"6ad1b13fe4f5a6b7c8d9e12f","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager, then log it in People."}]}]},"editedBy":"66f1b2c3d4e5f60718293a4b","editedAt":"2026-09-02T08:00:00.000Z","summary":"Initial creation"}}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the page's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it or its wiki is archived, or the page has no saved copy with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]}},"/wiki/pages/{pageId}/viewers":{"get":{"tags":["Docs"],"summary":"List a page's viewers","description":"Lists who has viewed a page, most recent first, with its view totals. Needs a role in the page's space (viewer or higher), so on a public space people who are not members are refused.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"listWikiPageViewers","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"Most viewers to return","example":20}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"viewers":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who viewed it: id, firstName, lastName and email; null if that person is no longer on record"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"The people who have viewed the page, most recent view first"},"totalViews":{"type":"integer","description":"How many times the page has been viewed, repeat views included"},"viewerCount":{"type":"integer","description":"How many different people have viewed it, over all of them (not only this list)"}}},"example":{"viewers":[{"user":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"viewedAt":"2026-10-15T09:25:00.000Z","viewCount":5},{"user":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"viewedAt":"2026-10-14T13:02:00.000Z","viewCount":2}],"totalViews":7,"viewerCount":2}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]}},"/wikis/{wikiId}/archived":{"get":{"tags":["Docs"],"summary":"List a wiki's archived pages","description":"Lists the pages archived in a wiki (archiveWikiPage), for bringing them back with restoreWikiPage. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"listArchivedWikiPages","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Page ID, for restoreWikiPage and deleteWikiPage"},"title":{"type":"string","description":"Page title"},"icon":{"type":"string","description":"Emoji shown with the page"},"archivedAt":{"type":"string","format":"date-time","description":"When it was archived"},"archivedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who archived it; null for pages archived before Spaces recorded it: id, firstName, lastName and email; null if that person is no longer on record"},"subpageCount":{"type":"integer","description":"How many pages under it were archived with it and come back with it"},"restoresToTop":{"type":"boolean","description":"true when the page it sat under is archived or gone: restoring puts it at the top level of the wiki"}}},"description":"Each page someone archived, newest archiving first. A page archived because a page above it was archived is not listed on its own: it is counted in that page's subpageCount and comes back with it"}}},"example":{"pages":[{"id":"6ad1b11ce4f5a6b7c8d9e10c","title":"Leave policy","icon":"🌴","archivedAt":"2026-10-20T14:05:00.000Z","archivedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"subpageCount":2,"restoresToTop":false}]}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No wiki with that ID, it is archived, or you cannot see it: you cannot see its space (you are not a member and it is not public, or it is archived), or it is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]},"delete":{"tags":["Docs"],"summary":"Delete a wiki's archived pages","description":"Deletes every archived page in a wiki and all their comments, for good. Needs the owner role in its space, and works on an archived wiki too.\n\n**Permission:** `spaces.wiki.admin` (Purge wikis).","operationId":"deleteArchivedWikiPages","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"deletedCount":{"type":"integer","description":"How many archived pages were deleted. With none to delete it is 0, and message says \"No archived pages to purge\""}}},"example":{"success":true,"deletedCount":5}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the owner of the wiki's space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.admin"]}],"x-required-scopes":["spaces.wiki.admin"]}},"/wiki/pages/{pageId}/comments":{"get":{"tags":["Docs"],"summary":"List comments on a page","description":"Lists the top-level comments on a page, newest first; listWikiCommentReplies gives the replies to each. Resolved comments are left out unless includeResolved is true. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wikiComments.read` (View wiki comments).","operationId":"listWikiComments","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"},{"name":"includeResolved","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Also list resolved comments: true (or 1). false, 0 or leaving it out hides them","example":true}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the page it is on"},"wikiId":{"type":"string","description":"ID of the page's wiki"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"authorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote it: id, firstName, lastName and email; null if that person is no longer on record"},"content":{"type":"string","description":"The comment text, up to 5,000 characters"},"selection":{"type":"object","properties":{"from":{"type":"integer","description":"Where the selected text starts, as a position in the page's editor document"},"to":{"type":"integer","description":"Where it ends"},"text":{"type":"string","description":"The selected words"}},"description":"The part of the page it is about; absent on a comment about the whole page"},"replyCount":{"type":"integer","description":"How many replies it has; a deleted reply comes off it"},"isResolved":{"type":"boolean","description":"Whether it is resolved"},"resolvedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who resolved it; only while it is resolved: id, firstName, lastName and email; null if that person is no longer on record"},"resolvedAt":{"type":"string","format":"date-time","description":"When it was resolved; only while it is resolved"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was written"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}},"description":"The page's top-level comments that are not deleted, newest first"}}},"example":{"comments":[{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"content":"Link the leave form in People here.","selection":{"from":60,"to":76,"text":"log it in People"},"replyCount":0,"isResolved":true,"resolvedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"resolvedAt":"2026-10-15T11:30:00.000Z","isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:20:00.000Z","updatedAt":"2026-10-15T11:30:00.000Z","id":"6ad1b168e4f5a6b7c8d9e158"},{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"content":"Does the two-week rule apply to sick leave too?","selection":{"from":42,"to":57,"text":"two weeks ahead"},"replyCount":1,"isResolved":false,"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:00:00.000Z","updatedAt":"2026-10-15T10:00:00.000Z","id":"6ad1b170e4f5a6b7c8d9e160"}]}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the page's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.read"]}],"x-required-scopes":["spaces.wikiComments.read"]},"post":{"tags":["Docs"],"summary":"Comment on a page","description":"Adds a comment to a page, or a reply to a comment, and answers with status 201. Needs the contributor role in the page's space, and the wiki must allow comments. A reply adds one to its parent's replyCount.\n\n**Permission:** `spaces.wikiComments.create` (Add wiki comments).","operationId":"createWikiComment","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The comment text, up to 5,000 characters","examples":["Does the two-week rule apply to sick leave too?"]},"parentId":{"type":"string","description":"ID of the comment to reply to, on the same page","examples":["6ad1b170e4f5a6b7c8d9e160"]},"selection":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"text":{"type":"string"}},"description":"The part of the page the comment is about: from and to are positions in the page's editor document, text is the selected words. The same object as JSON text also works. Leave out for a comment on the whole page","examples":[{"from":42,"to":57,"text":"two weeks ahead"}]}},"required":["content"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the page it is on"},"wikiId":{"type":"string","description":"ID of the page's wiki"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"authorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote it: id, firstName, lastName and email; null if that person is no longer on record"},"content":{"type":"string","description":"The comment text, up to 5,000 characters"},"selection":{"type":"object","properties":{"from":{"type":"integer","description":"Where the selected text starts, as a position in the page's editor document"},"to":{"type":"integer","description":"Where it ends"},"text":{"type":"string","description":"The selected words"}},"description":"The part of the page it is about; absent on a comment about the whole page"},"replyCount":{"type":"integer","description":"How many replies it has; a deleted reply comes off it"},"isResolved":{"type":"boolean","description":"Whether it is resolved"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was written"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}}}},"example":{"comment":{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"content":"Does the two-week rule apply to sick leave too?","selection":{"from":42,"to":57,"text":"two weeks ahead"},"replyCount":0,"isResolved":false,"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:00:00.000Z","updatedAt":"2026-10-15T10:00:00.000Z","id":"6ad1b170e4f5a6b7c8d9e160"}}}}},"400":{"description":"pageId or parentId is not a valid ID, the wiki does not allow comments, the parent comment does not exist, is deleted or is on another page, selection is text that is not valid JSON, or content is over 5,000 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the contributor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.create"]}],"x-required-scopes":["spaces.wikiComments.create"]}},"/wiki/comments/{commentId}/replies":{"get":{"tags":["Docs"],"summary":"List replies to a comment","description":"Lists the replies to a comment, oldest first; deleted ones are left out. Open to members of the comment's space, and to anyone if the space is public, unless its wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wikiComments.read` (View wiki comments).","operationId":"listWikiCommentReplies","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad1b170e4f5a6b7c8d9e160"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"replies":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the page it is on"},"wikiId":{"type":"string","description":"ID of the page's wiki"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"authorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote it: id, firstName, lastName and email; null if that person is no longer on record"},"content":{"type":"string","description":"The comment text, up to 5,000 characters"},"parentId":{"type":"string","description":"ID of the comment it replies to; absent on a top-level comment"},"replyCount":{"type":"integer","description":"How many replies it has; a deleted reply comes off it"},"isResolved":{"type":"boolean","description":"Whether it is resolved"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was written"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}},"description":"Replies to the comment that are not deleted, oldest first"}}},"example":{"replies":[{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"content":"No, sick leave only needs a note from a doctor.","parentId":"6ad1b170e4f5a6b7c8d9e160","replyCount":0,"isResolved":false,"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:12:00.000Z","updatedAt":"2026-10-15T10:12:00.000Z","id":"6ad1b178e4f5a6b7c8d9e168"}]}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the comment's space (you are not a member and it is not public, or it is archived), or its wiki is private and you are not a member of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, it is deleted, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.read"]}],"x-required-scopes":["spaces.wikiComments.read"]}},"/comments/{commentId}/replies":{"get":{"tags":["Comments"],"summary":"List replies to a comment","description":"Lists the whole thread under a comment: its replies, the replies to those, and so on, oldest first. Open to members of the space the item is in (any role). On a task, people who follow it also get in, whatever their place in the space; a personal task (no space) is open to its creator, assignees and followers, and a personal event to its creator and attendees.\n\n**Permission:** `spaces.comments.read` (View comments).","operationId":"listCommentReplies","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad0a3c2d5c26de56de94a10"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"replies":{"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","description":"What kind of item it is on: task, wiki_page, pipeline, pipeline_record or event"},"targetId":{"type":"string","description":"ID of that item"},"spaceId":{"type":"string","description":"ID of the space the item is in; absent for a personal task or event"},"authorId":{"type":"object","properties":{"name":{"type":"string","description":"Full name, when Kazee sign-in has one for them"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who wrote it"},"actedBy":{"type":"object","properties":{"id":{"type":"string","description":"The bot's ID"},"name":{"type":"string","description":"The bot's name"},"ai":{"type":"boolean","description":"Always true"}},"description":"Only when an AI assistant (a bot) did it: the bot. When its id is not the person's, it acted for that person: show \"Brian Mwangi (via smart-brian)\"; otherwise it acted as itself. Absent when a person did it themselves"},"kind":{"type":"string","description":"comment: written by a person. transition: a note added when someone moves a pipeline record through a stage transition with notes"},"content":{"type":"string","description":"The text: plain text, or a rich-text document as a JSON string"},"attachments":{"type":"array","description":"Files attached to it"},"parentId":{"type":"string","description":"Only on a reply: ID of the comment it answers"},"replyCount":{"type":"integer","description":"How many direct replies it has"},"mentions":{"type":"array","description":"IDs of the people mentioned in it"},"reactions":{"type":"array","description":"Emoji reactions, at most one per person"},"seenBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who saw it"},"seenAt":{"type":"string","format":"date-time","description":"When they first saw it"},"_id":{"type":"string","description":"ID of this entry"}}},"description":"Who has seen it, and when; the author counts as having seen it from the start"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was posted"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}},"description":"Every reply under the comment, at any depth, oldest first; deleted ones are left out"}}},"example":{"replies":[{"targetType":"task","targetId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"name":"Brian Mwangi","firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@acme.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"actedBy":{"id":"66f1b2c3d4e5f60718293a6d","name":"smart-brian","ai":true},"kind":"comment","content":"Thanks, I'll file it with the October invoices.","attachments":[],"parentId":"6ad0a3c2d5c26de56de94a10","replyCount":0,"mentions":[],"reactions":[],"seenBy":[{"userId":"66f1b2c3d4e5f60718293a5c","seenAt":"2026-10-15T10:01:45.000Z","_id":"6ad0a3f8d5c26de56de94a1d"}],"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:01:45.000Z","updatedAt":"2026-10-15T10:01:45.000Z","id":"6ad0a3f8d5c26de56de94a1c"}]}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not read comments on the item (see above), or the item is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comments.read"]}],"x-required-scopes":["spaces.comments.read"]}},"/comments/{commentId}/attachment-url":{"get":{"tags":["Comments"],"summary":"Get a download link for a comment file","description":"Returns a one-hour download link for a file attached to a comment. Only files uploaded for the comment's own item are signed. Open to members of the space the item is in (any role). On a task, people who follow it also get in, whatever their place in the space; a personal task (no space) is open to its creator, assignees and followers, and a personal event to its creator and attendees.\n\n**Permission:** `spaces.comments.read` (View comments).","operationId":"getCommentAttachmentUrl","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad0a3c2d5c26de56de94a10"},{"name":"minioKey","in":"query","required":true,"schema":{"type":"string"},"description":"Key of the file: its minioKey in the comment's attachments, URL-encoded in the query","example":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Download link for the file; anyone who has it can download the file until it expires"},"expiresIn":{"type":"integer","description":"Seconds until the link stops working (always 3600, one hour)"}}},"example":{"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c","expiresIn":3600}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not read comments on the item (see above), or the item is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID (or it was deleted), or the comment has no file with that key that was uploaded for its item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comments.read"]}],"x-required-scopes":["spaces.comments.read"]}},"/comments/{targetType}/{targetId}":{"get":{"tags":["Comments"],"summary":"List comments","description":"Lists the top-level comments on a task, wiki page, pipeline, pipeline record or event, a page at a time, newest first. With withReplies it also returns every reply to the comments on that page. Open to members of the space the item is in (any role). On a task, people who follow it also get in, whatever their place in the space; a personal task (no space) is open to its creator, assignees and followers, and a personal event to its creator and attendees.\n\n**Permission:** `spaces.comments.read` (View comments).","operationId":"listComments","parameters":[{"name":"targetType","in":"path","required":true,"schema":{"type":"string","enum":["task","wiki_page","pipeline","pipeline_record","event"]},"description":"What kind of item the comments are on","example":"task"},{"name":"targetId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of that task, wiki page, pipeline, pipeline record or event","example":"6ad0a044d5c26de56de949a8"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"description":"Most top-level comments to return","example":20},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many top-level comments to skip, for paging","example":0},{"name":"withReplies","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true also returns replies: every reply to the comments on this page, so one call can draw the threads","example":true}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","description":"What kind of item it is on: task, wiki_page, pipeline, pipeline_record or event"},"targetId":{"type":"string","description":"ID of that item"},"spaceId":{"type":"string","description":"ID of the space the item is in; absent for a personal task or event"},"authorId":{"type":"object","properties":{"name":{"type":"string","description":"Full name, when Kazee sign-in has one for them"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who wrote it"},"kind":{"type":"string","description":"comment: written by a person. transition: a note added when someone moves a pipeline record through a stage transition with notes"},"content":{"type":"string","description":"The text: plain text, or a rich-text document as a JSON string"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with a short random code added, e.g. delivery-note-3f9c2a1b.jpg"},"originalName":{"type":"string","description":"Name of the file as it was uploaded"},"fileSize":{"type":"integer","description":"Size in bytes"},"mimeType":{"type":"string","description":"File type, e.g. image/jpeg"},"minioKey":{"type":"string","description":"Key of the stored file; pass it as minioKey to getCommentAttachmentUrl for a download link"},"bucketName":{"type":"string","description":"Which store holds the file; absent on older files"},"type":{"type":"string","description":"image, video or file, from the file type"},"uploadedAt":{"type":"string","format":"date-time","description":"When the file was stored"},"_id":{"type":"string","description":"ID of this file entry on the comment"}}},"description":"Files attached to it"},"replyCount":{"type":"integer","description":"How many direct replies it has"},"mentions":{"type":"array","items":{"type":"string"},"description":"IDs of the people mentioned in it"},"reactions":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who reacted"},"emoji":{"type":"string","description":"The emoji"},"createdAt":{"type":"string","format":"date-time","description":"When they reacted"},"_id":{"type":"string","description":"ID of this reaction entry"}}},"description":"Emoji reactions, at most one per person"},"seenBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who saw it"},"seenAt":{"type":"string","format":"date-time","description":"When they first saw it"},"_id":{"type":"string","description":"ID of this entry"}}},"description":"Who has seen it, and when; the author counts as having seen it from the start"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was posted"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}},"description":"Top-level comments on the item, newest first; replies are not in this list"},"replies":{"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","description":"What kind of item it is on: task, wiki_page, pipeline, pipeline_record or event"},"targetId":{"type":"string","description":"ID of that item"},"spaceId":{"type":"string","description":"ID of the space the item is in; absent for a personal task or event"},"authorId":{"type":"object","properties":{"name":{"type":"string","description":"Full name, when Kazee sign-in has one for them"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who wrote it"},"actedBy":{"type":"object","properties":{"id":{"type":"string","description":"The bot's ID"},"name":{"type":"string","description":"The bot's name"},"ai":{"type":"boolean","description":"Always true"}},"description":"Only when an AI assistant (a bot) did it: the bot. When its id is not the person's, it acted for that person: show \"Brian Mwangi (via smart-brian)\"; otherwise it acted as itself. Absent when a person did it themselves"},"kind":{"type":"string","description":"comment: written by a person. transition: a note added when someone moves a pipeline record through a stage transition with notes"},"content":{"type":"string","description":"The text: plain text, or a rich-text document as a JSON string"},"attachments":{"type":"array","description":"Files attached to it"},"parentId":{"type":"string","description":"Only on a reply: ID of the comment it answers"},"replyCount":{"type":"integer","description":"How many direct replies it has"},"mentions":{"type":"array","description":"IDs of the people mentioned in it"},"reactions":{"type":"array","description":"Emoji reactions, at most one per person"},"seenBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who saw it"},"seenAt":{"type":"string","format":"date-time","description":"When they first saw it"},"_id":{"type":"string","description":"ID of this entry"}}},"description":"Who has seen it, and when; the author counts as having seen it from the start"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was posted"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}},"description":"Only when withReplies is true: every reply, at any depth, to the comments on this page, oldest first"},"total":{"type":"integer","description":"How many comments the item has, replies included (deleted ones are not counted)"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Most items in this page"},"skip":{"type":"integer","description":"How many items were skipped before this page"},"hasMore":{"type":"boolean","description":"Whether more top-level comments follow this page"}}}}},"example":{"comments":[{"targetType":"task","targetId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"name":"Amina Otieno","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"kind":"comment","content":"Sent the invoice to the client this morning. Photo of the signed delivery note attached.","attachments":[{"fileName":"delivery-note-3f9c2a1b.jpg","originalName":"delivery-note.jpg","fileSize":482133,"mimeType":"image/jpeg","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","type":"image","uploadedAt":"2026-10-15T09:40:12.000Z","_id":"6ad0a3c2d5c26de56de94a11"}],"replyCount":1,"mentions":["66f1b2c3d4e5f60718293a5c"],"reactions":[{"userId":"66f1b2c3d4e5f60718293a5c","emoji":"👍","createdAt":"2026-10-15T10:02:00.000Z","_id":"6ad0a41ad5c26de56de94a25"}],"seenBy":[{"userId":"66f1b2c3d4e5f60718293a4b","seenAt":"2026-10-15T09:41:00.000Z","_id":"6ad0a3c2d5c26de56de94a12"},{"userId":"66f1b2c3d4e5f60718293a5c","seenAt":"2026-10-15T10:01:30.000Z","_id":"6ad0a45bd5c26de56de94a2e"}],"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:41:00.000Z","updatedAt":"2026-10-15T10:02:00.000Z","id":"6ad0a3c2d5c26de56de94a10"}],"replies":[{"targetType":"task","targetId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"name":"Brian Mwangi","firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@acme.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"actedBy":{"id":"66f1b2c3d4e5f60718293a6d","name":"smart-brian","ai":true},"kind":"comment","content":"Thanks, I'll file it with the October invoices.","attachments":[],"parentId":"6ad0a3c2d5c26de56de94a10","replyCount":0,"mentions":[],"reactions":[],"seenBy":[{"userId":"66f1b2c3d4e5f60718293a5c","seenAt":"2026-10-15T10:01:45.000Z","_id":"6ad0a3f8d5c26de56de94a1d"}],"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:01:45.000Z","updatedAt":"2026-10-15T10:01:45.000Z","id":"6ad0a3f8d5c26de56de94a1c"}],"total":2,"pagination":{"limit":20,"skip":0,"hasMore":false}}}}},"400":{"description":"targetId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not read comments on the item (see above), targetType is not one listed, or the event is managed by Kazee People","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task, wiki page, pipeline, record or event, it is archived, or its wiki or space is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comments.read"]}],"x-required-scopes":["spaces.comments.read"]}},"/media/refresh-url":{"get":{"tags":["Comments"],"summary":"Renew a link to an embedded file","description":"Returns a new 7-day download link for a file whose link is saved inside text, such as an image in a comment or a description, so a link that has run out can be renewed. Any signed-in person may renew a link to any of their organisation's Spaces files; it does not check which item the file belongs to.\n\n**Permission:** `spaces.comments.read` (View comments).","operationId":"getMediaRefreshUrl","parameters":[{"name":"bucketName","in":"query","required":true,"schema":{"type":"string"},"description":"Store holding the file: the first part of the old link's path, e.g. org-<organisation ID>","example":"org-66a4b275003d1b495212b5aa"},{"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"Key of the file: the rest of the old link's path, without the query. In an organisation store it starts with spaces/<organisation ID>/, in the older shared store with <organisation ID>/","example":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"New download link for the file; anyone who has it can download the file until it expires"},"expiresIn":{"type":"integer","description":"Seconds until the link stops working (always 604800, 7 days)"}}},"example":{"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c","expiresIn":604800}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The file is not one of your organisation's Spaces files: the key does not start with your organisation's folder in that store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comments.read"]}],"x-required-scopes":["spaces.comments.read"]}},"/notifications/settings":{"get":{"tags":["Notifications"],"summary":"Get my notification settings","description":"Returns your notification settings: for each of the 11 categories, whether you get a phone notification and an email. A category missing from your stored settings shows both as on.\n\n**Permission:** `spaces.notifications.read` (View notifications).","operationId":"getNotificationSettings","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"settings":{"type":"object","properties":{"task_assigned":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task is assigned to you: push (phone notification) and email, each true when on"},"task_updated":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task you're involved in is updated: push (phone notification) and email, each true when on"},"task_due":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for tasks approaching their due date: push (phone notification) and email, each true when on"},"mentions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone @mentions you: push (phone notification) and email, each true when on"},"comments":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone comments on your items: push (phone notification) and email, each true when on"},"replies":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone replies to your comments: push (phone notification) and email, each true when on"},"reactions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone reacts to your comment: push (phone notification) and email, each true when on"},"space_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to join a space: push (phone notification) and email, each true when on"},"event_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to an event or someone responds to your invite: push (phone notification) and email, each true when on"},"event_reminders":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for upcoming calendar events: push (phone notification) and email, each true when on"},"system":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Important system announcements: push (phone notification) and email, each true when on"}},"description":"For each category, whether you get it as a phone notification (push) and by email; in-app notifications are always on"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The category key used in settings"},"name":{"type":"string","description":"Display name, e.g. Task Assigned"},"description":{"type":"string","description":"What the category covers"},"settings":{"type":"object","properties":{"push":{"type":"boolean","description":"Whether you get a phone notification"},"email":{"type":"boolean","description":"Whether you get an email"}},"description":"Its push and email setting"}}},"description":"The same settings as a list, with a name and description for each category, for showing on a settings screen"}}},"example":{"success":true,"settings":{"task_assigned":{"push":true,"email":true},"task_updated":{"push":true,"email":false},"task_due":{"push":true,"email":true},"mentions":{"push":true,"email":true},"comments":{"push":true,"email":true},"replies":{"push":true,"email":true},"reactions":{"push":true,"email":false},"space_invites":{"push":true,"email":true},"event_invites":{"push":true,"email":true},"event_reminders":{"push":true,"email":true},"system":{"push":true,"email":true}},"categories":[{"id":"task_assigned","name":"Task Assigned","description":"When a task is assigned to you","settings":{"push":true,"email":true}},{"id":"task_updated","name":"Task Updated","description":"When a task you're involved in is updated","settings":{"push":true,"email":false}},{"id":"task_due","name":"Task Due","description":"Reminders for tasks approaching their due date","settings":{"push":true,"email":true}},{"id":"mentions","name":"Mentions","description":"When someone @mentions you","settings":{"push":true,"email":true}},{"id":"comments","name":"Comments","description":"When someone comments on your items","settings":{"push":true,"email":true}},{"id":"replies","name":"Replies","description":"When someone replies to your comments","settings":{"push":true,"email":true}},{"id":"reactions","name":"Reactions","description":"When someone reacts to your comment","settings":{"push":true,"email":false}},{"id":"space_invites","name":"Space Invitations","description":"When you're invited to join a space","settings":{"push":true,"email":true}},{"id":"event_invites","name":"Event Invitations","description":"When you're invited to an event or someone responds to your invite","settings":{"push":true,"email":true}},{"id":"event_reminders","name":"Event Reminders","description":"Reminders for upcoming calendar events","settings":{"push":true,"email":true}},{"id":"system","name":"System Notifications","description":"Important system announcements","settings":{"push":true,"email":true}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.read"]}],"x-required-scopes":["spaces.notifications.read"]},"post":{"tags":["Notifications"],"summary":"Change my notification settings","description":"Turns phone notifications (push) or email on or off for the categories you send; categories and channels you leave out keep their setting. Your in-app notifications are not affected.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"updateNotificationSettings","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","description":"Category -> { push, email }, each true or false and either one optional. Categories: task_assigned, task_updated, task_due, mentions, comments, replies, reactions, space_invites, event_invites, event_reminders, system. A JSON object in a string also works","examples":[{"task_updated":{"email":false},"reactions":{"push":false}}]}},"required":["settings"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"settings":{"type":"object","properties":{"task_assigned":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task is assigned to you: push (phone notification) and email, each true when on"},"task_updated":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task you're involved in is updated: push (phone notification) and email, each true when on"},"task_due":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for tasks approaching their due date: push (phone notification) and email, each true when on"},"mentions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone @mentions you: push (phone notification) and email, each true when on"},"comments":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone comments on your items: push (phone notification) and email, each true when on"},"replies":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone replies to your comments: push (phone notification) and email, each true when on"},"reactions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone reacts to your comment: push (phone notification) and email, each true when on"},"space_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to join a space: push (phone notification) and email, each true when on"},"event_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to an event or someone responds to your invite: push (phone notification) and email, each true when on"},"event_reminders":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for upcoming calendar events: push (phone notification) and email, each true when on"},"system":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Important system announcements: push (phone notification) and email, each true when on"}},"description":"All your settings after the change"},"updated":{"type":"array","items":{"type":"string"},"description":"The categories you sent"}}},"example":{"success":true,"settings":{"task_assigned":{"push":true,"email":true},"task_updated":{"push":true,"email":false},"task_due":{"push":true,"email":true},"mentions":{"push":true,"email":true},"comments":{"push":true,"email":true},"replies":{"push":true,"email":true},"reactions":{"push":true,"email":false},"space_invites":{"push":true,"email":true},"event_invites":{"push":true,"email":true},"event_reminders":{"push":true,"email":true},"system":{"push":true,"email":true}},"updated":["task_updated"]}}}},"400":{"description":"settings is missing or not an object, names a category not listed, or has a push or email that is not true or false","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications":{"get":{"tags":["Notifications"],"summary":"List my notifications","description":"Lists your own notifications, newest first, a page at a time. Archived ones are left out unless isArchived is true.\n\n**Permission:** `spaces.notifications.read` (View notifications).","operationId":"listNotifications","parameters":[{"name":"isArchived","in":"query","required":false,"schema":{"type":"boolean"},"description":"true: only archived ones; anything else, or left out: only ones not archived","example":false},{"name":"isRead","in":"query","required":false,"schema":{"type":"boolean"},"description":"true: only read ones; false: only unread ones; left out (or any other value): both","example":false},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Most notifications to return, from 1 to 100; larger values count as 100, and 0 or text as 20","example":20},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"How many notifications to skip, for paging","example":0},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Only notifications whose source starts with this text, e.g. spaces:task, spaces:event or spaces:system","example":"spaces:task"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"notifications":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Notification ID"},"userId":{"type":"string","description":"Who it is for: you"},"actorId":{"type":"object","properties":{"_id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who caused it; absent when nobody did (reminders, system notices)"},"category":{"type":"string","description":"The setting that governs it: task_assigned, task_updated, task_due, mentions, comments, replies, reactions, space_invites, event_invites, event_reminders or system"},"notificationType":{"type":"string","description":"mention, reply, reaction, task_assigned, task_updated, comment_added or system"},"title":{"type":"string","description":"Headline, e.g. Brian Mwangi replied to your comment"},"content":{"type":"string","description":"Body text"},"source":{"type":"string","description":"What it is about, as spaces:<kind>: spaces:task, spaces:wiki_page, spaces:pipeline, spaces:pipeline_record, spaces:event, spaces:comment, spaces:space or spaces:system"},"sourceEntityId":{"type":"string","description":"ID of that item; system for system notices"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"data":{"type":"object","properties":{"deepLink":{"type":"string","description":"Path in the Spaces web app that opens the item"},"payload":{"type":"object","properties":{"category":{"type":"string"},"recipientId":{"type":"string"},"actorId":{"type":"string"},"actorName":{"type":"string"},"organizationId":{"type":"string"},"targetType":{"type":"string"},"targetId":{"type":"string"},"targetTitle":{"type":"string"},"parentCommentId":{"type":"string"},"replyId":{"type":"string"},"replyContent":{"type":"string"},"spaceId":{"type":"string"},"deepLink":{"type":"string"}},"description":"Everything the notification was built from; its fields depend on the category"}},"description":"Extra detail"},"isRead":{"type":"boolean","description":"Whether you have read it"},"isArchived":{"type":"boolean","description":"Whether you archived it"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was sent"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"__v":{"type":"integer","description":"Internal revision number"}}},"description":"Your notifications, newest first"},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"How many notifications match, over all pages"},"limit":{"type":"integer","description":"Most notifications in this page"},"skip":{"type":"integer","description":"How many were skipped before this page"},"hasMore":{"type":"boolean","description":"Whether another page follows"}},"description":"Where this page sits"}}},"example":{"success":true,"notifications":[{"_id":"6ad0a3f9d5c26de56de94a21","userId":"66f1b2c3d4e5f60718293a4b","actorId":{"_id":"66f1b2c3d4e5f60718293a5c","firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@acme.co.ke"},"category":"replies","notificationType":"reply","title":"Brian Mwangi replied to your comment","content":"Thanks, I'll file it with the October invoices.","source":"spaces:task","sourceEntityId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","data":{"deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c","payload":{"category":"replies","recipientId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","actorName":"Brian Mwangi","organizationId":"66a4b275003d1b495212b5aa","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","parentCommentId":"6ad0a3c2d5c26de56de94a10","replyId":"6ad0a3f8d5c26de56de94a1c","replyContent":"Thanks, I'll file it with the October invoices.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c"}},"isRead":false,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:01:46.000Z","updatedAt":"2026-10-15T10:01:46.000Z","__v":0}],"pagination":{"total":37,"limit":20,"skip":0,"hasMore":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.read"]}],"x-required-scopes":["spaces.notifications.read"]}},"/notifications/unread-count":{"get":{"tags":["Notifications"],"summary":"Count my unread notifications","description":"Counts your unread notifications, leaving out archived ones.\n\n**Permission:** `spaces.notifications.read` (View notifications).","operationId":"getUnreadNotificationCount","parameters":[{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Only notifications whose source starts with this text, e.g. spaces:task, spaces:event or spaces:system","example":"spaces:task"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"count":{"type":"integer","description":"How many of your notifications are unread and not archived"}}},"example":{"success":true,"count":4}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.read"]}],"x-required-scopes":["spaces.notifications.read"]}},"/search":{"get":{"tags":["Search"],"summary":"Search everything","description":"Finds spaces, tasks, pipelines, pipeline records, wiki pages, sheets and documents, events and drive files whose name, title or text contains the query, ignoring case, most recently changed first (events: latest start first). It looks in the spaces you are a member of, or only in spaceId when given (a space you are a member of, or a public one); tasks also include those you created or are assigned to, and events those you created or are invited to. Archived items are left out, and so are the pages of a private wiki in a public space you are not a member of.\n\n**Permission:** `spaces.search.read` (Global search).","operationId":"searchAll","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"default":20},"description":"Most matches of each kind; at most 50","example":20},{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Text to look for; at least 2 characters. It is matched as plain text, so . or ( match only themselves","example":"invoice"},{"name":"spaceId","in":"query","required":false,"schema":{"type":"string"},"description":"Only search inside this space; spaces themselves are then not searched","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"types","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated kinds to search: spaces, tasks, pipelines, pipelineRecords, wiki, documents, events, driveFiles. Unknown kinds are ignored. Defaults to all of them","example":"tasks,wiki,driveFiles"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"spaces":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Space name"},"description":{"type":"string","description":"Space description"},"color":{"type":"string","description":"Space colour"},"icon":{"type":"string","description":"Space icon"},"memberCount":{"type":"integer","description":"Stored member count, when the space has one"},"id":{"type":"string","description":"Space ID"}}},"description":"Spaces you are a member of whose name or description matches; not searched when spaceId is given"},"tasks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon; absent for a personal task"},"creatorId":{"type":"string","description":"ID of the person who created it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"id":{"type":"string","description":"Task ID"}}},"description":"Tasks whose title matches"},"pipelines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name"},"description":{"type":"string","description":"Description"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}}},"description":"Pipelines whose name or description matches"},"pipelineRecords":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title"},"pipelineId":{"type":"string","description":"ID of its pipeline"},"stageId":{"type":"string","description":"ID of the stage it is in"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}}},"description":"Pipeline records whose title matches"},"wikiPages":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title"},"slug":{"type":"string","description":"Short name used in the page's web address"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon"},"creatorId":{"type":"string","description":"ID of the person who created it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Page ID"}}},"description":"Wiki pages whose title or text matches"},"documents":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"description":{"type":"string","description":"Description"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon"},"creatorId":{"type":"string","description":"ID of the person who created it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Document ID"}}},"description":"Sheets, documents and slides whose name or description matches"},"events":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title"},"description":{"type":"string","description":"Description"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it lasts all day"},"category":{"type":"string","description":"meeting, deadline, milestone, reminder or other"},"color":{"type":"string","description":"Colour shown in the calendar"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon; absent for a personal event"},"creatorId":{"type":"string","description":"ID of the person who created it"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Always 0 here: the search does not read the event's revision"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer"},"state":{"type":"string"},"retryable":{"type":"boolean"}},"description":"Online meeting state; here always { contract: 1, state: none, retryable: false }, as the search does not read the meeting"}}},"description":"Events whose title or description matches, latest start first"},"driveFiles":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name"},"itemType":{"type":"string","description":"file or folder"},"mimeType":{"type":"string","description":"Files only: file type"},"fileSize":{"type":"integer","description":"Files only: size in bytes"},"spaceId":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"id":{"type":"string"}},"description":"The space it is in: id, name, color and icon"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string"}},"description":"Who uploaded it, as { id }"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"File or folder ID"}}},"description":"Drive files and folders whose name matches; pending uploads are left out"}},"description":"Matches, by kind; a kind not searched is an empty list"},"totalCount":{"type":"integer","description":"How many matches came back, over all kinds"}}},"example":{"results":{"spaces":[{"name":"Finance","description":"Invoices, payments and the monthly close","color":"#3b82f6","icon":"💼","memberCount":6,"id":"6a9f3c21b7e4a20f1c5d8e41"}],"tasks":[{"title":"Send the October invoice","status":"in_progress","priority":"high","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-10-15T08:00:00.000Z","id":"6ad0a044d5c26de56de949a8"}],"pipelines":[{"name":"Invoice approvals","description":"Supplier invoices waiting for sign-off","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"createdAt":"2026-09-02T07:30:00.000Z","updatedAt":"2026-10-13T11:12:00.000Z","id":"6ad0a520d5c26de56de94a48"}],"pipelineRecords":[{"title":"Invoice INV-2026-1042","pipelineId":"6ad0a520d5c26de56de94a48","stageId":"awaiting_approval","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"assignees":["66f1b2c3d4e5f60718293a5c"],"createdAt":"2026-10-10T09:00:00.000Z","updatedAt":"2026-10-14T16:45:00.000Z","id":"6ad0a531d5c26de56de94a4f"}],"wikiPages":[{"title":"How we invoice clients","slug":"how-we-invoice-clients","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-08-21T10:00:00.000Z","updatedAt":"2026-10-01T14:30:00.000Z","id":"6ad0a512d5c26de56de94a40"}],"documents":[{"name":"Invoice tracker 2026","type":"spreadsheet","description":"Every invoice sent this year","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a5c","createdAt":"2026-01-05T08:15:00.000Z","updatedAt":"2026-10-15T09:00:00.000Z","id":"6ad0a540d5c26de56de94a55"}],"events":[{"title":"Invoice review","description":"Go through overdue invoices","startDate":"2026-10-17T07:00:00.000Z","endDate":"2026-10-17T07:30:00.000Z","allDay":false,"category":"meeting","color":"#3b82f6","spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","id":"6ad0a551d5c26de56de94a5c","version":0,"meetingReadiness":{"contract":1,"state":"none","retryable":false}}],"driveFiles":[{"name":"October invoice.pdf","itemType":"file","mimeType":"application/pdf","fileSize":184320,"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b"},"createdAt":"2026-10-15T09:15:00.000Z","updatedAt":"2026-10-15T09:15:20.000Z","id":"6ad0a301d5c26de56de94a07"}]},"totalCount":8}}}},"400":{"description":"query is shorter than 2 characters (after trimming), or spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"spaceId names a space you cannot see: it does not exist, is archived, or is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.search.read"]}],"x-required-scopes":["spaces.search.read"]}},"/link-preview":{"get":{"tags":["Comments"],"summary":"Get a preview of a web link","description":"Reads a web page's title, summary and image so a link in a comment or description can be shown as a card. The server fetches the page itself, following up to 5 redirects, reading at most 50 KB and waiting at most 5 seconds in all; a page that fails, is not HTML or answers with an error still gives a short preview of just the link and host name. Good previews are kept for 30 minutes.\n\n**Permission:** `spaces.search.read` (Global search).","operationId":"getLinkPreview","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"The full web address, starting http:// or https://","example":"https://www.kazee.africa/blog/spaces-for-teams"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"preview":{"type":"object","properties":{"url":{"type":"string","description":"The link, as you sent it"},"title":{"type":"string","description":"Page title (at most 300 characters plus ...); when the page could not be read, just the site's host name"},"description":{"type":"string","description":"Page summary, at most 500 characters plus ..."},"image":{"type":"string","description":"Full address of the page's preview image"},"siteName":{"type":"string","description":"Name of the site"},"type":{"type":"string","description":"The page's own type, e.g. website or article; for a link that is not a web page, its file type, e.g. application/pdf"},"favicon":{"type":"string","description":"Full address of the site's icon; /favicon.ico on the site when the page names none"}},"description":"What to show for the link; fields the page does not give are left out"}}},"example":{"preview":{"url":"https://www.kazee.africa/blog/spaces-for-teams","title":"Kazee Spaces for teams","description":"Plan work, share files and keep every conversation next to the task it is about.","image":"https://www.kazee.africa/images/blog/spaces-for-teams.png","siteName":"Kazee","type":"article","favicon":"https://www.kazee.africa/favicon.ico"}}}}},"400":{"description":"url is not a full web address, is not http or https, or it or a redirect from it points at an internal host: a name such as localhost, a single word, or one ending .local, .internal or .svc.cluster.local, or a private, loopback, link-local (169.254.x) or IPv6 local address, written or resolved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.search.read"]}],"x-required-scopes":["spaces.search.read"]}},"/calendar/auth-url":{"get":{"tags":["Calendar"],"summary":"Get a link to connect Google Calendar","description":"Gives the Google page where a person agrees to connect their Google Calendar to Spaces. It changes nothing; the connection is made when connectCalendar receives the code Google returns.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"getCalendarAuthUrl","parameters":[{"name":"redirectUri","in":"query","required":true,"schema":{"type":"string"},"description":"Address Google sends the person back to with the code; it must be one Google knows for Spaces","example":"https://spaces.kazee.africa/settings/calendar/callback"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"authUrl":{"type":"string","description":"Google sign-in page where the person allows Spaces to read their Google calendars and events (not change them) and see their email address. Google then sends them to redirectUri with a code for connectCalendar"}}},"example":{"authUrl":"https://accounts.google.com/o/oauth2/v2/auth?client_id=123456789012-abc.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fspaces.kazee.africa%2Fsettings%2Fcalendar%2Fcallback&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&access_type=offline&prompt=consent&state=eyJ1c2VySWQiOiI2NmYxYjJjM2Q0ZTVmNjA3MTgyOTNhNGIiLCJvcmdhbml6YXRpb25JZCI6IjY2YTRiMjc1MDAzZDFiNDk1MjEyYjVhYSJ9"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]}},"/calendar/integrations":{"get":{"tags":["Calendar"],"summary":"List my connected calendars","description":"Lists the outside calendars (Google Calendar) you have connected and not disconnected.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"listCalendarIntegrations","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"integrations":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person who connected it"},"provider":{"type":"string","description":"Which calendar service: google"},"tokenExpiry":{"type":"string","format":"date-time","description":"When Spaces' current access to the calendar runs out; it is renewed when needed"},"email":{"type":"string","description":"The Google account it is connected to"},"calendarId":{"type":"string","description":"Which Google calendar is read: the account's main one"},"selectedCalendars":{"type":"array","description":"Saved setting, not used yet: IDs of other Google calendars chosen for syncing"},"syncEnabled":{"type":"boolean","description":"Saved setting, not used yet: whether syncing is on"},"twoWaySync":{"type":"boolean","description":"Saved setting, not used yet: whether time blocks should also be written to Google"},"createEventsForTimeBlocks":{"type":"boolean","description":"Saved setting, not used yet: whether time blocks should become Google events"},"importEventsAsBlocking":{"type":"boolean","description":"Saved setting, not used yet: whether Google events should count as busy time"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether the connection is in use"},"lastSyncAt":{"type":"string","format":"date-time","description":"When events were last fetched from Google"},"lastSyncError":{"description":"Why the last fetch failed; null when it worked"},"createdAt":{"type":"string","format":"date-time","description":"When it was first connected"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Connection ID; use it as integrationId"}}},"description":"Your calendar connections that are in use"}}},"example":{"integrations":[{"userId":"66f1b2c3d4e5f60718293a4b","provider":"google","tokenExpiry":"2026-10-15T09:00:00.000Z","email":"grace.namutebi@gmail.com","calendarId":"grace.namutebi@gmail.com","selectedCalendars":[],"syncEnabled":true,"twoWaySync":false,"createEventsForTimeBlocks":true,"importEventsAsBlocking":true,"organizationId":"66a4b275003d1b495212b5aa","isActive":true,"lastSyncAt":"2026-10-15T08:30:00.000Z","lastSyncError":null,"createdAt":"2026-10-01T07:45:00.000Z","updatedAt":"2026-10-15T08:30:00.000Z","id":"6ad1c3d8d5c26de56de94a55"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]}},"/univer/documents":{"get":{"tags":["Sheets & documents"],"summary":"List a space's sheets and documents","description":"Lists a space's spreadsheets, documents and presentations that are not archived, with their creator and last editor filled in; collaborators come as user IDs. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.univer.read` (View spreadsheets).","operationId":"listDocuments","parameters":[{"name":"spaceId","in":"query","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["spreadsheet","document","presentation"]},"description":"Only this kind; any other value matches nothing","example":"spreadsheet"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last saved it: a user ID, or filled in like creatorId"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}},"description":"The space's sheets, documents and presentations, most recently changed first"}}},"example":{"documents":[{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":18734,"version":7,"collaborators":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":"66f1b2c3d4e5f60718293a4b"}],"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"lastEditedAt":"2026-10-15T11:05:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":["budget"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:05:00.000Z","snapshotCount":3}]}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID, it is archived, or it is private and you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.univer.read"]}],"x-required-scopes":["spaces.univer.read"]},"post":{"tags":["Sheets & documents"],"summary":"Create a sheet or document","description":"Creates a spreadsheet, document or presentation in a space, with you as its owner, and answers with status 201. Without content it starts empty. It also gets an item in the space's sidebar unless createSpaceItem is false. Needs the editor role or higher in the space; an archived space takes no new ones.\n\n**Permission:** `spaces.univer.create` (Create spreadsheets).","operationId":"createDocument","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"object","description":"Starting content, as the editor's JSON (the shape the content call returns). A JSON text in a string also works; any other text is stored as it is. Leave out to start empty","examples":[{"id":"6ad0a0d2d5c26de56de949e6","sheetOrder":["sheet1"],"name":"October budget","appVersion":"1.0.0","locale":"en-US","styles":{},"sheets":{"sheet1":{"id":"sheet1","name":"Sheet 1","rowCount":1000,"columnCount":26,"cellData":{"0":{"0":{"v":"Team"},"1":{"v":"Budget"}},"1":{"0":{"v":"Sales"},"1":{"v":18450}}},"rowData":{},"columnData":{}}}}]},"createSpaceItem":{"type":"boolean","default":true,"description":"Whether to add it to the space's sidebar as well"},"description":{"type":"string","description":"Longer notes","examples":["Spending against budget, by team."]},"name":{"type":"string","description":"Name of the sheet or document","examples":["October budget"]},"parentItemId":{"type":"string","description":"ID of a folder in this space's sidebar to put that item in; leave out for the top level","examples":["6a9f3c71b7e4a20f1c5d8e4c"]},"spaceId":{"type":"string","description":"ID of the space to put it in","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"type":{"type":"string","enum":["spreadsheet","document","presentation"],"description":"What to make","examples":["spreadsheet"]}},"required":["name","spaceId","type"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"string","description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"string","description":"Who last saved it: a user ID, or filled in like creatorId"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}},"spaceItem":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"spaceId":{"type":"string","description":"ID of the space it is in"},"itemType":{"type":"string","description":"What it is: folder, calendar, pipeline, wiki, document, tasks, spreadsheet, presentation, custom, analytics, strategy, drive. tasks is a task list"},"name":{"type":"string","description":"Name shown in the sidebar"},"icon":{"type":"string","description":"An emoji or icon name; each type has its own default, e.g. 📁 for a folder"},"parentId":{"type":"string","description":"ID of the folder it sits in; null at the top level"},"orderNum":{"type":"integer","description":"Position among the items in the same folder; 0 comes first"},"targetId":{"type":"string","description":"ID of the thing it opens: a pipeline, wiki, strategy, or a sheet or document. Absent for folders, task lists and other space-wide items"},"targetType":{"type":"string","description":"Kind of thing targetId points to: Pipeline, Wiki, WikiPage, UniverDocument (a sheet or document) or Strategy"},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"metadata":{"description":"Extra settings some item types keep, e.g. the dashboard an analytics item shows; null when none"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}},"description":"Its new sidebar item; null when createSpaceItem is false"}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":"66f1b2c3d4e5f60718293a4b","fileSize":412,"version":1,"collaborators":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","addedAt":"2026-10-15T08:10:00.000Z"}],"lastEditedBy":"66f1b2c3d4e5f60718293a4b","lastEditedAt":"2026-10-15T08:10:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T08:10:00.000Z","snapshotCount":0},"spaceItem":{"id":"6ad0a0c7d5c26de56de949e1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"spreadsheet","name":"October budget","icon":"📊","parentId":"6a9f3c71b7e4a20f1c5d8e4c","orderNum":0,"targetId":"6ad0a0d2d5c26de56de949e6","targetType":"UniverDocument","isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T08:10:00.000Z"}}}}},"400":{"description":"spaceId or parentItemId is not a valid ID, parentItemId is not a folder in this space, or type is not spreadsheet, document or presentation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.create"]}],"x-required-scopes":["spaces.univer.create"]}},"/univer/documents/{documentId}":{"get":{"tags":["Sheets & documents"],"summary":"Get a sheet or document","description":"Gets one spreadsheet, document or presentation with its creator, last editor and collaborators filled in, and a link to download its content. Open to the members of its space, to anyone when the space is public, and to the people it was shared with. Its creator's own access ends when they leave the space.\n\n**Permission:** `spaces.univer.read` (View spreadsheets).","operationId":"getDocument","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last saved it: a user ID, or filled in like creatorId"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}},"contentUrl":{"type":"string","description":"Link to download its content as JSON, valid for 1 hour; null when file storage is not available"}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":18734,"version":7,"collaborators":[{"userId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}}],"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"lastEditedAt":"2026-10-15T11:05:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":["budget"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:05:00.000Z","snapshotCount":3},"contentUrl":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/6a9f3c21b7e4a20f1c5d8e41/univer/spreadsheet/6ad0a0d2d5c26de56de949e6/data.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T110500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4d1e7a9c2b5f8e3d6a0c9b4f7e2d5a8c1b6f9e3d7a0c4b8f2e5d9a3c6b0f7e1d"}}}},"400":{"description":"documentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see its space (it is private and you are not a member, or it is archived) and it was not shared with you; its creator's own access ends when they leave the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.univer.read"]}],"x-required-scopes":["spaces.univer.read"]},"put":{"tags":["Sheets & documents"],"summary":"Update a sheet or document's details","description":"Changes the name, description, tags or settings of a spreadsheet, document or presentation, not its content; inputs you leave out stay as they are. A new name goes to its sidebar item too. Needs the editor role or higher in its space, or the editor role on the document itself, given when it was shared; its creator's owner role counts only while they are an editor or owner of the space. Not while its space is archived.\n\n**Permission:** `spaces.univer.update` (Edit spreadsheets).","operationId":"updateDocument","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"New longer notes","examples":["Spending against budget, by team."]},"name":{"type":"string","description":"New name","examples":["October budget (final)"]},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean"},"allowComments":{"type":"boolean"},"allowExport":{"type":"boolean"}},"description":"Settings to change: isPublic, allowComments, allowExport; the ones you leave out keep their value. The server stores them but does not enforce them. A JSON object in a string also works","examples":[{"allowExport":false}]},"tags":{"type":"array","items":{"type":"string"},"description":"Labels; replaces the ones it has (a JSON array in a string also works)","examples":[["budget","final"]]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last saved it: a user ID, or filled in like creatorId"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget (final)","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":18734,"version":7,"collaborators":[{"userId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}}],"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"lastEditedAt":"2026-10-15T11:05:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":false},"description":"Spending against budget, by team.","tags":["budget","final"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:40:00.000Z","snapshotCount":3}}}}},"400":{"description":"documentId is not a valid ID, or tags or settings is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of its space, nor an editor of the document; its creator counts only while an editor or owner of the space, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.univer.update"]}],"x-required-scopes":["spaces.univer.update"]},"delete":{"tags":["Sheets & documents"],"summary":"Delete a sheet or document","description":"Archives a spreadsheet, document or presentation or, with permanent true, deletes it for good together with its content and earlier versions. Either way its sidebar item is archived. Only the owner of its space, or its creator while still an editor or owner of the space, may do it. A permanent delete removes the stored content and versions first: when file storage is not available or does not delete one, the document is kept and the answer is 503, so try again. There is no call to bring an archived one back.\n\n**Permission:** `spaces.univer.delete` (Delete spreadsheets).","operationId":"deleteDocument","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"},{"name":"permanent","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true deletes it for good instead of archiving it"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"documentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the owner of its space, nor the document's creator while still an editor or owner of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"With permanent true: file storage is not available right now, or did not delete its content or an earlier version, so the document was kept (earlier versions already deleted stay deleted). Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.delete"]}],"x-required-scopes":["spaces.univer.delete"]}},"/univer/documents/{documentId}/content":{"get":{"tags":["Sheets & documents"],"summary":"Get a sheet or document's content","description":"Gets the content of a spreadsheet, document or presentation, as the JSON its editor saved. Open to the members of its space, to anyone when the space is public, and to the people it was shared with. Its creator's own access ends when they leave the space.\n\n**Permission:** `spaces.univer.read` (View spreadsheets).","operationId":"getDocumentContent","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"object","properties":{"id":{"type":"string"},"sheetOrder":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"appVersion":{"type":"string"},"locale":{"type":"string"},"styles":{"type":"object","properties":{}},"sheets":{"type":"object","properties":{"sheet1":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rowCount":{"type":"integer"},"columnCount":{"type":"integer"},"cellData":{"type":"object","properties":{"0":{"type":"object","properties":{"0":{"type":"object","properties":{"v":{"type":"string"}}},"1":{"type":"object","properties":{"v":{"type":"string"}}}}},"1":{"type":"object","properties":{"0":{"type":"object","properties":{"v":{"type":"string"}}},"1":{"type":"object","properties":{"v":{"type":"integer"}}}}}}},"rowData":{"type":"object","properties":{}},"columnData":{"type":"object","properties":{}}}}}}},"description":"The content as the editor saved it, as JSON: for a spreadsheet a workbook whose sheets hold cellData by row and then column (shown here), for a document its body and page style, for a presentation its slides"}}},"example":{"content":{"id":"6ad0a0d2d5c26de56de949e6","sheetOrder":["sheet1"],"name":"October budget","appVersion":"1.0.0","locale":"en-US","styles":{},"sheets":{"sheet1":{"id":"sheet1","name":"Sheet 1","rowCount":1000,"columnCount":26,"cellData":{"0":{"0":{"v":"Team"},"1":{"v":"Budget"}},"1":{"0":{"v":"Sales"},"1":{"v":18450}}},"rowData":{},"columnData":{}}}}}}}},"400":{"description":"documentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see its space (it is private and you are not a member, or it is archived) and it was not shared with you; its creator's own access ends when they leave the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.read"]}],"x-required-scopes":["spaces.univer.read"]}},"/univer/documents/{documentId}/upload-url":{"get":{"tags":["Sheets & documents"],"summary":"Get an upload link for a sheet or document","description":"Gives you a link, valid for 1 hour, to upload new content for a spreadsheet, document or presentation straight to file storage. Asking for the link changes nothing; once content has been uploaded with it, the document is read from there the next time it is opened, read or saved. Uploading this way does not change its version or last editor. Needs the editor role or higher in its space, or the editor role on the document itself, given when it was shared; its creator's owner role counts only while they are an editor or owner of the space. Not while its space is archived.\n\n**Permission:** `spaces.univer.read` (View spreadsheets).","operationId":"getDocumentUploadUrl","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"type":"string","description":"Link to send the new content to with an HTTP PUT"},"expiresIn":{"type":"integer","description":"How long the link works, in seconds (always 3600)"}}},"example":{"uploadUrl":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/6a9f3c21b7e4a20f1c5d8e41/univer/spreadsheet/6ad0a0d2d5c26de56de949e6/data.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T110500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4d1e7a9c2b5f8e3d6a0c9b4f7e2d5a8c1b6f9e3d7a0c4b8f2e5d9a3c6b0f7e1d","expiresIn":3600}}}},"400":{"description":"documentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of its space, nor an editor of the document; its creator counts only while an editor or owner of the space, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.read"]}],"x-required-scopes":["spaces.univer.read"]}},"/univer/documents/{documentId}/versions":{"get":{"tags":["Sheets & documents"],"summary":"List a sheet or document's versions","description":"Lists the earlier versions kept for a spreadsheet, document or presentation, newest first. One is kept each time its content is saved with createSnapshot, up to the latest 50. Open to the members of its space, to anyone when the space is public, and to the people it was shared with; its creator's own access ends when they leave the space. getDocumentVersion opens one, restoreDocumentVersion brings one back.\n\n**Permission:** `spaces.univer.read` (View spreadsheets).","operationId":"listDocumentVersions","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"How many of the latest versions to return","example":10}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the earlier version"},"version":{"type":"integer","description":"The version number the content had"},"createdBy":{"type":"object","properties":{"_id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"}},"description":"Who saved over it: { _id, firstName, lastName, email }, or null when there is no user record"},"createdAt":{"type":"string","format":"date-time","description":"When it was kept"},"summary":{"type":"string","description":"The note saved with it; absent when none was given"},"fileSize":{"type":"integer","description":"Its size in bytes"}}},"description":"Earlier versions kept, newest first"},"currentVersion":{"type":"integer","description":"The version number of the current content"}}},"example":{"versions":[{"id":"6ad0a0e9d5c26de56de949f0","version":6,"createdBy":{"_id":"66f1b2c3d4e5f60718293a5c","firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com"},"createdAt":"2026-10-15T11:05:00.000Z","summary":"Before adding November","fileSize":18102},{"id":"6ad0a0e1d5c26de56de949ec","version":5,"createdBy":{"_id":"66f1b2c3d4e5f60718293a5c","firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com"},"createdAt":"2026-10-15T10:20:00.000Z","summary":"Before the sales figures","fileSize":16488}],"currentVersion":7}}}},"400":{"description":"documentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see its space (it is private and you are not a member, or it is archived) and it was not shared with you; its creator's own access ends when they leave the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.univer.read"]}],"x-required-scopes":["spaces.univer.read"]}},"/univer/documents/{documentId}/versions/{versionId}":{"get":{"tags":["Sheets & documents"],"summary":"Open an earlier version of a sheet or document","description":"Gets the content an earlier version of a spreadsheet, document or presentation had, to look at it before bringing it back with restoreDocumentVersion. Nothing changes. Open to the members of its space, to anyone when the space is public, and to the people it was shared with. Its creator's own access ends when they leave the space.\n\n**Permission:** `spaces.univer.read` (View spreadsheets).","operationId":"getDocumentVersion","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the earlier version, from listDocumentVersions","example":"6ad0a0e9d5c26de56de949f0"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"object","properties":{"id":{"type":"string","description":"ID of the earlier version"},"version":{"type":"integer","description":"The version number the content had"},"createdBy":{"type":"string","description":"Who saved over it, as a user ID"},"createdAt":{"type":"string","format":"date-time","description":"When it was kept"},"summary":{"type":"string","description":"The note saved with it; absent when none was given"},"fileSize":{"type":"integer","description":"Its size in bytes"}}},"content":{"type":"object","properties":{"id":{"type":"string"},"sheetOrder":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"appVersion":{"type":"string"},"locale":{"type":"string"},"styles":{"type":"object","properties":{}},"sheets":{"type":"object","properties":{"sheet1":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rowCount":{"type":"integer"},"columnCount":{"type":"integer"},"cellData":{"type":"object","properties":{"0":{"type":"object","properties":{"0":{"type":"object","properties":{"v":{"type":"string"}}},"1":{"type":"object","properties":{"v":{"type":"string"}}}}},"1":{"type":"object","properties":{"0":{"type":"object","properties":{"v":{"type":"string"}}},"1":{"type":"object","properties":{"v":{"type":"integer"}}}}}}},"rowData":{"type":"object","properties":{}},"columnData":{"type":"object","properties":{}}}}}}},"description":"The content that version had, as JSON in the same shape as getDocumentContent's: for a spreadsheet a workbook, for a document its body and page style, for a presentation its slides"},"currentVersion":{"type":"integer","description":"The version number of the current content"}}},"example":{"version":{"id":"6ad0a0e9d5c26de56de949f0","version":6,"createdBy":"66f1b2c3d4e5f60718293a5c","createdAt":"2026-10-15T11:05:00.000Z","summary":"Before adding November","fileSize":18102},"content":{"id":"6ad0a0d2d5c26de56de949e6","sheetOrder":["sheet1"],"name":"October budget","appVersion":"1.0.0","locale":"en-US","styles":{},"sheets":{"sheet1":{"id":"sheet1","name":"Sheet 1","rowCount":1000,"columnCount":26,"cellData":{"0":{"0":{"v":"Team"},"1":{"v":"Budget"}},"1":{"0":{"v":"Sales"},"1":{"v":18450}}},"rowData":{},"columnData":{}}}},"currentVersion":7}}}},"400":{"description":"documentId or versionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see its space (it is private and you are not a member, or it is archived) and it was not shared with you; its creator's own access ends when they leave the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, it is archived, or it has no earlier version with that ID (the latest 50 are kept)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The version's stored content could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"File storage is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.read"]}],"x-required-scopes":["spaces.univer.read"]}},"/strategies/{strategyId}":{"get":{"tags":["Strategies"],"summary":"Get a strategy","description":"Gets a strategy with everything in it: vision, mission, timeframe, SWOT items, pillars, objectives with their key results, initiatives, milestones and reviews. You must be able to see the strategy's space: be a member, or it is public. Strategies are made by adding a strategy item to a space (createSpaceItemWithTarget), and archived by archiving that item (archiveSpaceItem).\n\n**Permission:** `spaces.strategies.read` (View strategy).","operationId":"getStrategy","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the strategy's space: you are not a member and it is not public","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.read"]}],"x-required-scopes":["spaces.strategies.read"]},"put":{"tags":["Strategies"],"summary":"Update a strategy","description":"Changes a strategy's name, description, vision, mission, desired outcome, timeframe, status or phase; fields you leave out stay as they are. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateStrategy","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currentPhase":{"type":"string","enum":["define","analyze","plan","mobilize","execute","review"],"description":"Which planning phase the strategy is in","examples":["execute"]},"description":{"type":"string","description":"New short description","examples":["How we grow business customers over the next year"]},"desiredOutcome":{"type":"string","description":"What success looks like","examples":["Business revenue doubled by June 2027"]},"mission":{"type":"string","description":"How it will get there","examples":["Reliable fibre with support that answers in minutes"]},"name":{"type":"string","description":"New name","examples":["Business growth 2026-27"]},"status":{"type":"string","enum":["draft","active","completed","archived"],"description":"Where the strategy stands. archived here is only a label: the strategy stays readable","examples":["active"]},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}},"description":"Period the strategy covers, as { startDate, endDate } (a JSON object in a string also works). Replaces the whole timeframe, so send both dates","examples":[{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"}]},"vision":{"type":"string","description":"Where the organisation wants to be","examples":["The first choice for business internet in East Africa"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which), or timeframe is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/metabase/config":{"get":{"tags":["Settings"],"summary":"Get the analytics settings","description":"Shows the address of the organisation's analytics server (Metabase) and whether its dashboards can be shown in the app. The embedding secret is never shown. Anyone with this permission can read the settings; config is null when none are saved.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getAnalyticsConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"id":{"type":"string","description":"ID of the analytics settings"},"siteUrl":{"type":"string","description":"Address of the analytics server"},"isEnabled":{"type":"boolean","description":"Whether dashboards can be shown"},"createdAt":{"type":"string","format":"date-time","description":"When analytics was first set up"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed"}},"description":"The organisation's analytics settings; null when none are saved"}}},"example":{"config":{"id":"6ad1b0c2e4f5a60718293b05","siteUrl":"https://analytics.example.com","isEnabled":true,"createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T13:00:00.000Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]},"put":{"tags":["Settings"],"summary":"Set up or change the analytics server","description":"Saves the address of the organisation's analytics server (Metabase) and the secret used to sign dashboard links. Needs an organisation admin. The secret is needed the first time; later, leave it out to keep it. Leaving isEnabled out turns dashboards on.\n\n**Permission:** `spaces.integrations.update` (Configure integrations).","operationId":"updateAnalyticsConfig","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"embeddingSecret":{"type":"string","description":"The analytics server's embedding secret key, used to sign dashboard links. Needed when none is saved; leave out to keep the saved one. Never returned","examples":["fake-embedding-secret-0000"]},"isEnabled":{"type":"boolean","description":"false stops dashboard links from being made (getAnalyticsDashboardUrl refuses). Leaving it out sets it to true, even if it was false","examples":[true]},"siteUrl":{"type":"string","description":"Address of the analytics server; one trailing / is removed. It is not checked further","examples":["https://analytics.example.com"]}},"required":["siteUrl"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"id":{"type":"string","description":"ID of the analytics settings"},"siteUrl":{"type":"string","description":"Address of the analytics server"},"isEnabled":{"type":"boolean","description":"Whether dashboards can be shown"},"createdAt":{"type":"string","format":"date-time","description":"When analytics was first set up"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed"}},"description":"The analytics settings as saved"}}},"example":{"config":{"id":"6ad1b0c2e4f5a60718293b05","siteUrl":"https://analytics.example.com","isEnabled":true,"createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T13:00:00.000Z"}}}}},"400":{"description":"No embedding secret is given when none is saved, or the settings could not be saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.update"]}],"x-required-scopes":["spaces.integrations.update"]},"delete":{"tags":["Settings"],"summary":"Delete the analytics settings","description":"Deletes the organisation's analytics server address and secret for good, so dashboard links can no longer be made. Needs an organisation admin. Succeeds even when nothing was saved.\n\n**Permission:** `spaces.integrations.delete` (Delete integrations).","operationId":"deleteAnalyticsConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.delete"]}],"x-required-scopes":["spaces.integrations.delete"]}},"/metabase/embed-url":{"get":{"tags":["Settings"],"summary":"Get a link to an analytics dashboard","description":"Makes a signed link that shows one dashboard from the organisation's analytics server inside the app, valid for 10 minutes. Anyone with this permission can get a link to any dashboard number, locked to whatever filter values they pass.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getAnalyticsDashboardUrl","parameters":[{"name":"dashboardId","in":"query","required":true,"schema":{"type":"integer"},"description":"Number of the dashboard on the analytics server (the number in its address)","example":12},{"name":"params","in":"query","required":false,"schema":{"type":"string"},"description":"Filter values to lock the dashboard to, as a JSON object in a string. Defaults to none","example":"{\"region\":\"Nairobi\"}"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"embedUrl":{"type":"string","description":"Signed link that shows the dashboard, for a frame in the app; it works for 10 minutes"}}},"example":{"embedUrl":"https://analytics.example.com/embed/dashboard/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNvdXJjZSI6eyJkYXNoYm9hcmQiOjEyfX0.fake-signature#bordered=false&titled=true"}}}},"400":{"description":"Analytics is not set up or is turned off, dashboardId is not a number, or params is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The link could not be signed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]}},"/settings/ai-config":{"get":{"tags":["Settings"],"summary":"Get the AI provider settings","description":"Shows which AI providers (OpenAI, Anthropic) the organisation has an API key for, with each key's model, and which provider is the default. No part of a key is ever shown. With nothing saved, both providers are null and the default is openai.\n\n**Permission:** `spaces.settings.read` (View AI settings).","operationId":"getOrgAIConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"defaultProvider":{"type":"string","description":"Provider AI features use unless told otherwise: openai or anthropic"},"openai":{"type":"object","properties":{"configured":{"type":"boolean","description":"Always true: a key is saved"},"hint":{"type":"string","description":"Always empty: no part of the key is ever shown (configured says a key is saved)"},"model":{"type":"string","description":"Model to use; empty means the provider's default model"},"configuredBy":{"type":"string","description":"ID of the admin who saved the key"},"configuredAt":{"type":"string","format":"date-time","description":"When the key was saved"}},"description":"OpenAI key details; null when no OpenAI key is saved"},"anthropic":{"type":"object","properties":{"configured":{"type":"boolean","description":"Always true: a key is saved"},"hint":{"type":"string","description":"Always empty: no part of the key is ever shown (configured says a key is saved)"},"model":{"type":"string","description":"Model to use; empty means the provider's default model"},"configuredBy":{"type":"string","description":"ID of the admin who saved the key"},"configuredAt":{"type":"string","format":"date-time","description":"When the key was saved"}},"description":"Anthropic key details; null when no Anthropic key is saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the AI settings last changed; null when none are saved"}},"description":"The organisation's AI settings"},"cryptoReady":{"type":"boolean","description":"Whether the server can store keys; when false, saving a key fails"},"isAdmin":{"type":"boolean","description":"Whether you are an organisation admin, and so may change these settings"}}},"example":{"config":{"defaultProvider":"openai","openai":{"configured":true,"hint":"","model":"gpt-4.1","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T12:00:00.000Z"},"anthropic":{"configured":true,"hint":"","model":"claude-sonnet-5-5","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T12:05:00.000Z"},"updatedAt":"2026-10-14T12:05:00.000Z"},"cryptoReady":true,"isAdmin":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.settings.read"]}],"x-required-scopes":["spaces.settings.read"]},"put":{"tags":["Settings"],"summary":"Save an AI provider key","description":"Saves the API key and model for one AI provider, replacing any saved key; the key is stored encrypted. Needs an organisation admin; after 10 AI setting changes or tests in a row, further ones fail until a minute passes after the last. When the organisation has no AI settings yet, or with setAsDefault, the provider becomes the default.\n\n**Permission:** `spaces.settings.update` (Update AI settings).","operationId":"updateOrgAIConfig","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string","minLength":8,"description":"The provider's API key, at least 8 characters (spaces at the ends are removed)","examples":["sk-fake-example-key-0000"]},"model":{"type":"string","description":"Model to use, e.g. gpt-4.1. Leaving it out saves no model, so the provider's default is used (gpt-4.1 for OpenAI, claude-sonnet-5-5 for Anthropic, unless the server is set up with others)","examples":["gpt-4.1"]},"provider":{"type":"string","enum":["openai","anthropic"],"description":"Which AI provider the key is for","examples":["openai"]},"setAsDefault":{"type":"boolean","description":"true (or the string \"true\") to make this provider the default","examples":[true]}},"required":["apiKey","provider"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"defaultProvider":{"type":"string","description":"Provider AI features use unless told otherwise: openai or anthropic"},"openai":{"type":"object","properties":{"configured":{"type":"boolean","description":"Always true: a key is saved"},"hint":{"type":"string","description":"Always empty: no part of the key is ever shown (configured says a key is saved)"},"model":{"type":"string","description":"Model to use; empty means the provider's default model"},"configuredBy":{"type":"string","description":"ID of the admin who saved the key"},"configuredAt":{"type":"string","format":"date-time","description":"When the key was saved"}},"description":"OpenAI key details; null when no OpenAI key is saved"},"anthropic":{"type":"object","properties":{"configured":{"type":"boolean","description":"Always true: a key is saved"},"hint":{"type":"string","description":"Always empty: no part of the key is ever shown (configured says a key is saved)"},"model":{"type":"string","description":"Model to use; empty means the provider's default model"},"configuredBy":{"type":"string","description":"ID of the admin who saved the key"},"configuredAt":{"type":"string","format":"date-time","description":"When the key was saved"}},"description":"Anthropic key details; null when no Anthropic key is saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the AI settings last changed; null when none are saved"}},"description":"The AI settings after the save"}}},"example":{"config":{"defaultProvider":"openai","openai":{"configured":true,"hint":"","model":"gpt-4.1","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T12:00:00.000Z"},"anthropic":{"configured":true,"hint":"","model":"claude-sonnet-5-5","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T12:05:00.000Z"},"updatedAt":"2026-10-14T12:05:00.000Z"}}}}},"400":{"description":"provider is not openai or anthropic, or apiKey is under 8 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"You made 10 AI setting changes or tests in a row; wait a minute after the last one (code RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The server has no encryption key set up, so it cannot store the key (code CRYPTO_NOT_CONFIGURED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.settings.update"]}],"x-required-scopes":["spaces.settings.update"]}},"/integrations/yeastar/config":{"get":{"tags":["Settings"],"summary":"Get the phone system settings","description":"Shows how the organisation's phone system (Kazee Phone's PBX) is connected: its type, address, whether calling is on and the last test result. No part of its login details is shown, only whether they are saved. Anyone with this permission can read the settings, not only admins; config is null when none are saved.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getPhoneSystemConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"id":{"type":"string","description":"ID of the phone system settings"},"pbxType":{"type":"string","description":"Phone system model: k2_v2 (K2 and S-Series) or p_series (P-Series)"},"baseUrl":{"type":"string","description":"Address of the phone system"},"apiPath":{"type":"string","description":"Path of its API; the type's usual path when none was saved"},"isEnabled":{"type":"boolean","description":"Whether calling through it is turned on"},"insecureTLS":{"type":"boolean","description":"Whether its self-signed certificate is accepted"},"configured":{"type":"boolean","description":"Whether login details are saved"},"clientIdHint":{"type":"string","description":"Always empty: no part of the login details is ever shown"},"clientSecretHint":{"type":"string","description":"Always empty: no part of the login details is ever shown"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the saved settings were last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested. Click-to-call needs ok"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"pbxInfo":{"type":"object","properties":{"deviceName":{"type":"string","description":"Device model name"},"serialNumber":{"type":"string","description":"Device serial number"},"firmwareVersion":{"type":"string","description":"Firmware version"}},"description":"Device details from the last successful test (K2 and S-Series only); empty texts until then"},"configuredBy":{"type":"string","description":"ID of the admin who last saved the settings"},"configuredAt":{"type":"string","format":"date-time","description":"When the settings were last saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed"}},"description":"The organisation's phone system settings; null when none are saved"},"cryptoReady":{"type":"boolean","description":"Whether the server can store login details; when false, saving the settings fails"},"isAdmin":{"type":"boolean","description":"Whether you are an organisation admin, and so may change these settings"}}},"example":{"config":{"id":"6ad1b0c2e4f5a60718293b03","pbxType":"k2_v2","baseUrl":"https://pbx.example.com:8088","apiPath":"/api/v2.0.0","isEnabled":true,"insecureTLS":true,"configured":true,"clientIdHint":"","clientSecretHint":"","lastTestedAt":"2026-10-14T11:00:00.000Z","lastTestStatus":"ok","lastTestError":"","pbxInfo":{"deviceName":"S50","serialNumber":"3631A0000001","firmwareVersion":"30.12.0.16"},"configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T10:55:00.000Z","updatedAt":"2026-10-14T11:00:00.000Z"},"cryptoReady":true,"isAdmin":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]},"put":{"tags":["Settings"],"summary":"Set up or change the phone system","description":"Saves how the organisation connects to its phone system. Needs an organisation admin. clientId and clientSecret are needed the first time and are stored encrypted; later, leave both out to keep them. Changing the type or address clears the saved device details until the next test, and saving does not test the connection.\n\n**Permission:** `spaces.integrations.update` (Configure integrations).","operationId":"updatePhoneSystemConfig","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiPath":{"type":"string","description":"Path of the phone system's API. Leave out or empty for the type's usual path (/api/v2.0.0 for k2_v2, /openapi/v1.0 for p_series); leaving it out also replaces a path saved before","examples":[""]},"baseUrl":{"type":"string","description":"Address of the phone system. https:// is added when no scheme is given, and trailing / are removed. It may be on a private network (10.x, 172.16-31.x, 192.168.x), not on the platform's own (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names), by name or by what the name resolves to","examples":["https://pbx.example.com:8088"]},"clientId":{"type":"string","description":"API user name (K2 and S-Series) or client ID (P-Series). Send it with clientSecret to replace the saved login details; sending only one of the two changes neither","examples":["fake-api-user"]},"clientSecret":{"type":"string","description":"API password (K2 and S-Series) or client secret (P-Series); see clientId","examples":["fake-api-password"]},"insecureTLS":{"type":"boolean","description":"true (or the string \"true\") to accept the phone system's self-signed certificate, common on office networks. Leave out to keep the saved value (false for new settings)","examples":[true]},"isEnabled":{"type":"boolean","description":"false turns calling off without deleting the settings. Must be a JSON true or false; leave out to keep the saved value (true for new settings)","examples":[true]},"pbxType":{"type":"string","enum":["p_series","k2_v2"],"description":"Phone system model: k2_v2 for K2 and S-Series, p_series for P-Series. Leave out to keep the saved one (k2_v2 for new settings); an unknown value counts as left out","examples":["k2_v2"]}},"required":["baseUrl"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"id":{"type":"string","description":"ID of the phone system settings"},"pbxType":{"type":"string","description":"Phone system model: k2_v2 (K2 and S-Series) or p_series (P-Series)"},"baseUrl":{"type":"string","description":"Address of the phone system"},"apiPath":{"type":"string","description":"Path of its API; the type's usual path when none was saved"},"isEnabled":{"type":"boolean","description":"Whether calling through it is turned on"},"insecureTLS":{"type":"boolean","description":"Whether its self-signed certificate is accepted"},"configured":{"type":"boolean","description":"Whether login details are saved"},"clientIdHint":{"type":"string","description":"Always empty: no part of the login details is ever shown"},"clientSecretHint":{"type":"string","description":"Always empty: no part of the login details is ever shown"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the saved settings were last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested. Click-to-call needs ok"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"pbxInfo":{"type":"object","properties":{"deviceName":{"type":"string","description":"Device model name"},"serialNumber":{"type":"string","description":"Device serial number"},"firmwareVersion":{"type":"string","description":"Firmware version"}},"description":"Device details from the last successful test (K2 and S-Series only); empty texts until then"},"configuredBy":{"type":"string","description":"ID of the admin who last saved the settings"},"configuredAt":{"type":"string","format":"date-time","description":"When the settings were last saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed"}},"description":"The phone system settings as saved"}}},"example":{"config":{"id":"6ad1b0c2e4f5a60718293b03","pbxType":"k2_v2","baseUrl":"https://pbx.example.com:8088","apiPath":"/api/v2.0.0","isEnabled":true,"insecureTLS":true,"configured":true,"clientIdHint":"","clientSecretHint":"","lastTestedAt":"2026-10-14T11:00:00.000Z","lastTestStatus":"ok","lastTestError":"","pbxInfo":{"deviceName":"S50","serialNumber":"3631A0000001","firmwareVersion":"30.12.0.16"},"configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T10:55:00.000Z","updatedAt":"2026-10-14T11:00:00.000Z"}}}}},"400":{"description":"baseUrl is not a valid address, or is on the platform's own network (code INTERNAL_ADDRESS); or clientId and clientSecret are missing when none are saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The server has no encryption key set up, so it cannot store login details (code CRYPTO_NOT_CONFIGURED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.update"]}],"x-required-scopes":["spaces.integrations.update"]},"delete":{"tags":["Settings"],"summary":"Delete the phone system settings","description":"Deletes the organisation's phone system settings and login details for good, removes every person's link to an extension and clears the extension on every profile. Needs an organisation admin. Click-to-call stops working until the phone system is set up and the people are linked again. Succeeds even when nothing was saved.\n\n**Permission:** `spaces.integrations.delete` (Delete integrations).","operationId":"deletePhoneSystemConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.delete"]}],"x-required-scopes":["spaces.integrations.delete"]}},"/integrations/yeastar/me":{"get":{"tags":["Messages & calls"],"summary":"Check whether I can place calls","description":"Tells you whether click-to-call works for you: the phone system must be set up, turned on and have passed its last test, and you need a linked extension. It does not contact the phone system.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getMyPhoneStatus","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the phone system is set up, turned on and passed its last test"},"extension":{"type":"string","description":"Your linked extension; null when you have none"},"canPlaceCalls":{"type":"boolean","description":"true when both hold, so startPhoneCall can call from your extension"}}},"example":{"enabled":true,"extension":"2001","canPlaceCalls":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]}},"/integrations/yeastar/extensions":{"get":{"tags":["Settings"],"summary":"List the phone system's extensions","description":"Fetches every extension straight from the phone system, to choose from when linking people to extensions. Needs an organisation admin. Each call asks the phone system again; nothing is saved.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"listPhoneExtensions","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"extensions":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The phone system's own ID for the extension (P-Series only); null on K2 and S-Series"},"number":{"type":"string","description":"Extension number"},"callerIdName":{"type":"string","description":"Name shown for the extension"},"emailAddr":{"type":"string","description":"Email address set on the extension; empty when there is none"},"mobileNumber":{"type":"string","description":"Mobile number set on the extension; empty when there is none"},"roleName":{"type":"string","description":"Role (P-Series) or extension type such as SIP (K2 and S-Series)"},"presenceStatus":{"type":"string","description":"Presence (P-Series) or registration status (K2 and S-Series), as the phone system reports it"}}},"description":"Every extension on the phone system"},"total":{"type":"integer","description":"How many extensions there are"}}},"example":{"extensions":[{"id":null,"number":"2001","callerIdName":"Jane Wanjiku","emailAddr":"jane@example.com","mobileNumber":"+254712345678","roleName":"SIP","presenceStatus":"Registered"},{"id":null,"number":"2002","callerIdName":"Peter Otieno","emailAddr":"peter@example.com","mobileNumber":"+254722000111","roleName":"SIP","presenceStatus":"Unavailable"}],"total":2}}}},"400":{"description":"The phone system is not set up (code NOT_CONFIGURED), the saved address is on the platform's own network (code INTERNAL_ADDRESS; saved before addresses were checked), so nothing is called, or the phone system rejected the saved login details (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The saved login details cannot be read, e.g. the server's encryption key changed (code DECRYPT_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The phone system failed or could not be reached (code PBX_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]}},"/integrations/yeastar/mappings":{"get":{"tags":["Settings"],"summary":"List people's phone extensions","description":"Lists which person is linked to which phone extension in the organisation. Anyone with this permission can see the whole list, not only admins.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"listPhoneExtensionMappings","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the link"},"userId":{"type":"string","description":"ID of the person"},"extensionNumber":{"type":"string","description":"Extension the person calls from"},"extensionId":{"description":"The phone system's own ID for the extension (P-Series only); null when unknown"},"callerIdName":{"type":"string","description":"Name shown for the extension, copied when the link was made"},"emailAddr":{"type":"string","description":"Email address of the extension, copied when the link was made"},"mobileNumber":{"type":"string","description":"Mobile number of the extension, copied when the link was made"},"roleName":{"type":"string","description":"Role or type of the extension, copied when the link was made"},"lastSyncedAt":{"type":"string","format":"date-time","description":"When those details were copied"},"mappedBy":{"type":"string","description":"ID of the admin who made the link"},"mappedAt":{"type":"string","format":"date-time","description":"When the link was made"}}},"description":"Every link between a person and an extension in the organisation"},"count":{"type":"integer","description":"How many links there are"}}},"example":{"mappings":[{"id":"6ad1b0c2e4f5a60718293b04","userId":"66f1b2c3d4e5f60718293a5c","extensionNumber":"2001","extensionId":null,"callerIdName":"Jane Wanjiku","emailAddr":"jane@example.com","mobileNumber":"+254712345678","roleName":"SIP","lastSyncedAt":"2026-10-14T11:10:00.000Z","mappedBy":"66f1b2c3d4e5f60718293a4b","mappedAt":"2026-10-14T11:10:00.000Z"},{"id":"6ad1b0c2e4f5a60718293b0a","userId":"66f1b2c3d4e5f60718293a4b","extensionNumber":"2002","extensionId":null,"callerIdName":"Peter Otieno","emailAddr":"peter@example.com","mobileNumber":"+254722000111","roleName":"SIP","lastSyncedAt":"2026-10-14T11:10:00.000Z","mappedBy":"66f1b2c3d4e5f60718293a4b","mappedAt":"2026-10-14T11:10:00.000Z"}],"count":2}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]}},"/integrations/sms/config":{"get":{"tags":["Settings"],"summary":"Get the SMS provider settings","description":"Shows the organisation's SMS provider settings without their secrets: for each secret only whether it is set, never any part of it. Anyone with this permission can read them, not only admins. config is null when none are saved.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getSmsProviderConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SMS settings"},"provider":{"type":"string","description":"Which provider sends the texts: celcom, or generic_http (any provider with an HTTP API)"},"isEnabled":{"type":"boolean","description":"Whether SMS is on for the organisation; when false nothing is sent"},"senderId":{"type":"string","description":"Sender name or short code recipients see"},"defaultCountryCode":{"type":"string","description":"Country calling code put in front of local numbers, without +; empty means none"},"celcom":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address texts are sent to"},"partnerId":{"type":"integer","description":"Celcom partner ID"},"passType":{"type":"string","description":"How the API key is passed, e.g. plain"},"configured":{"type":"boolean","description":"Whether an API key is saved"},"apiKeyHint":{"type":"string","description":"Always empty: no part of the API key is ever shown (celcom.configured says whether one is saved)"}},"description":"Celcom details (always present; used when provider is celcom)"},"generic":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address the request goes to"},"method":{"type":"string","description":"POST or PUT"},"contentType":{"type":"string","description":"application/json or application/x-www-form-urlencoded"},"headersTemplate":{"type":"string","description":"Request headers, one \"Key: Value\" per line; {{authHeader}} stands for the saved secret"},"bodyTemplate":{"type":"string","description":"Request body; {{phone}}, {{message}} and {{senderId}} are filled in"},"configured":{"type":"boolean","description":"Whether an auth header secret is saved"},"authHeaderHint":{"type":"string","description":"Always empty: no part of the auth header secret is ever shown (generic.configured says whether one is saved)"},"successPath":{"type":"string","description":"Field of the provider's reply checked for success, as a dotted path; empty means any 2xx reply counts"},"successValue":{"type":"string","description":"Value that field must have for a send to count"}},"description":"Details for a provider with an HTTP API (always present; used when provider is generic_http)"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the saved settings were last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"configuredBy":{"type":"string","description":"ID of the admin who last saved the settings"},"configuredAt":{"type":"string","format":"date-time","description":"When the settings were last saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed"}},"description":"The organisation's SMS settings; null when none are saved"},"cryptoReady":{"type":"boolean","description":"Whether the server can store secrets; when false, saving the settings fails"},"isAdmin":{"type":"boolean","description":"Whether you are an organisation admin, and so may change these settings"},"envFallbackActive":{"type":"boolean","description":"true when no settings are saved but the server has a default Celcom account set up, so texts may still go out through it"}}},"example":{"config":{"id":"6ad1b0c2e4f5a60718293b02","provider":"celcom","isEnabled":true,"senderId":"ExampleCo","defaultCountryCode":"254","celcom":{"baseUrl":"https://isms.celcomafrica.com/api/services/sendsms","partnerId":1234,"passType":"plain","configured":true,"apiKeyHint":""},"generic":{"baseUrl":"","method":"POST","contentType":"application/json","headersTemplate":"","bodyTemplate":"","configured":false,"authHeaderHint":"","successPath":"","successValue":""},"lastTestedAt":"2026-10-14T10:05:00.000Z","lastTestStatus":"ok","lastTestError":"","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T10:00:00.000Z","updatedAt":"2026-10-14T10:05:00.000Z"},"cryptoReady":true,"isAdmin":true,"envFallbackActive":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]},"put":{"tags":["Settings"],"summary":"Set up or change the SMS provider","description":"Saves the organisation's SMS provider: Celcom, or any provider with an HTTP API (generic_http). Needs an organisation admin. Only what you send changes, and only the chosen provider's details are saved; secrets (the Celcom API key, the generic auth header) are stored encrypted, and leaving one out keeps the saved one. Saving does not test the settings.\n\n**Permission:** `spaces.integrations.update` (Configure integrations).","operationId":"updateSmsProviderConfig","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"celcom":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address texts are sent to; defaults to Celcom's send address; it may be on a private network (10.x, 172.16-31.x, 192.168.x), not on the platform's own (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names)"},"apiKey":{"type":"string","description":"Celcom API key, at least 8 characters"},"partnerId":{"type":"integer","description":"Celcom partner ID, above 0"},"passType":{"type":"string","description":"How the API key is passed; defaults to plain"}},"description":"Celcom details, used when provider is celcom. apiKey is needed when none is saved (leave it out to keep the saved one); partnerId must be above 0; parts left out keep their saved values","examples":[{"apiKey":"fake-celcom-api-key-0000","partnerId":1234,"passType":"plain"}]},"defaultCountryCode":{"type":"string","description":"Country calling code put in front of local numbers (a leading + is removed). A local number loses its leading 0: with 254, 0712345678 becomes +254712345678. Empty turns this off","examples":["254"]},"generic":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address the request goes to; must start with http:// or https://; it may be on a private network (10.x, 172.16-31.x, 192.168.x), not on the platform's own (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names)"},"method":{"type":"string","enum":["POST","PUT"],"description":"Defaults to POST"},"contentType":{"type":"string","enum":["application/json","application/x-www-form-urlencoded"],"description":"Defaults to application/json"},"headersTemplate":{"type":"string","description":"Request headers, one \"Key: Value\" per line; {{authHeader}} stands for the secret"},"bodyTemplate":{"type":"string","description":"Request body; {{phone}}, {{message}} and {{senderId}} are filled in"},"authHeader":{"type":"string","description":"Secret for {{authHeader}}, stored encrypted"},"successPath":{"type":"string","description":"Dotted path of a field in the provider's reply; empty means any 2xx reply counts"},"successValue":{"type":"string","description":"Value that field must have for a send to count"}},"description":"Details for a provider with an HTTP API, used when provider is generic_http. baseUrl is needed unless one is saved; authHeader is optional (leave it out to keep the saved one); parts left out keep their saved values","examples":[{"baseUrl":"https://sms.example.com/api/send","method":"POST","contentType":"application/json","headersTemplate":"Authorization: Bearer {{authHeader}}","bodyTemplate":"{\"to\":\"{{phone}}\",\"text\":\"{{message}}\",\"from\":\"{{senderId}}\"}","authHeader":"fake-bearer-token-0000","successPath":"status","successValue":"sent"}]},"isEnabled":{"type":"boolean","description":"false turns SMS off for the organisation without deleting the settings: nothing is sent, not even through the server's default Celcom account, until it is turned back on. Must be a JSON true or false; leave out to keep the saved value (true for new settings)","examples":[true]},"provider":{"type":"string","enum":["celcom","generic_http"],"description":"Which provider sends the texts. Leave out to keep the saved one (celcom for new settings); an unknown value counts as left out","examples":["celcom"]},"senderId":{"type":"string","description":"Sender name or short code recipients see; needed for Celcom when none is saved","examples":["ExampleCo"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SMS settings"},"provider":{"type":"string","description":"Which provider sends the texts: celcom, or generic_http (any provider with an HTTP API)"},"isEnabled":{"type":"boolean","description":"Whether SMS is on for the organisation; when false nothing is sent"},"senderId":{"type":"string","description":"Sender name or short code recipients see"},"defaultCountryCode":{"type":"string","description":"Country calling code put in front of local numbers, without +; empty means none"},"celcom":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address texts are sent to"},"partnerId":{"type":"integer","description":"Celcom partner ID"},"passType":{"type":"string","description":"How the API key is passed, e.g. plain"},"configured":{"type":"boolean","description":"Whether an API key is saved"},"apiKeyHint":{"type":"string","description":"Always empty: no part of the API key is ever shown (celcom.configured says whether one is saved)"}},"description":"Celcom details (always present; used when provider is celcom)"},"generic":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address the request goes to"},"method":{"type":"string","description":"POST or PUT"},"contentType":{"type":"string","description":"application/json or application/x-www-form-urlencoded"},"headersTemplate":{"type":"string","description":"Request headers, one \"Key: Value\" per line; {{authHeader}} stands for the saved secret"},"bodyTemplate":{"type":"string","description":"Request body; {{phone}}, {{message}} and {{senderId}} are filled in"},"configured":{"type":"boolean","description":"Whether an auth header secret is saved"},"authHeaderHint":{"type":"string","description":"Always empty: no part of the auth header secret is ever shown (generic.configured says whether one is saved)"},"successPath":{"type":"string","description":"Field of the provider's reply checked for success, as a dotted path; empty means any 2xx reply counts"},"successValue":{"type":"string","description":"Value that field must have for a send to count"}},"description":"Details for a provider with an HTTP API (always present; used when provider is generic_http)"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the saved settings were last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"configuredBy":{"type":"string","description":"ID of the admin who last saved the settings"},"configuredAt":{"type":"string","format":"date-time","description":"When the settings were last saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed"}},"description":"The SMS settings as saved"}}},"example":{"config":{"id":"6ad1b0c2e4f5a60718293b02","provider":"celcom","isEnabled":true,"senderId":"ExampleCo","defaultCountryCode":"254","celcom":{"baseUrl":"https://isms.celcomafrica.com/api/services/sendsms","partnerId":1234,"passType":"plain","configured":true,"apiKeyHint":""},"generic":{"baseUrl":"","method":"POST","contentType":"application/json","headersTemplate":"","bodyTemplate":"","configured":false,"authHeaderHint":"","successPath":"","successValue":""},"lastTestedAt":"2026-10-14T10:05:00.000Z","lastTestStatus":"ok","lastTestError":"","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T10:00:00.000Z","updatedAt":"2026-10-14T10:05:00.000Z"}}}}},"400":{"description":"For Celcom: apiKey is under 8 characters, or missing when none is saved; partnerId is missing; or there is no senderId. For generic_http: contentType is not allowed, or baseUrl does not start with http:// or https://. For either: the address is on the platform's own network (code INTERNAL_ADDRESS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The server has no encryption key set up, so it cannot store secrets (code CRYPTO_NOT_CONFIGURED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.update"]}],"x-required-scopes":["spaces.integrations.update"]},"delete":{"tags":["Settings"],"summary":"Delete the SMS provider settings","description":"Deletes the organisation's SMS provider settings and secrets for good. Needs an organisation admin. Afterwards texts go out through the server's default Celcom account if it has one, otherwise sending fails. Succeeds even when nothing was saved.\n\n**Permission:** `spaces.integrations.delete` (Delete integrations).","operationId":"deleteSmsProviderConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.delete"]}],"x-required-scopes":["spaces.integrations.delete"]}},"/integrations/sms/me":{"get":{"tags":["Messages & calls"],"summary":"Check whether I can send SMS","description":"Tells you whether texts can be sent in your organisation, through its own SMS settings or, when it has none, the server's default Celcom account, and which country code local numbers get. No secrets are shown. When neither works, or the organisation's own settings are turned off or cannot be read, enabled is false, provider and source are null and the texts are empty.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getMySmsStatus","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether texts can be sent"},"provider":{"type":"string","description":"celcom or generic_http; null when enabled is false"},"senderId":{"type":"string","description":"Sender name or short code recipients see; empty when enabled is false"},"defaultCountryCode":{"type":"string","description":"Country code put in front of local numbers, without +; empty when none or when enabled is false"},"source":{"type":"string","description":"org_config (the organisation's own settings) or env_fallback (the server's default Celcom account); null when enabled is false"}}},"example":{"enabled":true,"provider":"celcom","senderId":"ExampleCo","defaultCountryCode":"254","source":"org_config"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]}},"/integrations/email/config":{"get":{"tags":["Settings"],"summary":"Get the email account settings","description":"Shows the organisation's send-as email accounts (address, mail server, last test result) without their passwords. Anyone with this permission can read them, not only admins. With no settings saved, config holds only an empty accounts list.\n\n**Permission:** `spaces.integrations.read` (View integrations).","operationId":"getEmailProviderConfig","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Account ID; pass it as accountId to send from, test or delete the account"},"label":{"type":"string","description":"Name shown when picking the account"},"fromAddress":{"type":"string","description":"Address the emails come from"},"fromName":{"type":"string","description":"Sender name shown with the address; empty if none"},"replyTo":{"type":"string","description":"Address replies go to; empty means replies go to fromAddress"},"host":{"type":"string","description":"Mail server (SMTP) host"},"port":{"type":"integer","description":"Mail server port"},"secure":{"type":"boolean","description":"true: TLS from the start (usually port 465); false: STARTTLS (usually port 587)"},"username":{"type":"string","description":"User name for logging in to the mail server"},"isEnabled":{"type":"boolean","description":"Whether the account may send; a turned-off account cannot"},"configured":{"type":"boolean","description":"Whether a password is saved"},"passwordHint":{"type":"string","description":"Always empty: no part of the password is ever shown (configured says whether one is saved)"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the account was last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"createdAt":{"type":"string","format":"date-time","description":"When the account was added"},"updatedAt":{"type":"string","format":"date-time","description":"When the account last changed"}}},"description":"The organisation's send-as email accounts; empty when none are set up"},"configuredBy":{"type":"string","description":"ID of the admin who last saved an account; absent when nothing was ever saved"},"configuredAt":{"type":"string","format":"date-time","description":"When an account was last saved; absent when nothing was ever saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed; absent when nothing was ever saved"}},"description":"The organisation's email settings"},"cryptoReady":{"type":"boolean","description":"Whether the server can store passwords; when false, saving an account fails"},"isAdmin":{"type":"boolean","description":"Whether you are an organisation admin, and so may change these settings"}}},"example":{"config":{"accounts":[{"id":"3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90","label":"Sales","fromAddress":"sales@example.com","fromName":"Example Ltd Sales","replyTo":"support@example.com","host":"smtp.example.com","port":587,"secure":false,"username":"sales@example.com","isEnabled":true,"configured":true,"passwordHint":"","lastTestedAt":"2026-10-14T09:12:00.000Z","lastTestStatus":"ok","lastTestError":"","createdAt":"2026-10-01T08:00:00.000Z","updatedAt":"2026-10-14T09:10:00.000Z"}],"configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T09:10:00.000Z","updatedAt":"2026-10-14T09:12:00.000Z"},"cryptoReady":true,"isAdmin":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.read"]}],"x-required-scopes":["spaces.integrations.read"]}},"/pipelines/{pipelineId}/email-templates":{"get":{"tags":["Pipelines"],"summary":"List a pipeline's email templates","description":"Lists a pipeline's email templates by name, turned-off ones too. You must be able to see the pipeline's space (a member, or it is public); archived pipelines work too.\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"listPipelineEmailTemplates","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Template ID"},"pipelineId":{"type":"string","description":"ID of the pipeline it belongs to"},"name":{"type":"string","description":"Name, unique within the pipeline"},"description":{"type":"string","description":"What it is for"},"subject":{"type":"string","description":"Subject line; may hold macros"},"bodyHtml":{"type":"string","description":"HTML body; may hold macros"},"bodyText":{"type":"string","description":"Plain-text body; may hold macros. When empty, a text version of bodyHtml is used at send time"},"allowedAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts it may be sent from; empty means any the pipeline allows"},"isEnabled":{"type":"boolean","description":"Whether it is offered when writing an email on a record"},"createdBy":{"type":"string","description":"ID of the person who created it"},"updatedBy":{"type":"string","description":"ID of the person who changed it last"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}},"isAdmin":{"type":"boolean","description":"Whether you are an organisation admin, so may create, change and delete templates"}}},"example":{"templates":[{"id":"6ad1c2e0f3a4b5c6d7e8f903","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","name":"Quote follow-up","description":"Sent two days after a quote goes out","subject":"Your quote for {{record.title}}","bodyHtml":"<p>Hello {{field.contactName | default: \"there\"}},</p><p>Following up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.</p><p>{{actor.firstName}}</p>","bodyText":"Hello {{field.contactName | default: \"there\"}},\n\nFollowing up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.\n\n{{actor.firstName}}","allowedAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"isEnabled":true,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-10-01T08:15:00.000Z","updatedAt":"2026-10-14T13:05:00.000Z"},{"id":"6ad1c2e0f3a4b5c6d7e8f904","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","name":"Welcome","description":"","subject":"Welcome, {{record.title}}","bodyHtml":"<p>Thanks for choosing us, {{field.contactName}}.</p>","bodyText":"","allowedAccountIds":[],"isEnabled":false,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a5c","createdAt":"2026-10-01T08:15:00.000Z","updatedAt":"2026-10-14T13:05:00.000Z"}],"isAdmin":true}}}},"400":{"description":"pipelineId is not a valid ID (code INVALID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space: you are not a member and it is not public (code FORBIDDEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID in your organisation (code PIPELINE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]},"post":{"tags":["Pipelines"],"summary":"Create a pipeline email template","description":"Creates an email template for a pipeline, which people can pick when writing an email on one of its records. Only organisation admins may call it, and not while the pipeline's space is archived.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"createPipelineEmailTemplate","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allowedAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts it may be sent from; empty means any the pipeline allows. Must be a JSON array; anything else is ignored","examples":[["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"]]},"bodyHtml":{"type":"string","description":"HTML body; macros work here too","examples":["<p>Hello {{field.contactName | default: \"there\"}},</p><p>Following up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.</p><p>{{actor.firstName}}</p>"]},"bodyText":{"type":"string","description":"Plain-text body; macros work here too. When empty, a text version of bodyHtml is used at send time","examples":["Hello {{field.contactName | default: \"there\"}},\n\nFollowing up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.\n\n{{actor.firstName}}"]},"description":{"type":"string","description":"What the template is for; spaces at the ends are trimmed","examples":["Sent two days after a quote goes out"]},"isEnabled":{"type":"boolean","description":"Whether it is offered when writing an email. Defaults to true. The text \"true\" or \"false\" also works","examples":[true]},"name":{"type":"string","description":"Name, unique within the pipeline; spaces at the ends are trimmed","examples":["Quote follow-up"]},"subject":{"type":"string","description":"Subject line. Macros: {{record.<key>}} for the record (e.g. {{record.title}}), {{field.<field>}} for a custom field, {{actor.firstName}} for the sender, {{today}}; {{x | default: \"text\"}} gives a fallback","examples":["Your quote for {{record.title}}"]}},"required":["name"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string","description":"Template ID"},"pipelineId":{"type":"string","description":"ID of the pipeline it belongs to"},"name":{"type":"string","description":"Name, unique within the pipeline"},"description":{"type":"string","description":"What it is for"},"subject":{"type":"string","description":"Subject line; may hold macros"},"bodyHtml":{"type":"string","description":"HTML body; may hold macros"},"bodyText":{"type":"string","description":"Plain-text body; may hold macros. When empty, a text version of bodyHtml is used at send time"},"allowedAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts it may be sent from; empty means any the pipeline allows"},"isEnabled":{"type":"boolean","description":"Whether it is offered when writing an email on a record"},"createdBy":{"type":"string","description":"ID of the person who created it"},"updatedBy":{"type":"string","description":"ID of the person who changed it last"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"template":{"id":"6ad1c2e0f3a4b5c6d7e8f903","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","name":"Quote follow-up","description":"Sent two days after a quote goes out","subject":"Your quote for {{record.title}}","bodyHtml":"<p>Hello {{field.contactName | default: \"there\"}},</p><p>Following up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.</p><p>{{actor.firstName}}</p>","bodyText":"Hello {{field.contactName | default: \"there\"}},\n\nFollowing up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.\n\n{{actor.firstName}}","allowedAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"isEnabled":true,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-10-01T08:15:00.000Z","updatedAt":"2026-10-14T13:05:00.000Z"}}}}},"400":{"description":"pipelineId is not a valid ID, or name is blank (code INVALID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin, or the pipeline's space is archived (code FORBIDDEN), or you are an assistant acting for an admin (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID in your organisation (code PIPELINE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has a template with that name (code DUPLICATE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/records/{recordId}/comms":{"get":{"tags":["Pipelines"],"summary":"List a record's emails, texts and calls","description":"Lists the emails, text messages (SMS) and phone calls logged on one pipeline record, with their full text, latest first, a page at a time. Open to the members of the record's space, and to anyone when the space is public.\n\n**Permission:** `spaces.comms.read` (View communications).","operationId":"listRecordComms","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad0a520d5c26de56de94a48"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad0a531d5c26de56de94a4f"},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only entries from before this time: the cursor of the previous page. A date that cannot be read is ignored","example":"2026-10-15T09:41:00.000Z"},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["call","sms","email"]},"description":"Only this kind; any other value is ignored and all kinds are listed","example":"email"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Most entries to return, from 1 to 200. Defaults to 50; larger values count as 200","example":50}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the entry"},"channel":{"type":"string","description":"email, sms or call"},"direction":{"type":"string","description":"outbound or inbound"},"status":{"type":"string","description":"sent, delivered, failed, received, missed or queued"},"pipelineId":{"type":"string","description":"ID of the pipeline"},"recordId":{"type":"string","description":"ID of the record"},"externalContact":{"type":"string","description":"The other side: a phone number in +254 form for sms and calls, a lower-case address for email"},"externalContactName":{"type":"string","description":"Their name, as known when it was logged"},"accountId":{"type":"string","description":"What it was sent from: an email account, an SMS sender name or a phone extension"},"accountLabel":{"type":"string","description":"Display label of that account"},"subject":{"type":"string","description":"Email subject; empty for sms and calls"},"bodyText":{"type":"string","description":"Text of the message"},"bodyHtml":{"type":"string","description":"Email body as HTML; empty for sms and calls"},"cc":{"type":"array","items":{"type":"string"},"description":"Email copies"},"bcc":{"type":"array","description":"Email blind copies"},"templateId":{"type":"string","description":"ID of the email template used, or null"},"externalRef":{"type":"string","description":"The provider's reference (message or call ID)"},"error":{"type":"string","description":"Why it failed, when status is failed"},"actorId":{"type":"string","description":"ID of the person who sent or placed it; null for inbound ones"},"actorName":{"type":"string","description":"Their name"},"durationSeconds":{"type":"integer","description":"Call length in seconds; 0 for email and sms"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened"}}},"description":"Emails, text messages and calls logged on the record, latest first"},"cursor":{"description":"When the page is full: pass this as before to get the next page; null when there are no more"}}},"example":{"comms":[{"id":"6ad0a560d5c26de56de94a63","channel":"email","direction":"outbound","status":"sent","pipelineId":"6ad0a520d5c26de56de94a48","recordId":"6ad0a531d5c26de56de94a4f","externalContact":"wanjiku.kamau@zuri-traders.co.ke","externalContactName":"Wanjiku Kamau","accountId":"accounts","accountLabel":"Accounts <accounts@acme.co.ke>","subject":"Invoice INV-2026-1042","bodyText":"Dear Wanjiku, please find invoice INV-2026-1042 attached. Kind regards, Amina","bodyHtml":"<p>Dear Wanjiku,</p><p>Please find invoice INV-2026-1042 attached.</p><p>Kind regards,<br>Amina</p>","cc":["finance@zuri-traders.co.ke"],"bcc":[],"templateId":"6ad0a571d5c26de56de94a6a","externalRef":"<20261015094100.4f2a@mail.acme.co.ke>","error":"","actorId":"66f1b2c3d4e5f60718293a4b","actorName":"Amina Otieno","durationSeconds":0,"occurredAt":"2026-10-15T09:41:00.000Z"}],"cursor":null}}}},"400":{"description":"pipelineId or recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it (or the record is archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comms.read"]}],"x-required-scopes":["spaces.comms.read"]}},"/code-functions":{"get":{"tags":["Pipelines"],"summary":"List code functions","description":"Lists the organisation's saved code functions, the code pipeline actions can run by ID, most recently changed first and without their code. Turned-off functions are left out unless includeInactive is true.\n\n**Permission:** `spaces.codeFunctions.read` (View code functions).","operationId":"listCodeFunctions","parameters":[{"name":"includeInactive","in":"query","required":false,"schema":{"type":"boolean"},"description":"true also lists turned-off functions","example":true},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Most functions to return, 1 to 100. Defaults to 20","example":20},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Text to look for in the name, description or tags, ignoring case","example":"sms"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"functions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Function ID; pipeline code actions point at it"},"name":{"type":"string","description":"Name, unique in the organisation"},"slug":{"type":"string","description":"The name in lower case with other characters turned into dashes; two functions cannot share one"},"description":{"type":"string","description":"What it does"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels to find it by"},"version":{"type":"integer","description":"Goes up by one each time its code changes"},"isActive":{"type":"boolean","description":"Whether pipeline actions run it; when false they skip it with a warning"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}}},"example":{"functions":[{"id":"6ad1c2e0f3a4b5c6d7e8f905","name":"sendWelcomeSms","slug":"sendwelcomesms","description":"Texts a welcome message to the record's phone field","tags":["sms","onboarding"],"version":3,"isActive":true,"updatedAt":"2026-10-12T10:20:00.000Z"},{"id":"6ad1c2e0f3a4b5c6d7e8f906","name":"Flag big deals","slug":"flag-big-deals","description":"Raises priority when the deal amount is over 1,000,000","tags":["sales"],"version":1,"isActive":false,"updatedAt":"2026-10-03T14:45:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.codeFunctions.read"]}],"x-required-scopes":["spaces.codeFunctions.read"]},"post":{"tags":["Pipelines"],"summary":"Create a code function","description":"Saves a named piece of TypeScript that pipeline code actions (on transitions, automations and custom buttons) can run by its ID. Only organisation admins may call it. The code is compiled and checked first, and nothing is saved if that fails. It starts at version 1.\n\n**Permission:** `spaces.codeFunctions.create` (Create code functions).","operationId":"createCodeFunction","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"What it does, up to 500 characters","examples":["Texts a welcome message to the record's phone field"]},"isActive":{"type":"boolean","description":"false saves it turned off, so pipeline actions skip it. Must be a JSON true or false: anything else, the text \"false\" too, leaves it on","examples":[true]},"memoryLimit":{"type":"integer","description":"Megabytes it may use. Runs get at most 128 whatever is stored. Defaults to 64","examples":[64]},"name":{"type":"string","description":"Name, up to 80 characters, with at least one letter or digit. Unique in the organisation, ignoring case and punctuation","examples":["sendWelcomeSms"]},"sourceCode":{"type":"string","description":"TypeScript to run. It can read ctx.record, ctx.pipeline, ctx.transition and ctx.user and call setField, setFieldOn, notify, sendEmail, sendChatMessage, sendSms, initiateCall, http, getRecord, queryRecords, getTask and log; top-level await works. It must compile with no warnings and not use eval, Function, process, require, setTimeout or other blocked names","examples":["const phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}"]},"tags":{"type":"array","items":{"type":"string"},"description":"Labels to find it by, each up to 40 characters; blank ones are dropped and at most 20 kept. Must be a JSON array","examples":[["sms","onboarding"]]},"timeout":{"type":"integer","description":"Milliseconds it may run. Runs stop at 30,000 whatever is stored. Defaults to 5000","examples":[5000]}},"required":["name","sourceCode"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"function":{"type":"object","properties":{"id":{"type":"string","description":"Function ID; pipeline code actions point at it"},"name":{"type":"string","description":"Name, unique in the organisation"},"slug":{"type":"string","description":"The name in lower case with other characters turned into dashes; two functions cannot share one"},"description":{"type":"string","description":"What it does"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels to find it by"},"version":{"type":"integer","description":"Goes up by one each time its code changes"},"isActive":{"type":"boolean","description":"Whether pipeline actions run it; when false they skip it with a warning"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"sourceCode":{"type":"string","description":"The TypeScript as written"},"compiledCode":{"type":"string","description":"The JavaScript it was compiled to when saved"},"timeout":{"type":"integer","description":"Milliseconds it may run; runs stop at 30,000 whatever is stored"},"memoryLimit":{"type":"integer","description":"Megabytes it may use; runs get at most 128"},"createdBy":{"type":"string","description":"ID of the person who created it"},"updatedBy":{"type":"string","description":"ID of the person who changed it last"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"}}}}},"example":{"function":{"id":"6ad1c2e0f3a4b5c6d7e8f905","name":"sendWelcomeSms","slug":"sendwelcomesms","description":"Texts a welcome message to the record's phone field","tags":["sms","onboarding"],"version":1,"isActive":true,"updatedAt":"2026-09-20T07:00:00.000Z","sourceCode":"const phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}","compiledCode":"(async () => {\nconst phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}\n\n})();","timeout":5000,"memoryLimit":64,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-09-20T07:00:00.000Z"}}}}},"400":{"description":"name is blank or has no letter or digit, sourceCode is blank, a name is over 80 characters, the description over 500 or a tag over 40, or the code does not compile, gives a compiler warning or uses a blocked name; the error lists why (code COMPILE_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A function with the same name, ignoring case and punctuation, already exists (code DUPLICATE_NAME)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.codeFunctions.create"]}],"x-required-scopes":["spaces.codeFunctions.create"]}},"/code-functions/{functionId}":{"get":{"tags":["Pipelines"],"summary":"Get a code function","description":"Gets one code function with its source and compiled code, turned off or not.\n\n**Permission:** `spaces.codeFunctions.read` (View code functions).","operationId":"getCodeFunction","parameters":[{"name":"functionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the code function","example":"6ad1c2e0f3a4b5c6d7e8f905"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"function":{"type":"object","properties":{"id":{"type":"string","description":"Function ID; pipeline code actions point at it"},"name":{"type":"string","description":"Name, unique in the organisation"},"slug":{"type":"string","description":"The name in lower case with other characters turned into dashes; two functions cannot share one"},"description":{"type":"string","description":"What it does"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels to find it by"},"version":{"type":"integer","description":"Goes up by one each time its code changes"},"isActive":{"type":"boolean","description":"Whether pipeline actions run it; when false they skip it with a warning"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"sourceCode":{"type":"string","description":"The TypeScript as written"},"compiledCode":{"type":"string","description":"The JavaScript it was compiled to when saved"},"timeout":{"type":"integer","description":"Milliseconds it may run; runs stop at 30,000 whatever is stored"},"memoryLimit":{"type":"integer","description":"Megabytes it may use; runs get at most 128"},"createdBy":{"type":"string","description":"ID of the person who created it"},"updatedBy":{"type":"string","description":"ID of the person who changed it last"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"}}},"isAdmin":{"type":"boolean","description":"Whether you are an organisation admin, so may change, test and delete it"}}},"example":{"function":{"id":"6ad1c2e0f3a4b5c6d7e8f905","name":"sendWelcomeSms","slug":"sendwelcomesms","description":"Texts a welcome message to the record's phone field","tags":["sms","onboarding"],"version":3,"isActive":true,"updatedAt":"2026-10-12T10:20:00.000Z","sourceCode":"const phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}","compiledCode":"(async () => {\nconst phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}\n\n})();","timeout":5000,"memoryLimit":64,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-09-20T07:00:00.000Z"},"isAdmin":true}}}},"400":{"description":"functionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No code function with that ID (code NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.codeFunctions.read"]}],"x-required-scopes":["spaces.codeFunctions.read"]},"put":{"tags":["Pipelines"],"summary":"Update a code function","description":"Changes a code function; only the inputs you send change. Only organisation admins may call it. sourceCode that differs from the saved code is compiled and checked first, and on success the version goes up by one.\n\n**Permission:** `spaces.codeFunctions.update` (Update code functions).","operationId":"updateCodeFunction","parameters":[{"name":"functionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the code function","example":"6ad1c2e0f3a4b5c6d7e8f905"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"What it does, up to 500 characters","examples":["Texts a welcome message to the record's phone field"]},"isActive":{"type":"boolean","description":"false turns it off, so pipeline actions skip it; true turns it back on. Must be a JSON true or false: anything else, the text \"false\" too, is ignored","examples":[false]},"memoryLimit":{"type":"integer","description":"Megabytes it may use. Runs get at most 128 whatever is stored. 0 or a value that is not a number keeps the current one","examples":[64]},"name":{"type":"string","description":"Name, up to 80 characters, with at least one letter or digit. Unique in the organisation, ignoring case and punctuation. A blank name is ignored","examples":["sendWelcomeSms"]},"sourceCode":{"type":"string","description":"TypeScript to run. It can read ctx.record, ctx.pipeline, ctx.transition and ctx.user and call setField, setFieldOn, notify, sendEmail, sendChatMessage, sendSms, initiateCall, http, getRecord, queryRecords, getTask and log; top-level await works. It must compile with no warnings and not use eval, Function, process, require, setTimeout or other blocked names","examples":["const phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}"]},"tags":{"type":"array","items":{"type":"string"},"description":"Labels to find it by, each up to 40 characters; blank ones are dropped and at most 20 kept. Must be a JSON array","examples":[["sms","onboarding"]]},"timeout":{"type":"integer","description":"Milliseconds it may run. Runs stop at 30,000 whatever is stored. 0 or a value that is not a number keeps the current one","examples":[5000]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"function":{"type":"object","properties":{"id":{"type":"string","description":"Function ID; pipeline code actions point at it"},"name":{"type":"string","description":"Name, unique in the organisation"},"slug":{"type":"string","description":"The name in lower case with other characters turned into dashes; two functions cannot share one"},"description":{"type":"string","description":"What it does"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels to find it by"},"version":{"type":"integer","description":"Goes up by one each time its code changes"},"isActive":{"type":"boolean","description":"Whether pipeline actions run it; when false they skip it with a warning"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"sourceCode":{"type":"string","description":"The TypeScript as written"},"compiledCode":{"type":"string","description":"The JavaScript it was compiled to when saved"},"timeout":{"type":"integer","description":"Milliseconds it may run; runs stop at 30,000 whatever is stored"},"memoryLimit":{"type":"integer","description":"Megabytes it may use; runs get at most 128"},"createdBy":{"type":"string","description":"ID of the person who created it"},"updatedBy":{"type":"string","description":"ID of the person who changed it last"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"}}}}},"example":{"function":{"id":"6ad1c2e0f3a4b5c6d7e8f905","name":"sendWelcomeSms","slug":"sendwelcomesms","description":"Texts a welcome message to the record's phone field","tags":["sms","onboarding"],"version":3,"isActive":true,"updatedAt":"2026-10-12T10:20:00.000Z","sourceCode":"const phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}","compiledCode":"(async () => {\nconst phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}\n\n})();","timeout":5000,"memoryLimit":64,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-09-20T07:00:00.000Z"}}}}},"400":{"description":"functionId is not a valid ID, name has no letter or digit, a name is over 80 characters, the description over 500 or a tag over 40, or the code does not compile, gives a compiler warning or uses a blocked name; the error lists why (code COMPILE_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No code function with that ID (code NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A function with the same name, ignoring case and punctuation, already exists (code DUPLICATE_NAME)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.codeFunctions.update"]}],"x-required-scopes":["spaces.codeFunctions.update"]},"delete":{"tags":["Pipelines"],"summary":"Delete a code function","description":"Deletes a code function for good. Only organisation admins may call it. Pipeline code actions that use it then skip it with a warning in their run log instead of failing.\n\n**Permission:** `spaces.codeFunctions.delete` (Delete code functions).","operationId":"deleteCodeFunction","parameters":[{"name":"functionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the code function","example":"6ad1c2e0f3a4b5c6d7e8f905"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it was deleted"}}},"example":{"success":true}}}},"400":{"description":"functionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No code function with that ID (code NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.codeFunctions.delete"]}],"x-required-scopes":["spaces.codeFunctions.delete"]}},"/spaces/{spaceId}/drive":{"get":{"tags":["Files"],"summary":"List files and folders","description":"Lists what one folder of a space's drive holds, or the top of the drive when parentId is left out, a page at a time. Needs a role in the space (any role; being able to see a public space is not enough).\n\n**Permission:** `spaces.drive.read` (View drive).","operationId":"listDriveItems","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100},"description":"Most items to return","example":100},{"name":"parentId","in":"query","required":false,"schema":{"type":"string"},"description":"ID of the folder to list; leave it out for the top of the drive","example":"6ad0a2e0d5c26de56de94a02"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"How many items to skip, for paging","example":0}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}}},"description":"What the folder holds, folders first, then by name; uploads not yet confirmed are included (status pending)"},"total":{"type":"integer","description":"How many items the folder holds, over all pages"}}},"example":{"items":[{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack.pdf","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-14T13:05:41.000Z","id":"6ad0a301d5c26de56de94a07"},{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 management accounts.xlsx","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","fileSize":91648,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a318d5c26de56de94a0b/0a8f3e27-9c1d-4b5e-8f72-6d4a3c2b1e09-Q3_management_accounts.xlsx","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a5c","firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T15:20:00.000Z","updatedAt":"2026-10-14T15:20:18.000Z","id":"6ad0a318d5c26de56de94a0b"}],"total":2}}}},"400":{"description":"spaceId or parentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No space with that ID, or you have no role in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.drive.read"]}],"x-required-scopes":["spaces.drive.read"]}},"/spaces/{spaceId}/drive/search":{"get":{"tags":["Files"],"summary":"Search files by name","description":"Finds files and folders in a space's drive whose name contains the words of the query, in any folder. It matches whole words (ignoring case and simple word endings), not parts of words. Needs a role in the space (any role; being able to see a public space is not enough).\n\n**Permission:** `spaces.drive.read` (View drive).","operationId":"searchDriveItems","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Words to look for in names; trimmed. An item matches if its name has any of them","example":"board pack"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}}},"description":"Up to 50 matching files and folders anywhere in the drive, best match first; uploads not yet confirmed are included"}}},"example":{"items":[{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack.pdf","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-14T13:05:41.000Z","id":"6ad0a301d5c26de56de94a07"}]}}}},"400":{"description":"spaceId is not a valid ID, or query is empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No space with that ID, or you have no role in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.drive.read"]}],"x-required-scopes":["spaces.drive.read"]}},"/drive/{itemId}":{"get":{"tags":["Files"],"summary":"Get a file or folder","description":"Returns one file or folder from a space's drive, with the path of folders above it. Needs a role in the space (any role; being able to see a public space is not enough).\n\n**Permission:** `spaces.drive.read` (View drive).","operationId":"getDriveItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the file or folder","example":"6ad0a301d5c26de56de94a07"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}},"description":"The file or folder"},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Folder ID"},"name":{"type":"string","description":"Folder name"}}},"description":"The folders it sits in, from the top of the drive down to its own folder; empty at the top"}}},"example":{"item":{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack.pdf","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-14T13:05:41.000Z","id":"6ad0a301d5c26de56de94a07"},"breadcrumbs":[{"id":"6ad0a2b4d5c26de56de949f8","name":"Board"},{"id":"6ad0a2e0d5c26de56de94a02","name":"2026 Q3"}]}}}},"400":{"description":"itemId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You have no role in the space whose drive holds it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No file or folder with that ID, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.drive.read"]}],"x-required-scopes":["spaces.drive.read"]},"put":{"tags":["Files"],"summary":"Rename a file or folder","description":"Changes the name a file or folder shows in the drive; the stored file is not touched. Open to the person who created or uploaded it while they are still a contributor, editor or owner of the space, and to its editors and owners; not in an archived space.\n\n**Permission:** `spaces.drive.update` (Manage drive items).","operationId":"renameDriveItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the file or folder","example":"6ad0a301d5c26de56de94a07"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name; trimmed","examples":["Q3 board pack (final).pdf"]}},"required":["name"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}},"description":"The file or folder with its new name"}}},"example":{"item":{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack (final).pdf","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-15T08:12:00.000Z","id":"6ad0a301d5c26de56de94a07"}}}}},"400":{"description":"itemId is not a valid ID, or name is empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the person who created or uploaded it, while still a contributor, editor or owner of the space, or an editor or owner, can rename it, and not in an archived space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No file or folder with that ID, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.drive.update"]}],"x-required-scopes":["spaces.drive.update"]},"delete":{"tags":["Files"],"summary":"Delete a file or folder","description":"Deletes a file, or a folder with everything inside it, from a space's drive. The stored files are removed for good and there is no call to bring the items back. Each stored file is deleted before its item: without file storage nothing is deleted, and a file storage does not delete is kept, with the folders leading to it, while the rest goes; either way the answer is 503, so try again. Open to the space's editors and owners, and to the person who created or uploaded the item while they are still a contributor, editor or owner of the space; but a folder holding files or folders other people added, at any depth, only an editor or owner may delete.\n\n**Permission:** `spaces.drive.delete` (Delete drive items).","operationId":"deleteDriveItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the file or folder","example":"6ad0a301d5c26de56de94a07"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"itemId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the person who created or uploaded it, while still a contributor, editor or owner of the space, or an editor or owner, can delete it; a folder holding files or folders other people added, at any depth, only an editor or owner can delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No file or folder with that ID, or it was already deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now, so nothing was deleted; or storage did not delete some files, which were kept with the folders holding them while the rest was deleted. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.drive.delete"]}],"x-required-scopes":["spaces.drive.delete"]}},"/drive/{itemId}/download":{"get":{"tags":["Files"],"summary":"Get a download link for a drive file","description":"Returns a one-hour download link for a file in a space's drive. Needs a role in the space (any role; being able to see a public space is not enough).\n\n**Permission:** `spaces.drive.read` (View drive).","operationId":"getDriveDownloadUrl","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the file","example":"6ad0a301d5c26de56de94a07"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Download link for the file; anyone who has it can download the file until it expires"},"fileName":{"type":"string","description":"Name of the file in the drive"},"mimeType":{"type":"string","description":"File type"},"expiresIn":{"type":"integer","description":"Seconds until the link stops working (always 3600, one hour)"}}},"example":{"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c","fileName":"Q3 board pack.pdf","mimeType":"application/pdf","expiresIn":3600}}}},"400":{"description":"itemId is not a valid ID, it is a folder, or its upload is not confirmed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You have no role in the space whose drive holds it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No file with that ID, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.drive.read"]}],"x-required-scopes":["spaces.drive.read"]}},"/strategies/{strategyId}/goals":{"get":{"tags":["Strategies"],"summary":"Get the organisation's goals for a strategy","description":"The organisation's company goals for a year, each with its department priorities, from Kazee Performance, to show beside a strategy. Read-only: goals are set in Kazee Performance. Answers enabled false and no goals while Performance goals are not switched on for the organisation; the strategy then keeps its own objectives. Work links show only task lists in spaces you can see. You must be able to see the strategy's space: be a member, or it is public.\n\n**Permission:** `spaces.strategies.read` (View strategy).","operationId":"getStrategyGoals","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"department","in":"query","required":false,"schema":{"type":"string"},"description":"Only the priorities of this department (Kazee People department ID); company goals are always listed","example":"6650a1b2c3d4e5f6a7b8c901"},{"name":"quarter","in":"query","required":false,"schema":{"type":"integer","enum":[1,2,3,4]},"description":"Only the department priorities of this quarter; leave out for the whole year","example":1},{"name":"year","in":"query","required":false,"schema":{"type":"integer"},"description":"The year; leave out for this year","example":2027}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false while Kazee Performance goals are not switched on for this organisation (or not set up for Spaces); goals is then empty and the strategy keeps its own objectives"},"year":{"type":"integer","description":"The year shown"},"quarter":{"type":"integer","description":"The quarter shown, when one was asked for"},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"level":{"type":"string","description":"company (a goal for the year)"},"type":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"},"progress":{"type":"integer"},"ownerSeatId":{"type":"string","description":"ID of the position that owns the goal"},"period":{"type":"object","properties":{"kind":{"type":"string"},"year":{"type":"integer"}},"description":"{kind: year, year} for a company goal; {kind: quarter, year, quarter} for a department priority"},"parentGoalId":{},"department":{},"keyResults":{"type":"array"},"workLinks":{"type":"array","description":"Task lists in Kazee Spaces linked to the goal; only those in spaces you can see"},"lastUpdate":{"description":"The latest weekly status (on_track or off_track) and its note; null before the first"},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"level":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"},"progress":{"type":"integer"},"ownerSeatId":{"type":"string"},"period":{"type":"object","properties":{"kind":{"type":"string"},"year":{"type":"integer"},"quarter":{"type":"integer"}}},"parentGoalId":{"type":"string"},"department":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"keyResults":{"type":"array"},"workLinks":{"type":"array","items":{"type":"object","properties":{"app":{"type":"string"},"spaceId":{"type":"string"},"itemId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"linkedBy":{"type":"string"},"linkedAt":{"type":"string","format":"date-time"}}}},"lastUpdate":{"type":"object","properties":{"weekStart":{"type":"string","format":"date-time"},"status":{"type":"string"},"note":{"type":"string"}}}}},"description":"The department priorities under the company goal, in the same shape"}}}}}},"example":{"enabled":true,"year":2027,"quarter":1,"goals":[{"id":"6660a1b2c3d4e5f6a7b8c910","title":"Customers rate us the best in the market","description":"Every channel answers within the hour.","level":"company","type":"organization","status":"active","priority":"high","progress":25,"ownerSeatId":"6670f0e1d2c3b4a596877801","period":{"kind":"year","year":2027},"parentGoalId":null,"department":null,"keyResults":[],"workLinks":[],"lastUpdate":null,"children":[{"id":"6660a1b2c3d4e5f6a7b8c911","title":"Clear the support backlog","description":"Nothing older than two days by the end of the quarter.","level":"department","type":"department","status":"active","priority":"high","progress":40,"ownerSeatId":"6670f0e1d2c3b4a596877802","period":{"kind":"quarter","year":2027,"quarter":1},"parentGoalId":"6660a1b2c3d4e5f6a7b8c910","department":{"id":"6650a1b2c3d4e5f6a7b8c901","name":"Customer Support"},"keyResults":[],"workLinks":[{"app":"spaces","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemId":"6a9f3c5eb7e4a20f1c5d8e47","name":"Support backlog","url":"https://spaces.kazee.africa/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?name=Support%20backlog","linkedBy":"Daniel Mwangi","linkedAt":"2027-01-05T09:00:00.000Z"}],"lastUpdate":{"weekStart":"2027-01-04T00:00:00.000Z","status":"off_track","note":"The vendor is a week late; we start on Monday."}}]}]}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the strategy's space: you are not a member and it is not public","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Kazee Performance refused the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Kazee Performance could not be asked just now; try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.strategies.read"]}],"x-required-scopes":["spaces.strategies.read"]}},"/space-items/{itemId}/goal":{"get":{"tags":["Spaces"],"summary":"Get the goal a task list serves","description":"The company goal or department priority in Kazee Performance a task list is linked to, with its current name (names are checked with Performance at most every 5 minutes). Answers enabled false while Performance goals are not switched on for the organisation. Open to the space's members, and to anyone when the space is public.\n\n**Permission:** `spaces.spaceItems.read` (View space items).","operationId":"getSpaceItemGoal","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task list's sidebar item","example":"6a9f3c5eb7e4a20f1c5d8e47"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false while Kazee Performance goals are not switched on for this organisation (or not set up for Spaces)"},"goal":{"type":"object","properties":{"app":{"type":"string","description":"Always performance"},"id":{"type":"string","description":"ID of the company goal or department priority in Kazee Performance"},"name":{"type":"string","description":"Its name, kept current from Kazee Performance"},"year":{"type":"integer","description":"The year of the goal"}},"description":"The company goal or department priority in Kazee Performance the task list is linked to; null when none"},"current":{"type":"boolean","description":"true when Kazee Performance confirmed the goal (in the last 5 minutes), so its name is current; false when Performance could not be asked or no longer has the goal"}}},"example":{"enabled":true,"goal":{"app":"performance","id":"6660a1b2c3d4e5f6a7b8c911","name":"Clear the support backlog","year":2027},"current":true}}}},"400":{"description":"itemId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No sidebar item with that ID in your organisation, or it is archived, or it is in a private space you are not a member of","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.read"]}],"x-required-scopes":["spaces.spaceItems.read"]},"post":{"tags":["Spaces"],"summary":"Link a task list to a goal","description":"Links a task list to a company goal or department priority in Kazee Performance: the goal shows the task list among its work, and the task list carries the goal in metadata.goal. Only metadata.goal is set; the item's other metadata stays. Linking to another goal moves the link. Needs the editor role or higher in the item's space, which must not be archived. Answers enabled false, and changes nothing, while Performance goals are not switched on for the organisation.\n\n**Permission:** `spaces.spaceItems.update` (Update space items).","operationId":"linkSpaceItemGoal","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task list's sidebar item","example":"6a9f3c5eb7e4a20f1c5d8e47"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goalId":{"type":"string","description":"ID of the company goal or department priority in Kazee Performance","examples":["6660a1b2c3d4e5f6a7b8c911"]},"year":{"type":"integer","description":"The goal's year; leave out for this year","examples":[2027]}},"required":["goalId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false while Kazee Performance goals are not switched on for this organisation (or not set up for Spaces)"},"goal":{"type":"object","properties":{"app":{"type":"string","description":"Always performance"},"id":{"type":"string","description":"ID of the company goal or department priority in Kazee Performance"},"name":{"type":"string","description":"Its name, kept current from Kazee Performance"},"year":{"type":"integer","description":"The year of the goal"}},"description":"The goal the task list is now linked to, as stored in the item's metadata.goal; null when Performance goals are off"}}},"example":{"enabled":true,"goal":{"app":"performance","id":"6660a1b2c3d4e5f6a7b8c911","name":"Clear the support backlog","year":2027}}}}},"400":{"description":"itemId or goalId is not a valid ID, the item is not a task list, or the goal is an ordinary goal (only company goals and department priorities take links)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the item's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sidebar item with that ID in your organisation, or it is archived, or Kazee Performance has no company goal or department priority with that ID in that year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The item's metadata is not an object, so a goal cannot be added to it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Kazee Performance refused the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Kazee Performance could not be asked just now; try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.spaceItems.update"]}],"x-required-scopes":["spaces.spaceItems.update"]},"delete":{"tags":["Spaces"],"summary":"Unlink a task list from its goal","description":"Removes a task list's link to its goal in Kazee Performance, on both sides: the goal no longer lists the task list, and metadata.goal is taken out of the item (its other metadata stays). A task list with no goal is left as it is. Needs the editor role or higher in the item's space, which must not be archived. Answers enabled false, and changes nothing, while Performance goals are not set up.\n\n**Permission:** `spaces.spaceItems.update` (Update space items).","operationId":"unlinkSpaceItemGoal","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task list's sidebar item","example":"6a9f3c5eb7e4a20f1c5d8e47"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false while Kazee Performance goals are not switched on for this organisation (or not set up for Spaces)"},"goal":{"description":"Always null: the task list serves no goal now"}}},"example":{"enabled":true,"goal":null}}}},"400":{"description":"itemId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the item's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sidebar item with that ID in your organisation, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Kazee Performance refused the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Kazee Performance could not be asked just now; try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.spaceItems.update"]}],"x-required-scopes":["spaces.spaceItems.update"]}},"/views/{viewId}":{"put":{"tags":["Saved views"],"summary":"Update a saved view","description":"Changes one of your own saved views; inputs you leave out stay as they are, and filters, sort and display replace what was there. It cannot move a view to another screen or make it the default.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"updateSavedView","parameters":[{"name":"viewId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of one of your saved views","example":"6ad0a0f4d5c26de56de949f8"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"display":{"type":"object","properties":{"viewMode":{"type":"string"},"groupBy":{"type":"string"},"compactView":{"type":"boolean"}},"description":"How the screen shows the view: viewMode, groupBy and compactView, as the apps use them. A JSON object in a string also works","examples":[{"viewMode":"board","groupBy":"status","compactView":false}]},"filters":{"type":"object","description":"Filter conditions by field, stored as given: field -> { operator, value } or { operator, values }, or { from, to } for a range. A date range may hold a preset such as last_7_days instead, which the apps work out when they apply the view. A JSON object in a string also works","examples":[{"priority":{"operator":"is","values":["critical","high"]},"dueDate":{"preset":"last_7_days"}}]},"name":{"type":"string","maxLength":80,"description":"New name, up to 80 characters; it cannot be empty, and spaces at either end are trimmed","examples":["Overdue criticals and highs"]},"order":{"type":"integer","description":"Its position among your views on that screen; lower comes first. Anything that is not a number counts as 0","examples":[0]},"search":{"type":"string","description":"Search text to keep with the view","examples":["invoice"]},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"description":"Sort field and direction (asc or desc; asc when left out). A JSON object in a string also works","examples":[{"field":"dueDate","direction":"asc"}]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"object","properties":{"_id":{"type":"string","description":"View ID"},"organizationId":{"type":"string","description":"ID of the organisation"},"userId":{"type":"string","description":"User ID of the owner; views are personal"},"context":{"type":"string","description":"The screen it belongs to: my-tasks, space-tasks or pipeline"},"contextId":{"type":"string","description":"ID of the space (space-tasks) or pipeline (pipeline); null for my-tasks"},"name":{"type":"string","description":"Name of the view"},"filters":{"type":"object","properties":{"priority":{"type":"object","properties":{"operator":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"dueDate":{"type":"object","properties":{"preset":{"type":"string"}}}},"description":"Filter conditions by field, as they were saved; absent when there are none"},"search":{"type":"string","description":"Search text; empty when none"},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string"}},"description":"Sort field and direction (asc or desc); absent when not set"},"display":{"type":"object","properties":{"viewMode":{"type":"string"},"groupBy":{"type":"string"},"compactView":{"type":"boolean"}},"description":"How the screen shows it (viewMode, groupBy, compactView); absent when not set"},"isDefault":{"type":"boolean","description":"Whether it opens by default on that screen"},"order":{"type":"integer","description":"Position among your views on that screen; lower comes first"},"visibility":{"type":"string","description":"Always private for now: only you see it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"View ID (same as _id)"}}}}},"example":{"view":{"_id":"6ad0a0f4d5c26de56de949f8","organizationId":"66a4b275003d1b495212b5aa","userId":"66f1b2c3d4e5f60718293a4b","context":"space-tasks","contextId":"6a9f3c21b7e4a20f1c5d8e41","name":"Overdue criticals and highs","filters":{"priority":{"operator":"is","values":["critical","high"]},"dueDate":{"preset":"last_7_days"}},"search":"","sort":{"field":"dueDate","direction":"asc"},"display":{"viewMode":"board","groupBy":"status","compactView":false},"isDefault":false,"order":2,"visibility":"private","createdAt":"2026-10-10T07:20:00.000Z","updatedAt":"2026-10-15T10:20:00.000Z","id":"6ad0a0f4d5c26de56de949f8"}}}}},"400":{"description":"viewId is not a valid ID, name is empty or longer than 80 characters, or sort.direction is not asc or desc","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"None of your saved views has that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]},"delete":{"tags":["Saved views"],"summary":"Delete a saved view","description":"Deletes one of your own saved views for good.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"deleteSavedView","parameters":[{"name":"viewId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of one of your saved views","example":"6ad0a0f4d5c26de56de949f8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"viewId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"None of your saved views has that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]}},"/integrations/yeastar/mappings/{userId}":{"put":{"tags":["Settings"],"summary":"Link a person to a phone extension","description":"Links a person to a phone extension so they can place calls from it, replacing any extension they had; the extension also shows on their profile. Needs an organisation admin. The other details are a copy of what the phone system shows for the extension and are not checked with it.\n\n**Permission:** `spaces.integrations.update` (Configure integrations).","operationId":"updatePhoneExtensionMapping","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the person","example":"66f1b2c3d4e5f60718293a5c"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callerIdName":{"type":"string","description":"Name shown for the extension, from listPhoneExtensions","examples":["Jane Wanjiku"]},"emailAddr":{"type":"string","description":"Email address of the extension, from listPhoneExtensions","examples":["jane@example.com"]},"extensionId":{"type":"integer","description":"The phone system's own ID for the extension (P-Series only), kept as sent","examples":[238]},"extensionNumber":{"type":"string","description":"Extension number to link, as listPhoneExtensions shows it","examples":["2001"]},"mobileNumber":{"type":"string","description":"Mobile number of the extension, from listPhoneExtensions","examples":["+254712345678"]},"roleName":{"type":"string","description":"Role or type of the extension, from listPhoneExtensions","examples":["SIP"]}},"required":["extensionNumber"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"mapping":{"type":"object","properties":{"id":{"type":"string","description":"ID of the link"},"userId":{"type":"string","description":"ID of the person"},"extensionNumber":{"type":"string","description":"Extension the person calls from"},"extensionId":{"type":"integer","description":"The phone system's own ID for the extension (P-Series only); null when unknown"},"callerIdName":{"type":"string","description":"Name shown for the extension, as sent; empty if none"},"emailAddr":{"type":"string","description":"Email address of the extension, as sent; empty if none"},"mobileNumber":{"type":"string","description":"Mobile number of the extension, as sent; empty if none"},"roleName":{"type":"string","description":"Role or type of the extension, as sent; empty if none"},"mappedAt":{"type":"string","format":"date-time","description":"When the link was made"}},"description":"The link as saved"}}},"example":{"mapping":{"id":"6ad1b0c2e4f5a60718293b04","userId":"66f1b2c3d4e5f60718293a5c","extensionNumber":"2001","extensionId":238,"callerIdName":"Jane Wanjiku","emailAddr":"jane@example.com","mobileNumber":"+254712345678","roleName":"SIP","mappedAt":"2026-10-15T09:30:00.000Z"}}}}},"400":{"description":"userId is not a valid ID, or extensionNumber is only spaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No person with that ID in your organisation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The extension is already linked to someone else (code EXTENSION_TAKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.update"]}],"x-required-scopes":["spaces.integrations.update"]},"delete":{"tags":["Settings"],"summary":"Unlink a person from their extension","description":"Removes the link between a person and their phone extension and clears the extension on their profile, so they can no longer place calls. Needs an organisation admin. Succeeds even when the person had no link.\n\n**Permission:** `spaces.integrations.delete` (Delete integrations).","operationId":"deletePhoneExtensionMapping","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the person","example":"66f1b2c3d4e5f60718293a5c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"userId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.delete"]}],"x-required-scopes":["spaces.integrations.delete"]}},"/integrations/email/accounts":{"put":{"tags":["Settings"],"summary":"Add or update an email account","description":"Adds a send-as email account to the organisation, or updates the one whose id you pass. Needs an organisation admin. The password is stored encrypted and never returned; on an update, leave it out to keep the saved one. The account's last test result is kept as it was, so test it again after a change.\n\n**Permission:** `spaces.integrations.update` (Configure integrations).","operationId":"updateEmailAccount","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fromAddress":{"type":"string","description":"Address the emails come from, up to 320 characters; saved in lower case","examples":["sales@example.com"]},"fromName":{"type":"string","description":"Sender name shown with the address; anything over 120 characters is cut off","examples":["Example Ltd Sales"]},"host":{"type":"string","description":"Mail server (SMTP) host, up to 320 characters","examples":["smtp.example.com"]},"id":{"type":"string","description":"ID of the account to update, up to 64 characters. Leave out to add a new account with a new ID; an ID that matches no account adds a new account with that ID","examples":["3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90"]},"isEnabled":{"type":"boolean","description":"false (or the string \"false\") turns the account off without deleting it, so it cannot send. Defaults to true","examples":[true]},"label":{"type":"string","description":"Name shown when picking the account, up to 80 characters","examples":["Sales"]},"password":{"type":"string","description":"Password for the mail server. Needed for a new account; on an update, leave out or send it empty to keep the saved one","examples":["not-a-real-password"]},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Mail server port, 1 to 65535: usually 587, or 465 with secure on","examples":[587]},"replyTo":{"type":"string","description":"Address replies go to, saved in lower case; anything over 320 characters is cut off. Empty means replies go to fromAddress","examples":["support@example.com"]},"secure":{"type":"boolean","description":"true (or the string \"true\") to use TLS from the start (usually port 465); false to upgrade the connection with STARTTLS (usually port 587). Defaults to false","examples":[false]},"username":{"type":"string","description":"User name for logging in to the mail server, up to 320 characters; often the full address","examples":["sales@example.com"]}},"required":["fromAddress","host","label","port","username"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"type":"string","description":"Account ID; pass it as accountId to send from, test or delete the account"},"label":{"type":"string","description":"Name shown when picking the account"},"fromAddress":{"type":"string","description":"Address the emails come from"},"fromName":{"type":"string","description":"Sender name shown with the address; empty if none"},"replyTo":{"type":"string","description":"Address replies go to; empty means replies go to fromAddress"},"host":{"type":"string","description":"Mail server (SMTP) host"},"port":{"type":"integer","description":"Mail server port"},"secure":{"type":"boolean","description":"true: TLS from the start (usually port 465); false: STARTTLS (usually port 587)"},"username":{"type":"string","description":"User name for logging in to the mail server"},"isEnabled":{"type":"boolean","description":"Whether the account may send; a turned-off account cannot"},"configured":{"type":"boolean","description":"Whether a password is saved"},"passwordHint":{"type":"string","description":"Always empty: no part of the password is ever shown (configured says whether one is saved)"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the account was last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"createdAt":{"type":"string","format":"date-time","description":"When the account was added"},"updatedAt":{"type":"string","format":"date-time","description":"When the account last changed"}},"description":"The account as saved"},"config":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Account ID; pass it as accountId to send from, test or delete the account"},"label":{"type":"string","description":"Name shown when picking the account"},"fromAddress":{"type":"string","description":"Address the emails come from"},"fromName":{"type":"string","description":"Sender name shown with the address; empty if none"},"replyTo":{"type":"string","description":"Address replies go to; empty means replies go to fromAddress"},"host":{"type":"string","description":"Mail server (SMTP) host"},"port":{"type":"integer","description":"Mail server port"},"secure":{"type":"boolean","description":"true: TLS from the start (usually port 465); false: STARTTLS (usually port 587)"},"username":{"type":"string","description":"User name for logging in to the mail server"},"isEnabled":{"type":"boolean","description":"Whether the account may send; a turned-off account cannot"},"configured":{"type":"boolean","description":"Whether a password is saved"},"passwordHint":{"type":"string","description":"Always empty: no part of the password is ever shown (configured says whether one is saved)"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the account was last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"createdAt":{"type":"string","format":"date-time","description":"When the account was added"},"updatedAt":{"type":"string","format":"date-time","description":"When the account last changed"}}},"description":"The organisation's send-as email accounts; empty when none are set up"},"configuredBy":{"type":"string","description":"ID of the admin who last saved an account; absent when nothing was ever saved"},"configuredAt":{"type":"string","format":"date-time","description":"When an account was last saved; absent when nothing was ever saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed; absent when nothing was ever saved"}},"description":"The organisation's email settings after the save"}}},"example":{"account":{"id":"3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90","label":"Sales","fromAddress":"sales@example.com","fromName":"Example Ltd Sales","replyTo":"support@example.com","host":"smtp.example.com","port":587,"secure":false,"username":"sales@example.com","isEnabled":true,"configured":true,"passwordHint":"","lastTestedAt":"2026-10-14T09:12:00.000Z","lastTestStatus":"ok","lastTestError":"","createdAt":"2026-10-01T08:00:00.000Z","updatedAt":"2026-10-14T09:10:00.000Z"},"config":{"accounts":[{"id":"3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90","label":"Sales","fromAddress":"sales@example.com","fromName":"Example Ltd Sales","replyTo":"support@example.com","host":"smtp.example.com","port":587,"secure":false,"username":"sales@example.com","isEnabled":true,"configured":true,"passwordHint":"","lastTestedAt":"2026-10-14T09:12:00.000Z","lastTestStatus":"ok","lastTestError":"","createdAt":"2026-10-01T08:00:00.000Z","updatedAt":"2026-10-14T09:10:00.000Z"}],"configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T09:10:00.000Z","updatedAt":"2026-10-14T09:12:00.000Z"}}}}},"400":{"description":"label, fromAddress, host or username is not text, is only spaces or is too long (80 characters for label, 320 for the others), or port is not a whole number from 1 to 65535 (code INVALID); or there is no password for a new account (code PASSWORD_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The server has no encryption key set up, so it cannot store the password (code CRYPTO_UNREADY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.update"]}],"x-required-scopes":["spaces.integrations.update"]}},"/pipelines/{pipelineId}/email-templates/{templateId}":{"put":{"tags":["Pipelines"],"summary":"Update a pipeline email template","description":"Changes an email template; only the inputs you send change. Only organisation admins may call it, and not while the pipeline's space is archived.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineEmailTemplate","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"templateId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the template","example":"6ad1c2e0f3a4b5c6d7e8f903"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"allowedAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts it may be sent from; empty means any the pipeline allows. Must be a JSON array; anything else is ignored","examples":[["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"]]},"bodyHtml":{"type":"string","description":"HTML body; macros work here too","examples":["<p>Hello {{field.contactName | default: \"there\"}},</p><p>Following up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.</p><p>{{actor.firstName}}</p>"]},"bodyText":{"type":"string","description":"Plain-text body; macros work here too. When empty, a text version of bodyHtml is used at send time","examples":["Hello {{field.contactName | default: \"there\"}},\n\nFollowing up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.\n\n{{actor.firstName}}"]},"description":{"type":"string","description":"What the template is for; spaces at the ends are trimmed","examples":["Sent two days after a quote goes out"]},"isEnabled":{"type":"boolean","description":"false stops it being offered when writing an email; true offers it again. The text \"true\" or \"false\" also works","examples":[false]},"name":{"type":"string","description":"New name, unique within the pipeline; spaces at the ends are trimmed","examples":["Quote reminder"]},"subject":{"type":"string","description":"Subject line. Macros: {{record.<key>}} for the record (e.g. {{record.title}}), {{field.<field>}} for a custom field, {{actor.firstName}} for the sender, {{today}}; {{x | default: \"text\"}} gives a fallback","examples":["Your quote for {{record.title}}"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string","description":"Template ID"},"pipelineId":{"type":"string","description":"ID of the pipeline it belongs to"},"name":{"type":"string","description":"Name, unique within the pipeline"},"description":{"type":"string","description":"What it is for"},"subject":{"type":"string","description":"Subject line; may hold macros"},"bodyHtml":{"type":"string","description":"HTML body; may hold macros"},"bodyText":{"type":"string","description":"Plain-text body; may hold macros. When empty, a text version of bodyHtml is used at send time"},"allowedAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts it may be sent from; empty means any the pipeline allows"},"isEnabled":{"type":"boolean","description":"Whether it is offered when writing an email on a record"},"createdBy":{"type":"string","description":"ID of the person who created it"},"updatedBy":{"type":"string","description":"ID of the person who changed it last"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"template":{"id":"6ad1c2e0f3a4b5c6d7e8f903","pipelineId":"6ad1c2e0f3a4b5c6d7e8f901","name":"Quote reminder","description":"Sent two days after a quote goes out","subject":"Your quote for {{record.title}}","bodyHtml":"<p>Hello {{field.contactName | default: \"there\"}},</p><p>Following up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.</p><p>{{actor.firstName}}</p>","bodyText":"Hello {{field.contactName | default: \"there\"}},\n\nFollowing up on the quote we sent on {{field.quoteSentOn}}. Reply to this email with any questions.\n\n{{actor.firstName}}","allowedAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"isEnabled":true,"createdBy":"66f1b2c3d4e5f60718293a4b","updatedBy":"66f1b2c3d4e5f60718293a4b","createdAt":"2026-10-01T08:15:00.000Z","updatedAt":"2026-10-15T09:10:00.000Z"}}}}},"400":{"description":"pipelineId or templateId is not a valid ID, or name is blank (code INVALID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin, or the pipeline's space is archived (code FORBIDDEN), or you are an assistant acting for an admin (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with that ID in this pipeline (code NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has a template with that name (code DUPLICATE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]},"delete":{"tags":["Pipelines"],"summary":"Delete a pipeline email template","description":"Deletes an email template for good. Only organisation admins may call it. An unknown template answers ok as well.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"deletePipelineEmailTemplate","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"templateId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the template","example":"6ad1c2e0f3a4b5c6d7e8f903"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true, whether or not a template was deleted"}}},"example":{"ok":true}}}},"400":{"description":"pipelineId or templateId is not a valid ID (code INVALID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/custom-buttons/{buttonId}":{"put":{"tags":["Pipelines"],"summary":"Update a pipeline's custom button","description":"Changes a custom button on a pipeline. Only the inputs you send change; actions, conditions, visibleInStages and confirmation are replaced whole. Needs the editor role or higher in the pipeline's space, which must not be archived. The reply is the whole updated pipeline.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineCustomButton","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"buttonId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the button","example":"send-quote"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"},"description":"Actions to run, each { id, actionType, isActive, config, orderNum } as on transitions. actionType is email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms, and config holds that action's settings. A JSON array in a string also works","examples":[[{"id":"action-stamp-quote-date","actionType":"update_field","isActive":true,"config":{"fieldId":"quoteSentOn","useCurrentDate":true},"orderNum":0},{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}]]},"color":{"type":"string","description":"Button colour as hex","examples":["#3b82f6"]},"commentPrompt":{"type":"string","description":"What the app asks for when a comment is needed","examples":["Say what the client agreed to"]},"conditions":{"type":"array","items":{"type":"object"},"description":"Conditions the record must meet for the button to run, each { id, fieldPath, fieldLabel, operator, value, logicOperator } as on transitions; they are checked against the record as it is before fieldValues are saved. A JSON array in a string also works","examples":[[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}]]},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether the app asks before running it, and what it asks: { enabled, prompt }. The server does not ask. A JSON object in a string also works","examples":[{"enabled":true,"prompt":"Send the quote to the client now?"}]},"description":{"type":"string","description":"What the button does","examples":["Stamps the quote date and tells the assignees"]},"icon":{"type":"string","description":"Name of the icon to show on the button","examples":["send"]},"isActive":{"type":"boolean","description":"false turns it off, so it can no longer be run. The text \"true\" or \"false\" also works","examples":[false]},"label":{"type":"string","description":"Text on the button","examples":["Send quote"]},"orderNum":{"type":"integer","description":"Position among the pipeline's buttons; lower comes first. A value that is not a number counts as 0","examples":[1]},"requireComment":{"type":"boolean","description":"Whether running it needs notes. The text \"true\" or \"false\" also works","examples":[true]},"requiredRole":{"type":"string","description":"admin: only organisation admins may run it. Any other value, or empty: anyone with the contributor role or higher in the space","examples":["admin"]},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"IDs of the stages where the button shows and may run; empty means every stage. A JSON array in a string also works","examples":[["quoted"]]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Name of the pipeline"},"description":{"type":"string","description":"What it is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"},"positionX":{"type":"integer"},"positionY":{"type":"integer"}}},"description":"Its stages (board columns): id, name, color, orderNum, isDefault, and positionX / positionY on the workflow map"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"fromStageId":{"type":"string"},"toStageId":{"type":"string"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}}},"orderNum":{"type":"integer"}}}},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fieldPath":{"type":"string"},"fieldLabel":{"type":"string"},"operator":{"type":"string"},"value":{"type":"integer"},"logicOperator":{"type":"string"}}}},"requiredFieldIds":{"type":"array","items":{"type":"string"}},"requireComment":{"type":"boolean"},"commentPrompt":{"type":"string"},"isGlobal":{"type":"boolean"},"fromStageIds":{"type":"array"},"isActive":{"type":"boolean"}}},"description":"Allowed moves between stages, each with the actions it runs and the conditions and fields it needs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID, as given when it was added"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon shown on the button"},"color":{"type":"string","description":"Button colour, as hex"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"IDs of the stages where the button shows and may run; empty means every stage"},"requiredRole":{"type":"string","description":"admin: only organisation admins may run it; empty: anyone who may run buttons"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the app asks for confirmation first"},"prompt":{"type":"string","description":"The question it asks"}},"description":"Whether the app asks before running it, and what it asks"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"fieldId":{"type":"string"},"useCurrentDate":{"type":"boolean"}},"description":"Settings for that kind of action, the same as on transitions"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What the button runs, in orderNum order; inactive actions are skipped"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"Record field it looks at: a custom field ID, or title, priority or stageName"},"fieldLabel":{"type":"string","description":"Name of that field as people see it"},"operator":{"type":"string","description":"How the field is compared, e.g. eq, gt, contains, isEmpty"},"value":{"type":"integer","description":"Value it is compared with"},"logicOperator":{"type":"string","description":"AND or OR: how it joins the condition before it"}}},"description":"Conditions saved with the button; running it through the API does not check them"},"requireComment":{"type":"boolean","description":"Whether running it needs a comment (notes)"},"commentPrompt":{"type":"string","description":"What the app asks for when a comment is needed"},"isActive":{"type":"boolean","description":"Whether the button can be run"},"orderNum":{"type":"integer","description":"Position among the pipeline's buttons; lower comes first"}}},"description":"Buttons that run a list of actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isActive":{"type":"boolean"},"trigger":{"type":"object","properties":{"event":{"type":"string"},"config":{"type":"object","properties":{"stageId":{"type":"string"}}}}},"conditions":{"type":"array"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}}},"orderNum":{"type":"integer"}}}},"orderNum":{"type":"integer"}}},"description":"Rules that run actions when something happens to a record (trigger.event, e.g. stage_entered)"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"sectionId":{"type":"string"},"colSpan":{"type":"integer"},"fieldType":{"type":"string"},"options":{"type":"array"},"isRequired":{"type":"boolean"},"placeholder":{"type":"string"},"description":{"type":"string"},"orderNum":{"type":"integer"},"showOnCard":{"type":"boolean"},"currencyCode":{"type":"string"},"validation":{"type":"object","properties":{"min":{"type":"integer"}}},"dependsOn":{"type":"object","properties":{"values":{"type":"array"},"requiredWhenVisible":{"type":"boolean"}}}}},"description":"Custom fields its records have"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orderNum":{"type":"integer"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean"},"showBadges":{"type":"boolean"},"columnMinWidth":{"type":"integer"},"columnMaxWidth":{"type":"integer"},"cardSubtitleField":{"type":"string"},"cardBadgeField":{"type":"string"},"defaultStageId":{"type":"string"},"requireTransitions":{"type":"boolean"},"enableSLA":{"type":"boolean"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}}},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}}},"conditionFields":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"}}}}},"description":"Board settings: card fields, default stage, whether moves must follow transitions, stage time limits (stageSLAs), column totals (stageRollups) and the fields conditions can use"},"roundRobinState":{"type":"object","properties":{"action-assign-owner":{"type":"integer"}},"description":"For round-robin assign actions: action ID to the position of the person assigned last"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts its records may send from; empty means any the organisation has"},"emailEnabled":{"type":"boolean","description":"Whether sending email is offered on its records"},"smsEnabled":{"type":"boolean","description":"Whether sending SMS is offered on its records"},"callEnabled":{"type":"boolean","description":"Whether calling is offered on its records"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}}}}},"example":{"pipeline":{"name":"Sales","description":"Deals from first contact to signed contract","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"lead","name":"Lead","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"quoted","name":"Quoted","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"won","name":"Won","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"lead-to-quoted","name":"Send quote","description":"The client has asked for a price","color":"#3b82f6","icon":"file-text","fromStageId":"lead","toStageId":"quoted","actions":[{"id":"action-assign-owner","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["dealAmount"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"send-quote","label":"Send quote","description":"Stamps the quote date and tells the assignees","icon":"send","color":"#3b82f6","visibleInStages":["quoted"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Send the quote to the client now?"},"actions":[{"id":"action-stamp-quote-date","actionType":"update_field","isActive":true,"config":{"fieldId":"quoteSentOn","useCurrentDate":true},"orderNum":0},{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"remind-stale-quote","name":"Remind on new quotes","description":"Tells the assignees when a deal reaches Quoted","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"quoted"}},"conditions":[],"actions":[{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"orderNum":0}],"fieldDefinitions":[{"id":"dealAmount","name":"dealAmount","label":"Deal amount","sectionId":"deal","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"placeholder":"0","description":"Contract value before tax","orderNum":0,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"quoteSentOn","name":"quoteSentOn","label":"Quote sent on","sectionId":"deal","colSpan":3,"fieldType":"date","options":[],"isRequired":false,"orderNum":1,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"contactName","name":"contactName","label":"Contact name","sectionId":"deal","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"deal","name":"Deal","orderNum":0}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"dealAmount","cardBadgeField":"quoteSentOn","defaultStageId":"lead","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"quoted","maxHours":72,"warningHours":48}],"stageRollups":[{"fieldId":"dealAmount","function":"sum","title":"Total value"}],"conditionFields":[{"_id":"6ad1c2e0f3a4b5c6d7e8f909","path":"dealAmount","label":"Deal amount","type":"number","options":[]}]},"roundRobinState":{"action-assign-owner":1},"enabledEmailAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"emailEnabled":true,"smsEnabled":true,"callEnabled":false,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-02T07:30:00.000Z","updatedAt":"2026-10-15T09:40:00.000Z","id":"6ad1c2e0f3a4b5c6d7e8f901"}}}}},"400":{"description":"pipelineId is not a valid ID, a JSON text input is not valid JSON, or the button does not pass the checks (e.g. an unknown condition operator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the pipeline's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no button with that ID on it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]},"delete":{"tags":["Pipelines"],"summary":"Remove a custom button from a pipeline","description":"Removes a custom button from a pipeline for good. Needs the editor role or higher in the pipeline's space, which must not be archived. An unknown buttonId changes nothing and still succeeds. The reply is the whole updated pipeline.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"removePipelineCustomButton","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"buttonId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the button","example":"send-quote"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Name of the pipeline"},"description":{"type":"string","description":"What it is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"},"positionX":{"type":"integer"},"positionY":{"type":"integer"}}},"description":"Its stages (board columns): id, name, color, orderNum, isDefault, and positionX / positionY on the workflow map"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"fromStageId":{"type":"string"},"toStageId":{"type":"string"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}}},"orderNum":{"type":"integer"}}}},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fieldPath":{"type":"string"},"fieldLabel":{"type":"string"},"operator":{"type":"string"},"value":{"type":"integer"},"logicOperator":{"type":"string"}}}},"requiredFieldIds":{"type":"array","items":{"type":"string"}},"requireComment":{"type":"boolean"},"commentPrompt":{"type":"string"},"isGlobal":{"type":"boolean"},"fromStageIds":{"type":"array"},"isActive":{"type":"boolean"}}},"description":"Allowed moves between stages, each with the actions it runs and the conditions and fields it needs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID, as given when it was added"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon shown on the button"},"color":{"type":"string","description":"Button colour, as hex"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"IDs of the stages where the button shows and may run; empty means every stage"},"requiredRole":{"type":"string","description":"admin: only organisation admins may run it; empty: anyone who may run buttons"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the app asks for confirmation first"},"prompt":{"type":"string","description":"The question it asks"}},"description":"Whether the app asks before running it, and what it asks"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"fieldId":{"type":"string"},"useCurrentDate":{"type":"boolean"}},"description":"Settings for that kind of action, the same as on transitions"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What the button runs, in orderNum order; inactive actions are skipped"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"Record field it looks at: a custom field ID, or title, priority or stageName"},"fieldLabel":{"type":"string","description":"Name of that field as people see it"},"operator":{"type":"string","description":"How the field is compared, e.g. eq, gt, contains, isEmpty"},"value":{"type":"integer","description":"Value it is compared with"},"logicOperator":{"type":"string","description":"AND or OR: how it joins the condition before it"}}},"description":"Conditions saved with the button; running it through the API does not check them"},"requireComment":{"type":"boolean","description":"Whether running it needs a comment (notes)"},"commentPrompt":{"type":"string","description":"What the app asks for when a comment is needed"},"isActive":{"type":"boolean","description":"Whether the button can be run"},"orderNum":{"type":"integer","description":"Position among the pipeline's buttons; lower comes first"}}},"description":"Buttons that run a list of actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isActive":{"type":"boolean"},"trigger":{"type":"object","properties":{"event":{"type":"string"},"config":{"type":"object","properties":{"stageId":{"type":"string"}}}}},"conditions":{"type":"array"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}}},"orderNum":{"type":"integer"}}}},"orderNum":{"type":"integer"}}},"description":"Rules that run actions when something happens to a record (trigger.event, e.g. stage_entered)"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"sectionId":{"type":"string"},"colSpan":{"type":"integer"},"fieldType":{"type":"string"},"options":{"type":"array"},"isRequired":{"type":"boolean"},"placeholder":{"type":"string"},"description":{"type":"string"},"orderNum":{"type":"integer"},"showOnCard":{"type":"boolean"},"currencyCode":{"type":"string"},"validation":{"type":"object","properties":{"min":{"type":"integer"}}},"dependsOn":{"type":"object","properties":{"values":{"type":"array"},"requiredWhenVisible":{"type":"boolean"}}}}},"description":"Custom fields its records have"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orderNum":{"type":"integer"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean"},"showBadges":{"type":"boolean"},"columnMinWidth":{"type":"integer"},"columnMaxWidth":{"type":"integer"},"cardSubtitleField":{"type":"string"},"cardBadgeField":{"type":"string"},"defaultStageId":{"type":"string"},"requireTransitions":{"type":"boolean"},"enableSLA":{"type":"boolean"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}}},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}}},"conditionFields":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"}}}}},"description":"Board settings: card fields, default stage, whether moves must follow transitions, stage time limits (stageSLAs), column totals (stageRollups) and the fields conditions can use"},"roundRobinState":{"type":"object","properties":{"action-assign-owner":{"type":"integer"}},"description":"For round-robin assign actions: action ID to the position of the person assigned last"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts its records may send from; empty means any the organisation has"},"emailEnabled":{"type":"boolean","description":"Whether sending email is offered on its records"},"smsEnabled":{"type":"boolean","description":"Whether sending SMS is offered on its records"},"callEnabled":{"type":"boolean","description":"Whether calling is offered on its records"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}}}}},"example":{"pipeline":{"name":"Sales","description":"Deals from first contact to signed contract","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"lead","name":"Lead","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"quoted","name":"Quoted","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"won","name":"Won","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"lead-to-quoted","name":"Send quote","description":"The client has asked for a price","color":"#3b82f6","icon":"file-text","fromStageId":"lead","toStageId":"quoted","actions":[{"id":"action-assign-owner","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["dealAmount"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"send-quote","label":"Send quote","description":"Stamps the quote date and tells the assignees","icon":"send","color":"#3b82f6","visibleInStages":["quoted"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Send the quote to the client now?"},"actions":[{"id":"action-stamp-quote-date","actionType":"update_field","isActive":true,"config":{"fieldId":"quoteSentOn","useCurrentDate":true},"orderNum":0},{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"remind-stale-quote","name":"Remind on new quotes","description":"Tells the assignees when a deal reaches Quoted","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"quoted"}},"conditions":[],"actions":[{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"orderNum":0}],"fieldDefinitions":[{"id":"dealAmount","name":"dealAmount","label":"Deal amount","sectionId":"deal","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"placeholder":"0","description":"Contract value before tax","orderNum":0,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"quoteSentOn","name":"quoteSentOn","label":"Quote sent on","sectionId":"deal","colSpan":3,"fieldType":"date","options":[],"isRequired":false,"orderNum":1,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"contactName","name":"contactName","label":"Contact name","sectionId":"deal","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"deal","name":"Deal","orderNum":0}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"dealAmount","cardBadgeField":"quoteSentOn","defaultStageId":"lead","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"quoted","maxHours":72,"warningHours":48}],"stageRollups":[{"fieldId":"dealAmount","function":"sum","title":"Total value"}],"conditionFields":[{"_id":"6ad1c2e0f3a4b5c6d7e8f909","path":"dealAmount","label":"Deal amount","type":"number","options":[]}]},"roundRobinState":{"action-assign-owner":1},"enabledEmailAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"emailEnabled":true,"smsEnabled":true,"callEnabled":false,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-02T07:30:00.000Z","updatedAt":"2026-10-15T09:40:00.000Z","id":"6ad1c2e0f3a4b5c6d7e8f901"}}}}},"400":{"description":"pipelineId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the pipeline's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/spaces/{spaceId}/members/{userId}/role":{"put":{"tags":["Spaces"],"summary":"Change a member's role","description":"Changes a member's role in a space. Only the space's owner may do it, and not in an archived space. Giving someone the owner role makes them another owner, and an owner cannot be moved to a lower role.\n\n**Permission:** `spaces.members.update` (Change member roles).","operationId":"updateSpaceMemberRole","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID of the member","example":"66f1b2c3d4e5f60718293a5c"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","editor","contributor","viewer"],"description":"Their new role","examples":["contributor"]}},"required":["role"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"space":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; absent until the room is first made, e.g. when someone first opens the space's chat"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"space":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"},{"userId":"66f1b2c3d4e5f60718293a5c","role":"contributor","joinedAt":"2026-09-03T10:15:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"chatId":"6a9f3d02b7e4a20f1c5d8e59","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:30:00.000Z"}}}}},"400":{"description":"spaceId is not a valid ID, or that person is not a member, is an owner, or role is not one of the four roles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.members.update"]}],"x-required-scopes":["spaces.members.update"]}},"/tasks/{taskId}/status":{"put":{"tags":["Tasks"],"summary":"Change a task's status","description":"Sets a task's status: completed stamps completedAt and any other status clears it. Its creator, its assignees and members of its space with the contributor role or higher can do this. Followers other than you get a notification, and people watching the space see the change live.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"updateTaskStatus","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","in_progress","completed","cancelled"],"description":"New status","examples":["completed"]}},"required":["status"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"type":"string","format":"date-time","description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"}},"description":"The space it belongs to, as { id } only; absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"completed","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":"2026-10-15T11:40:00.000Z","creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T11:40:00.000Z"}}}}},"400":{"description":"taskId is not a valid ID, or status is not open, in_progress, completed or cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not its creator or an assignee, nor a member of its space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/unarchive":{"put":{"tags":["Tasks"],"summary":"Restore an archived task","description":"Brings back an archived task together with all of its archived subtasks. Its creator or a member of its space with the editor role or higher can do this, but not while the space itself is archived. People watching the space see it reappear live.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"restoreTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the archived task","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it belongs to (id, name, color, icon); absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"taskListName":{"type":"string","description":"Name of that task list"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"archivedAt":{"description":"When it was archived; null now that it is restored"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","taskListName":"This month","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","archivedAt":null}}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not its creator, nor a member of its space with the editor role or higher, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No archived task with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/pipelines/{pipelineId}/from-blueprint":{"put":{"tags":["Pipelines"],"summary":"Replace a pipeline from a blueprint","description":"Rebuilds a pipeline from a blueprint: its name, description, stages, transitions, automations, custom fields, sections and settings become what the blueprint says. Stages that stay keep their editor positions, custom buttons are left alone, and settings the blueprint leaves out go back to their defaults (except showAvatars, showBadges and the column widths, which stay). Needs the editor or owner role in the pipeline's space, and is refused if it would remove a stage that still holds records that are not archived; people viewing the space get the change live.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineFromBlueprint","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blueprint":{"type":"object","description":"The whole pipeline, shaped like exportPipelineBlueprint's blueprint. name and at least one stage (each with id, name, color and a numeric orderNum) are required; transitions, automations, fieldDefinitions, fieldSections, config and templateId are optional. IDs must be unique, every stage, field and section it refers to must be in it (a transition's requiredFieldIds may also name _dueDate, _startDate and _priority), and action types, operators and trigger events must be ones getPipelineSchema lists. A JSON object in a string also works","examples":[{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","config":{"to":"creator","message":"{{record.title}} was approved"}},{"id":"approve-webhook","actionType":"webhook","config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note"},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","config":{"to":"assignees","message":"{{record.title}} is paid"}}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty"}],"requiredFieldIds":["payment-ref"]}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty"}],"actions":[{"id":"assign-payer","actionType":"assign","config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]}}]}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","fieldType":"text","sectionId":"invoice","isRequired":true,"placeholder":"Who sent the invoice","showOnCard":true},{"id":"amount","name":"amount","label":"Amount","fieldType":"currency","sectionId":"invoice","isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0}},{"id":"category","name":"category","label":"Category","fieldType":"select","sectionId":"invoice","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"defaultValue":"services","orderNum":2},{"id":"po-number","name":"poNumber","label":"PO number","fieldType":"text","sectionId":"invoice","placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","fieldType":"attachment","sectionId":"invoice","colSpan":6,"orderNum":4},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","fieldType":"text","sectionId":"payment","placeholder":"Bank reference","orderNum":5}],"fieldSections":[{"id":"invoice","name":"Invoice"},{"id":"payment","name":"Payment","orderNum":1}],"config":{"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}]}}]}},"required":["blueprint"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline as rebuilt"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e70"},{"path":"priority","label":"Priority","type":"string","options":[{"value":"none","label":"None","_id":"6ad1c7a2f4b2e81d9c7a5e72"},{"value":"low","label":"Low","_id":"6ad1c7a2f4b2e81d9c7a5e73"},{"value":"medium","label":"Medium","_id":"6ad1c7a2f4b2e81d9c7a5e74"},{"value":"high","label":"High","_id":"6ad1c7a2f4b2e81d9c7a5e75"},{"value":"critical","label":"Critical","_id":"6ad1c7a2f4b2e81d9c7a5e76"}],"_id":"6ad1c7a2f4b2e81d9c7a5e71"},{"path":"stageName","label":"Stage","type":"string","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e77"},{"path":"supplier","label":"Supplier","type":"string","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e78"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e79"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-15T09:00:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID; or the blueprint does not hold together (the reply lists each problem in validationErrors), is not valid JSON, would remove a stage that still holds records that are not archived, or fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/stages/{stageId}":{"put":{"tags":["Pipelines"],"summary":"Update a stage","description":"Changes a stage's name, colour or place in the workflow editor; inputs you leave out stay as they are. Needs the editor or owner role in the pipeline's space. Records already in the stage keep the old name in stageName until they move.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineStage","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"stageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the stage","example":"approved"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"New column colour as a hex code","examples":["#3b82f6"]},"name":{"type":"string","description":"New stage name","examples":["Approved"]},"positionX":{"type":"number","description":"New place across the workflow editor","examples":[360]},"positionY":{"type":"number","description":"New place down the workflow editor","examples":[120]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline after the change"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, there is no stage with that ID in the pipeline, or the stage fails the model's checks (e.g. an empty name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]},"delete":{"tags":["Pipelines"],"summary":"Remove a stage from a pipeline","description":"Removes a stage, together with every transition into or out of it, and takes it off global transitions' fromStageIds. Needs the editor or owner role in the pipeline's space. Refused while records that are not archived are in the stage; archived records in it keep its ID.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"removePipelineStage","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"stageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the stage","example":"on-hold"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline without the stage"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, records that are not archived are still in the stage, or there is no stage with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/transitions/{transitionId}":{"put":{"tags":["Pipelines"],"summary":"Update a transition","description":"Changes a transition; inputs you leave out stay as they are. Its from and to stages cannot be changed here. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineTransition","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"transitionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the transition","example":"approve"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"},"description":"Replaces all its actions. What runs after the move, each { id, actionType, isActive, config, orderNum }; getPipelineSchema lists the action types and their config keys. A JSON array in a string also works","examples":[[{"id":"reopen-notify","actionType":"notify","config":{"to":"assignees","message":"{{record.title}} was reopened"}}]]},"color":{"type":"string","description":"Button colour as a hex code; empty is ignored","examples":["#3b82f6"]},"commentPrompt":{"type":"string","description":"Prompt for the note, also the error text when it is missing","examples":["Add the approval note"]},"conditions":{"type":"array","items":{"type":"object"},"description":"Replaces all its conditions. Checks that must pass before the move, each { id, fieldPath, fieldLabel, operator, value, logicOperator }, read left to right; or give each a groupId (and groupOperator) to AND within a group and OR between groups. Rows with no fieldPath are dropped, and a leading fieldValues. is taken off fieldPath. A JSON array in a string also works","examples":[[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty"}]]},"description":{"type":"string","description":"What the move is for","examples":["Send it back for another look."]},"fromStageIds":{"type":"array","items":{"type":"string"},"description":"Replaces the list. With isGlobal: the other stages it can be used from. A JSON array in a string also works","examples":[["paid"]]},"icon":{"type":"string","description":"Name of the icon on the button; empty text clears it","examples":["check-circle"]},"isActive":{"type":"boolean","description":"false turns it off: it leaves the board (stagesWithTransitions), and movePipelineRecord refuses it","examples":[true]},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds; the text \"true\" also works","examples":[false]},"name":{"type":"string","description":"New name; empty is ignored","examples":["Approve"]},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move; the text \"true\" also works","examples":[true]},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Replaces its required fields. Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move. A JSON array in a string also works","examples":[["supplier"]]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline after the change"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, there is no transition with that ID, a list input is not valid JSON, or the result fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]},"delete":{"tags":["Pipelines"],"summary":"Remove a transition","description":"Removes a transition from a pipeline; records keep it in their transitionHistory. An ID that matches no transition changes nothing. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"removePipelineTransition","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"transitionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the transition","example":"reopen"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline without the transition"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or the pipeline could not be saved (it fails the model's checks)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/field-definitions/{fieldId}":{"put":{"tags":["Pipelines"],"summary":"Update a custom field","description":"Changes some of a custom field's settings: each key in updates replaces that key, the rest stay. Values records already hold are not checked again. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineFieldDefinition","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"fieldId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the field","example":"supplier"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"object","description":"Settings to change, keyed like the reply's fieldDefinitions items, e.g. { label, isRequired, options }. A JSON object in a string also works","examples":[{"label":"Supplier name","isRequired":true}]}},"required":["updates"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline after the change"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, there is no field with that ID, updates is not valid JSON, or the result fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]},"delete":{"tags":["Pipelines"],"summary":"Remove a custom field","description":"Removes a custom field from a pipeline. Values records hold for it stay in their fieldValues. An ID that matches no field changes nothing. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"removePipelineFieldDefinition","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"fieldId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the field","example":"payment-terms"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline without the field"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or the pipeline could not be saved (it fails the model's checks)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/automations/{automationId}":{"put":{"tags":["Pipelines"],"summary":"Update an automation","description":"Changes an automation: each top-level key in updates replaces that key (so a new trigger replaces the old one whole), the rest stay. Needs the editor or owner role in the pipeline's space; people viewing the pipeline get the change live.\n\n**Permission:** `spaces.pipelines.admin` (Manage pipeline automations).","operationId":"updatePipelineAutomation","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"automationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the automation","example":"assign-payer-on-approval"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"object","description":"Keys to change, named like the reply's automations items, e.g. { isActive: false }. Condition rows with no fieldPath are dropped. A JSON object in a string also works","examples":[{"isActive":false}]}},"required":["updates"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline after the change"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, updates is not valid JSON, or the result fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no automation with that ID in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.admin"]}],"x-required-scopes":["spaces.pipelines.admin"]},"delete":{"tags":["Pipelines"],"summary":"Remove an automation","description":"Removes an automation from a pipeline. An ID that matches no automation changes nothing. Needs the editor or owner role in the pipeline's space; people viewing the pipeline get the change live.\n\n**Permission:** `spaces.pipelines.admin` (Manage pipeline automations).","operationId":"removePipelineAutomation","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"automationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the automation","example":"flag-large-invoice"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline without the automation"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or the pipeline could not be saved (it fails the model's checks)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.admin"]}],"x-required-scopes":["spaces.pipelines.admin"]}},"/strategies/{strategyId}/swot/{itemId}":{"put":{"tags":["Strategies"],"summary":"Update a SWOT item","description":"Changes a SWOT item's statement, impact, notes or type; fields you leave out stay as they are. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateSwotItem","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the SWOT item","example":"1788253200123-k3x9q"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"New statement","examples":["Our fibre already reaches 40 business parks in Nairobi"]},"impact":{"type":"string","enum":["high","medium","low"],"description":"How much it matters","examples":["high"]},"notes":{"type":"string","description":"New supporting detail","examples":["Mapped in the August network review"]},"type":{"type":"string","enum":["strength","weakness","opportunity","threat"],"description":"Move it to another SWOT box","examples":["strength"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no SWOT item with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove a SWOT item","description":"Removes a SWOT item from a strategy for good and answers with the whole strategy. Needs the editor role or higher in the strategy's space, which must not be archived. An item ID the strategy does not have changes nothing.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removeSwotItem","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the SWOT item","example":"1788253500789-z8w4n"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/pillars/{pillarId}":{"put":{"tags":["Strategies"],"summary":"Update a pillar","description":"Changes a pillar's name, description or colour; fields you leave out stay as they are. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updatePillar","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"pillarId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pillar","example":"1788254100234-r5t8v"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"New colour as a hex code","examples":["#3b82f6"]},"description":{"type":"string","description":"New description","examples":["Win and keep companies on fibre"]},"name":{"type":"string","description":"New name","examples":["Business customers"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no pillar with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove a pillar","description":"Removes a pillar from a strategy for good and answers with the whole strategy. Objectives under it are kept, with pillarId null. Needs the editor role or higher in the strategy's space, which must not be archived. A pillar ID the strategy does not have removes no pillar.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removePillar","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"pillarId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pillar","example":"1788254400890-w9e3b"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/objectives/{objectiveId}":{"put":{"tags":["Strategies"],"summary":"Update an objective","description":"Changes an objective's pillar, title, description, status or progress; fields you leave out stay as they are. A progress you set is replaced the next time one of its key results is updated. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateObjective","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the objective","example":"1788255000345-m4q7x"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"New notes","examples":["Double monthly revenue from business customers"]},"pillarId":{"type":"string","description":"ID of the pillar to move it under; not checked","examples":["1788254100234-r5t8v"]},"progress":{"type":"number","minimum":0,"maximum":100,"description":"How far along it is, 0 to 100","examples":[38]},"status":{"type":"string","enum":["not_started","on_track","at_risk","behind","completed"],"description":"How it is going","examples":["on_track"]},"title":{"type":"string","description":"New title","examples":["Grow business revenue"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no objective with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove an objective","description":"Removes an objective and its key results from a strategy for good, and answers with the whole strategy. Initiatives linked to it are kept, with objectiveId and keyResultId null, and milestones linked to it are kept, with linkedObjectiveId null. Needs the editor role or higher in the strategy's space, which must not be archived. An objective ID the strategy does not have removes no objective.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removeObjective","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the objective","example":"1788255300901-y6u2k"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/objectives/{objectiveId}/key-results/{keyResultId}":{"put":{"tags":["Strategies"],"summary":"Update a key result","description":"Changes a key result (most often its current value); fields you leave out stay as they are. It then recalculates the objective's progress as the average, over all its key results, of how far each has moved from start to target (0 to 100 each, rounded). Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateKeyResult","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the objective","example":"1788255000345-m4q7x"},{"name":"keyResultId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the key result","example":"1788255600456-s3l9p"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currentValue":{"type":"number","description":"Value reached so far","examples":[45]},"dueDate":{"type":"string","format":"date-time","description":"New due date; an empty string clears it","examples":["2027-06-30T00:00:00.000Z"]},"startValue":{"type":"number","description":"New start value","examples":[0]},"status":{"type":"string","enum":["not_started","on_track","at_risk","behind","completed"],"description":"How it is going","examples":["on_track"]},"targetValue":{"type":"number","description":"New target value","examples":[120]},"title":{"type":"string","description":"New title","examples":["Sign 120 new business contracts"]},"unit":{"type":"string","description":"New unit","examples":["contracts"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no objective with that ID, or the objective has no key result with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove a key result","description":"Removes a key result from an objective for good and answers with the whole strategy. The objective's progress is not recalculated. Needs the editor role or higher in the strategy's space, which must not be archived. A key result ID the objective does not have changes nothing.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removeKeyResult","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the objective","example":"1788255000345-m4q7x"},{"name":"keyResultId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the key result","example":"1788255900012-t1o5z"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no objective with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/initiatives/{initiativeId}":{"put":{"tags":["Strategies"],"summary":"Update an initiative","description":"Changes an initiative; fields you leave out stay as they are, and the IDs you send are stored without checks. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateInitiative","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"initiativeId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the initiative","example":"1788256200567-b6x8w"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeId":{"type":"string","description":"ID of the person responsible","examples":["66f1b2c3d4e5f60718293a5c"]},"description":{"type":"string","description":"New notes","examples":["Fibre, phone lines and support in one monthly price"]},"dueDate":{"type":"string","format":"date-time","description":"New due date; an empty string clears it","examples":["2027-01-31T00:00:00.000Z"]},"keyResultId":{"type":"string","description":"ID of the key result it moves","examples":["1788255600456-s3l9p"]},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work","examples":["6ad1c3f84f3b8a1d2c7e5f37"]},"linkedTaskListId":{"type":"string","description":"ID of the task list for this work; an empty string unlinks it, so createInitiativeTaskList can make a new one","examples":["6ad1c3a24f3b8a1d2c7e5f2b"]},"objectiveId":{"type":"string","description":"ID of the objective it serves","examples":["1788255000345-m4q7x"]},"priority":{"type":"string","enum":["critical","high","medium","low"],"description":"How urgent it is","examples":["high"]},"status":{"type":"string","enum":["not_started","in_progress","completed","blocked","cancelled"],"description":"Where the work stands","examples":["in_progress"]},"title":{"type":"string","description":"New title","examples":["Launch a business fibre bundle"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no initiative with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove an initiative","description":"Removes an initiative from a strategy for good and answers with the whole strategy. Its task list, if it has one, stays in the space. Needs the editor role or higher in the strategy's space, which must not be archived. An initiative ID the strategy does not have changes nothing.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removeInitiative","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"initiativeId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the initiative","example":"1788256500123-n8r3j"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/milestones/{milestoneId}":{"put":{"tags":["Strategies"],"summary":"Update a milestone","description":"Changes a milestone's title, description, date, status or objective; fields you leave out stay as they are. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateMilestone","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"milestoneId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the milestone","example":"1788256800678-d5k1h"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"New notes","examples":["Halfway to the contracts target"]},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; not checked","examples":["1788255000345-m4q7x"]},"status":{"type":"string","enum":["pending","achieved","missed","moved"],"description":"Whether it was reached","examples":["pending"]},"targetDate":{"type":"string","format":"date-time","description":"New target date","examples":["2027-02-28T00:00:00.000Z"]},"title":{"type":"string","description":"New title","examples":["First 50 contracts signed"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no milestone with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove a milestone","description":"Removes a milestone from a strategy for good and answers with the whole strategy. Needs the editor role or higher in the strategy's space, which must not be archived. A milestone ID the strategy does not have changes nothing.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removeMilestone","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"milestoneId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the milestone","example":"1788257100234-f9p2s"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/reviews/{reviewId}":{"put":{"tags":["Strategies"],"summary":"Update a strategy review","description":"Changes a review; fields you leave out stay as they are, and decisions or nextActions replace the whole list. Its date stays the day it was added. Needs the editor role or higher in the strategy's space, which must not be archived. Answers with the whole strategy.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"updateReview","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the review","example":"1792054800345-e3y8r"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"decisions":{"type":"array","items":{"type":"string"},"description":"The full new list of decisions (a JSON array in a string also works)","examples":[["Hire a second install team"]]},"nextActions":{"type":"array","items":{"type":"string"},"description":"The full new list of next steps (a JSON array in a string also works)","examples":[["Post the install team job ad","Review install lead times weekly"]]},"overallHealth":{"type":"string","enum":["healthy","needs_attention","at_risk","critical"],"description":"How healthy the strategy is overall","examples":["needs_attention"]},"summary":{"type":"string","description":"New summary","examples":["Contracts are on pace; installs are slower than planned."]},"type":{"type":"string","enum":["weekly","monthly","quarterly","adhoc"],"description":"Which kind of review","examples":["monthly"]},"whatDidnt":{"type":"string","description":"What did not go well","examples":["Install lead times of over three weeks"]},"whatWorked":{"type":"string","description":"What went well","examples":["Referrals from existing customers"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which), or decisions or nextActions is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no review with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]},"delete":{"tags":["Strategies"],"summary":"Remove a strategy review","description":"Removes a review from a strategy for good and answers with the whole strategy. Needs the editor role or higher in the strategy's space, which must not be archived. A review ID the strategy does not have changes nothing.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"removeReview","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the review","example":"1789462800456-x2c9t"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/space-items/{itemId}":{"put":{"tags":["Spaces"],"summary":"Update a sidebar item","description":"Changes a sidebar item's name, icon, colour, whether a folder shows open, or its extra settings; inputs you leave out stay as they are. Needs the editor role or higher in the item's space, which must not be archived. Renaming an item does not rename the sheet, pipeline or wiki it opens.\n\n**Permission:** `spaces.spaceItems.update` (Update space items).","operationId":"updateSpaceItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sidebar item","example":"6a9f3c71b7e4a20f1c5d8e4c"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"New colour as a hex code","examples":["#f59e0b"]},"icon":{"type":"string","description":"New emoji or icon name; an empty text clears it","examples":["📁"]},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar","examples":[false]},"metadata":{"type":"object","description":"Extra settings; replaces what was there. A JSON object in a string also works","examples":[{"dashboardId":12}]},"name":{"type":"string","description":"New name","examples":["Budgets 2026"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"spaceId":{"type":"string","description":"ID of the space it is in"},"itemType":{"type":"string","description":"What it is: folder, calendar, pipeline, wiki, document, tasks, spreadsheet, presentation, custom, analytics, strategy, drive. tasks is a task list"},"name":{"type":"string","description":"Name shown in the sidebar"},"icon":{"type":"string","description":"An emoji or icon name; each type has its own default, e.g. 📁 for a folder"},"parentId":{"description":"ID of the folder it sits in; null at the top level"},"orderNum":{"type":"integer","description":"Position among the items in the same folder; 0 comes first"},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"metadata":{"description":"Extra settings some item types keep, e.g. the dashboard an analytics item shows; null when none"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"color":{"type":"string","description":"Colour as a hex code; absent when none was chosen"}}}}},"example":{"item":{"id":"6a9f3c71b7e4a20f1c5d8e4c","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"folder","name":"Budgets 2026","icon":"📁","parentId":null,"orderNum":1,"isExpanded":false,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-02T09:00:00.000Z","updatedAt":"2026-10-15T09:50:00.000Z","color":"#f59e0b"}}}}},"400":{"description":"itemId is not a valid ID, name is empty, or metadata is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the item's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sidebar item with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.update"]}],"x-required-scopes":["spaces.spaceItems.update"]},"delete":{"tags":["Spaces"],"summary":"Archive a sidebar item","description":"Archives a sidebar item, so it no longer shows in the sidebar. A folder must be empty first. A strategy item archives its strategy with it, unless another sidebar item still opens it: the strategy and its assistant then answer 404. The pipeline, wiki, sheet or document an item opens is not archived with it. Needs the editor role or higher in the item's space.\n\n**Permission:** `spaces.spaceItems.delete` (Delete space items).","operationId":"archiveSpaceItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sidebar item","example":"6ad0a0c7d5c26de56de949e1"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"itemId is not a valid ID, or it is a folder that still has items in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the item's space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sidebar item with that ID, or it is already archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.delete"]}],"x-required-scopes":["spaces.spaceItems.delete"]}},"/time-blocks/{blockId}":{"put":{"tags":["Calendar"],"summary":"Update a time block","description":"Changes one of your time blocks; only the fields you send change. Sharing it to a space needs you to see the space, as when creating.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"updateTimeBlock","parameters":[{"name":"blockId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the time block","example":"6ad1c2b0d5c26de56de94a40"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"blockType":{"type":"string","enum":["focus","meetings","admin","personal","break","custom"],"description":"Kind of block","examples":["focus"]},"color":{"type":"string","description":"Colour shown on the calendar","examples":["#3b82f6"]},"date":{"type":"string","format":"date-time","description":"Day of a one-off block","examples":["2026-10-20T00:00:00.000Z"]},"endTime":{"type":"string","description":"End time of day, HH:mm","examples":["11:00"]},"isActive":{"type":"boolean","description":"false hides the block from every list"},"recurrence":{"type":"object","properties":{"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}}},"description":"For a repeating block: { daysOfWeek } with 0 for Sunday to 6 (a JSON object in a string also works)","examples":[{"daysOfWeek":[1,2,3,4,5]}]},"spaceId":{"type":"string","description":"Space to share the block to","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"startTime":{"type":"string","description":"Start time of day, HH:mm","examples":["09:00"]},"title":{"type":"string","description":"Name of the block","examples":["Deep work"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"timeBlock":{"type":"object","properties":{"title":{"type":"string","description":"Name of the block, e.g. Deep work"},"blockType":{"type":"string","description":"Kind of block: focus, meetings, admin, personal, break, custom"},"color":{"type":"string","description":"Colour shown on the calendar"},"startTime":{"type":"string","description":"Start time of day, HH:mm"},"endTime":{"type":"string","description":"End time of day, HH:mm"},"recurrence":{"type":"object","properties":{"daysOfWeek":{"type":"array","items":{"type":"integer"},"description":"Weekdays it repeats on, 0 (Sunday) to 6; empty for a one-off block"}},"description":"When a repeating block comes back"},"userId":{"type":"string","description":"ID of the person whose block it is"},"spaceId":{"type":"string","description":"ID of the space it is shared to; absent when it is not shared"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether it is shown; lists leave out blocks that are not"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Time block ID"}},"description":"The time block after the change"}}},"example":{"timeBlock":{"title":"Deep work","blockType":"focus","color":"#3b82f6","startTime":"09:00","endTime":"11:00","recurrence":{"daysOfWeek":[1,2,3,4,5]},"userId":"66f1b2c3d4e5f60718293a4b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","organizationId":"66a4b275003d1b495212b5aa","isActive":true,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z","id":"6ad1c2b0d5c26de56de94a40"}}}}},"400":{"description":"blockId or spaceId is not a valid ID, or recurrence is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No time block with that ID of yours, or no space with spaceId that you can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]},"delete":{"tags":["Calendar"],"summary":"Delete a time block","description":"Deletes one of your time blocks for good.\n\n**Permission:** `spaces.calendar.delete` (Delete events).","operationId":"deleteTimeBlock","parameters":[{"name":"blockId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the time block","example":"6ad1c2b0d5c26de56de94a40"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"blockId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No time block with that ID of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.delete"]}],"x-required-scopes":["spaces.calendar.delete"]}},"/wiki/comments/{commentId}":{"put":{"tags":["Docs"],"summary":"Edit a comment","description":"Changes the text of a comment. Only its author can, while they have the contributor role in the comment's space, as for resolving it; not in an archived space. It does not check whether the page or wiki is archived.\n\n**Permission:** `spaces.wikiComments.update` (Edit wiki comments).","operationId":"updateWikiComment","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad1b170e4f5a6b7c8d9e160"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The new text, up to 5,000 characters","examples":["Does the two-week rule apply to sick leave and compassionate leave too?"]}},"required":["content"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the page it is on"},"wikiId":{"type":"string","description":"ID of the page's wiki"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"authorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote it: id, firstName, lastName and email; null if that person is no longer on record"},"content":{"type":"string","description":"The comment text, up to 5,000 characters"},"selection":{"type":"object","properties":{"from":{"type":"integer","description":"Where the selected text starts, as a position in the page's editor document"},"to":{"type":"integer","description":"Where it ends"},"text":{"type":"string","description":"The selected words"}},"description":"The part of the page it is about; absent on a comment about the whole page"},"replyCount":{"type":"integer","description":"How many replies it has; a deleted reply comes off it"},"isResolved":{"type":"boolean","description":"Whether it is resolved"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was written"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}}}},"example":{"comment":{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"content":"Does the two-week rule apply to sick leave and compassionate leave too?","selection":{"from":42,"to":57,"text":"two weeks ahead"},"replyCount":1,"isResolved":false,"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:00:00.000Z","updatedAt":"2026-10-15T10:05:00.000Z","id":"6ad1b170e4f5a6b7c8d9e160"}}}}},"400":{"description":"commentId is not a valid ID, or content is empty or over 5,000 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the comment's space with the contributor role or higher, its wiki no longer exists, the space is archived, or you did not write the comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it is deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.update"]}],"x-required-scopes":["spaces.wikiComments.update"]},"delete":{"tags":["Docs"],"summary":"Delete a comment on a page","description":"Deletes a comment and its replies; they no longer show in any call. Its author, or anyone with the editor role in the comment's space, can do this. A deleted reply comes off its parent's replyCount.\n\n**Permission:** `spaces.wikiComments.delete` (Delete wiki comments).","operationId":"deleteWikiComment","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad1b170e4f5a6b7c8d9e160"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You did not write the comment and have no editor or owner role in its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it is deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.delete"]}],"x-required-scopes":["spaces.wikiComments.delete"]}},"/comments/{commentId}":{"put":{"tags":["Comments"],"summary":"Edit a comment","description":"Replaces the text of a comment. Only its author can edit it, and only while they may still post on the item. Needs the contributor, editor or owner role in the space the item is in. On a task, people who follow it may also post, whatever their place in the space; on a personal task (no space) its creator, assignees and followers may, and on a personal event its creator and attendees. An item in an archived space takes no new comments, edits, files or reactions. Files, mentions and reactions stay as they were, nobody is notified and nothing is sent live.\n\n**Permission:** `spaces.comments.update` (Edit comments).","operationId":"updateComment","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad0a3c2d5c26de56de94a10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The new text: plain text, or a rich-text document as a JSON string; at most 50,000 characters, trimmed","examples":["Sent the invoice and the signed delivery note to the client this morning."]}},"required":["content"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"targetType":{"type":"string","description":"What kind of item it is on: task, wiki_page, pipeline, pipeline_record or event"},"targetId":{"type":"string","description":"ID of that item"},"spaceId":{"type":"string","description":"ID of the space the item is in; absent for a personal task or event"},"authorId":{"type":"object","properties":{"name":{"type":"string","description":"Full name, when Kazee sign-in has one for them"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who wrote it"},"kind":{"type":"string","description":"comment: written by a person. transition: a note added when someone moves a pipeline record through a stage transition with notes"},"content":{"type":"string","description":"The text: plain text, or a rich-text document as a JSON string"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with a short random code added, e.g. delivery-note-3f9c2a1b.jpg"},"originalName":{"type":"string","description":"Name of the file as it was uploaded"},"fileSize":{"type":"integer","description":"Size in bytes"},"mimeType":{"type":"string","description":"File type, e.g. image/jpeg"},"minioKey":{"type":"string","description":"Key of the stored file; pass it as minioKey to getCommentAttachmentUrl for a download link"},"bucketName":{"type":"string","description":"Which store holds the file; absent on older files"},"type":{"type":"string","description":"image, video or file, from the file type"},"uploadedAt":{"type":"string","format":"date-time","description":"When the file was stored"},"_id":{"type":"string","description":"ID of this file entry on the comment"}}},"description":"Files attached to it"},"replyCount":{"type":"integer","description":"How many direct replies it has"},"mentions":{"type":"array","items":{"type":"string"},"description":"IDs of the people mentioned in it"},"reactions":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who reacted"},"emoji":{"type":"string","description":"The emoji"},"createdAt":{"type":"string","format":"date-time","description":"When they reacted"},"_id":{"type":"string","description":"ID of this reaction entry"}}},"description":"Emoji reactions, at most one per person"},"seenBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who saw it"},"seenAt":{"type":"string","format":"date-time","description":"When they first saw it"},"_id":{"type":"string","description":"ID of this entry"}}},"description":"Who has seen it, and when; the author counts as having seen it from the start"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was posted"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}},"description":"The comment with its new text"}}},"example":{"comment":{"targetType":"task","targetId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"name":"Amina Otieno","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"kind":"comment","content":"Sent the invoice and the signed delivery note to the client this morning.","attachments":[{"fileName":"delivery-note-3f9c2a1b.jpg","originalName":"delivery-note.jpg","fileSize":482133,"mimeType":"image/jpeg","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","type":"image","uploadedAt":"2026-10-15T09:40:12.000Z","_id":"6ad0a3c2d5c26de56de94a11"}],"replyCount":1,"mentions":["66f1b2c3d4e5f60718293a5c"],"reactions":[{"userId":"66f1b2c3d4e5f60718293a5c","emoji":"👍","createdAt":"2026-10-15T10:02:00.000Z","_id":"6ad0a41ad5c26de56de94a25"}],"seenBy":[{"userId":"66f1b2c3d4e5f60718293a4b","seenAt":"2026-10-15T09:41:00.000Z","_id":"6ad0a3c2d5c26de56de94a12"},{"userId":"66f1b2c3d4e5f60718293a5c","seenAt":"2026-10-15T10:01:30.000Z","_id":"6ad0a45bd5c26de56de94a2e"}],"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:41:00.000Z","updatedAt":"2026-10-15T10:20:00.000Z","id":"6ad0a3c2d5c26de56de94a10"}}}}},"400":{"description":"commentId is not a valid ID, content is missing or empty, or the new text could not be saved (over 50,000 characters, or only spaces on a comment with no files)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the comment's author can edit it, and only while they may still post on the item (see createComment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it was deleted, or its item is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comments.update"]}],"x-required-scopes":["spaces.comments.update"]},"delete":{"tags":["Comments"],"summary":"Delete a comment","description":"Deletes a comment and the whole thread under it (its replies, the replies to those, and so on), which then disappear from every list and from listComments' total; there is no call to bring them back. Open to editors and owners of the space the item is in, and to the comment's author while they may still post on the item, an archived space included. Files stay in storage, and nothing is sent live.\n\n**Permission:** `spaces.comments.delete` (Delete comments).","operationId":"deleteComment","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad0a3c2d5c26de56de94a10"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only an editor or owner of the item's space, or the comment's author while they may still post on the item (see createComment), can delete it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it was already deleted, or its item is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comments.delete"]}],"x-required-scopes":["spaces.comments.delete"]}},"/calendar/integrations/{integrationId}":{"put":{"tags":["Calendar"],"summary":"Update a connected calendar's settings","description":"Saves the sync settings of one of your calendar connections; only the settings you send change. Nothing on the server acts on these settings yet: they are stored for the apps, and getting events from the calendar ignores them.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"updateCalendarSettings","parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the calendar connection (id from listCalendarIntegrations)","example":"6ad1c3d8d5c26de56de94a55"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"createEventsForTimeBlocks":{"type":"boolean","description":"Whether time blocks should become Google events"},"importEventsAsBlocking":{"type":"boolean","description":"Whether Google events should count as busy time"},"selectedCalendars":{"type":"array","items":{"type":"string"},"description":"IDs of the Google calendars to sync, replacing the list (a JSON array in a string also works)","examples":[["grace.namutebi@gmail.com","en.ug#holiday@group.v.calendar.google.com"]]},"syncEnabled":{"type":"boolean","description":"Whether syncing is on"},"twoWaySync":{"type":"boolean","description":"Whether time blocks should also be written to Google"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"integration":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person who connected it"},"provider":{"type":"string","description":"Which calendar service: google"},"tokenExpiry":{"type":"string","format":"date-time","description":"When Spaces' current access to the calendar runs out; it is renewed when needed"},"email":{"type":"string","description":"The Google account it is connected to"},"calendarId":{"type":"string","description":"Which Google calendar is read: the account's main one"},"selectedCalendars":{"type":"array","description":"Saved setting, not used yet: IDs of other Google calendars chosen for syncing"},"syncEnabled":{"type":"boolean","description":"Saved setting, not used yet: whether syncing is on"},"twoWaySync":{"type":"boolean","description":"Saved setting, not used yet: whether time blocks should also be written to Google"},"createEventsForTimeBlocks":{"type":"boolean","description":"Saved setting, not used yet: whether time blocks should become Google events"},"importEventsAsBlocking":{"type":"boolean","description":"Saved setting, not used yet: whether Google events should count as busy time"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether the connection is in use"},"lastSyncAt":{"type":"string","format":"date-time","description":"When events were last fetched from Google"},"lastSyncError":{"description":"Why the last fetch failed; null when it worked"},"createdAt":{"type":"string","format":"date-time","description":"When it was first connected"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Connection ID; use it as integrationId"}},"description":"The connection with its new settings"}}},"example":{"integration":{"userId":"66f1b2c3d4e5f60718293a4b","provider":"google","tokenExpiry":"2026-10-15T09:00:00.000Z","email":"grace.namutebi@gmail.com","calendarId":"grace.namutebi@gmail.com","selectedCalendars":[],"syncEnabled":true,"twoWaySync":false,"createEventsForTimeBlocks":true,"importEventsAsBlocking":true,"organizationId":"66a4b275003d1b495212b5aa","isActive":true,"lastSyncAt":"2026-10-15T08:30:00.000Z","lastSyncError":null,"createdAt":"2026-10-01T07:45:00.000Z","updatedAt":"2026-10-15T08:30:00.000Z","id":"6ad1c3d8d5c26de56de94a55"}}}}},"400":{"description":"integrationId is not a valid ID, or selectedCalendars is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No calendar connection with that ID of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]},"delete":{"tags":["Calendar"],"summary":"Disconnect a calendar","description":"Disconnects one of your calendar connections: Spaces forgets its Google keys and stops using it, and it leaves listCalendarIntegrations.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"disconnectCalendar","parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the calendar connection (id from listCalendarIntegrations)","example":"6ad1c3d8d5c26de56de94a55"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"integrationId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No calendar connection with that ID of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]}},"/views/default":{"post":{"tags":["Saved views"],"summary":"Set my default view for a screen","description":"Makes one of your saved views the one that opens by default on a screen, and stops any other view of yours there from being the default. Leave viewId out to have no default view, so the screen opens on its standard tabs. A viewId that is not one of yours on that screen answers 404 and changes nothing.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"updateDefaultSavedView","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"context":{"type":"string","enum":["my-tasks","space-tasks","pipeline"],"description":"The screen: my-tasks (your My Tasks page), space-tasks (a space's tasks) or pipeline (a pipeline board)","examples":["space-tasks"]},"contextId":{"type":"string","description":"ID of the space for space-tasks, or of the pipeline for pipeline; leave out for my-tasks. An empty text or null also mean none. It is not checked","examples":["6a9f3c21b7e4a20f1c5d8e41"]},"viewId":{"type":"string","description":"ID of your saved view on that screen; leave out, or send empty or null, for no default","examples":["6ad0a0f4d5c26de56de949f8"]}},"required":["context"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"object","properties":{"_id":{"type":"string","description":"View ID"},"organizationId":{"type":"string","description":"ID of the organisation"},"userId":{"type":"string","description":"User ID of the owner; views are personal"},"context":{"type":"string","description":"The screen it belongs to: my-tasks, space-tasks or pipeline"},"contextId":{"type":"string","description":"ID of the space (space-tasks) or pipeline (pipeline); null for my-tasks"},"name":{"type":"string","description":"Name of the view"},"filters":{"type":"object","properties":{"priority":{"type":"object","properties":{"operator":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"dueDate":{"type":"object","properties":{"preset":{"type":"string"}}}},"description":"Filter conditions by field, as they were saved; absent when there are none"},"search":{"type":"string","description":"Search text; empty when none"},"sort":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string"}},"description":"Sort field and direction (asc or desc); absent when not set"},"display":{"type":"object","properties":{"viewMode":{"type":"string"},"groupBy":{"type":"string"},"compactView":{"type":"boolean"}},"description":"How the screen shows it (viewMode, groupBy, compactView); absent when not set"},"isDefault":{"type":"boolean","description":"Whether it opens by default on that screen"},"order":{"type":"integer","description":"Position among your views on that screen; lower comes first"},"visibility":{"type":"string","description":"Always private for now: only you see it"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"View ID (same as _id)"}},"description":"The view that now opens by default; null when you cleared the default"},"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"view":{"_id":"6ad0a0f4d5c26de56de949f8","organizationId":"66a4b275003d1b495212b5aa","userId":"66f1b2c3d4e5f60718293a4b","context":"space-tasks","contextId":"6a9f3c21b7e4a20f1c5d8e41","name":"Overdue criticals","filters":{"priority":{"operator":"is","values":["critical"]},"dueDate":{"preset":"last_7_days"}},"search":"","sort":{"field":"dueDate","direction":"asc"},"display":{"viewMode":"board","groupBy":"status","compactView":false},"isDefault":true,"order":2,"visibility":"private","createdAt":"2026-10-10T07:20:00.000Z","updatedAt":"2026-10-15T10:30:00.000Z","id":"6ad0a0f4d5c26de56de949f8"},"success":true}}}},"400":{"description":"context is not my-tasks, space-tasks or pipeline, or viewId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"None of your saved views on that screen has that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]}},"/spaces/{spaceId}/chat":{"post":{"tags":["Spaces"],"summary":"Open a space's chat room","description":"Gives you the ID of the space's room in Kazee Chat, making the room the first time and bringing its members in line with the space's. Open to any member of the space; on a public space, people who are not members get 404.\n\n**Permission:** `spaces.read` (View spaces).","operationId":"getSpaceChat","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; open it there"},"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"chatId":"6a9f3d02b7e4a20f1c5d8e59","success":true}}}},"400":{"description":"spaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No space with that ID in your organisation, it is archived, or you are not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Kazee Chat could not open the space's room just now; try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.read"]}],"x-required-scopes":["spaces.read"]}},"/tasks/{taskId}/assign":{"post":{"tags":["Tasks"],"summary":"Assign someone to a task","description":"Assigns a person to a task; they start following it, and people watching the space see the change live. Its creator or a member of its space with the contributor role or higher can do this, and for a space task the person must be able to see the space (as a member, or anyone for a public space). Assigning someone who is already assigned changes nothing.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"addTaskAssignee","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person to assign","examples":["66f1b2c3d4e5f60718293a5c"]}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"}},"description":"The space it belongs to, as { id } only; absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"taskId or userId is not a valid ID, or the person cannot see the task's space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not its creator, nor a member of its space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID (or it is archived), or no person with that userId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/unassign":{"post":{"tags":["Tasks"],"summary":"Unassign someone from a task","description":"Takes a person off a task's assignees; people watching the space see the change live. The task's creator can remove anyone, and anyone can remove themselves. The person keeps following the task, and removing someone who is not assigned changes nothing.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"removeTaskAssignee","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person to take off the task","examples":["66f1b2c3d4e5f60718293a5c"]}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"}},"description":"The space it belongs to, as { id } only; absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":[],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"taskId or userId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the task's creator, and userId is not you","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/transfer":{"post":{"tags":["Tasks"],"summary":"Move a task to another space","description":"Moves a task to another space, or out of any space to make it personal; people watching either space see it leave or arrive live. You must be its creator or a member of its current space with the editor role or higher, and a member of the target space with the contributor role or higher. Its subtasks, at every depth and archived ones too, move with it and are put in its task list. Its own task list and everyone's assignees are left as they were.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"moveTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"targetSpaceId":{"type":"string","description":"Space to move it to; leave it out, or send null or an empty string, to make the task personal","examples":["6a9f3c8ab7e4a20f1c5d8e52"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"}},"description":"The space it is in now (id, name, color, icon); null when it was made personal"},"taskListId":{"type":"string","description":"ID of its task list; the move does not change it, and its subtasks now share it"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c8ab7e4a20f1c5d8e52","name":"Operations","color":"#10b981","icon":"🛠️"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"taskId or targetSpaceId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not its creator nor an editor or owner of its current space, or you are not a member of the target space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID (or it is archived), or no target space that you can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/attachments":{"post":{"tags":["Tasks"],"summary":"Attach a file to a task","description":"Uploads a file of up to 25 MB and attaches it to the task. Open to the task's creator, its assignees and members of its space with the contributor, editor or owner role. Replies with the new file and the updated task.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"uploadTaskAttachment","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"attachment":{"type":"string","format":"binary","description":"The file to attach, sent as multipart form data; at most 25 MB"}},"required":["attachment"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with a short random code added, e.g. invoice-october-3f9c2a1b.pdf"},"originalName":{"type":"string","description":"Name of the file as it was uploaded"},"fileSize":{"type":"integer","description":"Size in bytes"},"mimeType":{"type":"string","description":"File type, e.g. application/pdf"},"minioKey":{"type":"string","description":"Key of the stored file; pass it, URL-encoded, as fileKey to get a download link or to delete the file"},"bucketName":{"type":"string","description":"Which store holds the file; absent on older files"},"type":{"type":"string","description":"image, video or file"},"uploadedAt":{"type":"string","format":"date-time","description":"When the file was added"}}},"task":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"What needs doing"},"description":{"type":"string","description":"Longer notes on the task"},"status":{"type":"string","description":"open, in_progress, completed or cancelled"},"priority":{"type":"string","description":"low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work should start"},"completedAt":{"description":"When it was marked completed; null while it is not"},"creatorId":{"type":"string","description":"ID of the person who created it"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people it is assigned to"},"spaceId":{"type":"object","properties":{"id":{"type":"string"}},"description":"The space it belongs to, as { id } only; absent for a personal task"},"taskListId":{"type":"string","description":"ID of the task list it sits in, if any"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the task"},"chatId":{"type":"string","description":"ID of the task's comment chat in Kazee Chat, once it has one"},"estimatedHours":{"type":"integer","description":"Expected effort in hours"},"actualHours":{"type":"number","description":"Effort spent so far in hours"},"isTimeBlocked":{"type":"boolean","description":"Whether it has a slot in the planner"},"parentTaskId":{"description":"ID of the parent task when this is a subtask"},"orderIndex":{"type":"integer","description":"Position within its list; lower comes first"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string"},"originalName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"minioKey":{"type":"string"},"bucketName":{"type":"string"},"type":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}}},"description":"Files attached to the task"},"metadata":{"type":"object","properties":{},"description":"Extra data other features keep on the task"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"attachment":{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"},"task":{"id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","description":"Email the invoice to the client with the delivery note.","status":"in_progress","priority":"high","dueDate":"2026-10-20T09:00:00.000Z","startDate":"2026-10-16T06:00:00.000Z","completedAt":null,"creatorId":"66f1b2c3d4e5f60718293a4b","assignees":["66f1b2c3d4e5f60718293a5c"],"spaceId":{"id":"6a9f3c21b7e4a20f1c5d8e41"},"taskListId":"6a9f3c5eb7e4a20f1c5d8e47","tags":["billing"],"chatId":"6ad0a09ed5c26de56de949c0","estimatedHours":2,"actualHours":1.5,"isTimeBlocked":false,"parentTaskId":null,"orderIndex":3,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","attachments":[{"fileName":"invoice-october-3f9c2a1b.pdf","originalName":"invoice-october.pdf","fileSize":184320,"mimeType":"application/pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/tasks/6ad0a044d5c26de56de949a8/3f9c2a1b-5d7e-4c1a-9b2f-8e6d4a7c1b05-invoice-october.pdf","bucketName":"org-66a4b275003d1b495212b5aa","type":"file","uploadedAt":"2026-10-15T09:20:00.000Z"}],"metadata":{},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"taskId is not a valid ID, no file was sent, or the file is over 25 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator, its assignees and contributors, editors or owners of its space can attach files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/comments/participants":{"post":{"tags":["Tasks"],"summary":"Add someone to a task's comment chat","description":"Adds a person to the task's comment chat in Kazee Chat. Only the task's creator or an editor or owner of its space can do it (not in an archived space), and the chat must exist already. Where comment chats follow the task's people automatically, it only confirms the task's creator, assignees and space members, and refuses anyone else.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"addTaskCommentParticipant","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person to add","examples":["66f1b2c3d4e5f60718293a5c"]}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"taskId or userId is not a valid ID, or the task has no comment chat yet (getTaskCommentChat creates it)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator or an editor or owner of its space (while the space is not archived) can add people. Can also mean you signed in with a Kazee sign-in token, which Kazee Chat cannot take yet (sign in with your password)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Where the chat follows the task's people: this person is not the task's creator, an assignee or a member of its space, so assign them or add them to the space instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/follow":{"post":{"tags":["Tasks"],"summary":"Follow a task","description":"Follows a task for you, so you are notified of new comments on it and of status changes made with updateTaskStatus. Open to the task's creator, its assignees and anyone who can see its space. Following a task you already follow changes nothing.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"followTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"following":{"type":"boolean","description":"Always true: you now follow the task"}}},"example":{"success":true,"following":true}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the task's creator, its assignees and people who can see its space (its members, or anyone if it is public) can follow it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No task with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/{taskId}/unfollow":{"post":{"tags":["Tasks"],"summary":"Unfollow a task","description":"Stops you following a task, so you are no longer notified of its comments and status changes. It does not look the task up, and succeeds even if you were not following it. If following was your only way into the task, you can no longer open it.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"unfollowTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the task","example":"6ad0a044d5c26de56de949a8"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"following":{"type":"boolean","description":"Always false: you no longer follow the task"}}},"example":{"success":true,"following":false}}}},"400":{"description":"taskId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/tasks/bulk":{"post":{"tags":["Tasks"],"summary":"Update many tasks at once","description":"Makes one change to up to 100 tasks at once: set the status or priority, assign or unassign a person, archive, or restore. Each task is checked on its own and lands in updated or failed: archive needs an organisation admin (the Admin or SuperAdmin role), as archiveTask does, restore needs its creator or a space editor or higher and a space that is not archived, assign its creator or a space contributor or higher (as addTaskAssignee), unassign its creator or the person taking themselves off (as removeTaskAssignee), and a status or priority change its creator, an assignee or a space contributor or higher. Archive and restore cover subtasks too. As with addTaskAssignee, a new assignee must be able to see the space of a space task, and starts following each task they are assigned to. Setting the status stamps or clears completedAt as updateTaskStatus does, but unlike the one-task calls, nobody is notified.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"updateManyTasks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"object","properties":{"type":{"type":"string","enum":["change_status","change_priority","assign","unassign","archive","unarchive"]},"value":{"type":"string","description":"A status, a priority or a person's ID, as type needs"}},"description":"The change, as { type, value } (a JSON object in a string also works). change_status takes a status as value, change_priority a priority, assign and unassign a person's ID; archive and unarchive take no value","examples":[{"type":"change_status","value":"completed"}]},"taskIds":{"type":"array","items":{"type":"string"},"description":"IDs of the tasks, 1 to 100 (a JSON array in a string also works)","examples":[["6ad0a044d5c26de56de949a8","6ad0a051d5c26de56de949b2","6ad0a061d5c26de56de949b9"]]}},"required":["operation","taskIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"string"},"description":"IDs of the tasks that were changed (assigning someone already assigned counts as changed)"},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"reason":{"type":"string","description":"Task not found (no such task, or archived; for unarchive, not archived), Permission denied, for assign User \"<their name>\" is not a member of this space, or for unarchive Tasks in an archived space cannot be restored."}}},"description":"Tasks that were left as they were, each with its ID and why"},"totalRequested":{"type":"integer","description":"How many IDs were sent"},"totalUpdated":{"type":"integer","description":"How many tasks were changed"}}},"example":{"updated":["6ad0a044d5c26de56de949a8","6ad0a051d5c26de56de949b2"],"failed":[{"id":"6ad0a061d5c26de56de949b9","reason":"Permission denied"}],"totalRequested":3,"totalUpdated":2}}}},"400":{"description":"taskIds or operation is not valid JSON, taskIds is empty, has more than 100 IDs or an ID that is not valid, or the operation type or its value is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"For assign: no person with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/spaces/{spaceId}/tasks/reorder":{"post":{"tags":["Tasks"],"summary":"Reorder tasks in a space","description":"Sets the order of tasks in a space: each task's orderIndex becomes its position in taskIds, counting from 0. IDs of tasks that are not in this space are skipped. You need to be a member of the space with the contributor role or higher.\n\n**Permission:** `spaces.tasks.update` (Update tasks).","operationId":"reorderTasks","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"taskIds":{"type":"array","items":{"type":"string"},"description":"IDs of the space's tasks in their new order (a JSON array in a string also works)","examples":[["6ad0a044d5c26de56de949a8","6ad0a061d5c26de56de949b9"]]}},"required":["taskIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"spaceId is not a valid ID, taskIds is not a list, or the new order could not be saved (for example an ID in taskIds is not valid)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the space with the contributor role or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.tasks.update"]}],"x-required-scopes":["spaces.tasks.update"]}},"/spaces/{spaceId}/pipelines/from-blueprint":{"post":{"tags":["Pipelines"],"summary":"Create a pipeline from a blueprint","description":"Creates a whole pipeline (stages, transitions, automations, custom fields, sections and settings) from one blueprint, after checking that it holds together. Answers with status 201. Needs the editor or owner role in the space; people viewing the space get the new pipeline live. getPipelineSchema lists what a blueprint can contain.\n\n**Permission:** `spaces.pipelines.create` (Create pipelines).","operationId":"createPipelineFromBlueprint","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blueprint":{"type":"object","description":"The whole pipeline, shaped like exportPipelineBlueprint's blueprint. name and at least one stage (each with id, name, color and a numeric orderNum) are required; transitions, automations, fieldDefinitions, fieldSections, config and templateId are optional. IDs must be unique, every stage, field and section it refers to must be in it (a transition's requiredFieldIds may also name _dueDate, _startDate and _priority), and action types, operators and trigger events must be ones getPipelineSchema lists. A JSON object in a string also works","examples":[{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","config":{"to":"creator","message":"{{record.title}} was approved"}},{"id":"approve-webhook","actionType":"webhook","config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note"},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","config":{"to":"assignees","message":"{{record.title}} is paid"}}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty"}],"requiredFieldIds":["payment-ref"]}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty"}],"actions":[{"id":"assign-payer","actionType":"assign","config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]}}]}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","fieldType":"text","sectionId":"invoice","isRequired":true,"placeholder":"Who sent the invoice","showOnCard":true},{"id":"amount","name":"amount","label":"Amount","fieldType":"currency","sectionId":"invoice","isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0}},{"id":"category","name":"category","label":"Category","fieldType":"select","sectionId":"invoice","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"defaultValue":"services","orderNum":2},{"id":"po-number","name":"poNumber","label":"PO number","fieldType":"text","sectionId":"invoice","placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","fieldType":"attachment","sectionId":"invoice","colSpan":6,"orderNum":4},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","fieldType":"text","sectionId":"payment","placeholder":"Bank reference","orderNum":5}],"fieldSections":[{"id":"invoice","name":"Invoice"},{"id":"payment","name":"Payment","orderNum":1}],"config":{"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}]}}]}},"required":["blueprint"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"}}},"description":"Its stages (the board columns); sort by orderNum for board order. Keys some items also have: positionX (where the stage sits across the workflow editor; absent until positions are saved); positionY (where the stage sits down the workflow editor; absent until positions are saved)"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The new pipeline"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e70"},{"path":"priority","label":"Priority","type":"string","options":[{"value":"none","label":"None","_id":"6ad1c7a2f4b2e81d9c7a5e72"},{"value":"low","label":"Low","_id":"6ad1c7a2f4b2e81d9c7a5e73"},{"value":"medium","label":"Medium","_id":"6ad1c7a2f4b2e81d9c7a5e74"},{"value":"high","label":"High","_id":"6ad1c7a2f4b2e81d9c7a5e75"},{"value":"critical","label":"Critical","_id":"6ad1c7a2f4b2e81d9c7a5e76"}],"_id":"6ad1c7a2f4b2e81d9c7a5e71"},{"path":"stageName","label":"Stage","type":"string","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e77"},{"path":"supplier","label":"Supplier","type":"string","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e78"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c7a2f4b2e81d9c7a5e79"}]},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:00:00.000Z","updatedAt":"2026-10-15T09:00:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"spaceId is not a valid ID; or the blueprint does not hold together (the reply lists each problem in validationErrors), is not valid JSON, or fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.create"]}],"x-required-scopes":["spaces.pipelines.create"]}},"/pipelines/{pipelineId}/stages":{"post":{"tags":["Pipelines"],"summary":"Add a stage to a pipeline","description":"Adds a stage as the last column of a pipeline's board. Needs the editor or owner role in the pipeline's space. The ID is yours to choose; one the pipeline already has answers 409.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"addPipelineStage","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"Column colour as a hex code; defaults to grey (#6b7280)","examples":["#f59e0b"]},"id":{"type":"string","description":"ID for the stage, e.g. on-hold; records, transitions and settings refer to it","examples":["on-hold"]},"name":{"type":"string","description":"Stage name, shown as the column title","examples":["On hold"]}},"required":["id","name"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new stage at the end"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120},{"id":"on-hold","name":"On hold","color":"#f59e0b","orderNum":3,"isDefault":false}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or the stage fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has a stage with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/stages/reorder":{"post":{"tags":["Pipelines"],"summary":"Reorder a pipeline's stages","description":"Sets the board order of a pipeline's stages: each listed stage gets its place in the list as its orderNum. IDs that match no stage are skipped, and stages you leave out keep their orderNum. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"reorderPipelineStages","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stageIds":{"type":"array","items":{"type":"string"},"description":"Stage IDs in the new order. A JSON array in a string also works","examples":[["received","approved","paid"]]}},"required":["stageIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new stage order"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or stageIds is not valid JSON or not a list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/stages/positions":{"post":{"tags":["Pipelines"],"summary":"Save stage positions in the editor","description":"Saves where stages sit in the workflow editor. Stages you leave out, and IDs that match no stage, are left alone. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineStagePositions","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"positions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"positionX":{"type":"number"},"positionY":{"type":"number"}}},"description":"One { id, positionX, positionY } per stage to place. A JSON array in a string also works","examples":[[{"id":"received","positionX":80,"positionY":120},{"id":"approved","positionX":360,"positionY":120}]]}},"required":["positions"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new positions"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or positions is not valid JSON or not a list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/transitions":{"post":{"tags":["Pipelines"],"summary":"Add a transition to a pipeline","description":"Adds a move between two stages, with the checks it makes and the actions it runs; it starts active. Needs the editor or owner role in the pipeline's space. An ID the pipeline already has answers 409, and every stage it names (fromStageId, toStageId and, when global, fromStageIds) must be one of the pipeline's.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"addPipelineTransition","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"},"description":"What runs after the move, each { id, actionType, isActive, config, orderNum }; getPipelineSchema lists the action types and their config keys. A JSON array in a string also works","examples":[[{"id":"reopen-notify","actionType":"notify","config":{"to":"assignees","message":"{{record.title}} was reopened"}}]]},"color":{"type":"string","description":"Button colour as a hex code; defaults to blue (#3b82f6)","examples":["#ef4444"]},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing; defaults to \"Please add a note for this transition\"","examples":["Say why it is being reopened"]},"conditions":{"type":"array","items":{"type":"object"},"description":"Checks that must pass before the move, each { id, fieldPath, fieldLabel, operator, value, logicOperator }, read left to right; or give each a groupId (and groupOperator) to AND within a group and OR between groups. Rows with no fieldPath are dropped, and a leading fieldValues. is taken off fieldPath. A JSON array in a string also works","examples":[[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty"}]]},"description":{"type":"string","description":"What the move is for","examples":["Send it back for another look."]},"fromStageId":{"type":"string","description":"ID of the stage a record must be in to use it","examples":["approved"]},"fromStageIds":{"type":"array","items":{"type":"string"},"description":"With isGlobal: the other stages it can be used from. A JSON array in a string also works","examples":[["paid"]]},"icon":{"type":"string","description":"Name of the icon on the button","examples":["rotate-ccw"]},"id":{"type":"string","description":"ID for the transition, e.g. reopen","examples":["reopen"]},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds; the text \"true\" also works","examples":[false]},"name":{"type":"string","description":"Name of the move, shown on its button","examples":["Reopen"]},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move; the text \"true\" also works","examples":[true]},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move. A JSON array in a string also works","examples":[["supplier"]]},"toStageId":{"type":"string","description":"ID of the stage it moves the record to","examples":["received"]}},"required":["fromStageId","id","name","toStageId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new transition"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, a stage it names is not in the pipeline, a list input is not valid JSON, or the transition fails the model's checks (e.g. a condition with an unknown operator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has a transition with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/field-definitions":{"post":{"tags":["Pipelines"],"summary":"Add a custom field to a pipeline","description":"Adds a custom field to a pipeline's records, last in the form unless it has an orderNum. Needs the editor or owner role in the pipeline's space. An ID the pipeline already has answers 409.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"addPipelineFieldDefinition","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldDefinition":{"type":"object","description":"The field, shaped like the reply's fieldDefinitions items: id, name, label and fieldType are required. A JSON object in a string also works","examples":[{"id":"payment-terms","name":"paymentTerms","label":"Payment terms","fieldType":"select","sectionId":"payment","options":[{"value":"30","label":"30 days"},{"value":"60","label":"60 days"}]}]}},"required":["fieldDefinition"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new field"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, fieldDefinition is not valid JSON, or the field fails the model's checks (e.g. no label, an unknown fieldType)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has a field with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/field-definitions/reorder":{"post":{"tags":["Pipelines"],"summary":"Reorder a pipeline's custom fields","description":"Sets the form order of a pipeline's custom fields: each listed field gets its place in the list as its orderNum. IDs that match no field are skipped, and fields you leave out keep their orderNum. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"reorderPipelineFieldDefinitions","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldIds":{"type":"array","items":{"type":"string"},"description":"Field IDs in the new order. A JSON array in a string also works","examples":[["supplier","amount","category","po-number","invoice-file","payment-ref"]]}},"required":["fieldIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new field order"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, or fieldIds is not valid JSON or not a list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/field-sections":{"post":{"tags":["Pipelines"],"summary":"Replace a pipeline's field sections","description":"Replaces a pipeline's whole list of field sections. Needs the editor or owner role in the pipeline's space.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"updatePipelineFieldSections","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orderNum":{"type":"integer"}}},"description":"The sections in full, each { id, name, orderNum }; this list replaces the old one. A JSON array in a string also works","examples":[[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}]]}},"required":["fieldSections"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline after the change"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, fieldSections is not valid JSON, or a section fails the model's checks (e.g. no id or name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/records/bulk":{"post":{"tags":["Pipelines"],"summary":"Update many records at once","description":"Sets the priority, assignees or tags of several records in one go, or archives or restores them. Needs the contributor role or higher in the pipeline's space; archiving or restoring (isArchived) needs the editor or owner role, as archivePipelineRecord does. Records of other pipelines are skipped. Values are checked against the record model (as single updates are; custom fields are not involved), and no live updates, activity or automations follow.\n\n**Permission:** `spaces.pipelineRecords.update` (Update pipeline records).","operationId":"updateManyPipelineRecords","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recordIds":{"type":"array","items":{"type":"string"},"description":"IDs of the records. A JSON array in a string also works","examples":[["6ad1c4b2f4b2e81d9c7a5e17","6ad1c4c9f4b2e81d9c7a5e2b"]]},"updates":{"type":"object","properties":{"priority":{"type":"string","enum":["none","low","medium","high","critical"]},"assignees":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"isArchived":{"type":"boolean"}},"description":"What to set: priority, assignees (user IDs, replacing the old ones), tags (replacing the old ones), isArchived (true archives, false brings back). Keys you leave out, or give as empty text, stay as they are; other keys are ignored. A JSON object in a string also works","examples":[{"priority":"high","tags":["connectivity","urgent"]}]}},"required":["recordIds","updates"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"updatedCount":{"type":"integer","description":"How many records changed; records that already had these values are not counted"}}},"example":{"success":true,"updatedCount":2}}}},"400":{"description":"pipelineId is not a valid ID, recordIds or updates is not valid JSON, or a value fails the record model's checks (e.g. an unknown priority); nothing is changed then","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the contributor role or higher in the pipeline's space (editor or owner to archive or bring back records), and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.update"]}],"x-required-scopes":["spaces.pipelineRecords.update"]}},"/pipelines/{pipelineId}/records/{recordId}/transition":{"post":{"tags":["Pipelines"],"summary":"Move a record through a transition","description":"Moves a record along one of the pipeline's transitions to its next stage. Needs the contributor role or higher in the pipeline's space. It first checks the transition's conditions against the record as it is, then its required fields (fieldValues sent here count) and its note. Then it saves the move in transitionHistory, runs the transition's actions before answering (an action that fails does not undo the move), and posts the note as a comment on the record. It shows in the space's activity, people viewing the pipeline see the card move, and stage_exited and stage_entered automations run in the background.\n\n**Permission:** `spaces.pipelineRecords.update` (Update pipeline records).","operationId":"movePipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldValues":{"type":"object","description":"Values to save with the move: custom field ID -> value, plus _dueDate, _startDate and _priority for the record's own due date, start date and priority (empty ones are skipped). Custom values are merged into the record's and checked as in addPipelineRecord. A JSON object in a string also works","examples":[{"amount":184500}]},"notes":{"type":"string","description":"Note for the move, kept in transitionHistory and posted as a comment on the record. Needed when the transition has requireComment","examples":["Matches PO-2291; approved by the finance lead."]},"transitionId":{"type":"string","description":"ID of the transition","examples":["approve"]}},"required":["transitionId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"record":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"Record title"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}}},"description":"People assigned to it: id, firstName, lastName, email"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","items":{"type":"object","properties":{"transitionId":{"type":"string","description":"ID of the transition"},"transitionName":{"type":"string","description":"Its name at the time"},"fromStageId":{"type":"string","description":"Stage it left"},"fromStageName":{"type":"string","description":"Name of that stage"},"toStageId":{"type":"string","description":"Stage it entered"},"toStageName":{"type":"string","description":"Name of that stage"},"fieldValues":{"type":"object","properties":{"amount":{"type":"integer"}},"description":"Custom field values sent with the move"},"notes":{"type":"string","description":"Note given with the move"},"executedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who moved it: id, firstName, lastName, email"},"executedAt":{"type":"string","format":"date-time","description":"When"}}},"description":"Every transition it went through, oldest first"},"checklist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"isCompleted":{"type":"boolean"},"completedBy":{"type":"string"},"completedAt":{"type":"string","format":"date-time"},"orderNum":{"type":"integer"}}},"description":"Checklist items: id, text, isCompleted, completedBy (user ID), completedAt, orderNum"},"externalRef":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"description":"Where the record came from in another system: type and id"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who added it: id, firstName, lastName, email"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}},"description":"The record after the move, with people looked up"}}},"example":{"record":{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-14T11:05:00.000Z","title":"Safaricom Business, October bandwidth","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":[{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@kazee.africa","id":"66f1b2c3d4e5f60718293a5c"}],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[{"transitionId":"approve","transitionName":"Approve","fromStageId":"received","fromStageName":"Received","toStageId":"approved","toStageName":"Approved","fieldValues":{"amount":184500},"notes":"Matches PO-2291; approved by the finance lead.","executedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"executedAt":"2026-10-14T11:05:00.000Z"}],"checklist":[{"id":"match-po","text":"Match against the purchase order","isCompleted":true,"completedBy":"66f1b2c3d4e5f60718293a4b","completedAt":"2026-10-14T10:58:00.000Z","orderNum":0}],"externalRef":{"type":"books_bill","id":"BILL-00412"},"linkedItems":[],"createdBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@kazee.africa","id":"66f1b2c3d4e5f60718293a4b"},"orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-13T08:12:00.000Z","updatedAt":"2026-10-14T11:05:02.000Z","id":"6ad1c4b2f4b2e81d9c7a5e17"}}}}},"400":{"description":"pipelineId or recordId is not a valid ID, the transition is turned off (isActive false), the record is not in the transition's from stage (or one of its fromStageIds when global), a custom field value fails its checks, or fieldValues is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the contributor role or higher in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), no record with that ID in it (or it is archived), or no transition with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The move is blocked: a condition failed (\"Transition blocked: Condition not met for ...\"), required fields are empty (\"Required fields missing: ...\"), or a note is required and notes is empty (the error is the commentPrompt, and the reply also has requireComment: true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.update"]}],"x-required-scopes":["spaces.pipelineRecords.update"]}},"/pipelines/{pipelineId}/records/{recordId}/duplicate":{"post":{"tags":["Pipelines"],"summary":"Duplicate a record","description":"Copies a record within its pipeline and answers with status 201. The copy has the same description, assignees, priority, dates, tags, custom field values and card display, and (Copy) after the title; its history, checklist and external reference are not copied. Needs the contributor role or higher in the pipeline's space. People viewing the pipeline see the copy appear; no automations run for it. Archived records can be copied too.\n\n**Permission:** `spaces.pipelineRecords.create` (Add pipeline records).","operationId":"duplicatePipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"targetStageId":{"type":"string","description":"Stage for the copy, one of the pipeline's stages; defaults to the original's stage","examples":["received"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"record":{"type":"object","properties":{"pipelineId":{"type":"string","description":"ID of the pipeline it is in"},"spaceId":{"type":"string","description":"ID of the pipeline's space"},"stageId":{"type":"string","description":"ID of the stage it is in; absent when it has none"},"stageName":{"type":"string","description":"Name of that stage when the record entered it"},"stageEnteredAt":{"type":"string","format":"date-time","description":"When it entered its current stage"},"title":{"type":"string","description":"The original's title with (Copy) added"},"description":{"type":"string","description":"Longer notes on the record"},"assignees":{"type":"array","items":{"type":"string"},"description":"IDs of the people assigned, copied from the original"},"priority":{"type":"string","description":"none, low, medium, high or critical"},"dueDate":{"type":"string","format":"date-time","description":"When it is due"},"startDate":{"type":"string","format":"date-time","description":"When work starts"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on the record"},"fieldValues":{"type":"object","properties":{"supplier":{"type":"string"},"amount":{"type":"integer"},"category":{"type":"string"},"invoice-file":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"minioKey":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"}}}}},"description":"Custom field values, keyed by field ID. An attachment field holds a list of files: name, minioKey (pass it to getPipelineRecordAttachmentUrl), size in bytes, mimeType"},"displaySubtitle":{"type":"string","description":"Text shown under the title on its card"},"displayAvatar":{"type":"string","description":"Address of a picture shown on its card"},"displayBadge":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"color":{"type":"string"}},"description":"Badge on its card: label, value (shown instead of label when set) and color"},"transitionHistory":{"type":"array","description":"Empty: the copy starts with no history"},"checklist":{"type":"array","description":"Empty: the checklist is not copied"},"linkedItems":{"type":"array","description":"Linked tasks, pages or records; no call fills this yet, so it is empty"},"createdBy":{"type":"string","description":"ID of who made the copy (you)"},"orderIndex":{"type":"integer","description":"Sort position; lower comes first in record lists"},"attachments":{"type":"array","description":"Files attached to the record itself; no call adds any yet (files live in attachment fields)"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was added"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Record ID"}},"description":"The copy"}}},"example":{"record":{"pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stageId":"approved","stageName":"Approved","stageEnteredAt":"2026-10-15T09:30:00.000Z","title":"Safaricom Business, October bandwidth (Copy)","description":"100 Mbps dedicated link for the Westlands office, October.","assignees":["66f1b2c3d4e5f60718293a5c"],"priority":"high","dueDate":"2026-10-31T09:00:00.000Z","startDate":"2026-10-01T06:00:00.000Z","tags":["connectivity","monthly"],"fieldValues":{"supplier":"Safaricom Business","amount":184500,"category":"connectivity","invoice-file":[{"name":"INV-88214.pdf","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/media/field-attachment/9d4b2f6e-3a1c-4e8b-b7d5-0f2a6c9e1b37-INV-88214.pdf","size":201728,"mimeType":"application/pdf"}]},"displaySubtitle":"KES 184,500","displayAvatar":"https://example.com/logos/safaricom-business.png","displayBadge":{"label":"Due","value":"31 Oct","color":"#f59e0b"},"transitionHistory":[],"checklist":[],"linkedItems":[],"createdBy":"66f1b2c3d4e5f60718293a4b","orderIndex":0,"attachments":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:30:00.000Z","updatedAt":"2026-10-15T09:30:00.000Z","id":"6ad1c5d3f4b2e81d9c7a5e40"}}}}},"400":{"description":"pipelineId or recordId is not a valid ID, targetStageId is not one of the pipeline's stages, or the copy fails the model's checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the contributor role or higher in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.create"]}],"x-required-scopes":["spaces.pipelineRecords.create"]}},"/pipelines/{pipelineId}/records/{recordId}/follow":{"post":{"tags":["Pipelines"],"summary":"Follow a record","description":"Follows a record for you, so notify actions sent to the record's followers reach you. Open to the space's members, and to anyone when the space is public. Following a record you already follow changes nothing.\n\n**Permission:** `spaces.pipelineRecords.update` (Update pipeline records).","operationId":"followPipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"pipelineId or recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), or no record with that ID in it (or the record is archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.update"]}],"x-required-scopes":["spaces.pipelineRecords.update"]}},"/pipelines/{pipelineId}/records/{recordId}/unfollow":{"post":{"tags":["Pipelines"],"summary":"Unfollow a record","description":"Stops you following a record. It does not look the pipeline or record up, and succeeds even if you were not following it.\n\n**Permission:** `spaces.pipelineRecords.update` (Update pipeline records).","operationId":"unfollowPipelineRecord","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline; not checked","example":"6ad1c3a0f4b2e81d9c7a5e01"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record","example":"6ad1c4b2f4b2e81d9c7a5e17"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"recordId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelineRecords.update"]}],"x-required-scopes":["spaces.pipelineRecords.update"]}},"/pipelines/{pipelineId}/test-code":{"post":{"tags":["Pipelines"],"summary":"Test custom code for a pipeline","description":"Compiles custom code and runs it in the sandbox (at most 5 seconds and 64 MB) against a real record or sample data, and reports what it logged and what it asked for. By default nothing is sent or saved; with applyEffects the queued notifications, emails, chat messages, texts and calls really go out, and field writes are saved to recordId's record. Needs the editor or owner role in the pipeline's space, as saving code into a transition or automation does.\n\n**Permission:** `spaces.pipelines.admin` (Manage pipeline automations).","operationId":"testPipelineCode","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"applyEffects":{"type":"boolean","description":"true (or the text true) really carries out what the code queued; field writes are saved only to recordId's record","examples":[false]},"recordId":{"type":"string","description":"ID of a record in this pipeline (not archived) to run against; without it, or when it matches none, ctx.record is sample data","examples":["6ad1c4b2f4b2e81d9c7a5e17"]},"sourceCode":{"type":"string","description":"TypeScript or JavaScript to run. It can read ctx (record, pipeline, transition, user) and call the sandbox functions getPipelineSchema lists (setField, notify, log...)","examples":["const amount = Number(ctx.record.fieldValues.amount);\nlog(`Amount is ${amount}`);\nif (amount > 100000) {\n  await notify(ctx.user.id, `Large invoice: ${ctx.record.title}`);\n  setField(\"paymentRef\", \"HOLD\");\n}"]},"transitionId":{"type":"string","description":"ID of a transition whose details go in ctx.transition; otherwise sample details","examples":["approve"]}},"required":["sourceCode"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the code compiled and ran without throwing"},"compiledCode":{"type":"string","description":"The code as it ran, wrapped in an async function; absent when it did not compile"},"compilationErrors":{"type":"array","description":"Why it did not compile; empty when it did"},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the code wrote with log() (at most 50), plus notes on field writes when applyEffects saved them"},"sideEffects":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Kind of side effect"},"userId":{"type":"string"},"message":{"type":"string"},"recordId":{"type":"string"},"recordTitle":{"type":"string"},"pipelineId":{"type":"string"},"pipelineName":{"type":"string"}}},"description":"What the code asked for, in order: type (setField, setFieldOn, notify, sendEmail, sendChatMessage, sendSms or initiateCall) with its details"},"duration":{"type":"integer","description":"How long it ran, in milliseconds"},"applied":{"type":"boolean","description":"Whether the side effects were really carried out (applyEffects true, the code worked and it asked for any)"}}},"example":{"success":true,"compiledCode":"(async () => {\nconst amount = Number(ctx.record.fieldValues.amount);\nlog(`Amount is ${amount}`);\nif (amount > 100000) {\n  await notify(ctx.user.id, `Large invoice: ${ctx.record.title}`);\n  setField(\"paymentRef\", \"HOLD\");\n}\n\n})();","compilationErrors":[],"logs":["Amount is 184500"],"sideEffects":[{"type":"notify","userId":"66f1b2c3d4e5f60718293a4b","message":"Large invoice: Safaricom Business, October bandwidth","recordId":"6ad1c4b2f4b2e81d9c7a5e17","recordTitle":"Safaricom Business, October bandwidth","pipelineId":"6ad1c3a0f4b2e81d9c7a5e01","pipelineName":"Supplier invoices"},{"type":"setField","field":"paymentRef","value":"HOLD"}],"duration":37,"applied":false}}}},"400":{"description":"pipelineId or recordId is not a valid ID, or the code did not compile, timed out or threw: then the reply still carries success false, error, compilationErrors, logs and sideEffects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The sandbox itself failed (not the code): the reply has success false and error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.pipelines.admin"]}],"x-required-scopes":["spaces.pipelines.admin"]}},"/pipelines/{pipelineId}/automations":{"post":{"tags":["Pipelines"],"summary":"Add an automation to a pipeline","description":"Adds an automation: actions that run in the background when something happens to one of the pipeline's records and its conditions pass. Answers with status 201. Needs the editor or owner role in the pipeline's space; people viewing the pipeline get the change live. An ID the pipeline already has answers 409.\n\n**Permission:** `spaces.pipelines.admin` (Manage pipeline automations).","operationId":"addPipelineAutomation","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c3a0f4b2e81d9c7a5e01"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"type":"object","description":"The automation, shaped like the reply's automations items: id, name and trigger.event are required; isActive defaults to true, orderNum to the end of the list. Condition rows with no fieldPath are dropped. A JSON object in a string also works","examples":[{"id":"flag-large-invoice","name":"Flag large invoices","trigger":{"event":"record_created"},"conditions":[{"id":"cond-large","fieldPath":"amount","fieldLabel":"Amount","operator":"gte","value":500000}],"actions":[{"id":"flag-large-notify","actionType":"notify","config":{"to":["66f1b2c3d4e5f60718293a5c"],"message":"Large invoice: {{record.title}}"}}]}]}},"required":["automation"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Pipeline name"},"description":{"type":"string","description":"What the pipeline is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage ID, chosen when the stage was added, e.g. received"},"name":{"type":"string","description":"Stage name, shown as the board column title"},"color":{"type":"string","description":"Column colour as a hex code"},"orderNum":{"type":"integer","description":"Position on the board; lower comes first"},"isDefault":{"type":"boolean","description":"Whether new records start here when no stage is given and config.defaultStageId is not set"},"positionX":{"type":"integer","description":"Where the stage sits across the workflow editor; absent until positions are saved"},"positionY":{"type":"integer","description":"Where the stage sits down the workflow editor; absent until positions are saved"}}},"description":"Its stages (the board columns); sort by orderNum for board order"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Transition ID, chosen when it was added"},"name":{"type":"string","description":"Name of the move, shown on its button, e.g. Approve"},"description":{"type":"string","description":"What the move is for"},"color":{"type":"string","description":"Button colour as a hex code"},"icon":{"type":"string","description":"Name of the icon on the button"},"fromStageId":{"type":"string","description":"Stage a record must be in to use it"},"toStageId":{"type":"string","description":"Stage it moves the record to"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs after the move"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"value":{"type":"integer","description":"Value to compare with (a list for in and notIn); absent for operators that need none"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass before the move"},"requiredFieldIds":{"type":"array","items":{"type":"string"},"description":"Custom field IDs (or _dueDate, _startDate, _priority) that must have a value before the move; they can be filled in with the move itself"},"requireComment":{"type":"boolean","description":"Whether a note must be given with the move"},"commentPrompt":{"type":"string","description":"Prompt for that note, also the error text when it is missing"},"isGlobal":{"type":"boolean","description":"Whether it can also be used from each stage in fromStageIds"},"fromStageIds":{"type":"array","description":"With isGlobal: the other stages it can be used from"},"isActive":{"type":"boolean","description":"Whether it can be used: inactive ones are left out of stagesWithTransitions, and movePipelineRecord refuses them"}}},"description":"Allowed moves between stages, with what each one checks and runs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon on the button"},"color":{"type":"string","description":"Button colour as a hex code"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"Stages the button shows in; empty means every stage"},"requiredRole":{"type":"string","description":"admin shows it to admins only; empty means everyone who can use the pipeline"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether to ask before running (enabled) and what to ask (prompt)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"template":{"type":"string"}}},"orderNum":{"type":"integer"}}},"description":"What runs when it is pressed; the record does not move"},"conditions":{"type":"array","description":"Checks on the record that must pass"},"requireComment":{"type":"boolean","description":"Whether a note must be given"},"commentPrompt":{"type":"string","description":"Prompt for that note"},"isActive":{"type":"boolean","description":"Whether the button is on"},"orderNum":{"type":"integer","description":"Order among the buttons; lower comes first"}}},"description":"Buttons that run actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID, chosen when it was added"},"name":{"type":"string","description":"Automation name"},"description":{"type":"string","description":"What it is for"},"isActive":{"type":"boolean","description":"Whether it runs"},"trigger":{"type":"object","properties":{"event":{"type":"string","description":"record_created, record_updated, field_changed, stage_entered, stage_exited, assignee_changed, priority_changed, due_date_passed or record_archived"},"config":{"type":"object","properties":{"stageId":{"type":"string"}},"description":"Narrows the event, e.g. { stageId } for stage_entered and stage_exited, { fieldId } for field_changed; absent when empty"}},"description":"When it runs"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"What is checked: a custom field ID, or one of the record's own fields (title, priority, dueDate, startDate, stageId, stageName, assignees, tags; _priority, _dueDate and _startDate also work)"},"fieldLabel":{"type":"string","description":"Name used in the error when the condition fails"},"operator":{"type":"string","description":"eq, neq, gt, gte, lt, lte, contains, notContains, startsWith, endsWith, exists, notExists, in, notIn, isEmpty or isNotEmpty"},"logicOperator":{"type":"string","description":"AND or OR: how this condition joins the next one, read left to right. Ignored once any condition has a groupId: then conditions with the same groupId must all pass, and groups join by the first member's groupOperator (OR when unset)"}}},"description":"Checks on the record that must pass for the actions to run. Keys some items also have: value (value to compare with (a list for in and notIn); absent for operators that need none)"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}},"description":"Settings for that action type; getPipelineSchema lists the keys of each type"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What runs"},"orderNum":{"type":"integer","description":"Order among the pipeline's automations; lower comes first"}}},"description":"Rules that run actions when something happens to a record"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Field ID; a record keeps its value for this field under this key in fieldValues"},"name":{"type":"string","description":"camelCase name custom code uses for the field"},"label":{"type":"string","description":"Label people see"},"sectionId":{"type":"string","description":"ID of the field section it is shown in"},"colSpan":{"type":"integer","description":"Width in the record form, in grid columns (3 by default)"},"fieldType":{"type":"string","description":"text, textarea, number, date, datetime, select, multiselect, checkbox, email, phone, url, currency, user, multiuser, rating, color or attachment"},"options":{"type":"array","description":"For select and multiselect: the allowed values, each with a label and colour"},"isRequired":{"type":"boolean","description":"Whether a value sent for it may be empty"},"placeholder":{"type":"string","description":"Hint shown in the empty input"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"},"showOnCard":{"type":"boolean","description":"Whether the value shows on board cards"},"dependsOn":{"type":"object","properties":{"values":{"type":"array","description":"Values of that field that show this one (for a multiselect, any overlap). While hidden, a value for this field is dropped when the record is saved"},"requiredWhenVisible":{"type":"boolean","description":"Whether the field must be filled while it shows"}},"description":"Makes the field show only while another field has one of some values. It may also have: fieldId (ID of the field it depends on; absent when it depends on none)"}}},"description":"Custom fields the pipeline's records have. Keys some items also have: defaultValue (value the form starts with); description (help text for the field); currencyCode (for currency fields: the currency, e.g. KES); validation (limits checked when a value is saved: min and max for number, currency and rating (rating is 0 to 5 without them), pattern (a regular expression) for text, textarea, email, phone and url)"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Section ID; fields name it in sectionId"},"name":{"type":"string","description":"Section heading"},"orderNum":{"type":"integer","description":"Position in the form; lower comes first"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean","description":"Whether cards show assignee pictures"},"showBadges":{"type":"boolean","description":"Whether cards show their badge"},"columnMinWidth":{"type":"integer","description":"Narrowest a board column may be"},"columnMaxWidth":{"type":"integer","description":"Widest a board column may be"},"cardSubtitleField":{"type":"string","description":"ID of the custom field shown under the card title, if any"},"cardBadgeField":{"type":"string","description":"ID of the custom field shown as the card badge, if any"},"defaultStageId":{"type":"string","description":"Stage new records start in when none is given"},"requireTransitions":{"type":"boolean","description":"Whether records may move between stages only through transitions on the board"},"enableSLA":{"type":"boolean","description":"Whether stage time limits are on"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}},"description":"Time limits per stage: maxHours a record may stay, and warningHours before a warning"},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}},"description":"Totals on each column header, in this order: function (count, sum, avg, min or max) of the custom field fieldId, shown as title"},"conditionFields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"},"_id":{"type":"string"}}},"description":"Older list of fields conditions can use (path, label, type, options), kept for older screens"}},"description":"Board and card settings"},"roundRobinState":{"type":"object","properties":{"assign-payer":{"type":"integer"}},"description":"For round-robin assign actions: action ID -> position in its userPool of the last person assigned"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"IDs of the organisation's email accounts this pipeline may send from; empty means any of them"},"emailEnabled":{"type":"boolean","description":"false hides sending email from this pipeline's records"},"smsEnabled":{"type":"boolean","description":"false hides sending texts from this pipeline's records"},"callEnabled":{"type":"boolean","description":"false hides calling from this pipeline's records"},"isArchived":{"type":"boolean","description":"Whether it is archived; archived pipelines are hidden"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}},"description":"The pipeline with the new automation"}}},"example":{"pipeline":{"name":"Supplier invoices","description":"Bills from suppliers, from arrival to payment.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"received","name":"Received","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"approved","name":"Approved","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"paid","name":"Paid","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"approve","name":"Approve","description":"Finance lead checks the amount against the purchase order.","color":"#3b82f6","icon":"check-circle","fromStageId":"received","toStageId":"approved","actions":[{"id":"approve-notify","actionType":"notify","isActive":true,"config":{"to":"creator","message":"{{record.title}} was approved"},"orderNum":0},{"id":"approve-webhook","actionType":"webhook","isActive":true,"config":{"url":"https://books.example.com/hooks/bill-approved","method":"POST","includeFields":true},"orderNum":1}],"conditions":[{"id":"cond-amount","fieldPath":"amount","fieldLabel":"Amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["amount"],"requireComment":true,"commentPrompt":"Add the approval note","isGlobal":false,"fromStageIds":[],"isActive":true},{"id":"mark-paid","name":"Mark paid","description":"Payment has left the bank.","color":"#22c55e","icon":"banknote","fromStageId":"approved","toStageId":"paid","actions":[{"id":"paid-notify","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"{{record.title}} is paid"},"orderNum":0}],"conditions":[{"id":"cond-has-supplier","fieldPath":"supplier","fieldLabel":"Supplier","operator":"isNotEmpty","logicOperator":"AND"}],"requiredFieldIds":["payment-ref"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"request-credit-note","label":"Request credit note","description":"Email the supplier asking for a credit note.","icon":"mail","color":"#f59e0b","visibleInStages":["received"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Email the supplier now?"},"actions":[{"id":"credit-note-email","actionType":"email","isActive":true,"config":{"to":"assignees","subject":"Credit note for {{record.title}}","template":"Please ask the supplier for a credit note on {{record.title}}."},"orderNum":0}],"conditions":[],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"assign-payer-on-approval","name":"Assign a payer","description":"Give each approved invoice to the next person on the payables team.","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"approved"}},"conditions":[{"id":"cond-not-paid","fieldPath":"payment-ref","fieldLabel":"Payment reference","operator":"isEmpty","logicOperator":"AND"}],"actions":[{"id":"assign-payer","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"orderNum":0}],"fieldDefinitions":[{"id":"supplier","name":"supplier","label":"Supplier","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":true,"placeholder":"Who sent the invoice","orderNum":0,"showOnCard":true,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"amount","name":"amount","label":"Amount","sectionId":"invoice","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"orderNum":1,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"category","name":"category","label":"Category","sectionId":"invoice","colSpan":3,"fieldType":"select","options":[{"value":"connectivity","label":"Connectivity","color":"#3b82f6"},{"value":"equipment","label":"Equipment","color":"#a855f7"},{"value":"services","label":"Services","color":"#22c55e"}],"isRequired":false,"defaultValue":"services","orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"po-number","name":"poNumber","label":"PO number","sectionId":"invoice","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"PO-0000","description":"Purchase order the equipment was bought under","orderNum":3,"showOnCard":false,"validation":{"pattern":"^PO-\\d{4}$"},"dependsOn":{"fieldId":"category","values":["equipment"],"requiredWhenVisible":true}},{"id":"invoice-file","name":"invoiceFile","label":"Invoice file","sectionId":"invoice","colSpan":6,"fieldType":"attachment","options":[],"isRequired":false,"orderNum":4,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"payment-ref","name":"paymentRef","label":"Payment reference","sectionId":"payment","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"placeholder":"Bank reference","orderNum":5,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"invoice","name":"Invoice","orderNum":0},{"id":"payment","name":"Payment","orderNum":1}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"supplier","cardBadgeField":"amount","defaultStageId":"received","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"received","maxHours":48,"warningHours":24}],"stageRollups":[{"fieldId":"amount","function":"sum","title":"Total"}],"conditionFields":[{"path":"title","label":"Title","type":"string","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e03"},{"path":"amount","label":"Amount","type":"number","options":[],"_id":"6ad1c3a0f4b2e81d9c7a5e04"}]},"roundRobinState":{"assign-payer":1},"enabledEmailAccountIds":["3b7e9c2a-41d5-4f8e-9a6b-2c1d0e7f5a93"],"emailEnabled":true,"smsEnabled":false,"callEnabled":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-02T07:30:00.000Z","updatedAt":"2026-10-14T10:40:00.000Z","id":"6ad1c3a0f4b2e81d9c7a5e01"}}}}},"400":{"description":"pipelineId is not a valid ID, automation is not valid JSON or lacks id, name or trigger.event, or it fails the model's checks (e.g. an unknown event)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You need the editor or owner role in the pipeline's space, and the space must not be archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has an automation with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.admin"]}],"x-required-scopes":["spaces.pipelines.admin"]}},"/pipeline-agent/sessions/{sessionId}/messages":{"post":{"tags":["Pipelines"],"summary":"Send a message to Pipeline AI","description":"Sends your message to a Pipeline AI chat and answers at once with status 202. The reply streams as pipeline-agent:event messages in the live room pipeline-agent:<sessionId> (join it with room:join): message_start, text_delta, tool_call, tool_result, draft_updated, migration_plan_updated and message_end, ending with done or error. A reply takes at most 8 steps and about 60 seconds. Only the chat's owner may send, at most 20 messages a minute by default.\n\n**Permission:** `spaces.agents.update` (Send agent messages).","operationId":"sendPipelineAgentMessage","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the Pipeline AI chat","example":"6ad1c2e0f3a4b5c6d7e8f907"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Your message","examples":["Drop the Negotiation stage and move its deals to Quoted."]}},"required":["content"]}}}},"responses":{"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","description":"Always true: the assistant has started on its reply"}}},"example":{"accepted":true}}}},"400":{"description":"content is blank, or sessionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID; chats are removed 7 days after their last change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The assistant is still writing its last reply; a reply that has shown no sign of life for 10 minutes no longer counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"You went over the per-person limit, 20 messages a minute by default","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.update"]}],"x-required-scopes":["spaces.agents.update"]}},"/pipeline-agent/sessions/{sessionId}/cancel":{"post":{"tags":["Pipelines"],"summary":"Stop a Pipeline AI reply","description":"Stops the reply the assistant is writing in your chat, whichever server is writing it. It takes effect at the next step, after the text being written now, and the room then gets a done event with reason cancelled. Only the chat's owner may call it.\n\n**Permission:** `spaces.agents.update` (Send agent messages).","operationId":"cancelPipelineAgentTurn","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the Pipeline AI chat","example":"6ad1c2e0f3a4b5c6d7e8f907"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"boolean","description":"true when a reply was running and has been asked to stop; false when none was (a reply silent for 10 minutes counts as not running)"}}},"example":{"cancelled":true}}}},"400":{"description":"sessionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID; chats are removed 7 days after their last change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.update"]}],"x-required-scopes":["spaces.agents.update"]}},"/pipeline-agent/sessions/{sessionId}/apply":{"post":{"tags":["Pipelines"],"summary":"Apply a Pipeline AI draft","description":"Saves the chat's draft. In create mode it creates a new pipeline in the chat's space; in edit mode it replaces the pipeline's name, description, stages, transitions, automations, fields, sections and board settings with the draft, keeping its custom buttons and email settings. In edit mode, records on stages the draft removes are first moved or archived as the chat's migration plan says; if a removed stage the plan does not cover still has active records, nothing is changed and no record is moved. Needs a chat of your own and the editor role or higher in its space, which must not be archived; people watching the space see the pipeline change live.\n\n**Permission:** `spaces.agents.admin` (Apply agent blueprints).","operationId":"applyPipelineAgentDraft","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the Pipeline AI chat","example":"6ad1c2e0f3a4b5c6d7e8f907"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Name of the pipeline"},"description":{"type":"string","description":"What it is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"},"positionX":{"type":"integer"},"positionY":{"type":"integer"}}},"description":"Its stages (board columns): id, name, color, orderNum, isDefault, and positionX / positionY on the workflow map"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"fromStageId":{"type":"string"},"toStageId":{"type":"string"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}}},"orderNum":{"type":"integer"}}}},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fieldPath":{"type":"string"},"fieldLabel":{"type":"string"},"operator":{"type":"string"},"value":{"type":"integer"},"logicOperator":{"type":"string"}}}},"requiredFieldIds":{"type":"array","items":{"type":"string"}},"requireComment":{"type":"boolean"},"commentPrompt":{"type":"string"},"isGlobal":{"type":"boolean"},"fromStageIds":{"type":"array"},"isActive":{"type":"boolean"}}},"description":"Allowed moves between stages, each with the actions it runs and the conditions and fields it needs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID, as given when it was added"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon shown on the button"},"color":{"type":"string","description":"Button colour, as hex"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"IDs of the stages where the button shows and may run; empty means every stage"},"requiredRole":{"type":"string","description":"admin: only organisation admins may run it; empty: anyone who may run buttons"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the app asks for confirmation first"},"prompt":{"type":"string","description":"The question it asks"}},"description":"Whether the app asks before running it, and what it asks"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"fieldId":{"type":"string"},"useCurrentDate":{"type":"boolean"}},"description":"Settings for that kind of action, the same as on transitions"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What the button runs, in orderNum order; inactive actions are skipped"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"Record field it looks at: a custom field ID, or title, priority or stageName"},"fieldLabel":{"type":"string","description":"Name of that field as people see it"},"operator":{"type":"string","description":"How the field is compared, e.g. eq, gt, contains, isEmpty"},"value":{"type":"integer","description":"Value it is compared with"},"logicOperator":{"type":"string","description":"AND or OR: how it joins the condition before it"}}},"description":"Conditions saved with the button; running it through the API does not check them"},"requireComment":{"type":"boolean","description":"Whether running it needs a comment (notes)"},"commentPrompt":{"type":"string","description":"What the app asks for when a comment is needed"},"isActive":{"type":"boolean","description":"Whether the button can be run"},"orderNum":{"type":"integer","description":"Position among the pipeline's buttons; lower comes first"}}},"description":"Buttons that run a list of actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isActive":{"type":"boolean"},"trigger":{"type":"object","properties":{"event":{"type":"string"},"config":{"type":"object","properties":{"stageId":{"type":"string"}}}}},"conditions":{"type":"array"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}}},"orderNum":{"type":"integer"}}}},"orderNum":{"type":"integer"}}},"description":"Rules that run actions when something happens to a record (trigger.event, e.g. stage_entered)"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"sectionId":{"type":"string"},"colSpan":{"type":"integer"},"fieldType":{"type":"string"},"options":{"type":"array"},"isRequired":{"type":"boolean"},"placeholder":{"type":"string"},"description":{"type":"string"},"orderNum":{"type":"integer"},"showOnCard":{"type":"boolean"},"currencyCode":{"type":"string"},"validation":{"type":"object","properties":{"min":{"type":"integer"}}},"dependsOn":{"type":"object","properties":{"values":{"type":"array"},"requiredWhenVisible":{"type":"boolean"}}}}},"description":"Custom fields its records have"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orderNum":{"type":"integer"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean"},"showBadges":{"type":"boolean"},"columnMinWidth":{"type":"integer"},"columnMaxWidth":{"type":"integer"},"cardSubtitleField":{"type":"string"},"cardBadgeField":{"type":"string"},"defaultStageId":{"type":"string"},"requireTransitions":{"type":"boolean"},"enableSLA":{"type":"boolean"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}}},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}}},"conditionFields":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"}}}}},"description":"Board settings: card fields, default stage, whether moves must follow transitions, stage time limits (stageSLAs), column totals (stageRollups) and the fields conditions can use"},"roundRobinState":{"type":"object","properties":{"action-assign-owner":{"type":"integer"}},"description":"For round-robin assign actions: action ID to the position of the person assigned last"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts its records may send from; empty means any the organisation has"},"emailEnabled":{"type":"boolean","description":"Whether sending email is offered on its records"},"smsEnabled":{"type":"boolean","description":"Whether sending SMS is offered on its records"},"callEnabled":{"type":"boolean","description":"Whether calling is offered on its records"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}}}}},"example":{"pipeline":{"name":"Sales","description":"Deals from first contact to signed contract","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"lead","name":"Lead","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"quoted","name":"Quoted","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"won","name":"Won","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"lead-to-quoted","name":"Send quote","description":"The client has asked for a price","color":"#3b82f6","icon":"file-text","fromStageId":"lead","toStageId":"quoted","actions":[{"id":"action-assign-owner","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["dealAmount"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"send-quote","label":"Send quote","description":"Stamps the quote date and tells the assignees","icon":"send","color":"#3b82f6","visibleInStages":["quoted"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Send the quote to the client now?"},"actions":[{"id":"action-stamp-quote-date","actionType":"update_field","isActive":true,"config":{"fieldId":"quoteSentOn","useCurrentDate":true},"orderNum":0},{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"remind-stale-quote","name":"Remind on new quotes","description":"Tells the assignees when a deal reaches Quoted","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"quoted"}},"conditions":[],"actions":[{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"orderNum":0}],"fieldDefinitions":[{"id":"dealAmount","name":"dealAmount","label":"Deal amount","sectionId":"deal","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"placeholder":"0","description":"Contract value before tax","orderNum":0,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"quoteSentOn","name":"quoteSentOn","label":"Quote sent on","sectionId":"deal","colSpan":3,"fieldType":"date","options":[],"isRequired":false,"orderNum":1,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"contactName","name":"contactName","label":"Contact name","sectionId":"deal","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"deal","name":"Deal","orderNum":0}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"dealAmount","cardBadgeField":"quoteSentOn","defaultStageId":"lead","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"quoted","maxHours":72,"warningHours":48}],"stageRollups":[{"fieldId":"dealAmount","function":"sum","title":"Total value"}],"conditionFields":[{"_id":"6ad1c2e0f3a4b5c6d7e8f909","path":"dealAmount","label":"Deal amount","type":"number","options":[]}]},"roundRobinState":{"action-assign-owner":1},"enabledEmailAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"emailEnabled":true,"smsEnabled":true,"callEnabled":false,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-02T07:30:00.000Z","updatedAt":"2026-10-15T09:40:00.000Z","id":"6ad1c2e0f3a4b5c6d7e8f901"}}}}},"400":{"description":"sessionId is not a valid ID, the chat has no draft yet, the draft is not valid (validationErrors lists why), or it could not be saved, e.g. a stage it removes still has active records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else, or you are not an editor or owner of its space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID; chats are removed 7 days after their last change, or in edit mode its pipeline is not in the chat's space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.admin"]}],"x-required-scopes":["spaces.agents.admin"]}},"/strategy-agent/sessions/{sessionId}/messages":{"post":{"tags":["Strategies"],"summary":"Send the strategy assistant a message","description":"Sends your message to the strategy assistant and answers at once with status 202; the reply is worked out in the background. To follow it, join the Socket.IO room strategy-agent:<sessionId> (room:join, open only to the chat's owner) and read its strategy-agent:event events: message_start, text_delta, tool_call, tool_result, strategy_updated, message_end, then done (with a reason) or error. The assistant changes the strategy itself (vision, mission, desired outcome, SWOT items, pillars, objectives, key results, initiatives, milestones and phase) and stops after 8 rounds or 60 seconds. Only the chat's owner can send to it, and only while they have the editor role or higher in the strategy's space and it is not archived.\n\n**Permission:** `spaces.agents.update` (Send agent messages).","operationId":"sendStrategyAgentMessage","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the chat (session)","example":"6ad1c4b04f3b8a1d2c7e5f42"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Your message","examples":["Add a pillar for network reliability"]}},"required":["content"]}}}},"responses":{"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","description":"Always true: the message was taken and the reply is being worked out"}}},"example":{"accepted":true}}}},"400":{"description":"content is only spaces or not text, or sessionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else, or you are no longer a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID (chats are deleted 7 days after their last change)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The assistant is still working on your previous message; a reply that has shown no sign of life for 10 minutes no longer counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"Too many messages: by default more than 20 in one minute (the count starts again each minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.update"]}],"x-required-scopes":["spaces.agents.update"]}},"/strategy-agent/sessions/{sessionId}/cancel":{"post":{"tags":["Strategies"],"summary":"Stop the strategy assistant's reply","description":"Stops the reply the strategy assistant is working on in one of your chats, whichever server is working on it. The answer the AI is writing at that moment still finishes; the reply then stops before its next step and the stream ends with done, reason cancelled (or stop, if it had nothing left to do). Changes already made to the strategy stay. Answers cancelled: false when no reply was running.\n\n**Permission:** `spaces.agents.update` (Send agent messages).","operationId":"cancelStrategyAgentTurn","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the chat (session)","example":"6ad1c4b04f3b8a1d2c7e5f42"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"boolean","description":"true when a reply was running and has been asked to stop; false when none was (a reply silent for 10 minutes counts as not running)"}}},"example":{"cancelled":true}}}},"400":{"description":"sessionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The chat belongs to someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No chat with that ID (chats are deleted 7 days after their last change)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.agents.update"]}],"x-required-scopes":["spaces.agents.update"]}},"/strategies/{strategyId}/swot":{"post":{"tags":["Strategies"],"summary":"Add a SWOT item","description":"Adds a strength, weakness, opportunity or threat to a strategy's SWOT analysis, after the existing ones, and answers with status 201 and the whole strategy. You choose the item's ID, one no other SWOT item of the strategy has. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addSwotItem","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The statement","examples":["A rival prices business fibre 15% lower"]},"id":{"type":"string","description":"Your own ID for the item, unique within the strategy's SWOT items; later calls use it as itemId","examples":["1792141200456-p7m2c"]},"impact":{"type":"string","enum":["high","medium","low"],"description":"How much it matters. Defaults to medium","examples":["medium"]},"notes":{"type":"string","description":"Supporting detail","examples":["Seen in two lost tenders"]},"type":{"type":"string","enum":["strength","weakness","opportunity","threat"],"description":"Which SWOT box it goes in","examples":["threat"]}},"required":["content","id","type"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0},{"id":"1792141200456-p7m2c","type":"threat","content":"A rival prices business fibre 15% lower","impact":"medium","notes":"Seen in two lost tenders","orderNum":1}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The strategy already has a SWOT item with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/pillars":{"post":{"tags":["Strategies"],"summary":"Add a pillar","description":"Adds a pillar (a main theme that objectives are grouped under) to a strategy, after the existing ones, and answers with status 201 and the whole strategy. You choose the pillar's ID, one no other pillar of the strategy has. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addPillar","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"Colour as a hex code. Defaults to #6b7280 (grey)","examples":["#10b981"]},"description":{"type":"string","description":"What the pillar covers","examples":["Keep business links up"]},"id":{"type":"string","description":"Your own ID for the pillar, unique within the strategy's pillars; later calls use it as pillarId","examples":["1792141500567-h2j6d"]},"name":{"type":"string","description":"Name of the pillar","examples":["Network reliability"]}},"required":["id","name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0},{"id":"1792141500567-h2j6d","name":"Network reliability","description":"Keep business links up","color":"#10b981","orderNum":1}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The strategy already has a pillar with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/objectives":{"post":{"tags":["Strategies"],"summary":"Add an objective","description":"Adds an objective to a strategy, after the existing ones, with status not_started, progress 0 and no key results, and answers with status 201 and the whole strategy. You choose the objective's ID, one no other objective of the strategy has; the pillar is not checked to exist. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addObjective","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"Longer notes","examples":["Fewer companies leaving at contract renewal"]},"id":{"type":"string","description":"Your own ID for the objective, unique within the strategy's objectives; later calls use it as objectiveId","examples":["1792141800678-c8n1f"]},"pillarId":{"type":"string","description":"ID of the pillar to put it under; leave out for none","examples":["1788254100234-r5t8v"]},"title":{"type":"string","description":"What the objective is","examples":["Keep business customers longer"]}},"required":["id","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]},{"id":"1792141800678-c8n1f","pillarId":"1788254100234-r5t8v","title":"Keep business customers longer","description":"Fewer companies leaving at contract renewal","status":"not_started","progress":0,"orderNum":1,"keyResults":[]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The strategy already has an objective with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/objectives/{objectiveId}/key-results":{"post":{"tags":["Strategies"],"summary":"Add a key result","description":"Adds a key result (a number that shows the objective is met) to an objective, after its existing ones, and answers with status 201 and the whole strategy. It starts at its start value with status not_started; the objective's progress is not recalculated until a key result is updated. You choose the key result's ID, one no other key result of the objective has. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addKeyResult","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the objective","example":"1788255000345-m4q7x"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dueDate":{"type":"string","format":"date-time","description":"When it is due","examples":["2027-03-31T00:00:00.000Z"]},"id":{"type":"string","description":"Your own ID for the key result, unique within the objective; later calls use it as keyResultId","examples":["1792142100789-g7v4a"]},"startValue":{"type":"number","description":"Value when work starts; also its first current value. Defaults to 0","examples":[12]},"targetValue":{"type":"number","description":"Value that means done; may be below the start value for a number that should fall","examples":[5]},"title":{"type":"string","description":"What is measured","examples":["Cut contract signing time to 5 days"]},"unit":{"type":"string","description":"Unit of the values, e.g. %, contracts or days. Defaults to %","examples":["days"]}},"required":["id","targetValue","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0},{"id":"1792142100789-g7v4a","title":"Cut contract signing time to 5 days","targetValue":5,"currentValue":12,"startValue":12,"unit":"days","status":"not_started","dueDate":"2027-03-31T00:00:00.000Z","orderNum":1}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no objective with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The objective already has a key result with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/initiatives":{"post":{"tags":["Strategies"],"summary":"Add an initiative","description":"Adds an initiative (a piece of work that moves an objective forward) to a strategy, after the existing ones, with status not_started, and answers with status 201 and the whole strategy. You choose its ID, one no other initiative of the strategy has; the objective, key result, person, task list and pipeline IDs are stored as sent, none of them checked. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addInitiative","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeId":{"type":"string","description":"ID of the person responsible","examples":["66f1b2c3d4e5f60718293a4b"]},"description":{"type":"string","description":"Longer notes","examples":["One free month for each referred company that signs"]},"dueDate":{"type":"string","format":"date-time","description":"When it is due","examples":["2026-12-15T00:00:00.000Z"]},"id":{"type":"string","description":"Your own ID for the initiative, unique within the strategy's initiatives; later calls use it as initiativeId","examples":["1792142400890-q2m7e"]},"keyResultId":{"type":"string","description":"ID of the key result it moves","examples":["1788255600456-s3l9p"]},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work","examples":["6ad1c3f84f3b8a1d2c7e5f37"]},"linkedTaskListId":{"type":"string","description":"ID of an existing task list for this work. To make a new one instead, use createInitiativeTaskList","examples":["6ad1c3b94f3b8a1d2c7e5f31"]},"objectiveId":{"type":"string","description":"ID of the objective it serves","examples":["1788255000345-m4q7x"]},"priority":{"type":"string","enum":["critical","high","medium","low"],"description":"How urgent it is. Defaults to medium","examples":["medium"]},"title":{"type":"string","description":"What the work is","examples":["Run a referral reward for business customers"]}},"required":["id","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0},{"id":"1792142400890-q2m7e","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Run a referral reward for business customers","description":"One free month for each referred company that signs","status":"not_started","priority":"medium","assigneeId":"66f1b2c3d4e5f60718293a4b","dueDate":"2026-12-15T00:00:00.000Z","linkedTaskListId":"6ad1c3b94f3b8a1d2c7e5f31","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":1}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The strategy already has an initiative with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/initiatives/{initiativeId}/link-tasks":{"post":{"tags":["Strategies"],"summary":"Create a task list for an initiative","description":"Makes a new task list in the strategy's space, named after the initiative and placed last in the space's sidebar, and stores its ID as the initiative's linkedTaskListId. Answers with status 201, the whole strategy and the new list. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"createInitiativeTaskList","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"},{"name":"initiativeId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the initiative","example":"1788256200567-b6x8w"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"taskItem":{"type":"object","properties":{"id":{"type":"string","description":"ID of the new task list; also stored as the initiative's linkedTaskListId"},"spaceId":{"type":"string","description":"ID of the strategy's space, where the list was made"},"itemType":{"type":"string","description":"Always tasks: a task list"},"name":{"type":"string","description":"Name of the list: the initiative's title"},"icon":{"type":"string","description":"Icon shown beside the list"},"parentId":{"description":"Always null: the list sits at the top of the space, not in a folder"},"orderNum":{"type":"integer","description":"Position among the space's top-level items; it goes last"},"isExpanded":{"type":"boolean","description":"Always true for a new item"},"isArchived":{"type":"boolean","description":"Always false for a new list"},"metadata":{"description":"Always null for a task list"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"},"taskItem":{"id":"6ad1c3a24f3b8a1d2c7e5f2b","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"tasks","name":"Launch a business fibre bundle","icon":"✏️","parentId":null,"orderNum":6,"isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:20:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or the initiative already has a task list (clear its linkedTaskListId with updateInitiative first)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists, or it has no initiative with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/milestones":{"post":{"tags":["Strategies"],"summary":"Add a milestone","description":"Adds a milestone (a date that marks progress) to a strategy, after the existing ones, with status pending, and answers with status 201 and the whole strategy. You choose its ID, one no other milestone of the strategy has; the objective is not checked to exist. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addMilestone","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"Longer notes","examples":["The business fibre bundle can be ordered"]},"id":{"type":"string","description":"Your own ID for the milestone, unique within the strategy's milestones; later calls use it as milestoneId","examples":["1792142700901-u4w6c"]},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on","examples":["1788255000345-m4q7x"]},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached","examples":["2026-12-01T00:00:00.000Z"]},"title":{"type":"string","description":"What is reached","examples":["Bundle on sale"]}},"required":["id","targetDate","title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0},{"id":"1792142700901-u4w6c","title":"Bundle on sale","description":"The business fibre bundle can be ordered","targetDate":"2026-12-01T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":1}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The strategy already has a milestone with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/strategies/{strategyId}/reviews":{"post":{"tags":["Strategies"],"summary":"Add a strategy review","description":"Adds a review of how a strategy is going, dated now and placed after the existing ones, and answers with status 201 and the whole strategy. You choose its ID, one no other review of the strategy has. Needs the editor role or higher in the strategy's space, which must not be archived.\n\n**Permission:** `spaces.strategies.update` (Update strategy).","operationId":"addReview","parameters":[{"name":"strategyId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the strategy","example":"6ad1c2e04f3b8a1d2c7e5f10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken (a JSON array in a string also works)","examples":[["Price the bundle at KES 18,000 a month"]]},"id":{"type":"string","description":"Your own ID for the review, unique within the strategy's reviews; later calls use it as reviewId","examples":["1792143000012-l7b5m"]},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed (a JSON array in a string also works)","examples":[["Pick the bundle name by Friday"]]},"overallHealth":{"type":"string","enum":["healthy","needs_attention","at_risk","critical"],"description":"How healthy the strategy is overall. Defaults to healthy","examples":["healthy"]},"summary":{"type":"string","description":"Overall summary","examples":["Bundle pricing is agreed."]},"type":{"type":"string","enum":["weekly","monthly","quarterly","adhoc"],"description":"Which kind of review. Defaults to adhoc","examples":["weekly"]},"whatDidnt":{"type":"string","description":"What did not go well","examples":["The bundle name is still open"]},"whatWorked":{"type":"string","description":"What went well","examples":["Finance signed off the price in one meeting"]}},"required":["id"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string","description":"Strategy ID"},"name":{"type":"string","description":"Name of the strategy"},"description":{"type":"string","description":"Short description; empty when none"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"vision":{"type":"string","description":"Where the organisation wants to be; empty until set"},"mission":{"type":"string","description":"How it will get there; empty until set"},"desiredOutcome":{"type":"string","description":"What success looks like; empty until set"},"timeframe":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time","description":"When the period starts"},"endDate":{"type":"string","format":"date-time","description":"When the period ends"}},"description":"Period the strategy covers; absent until set"},"status":{"type":"string","description":"draft, active, completed or archived; new strategies start as draft"},"currentPhase":{"type":"string","description":"define, analyze, plan, mobilize, execute or review; new strategies start at define"},"swotItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the SWOT item, as sent when it was added"},"type":{"type":"string","description":"strength, weakness, opportunity or threat"},"content":{"type":"string","description":"The statement"},"impact":{"type":"string","description":"high, medium or low; medium unless set"},"notes":{"type":"string","description":"Supporting detail; empty when none"},"orderNum":{"type":"integer","description":"Position in the order items were added; lower comes first"}}},"description":"SWOT analysis: strengths, weaknesses, opportunities and threats"},"pillars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the pillar, as sent when it was added"},"name":{"type":"string","description":"Name of the pillar"},"description":{"type":"string","description":"What the pillar covers; empty when none"},"color":{"type":"string","description":"Colour as a hex code; #6b7280 unless set"},"orderNum":{"type":"integer","description":"Position in the order pillars were added; lower comes first"}}},"description":"Pillars: the main themes objectives are grouped under"},"objectives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the objective, as sent when it was added"},"pillarId":{"type":"string","description":"ID of the pillar it sits under; null when none"},"title":{"type":"string","description":"What the objective is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"progress":{"type":"integer","description":"0 to 100. Recalculated from its key results each time one of them is updated, as the average of how far each has moved from its start value to its target"},"orderNum":{"type":"integer","description":"Position in the order objectives were added; lower comes first"},"keyResults":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the key result, as sent when it was added"},"title":{"type":"string","description":"What is measured"},"targetValue":{"type":"integer","description":"Value that means done"},"currentValue":{"type":"integer","description":"Value reached so far"},"startValue":{"type":"integer","description":"Value when work started"},"unit":{"type":"string","description":"Unit of the values, e.g. % or contracts; % unless set"},"status":{"type":"string","description":"not_started, on_track, at_risk, behind or completed"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"orderNum":{"type":"integer","description":"Position in the order key results were added; lower comes first"}}},"description":"Its key results: the numbers that show the objective is met"}}},"description":"Objectives, each with its key results"},"initiatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the initiative, as sent when it was added"},"objectiveId":{"type":"string","description":"ID of the objective it serves; null when none"},"keyResultId":{"type":"string","description":"ID of the key result it moves; null when none"},"title":{"type":"string","description":"What the work is"},"description":{"type":"string","description":"Longer notes; empty when none"},"status":{"type":"string","description":"not_started, in_progress, completed, blocked or cancelled"},"priority":{"type":"string","description":"critical, high, medium or low"},"assigneeId":{"type":"string","description":"ID of the person responsible; null when none"},"dueDate":{"type":"string","format":"date-time","description":"When it is due; absent or null when none"},"linkedTaskListId":{"type":"string","description":"ID of the space's task list for this work; null when none"},"linkedPipelineId":{"type":"string","description":"ID of a pipeline linked to this work; null when none"},"orderNum":{"type":"integer","description":"Position in the order initiatives were added; lower comes first"}}},"description":"Initiatives: pieces of work that move objectives forward"},"milestones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the milestone, as sent when it was added"},"title":{"type":"string","description":"What is reached"},"description":{"type":"string","description":"Longer notes; empty when none"},"targetDate":{"type":"string","format":"date-time","description":"When it should be reached"},"status":{"type":"string","description":"pending, achieved, missed or moved"},"linkedObjectiveId":{"type":"string","description":"ID of the objective it marks progress on; null when none"},"orderNum":{"type":"integer","description":"Position in the order milestones were added; lower comes first"}}},"description":"Milestones: dates that mark progress"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the review, as sent when it was added"},"date":{"type":"string","format":"date-time","description":"When the review was added"},"type":{"type":"string","description":"weekly, monthly, quarterly or adhoc"},"summary":{"type":"string","description":"Overall summary; empty when none"},"whatWorked":{"type":"string","description":"What went well; empty when none"},"whatDidnt":{"type":"string","description":"What did not go well; empty when none"},"decisions":{"type":"array","items":{"type":"string"},"description":"Decisions taken"},"nextActions":{"type":"array","items":{"type":"string"},"description":"Next steps agreed"},"overallHealth":{"type":"string","description":"healthy, needs_attention, at_risk or critical"}}},"description":"Reviews of how the strategy is going, oldest first"},"isArchived":{"type":"boolean","description":"Always false: archived strategies are not returned"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"strategy":{"id":"6ad1c2e04f3b8a1d2c7e5f10","name":"Business growth 2026-27","description":"How we grow business customers over the next year","spaceId":"6a9f3c21b7e4a20f1c5d8e41","vision":"The first choice for business internet in East Africa","mission":"Reliable fibre with support that answers in minutes","desiredOutcome":"Business revenue doubled by June 2027","timeframe":{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2027-06-30T00:00:00.000Z"},"status":"active","currentPhase":"execute","swotItems":[{"id":"1788253200123-k3x9q","type":"strength","content":"Our fibre already reaches 40 business parks in Nairobi","impact":"high","notes":"Mapped in the August network review","orderNum":0}],"pillars":[{"id":"1788254100234-r5t8v","name":"Business customers","description":"Win and keep companies on fibre","color":"#3b82f6","orderNum":0}],"objectives":[{"id":"1788255000345-m4q7x","pillarId":"1788254100234-r5t8v","title":"Grow business revenue","description":"Double monthly revenue from business customers","status":"on_track","progress":38,"orderNum":0,"keyResults":[{"id":"1788255600456-s3l9p","title":"Sign 120 new business contracts","targetValue":120,"currentValue":45,"startValue":0,"unit":"contracts","status":"on_track","dueDate":"2027-06-30T00:00:00.000Z","orderNum":0}]}],"initiatives":[{"id":"1788256200567-b6x8w","objectiveId":"1788255000345-m4q7x","keyResultId":"1788255600456-s3l9p","title":"Launch a business fibre bundle","description":"Fibre, phone lines and support in one monthly price","status":"in_progress","priority":"high","assigneeId":"66f1b2c3d4e5f60718293a5c","dueDate":"2027-01-31T00:00:00.000Z","linkedTaskListId":"6ad1c3a24f3b8a1d2c7e5f2b","linkedPipelineId":"6ad1c3f84f3b8a1d2c7e5f37","orderNum":0}],"milestones":[{"id":"1788256800678-d5k1h","title":"First 50 contracts signed","description":"Halfway to the contracts target","targetDate":"2027-02-28T00:00:00.000Z","status":"pending","linkedObjectiveId":"1788255000345-m4q7x","orderNum":0}],"reviews":[{"id":"1792054800345-e3y8r","date":"2026-10-14T09:00:00.000Z","type":"monthly","summary":"Contracts are on pace; installs are slower than planned.","whatWorked":"Referrals from existing customers","whatDidnt":"Install lead times of over three weeks","decisions":["Hire a second install team"],"nextActions":["Post the install team job ad","Review install lead times weekly"],"overallHealth":"needs_attention"},{"id":"1792143000012-l7b5m","date":"2026-10-15T09:20:00.000Z","type":"weekly","summary":"Bundle pricing is agreed.","whatWorked":"Finance signed off the price in one meeting","whatDidnt":"The bundle name is still open","decisions":["Price the bundle at KES 18,000 a month"],"nextActions":["Pick the bundle name by Friday"],"overallHealth":"healthy"}],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z"}}}}},"400":{"description":"strategyId is not a valid ID, or a value the strategy cannot hold, e.g. an unknown status, a progress over 100, or a date or number that is not one (the error says which), or decisions or nextActions is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the strategy's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No strategy with that ID, it was archived with its sidebar item, or its space no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The strategy already has a review with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.strategies.update"]}],"x-required-scopes":["spaces.strategies.update"]}},"/spaces/{spaceId}/items/with-target":{"post":{"tags":["Spaces"],"summary":"Create a sidebar item with what it opens","description":"Makes the thing a sidebar item opens and the item itself in one go, and answers with status 201. itemType strategy, pipeline or wiki makes a new strategy, pipeline or wiki with the item's name; spreadsheet, document or presentation makes an empty one of those, with you as its owner. Any other item type makes the item alone. Needs the editor role or higher in the space; an archived space takes no new items.\n\n**Permission:** `spaces.spaceItems.create` (Create space items).","operationId":"createSpaceItemWithTarget","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","description":"Colour as a hex code","examples":["#22c55e"]},"icon":{"type":"string","description":"An emoji or icon name. Defaults to the type's own, e.g. 📊 for a spreadsheet","examples":["📊"]},"itemType":{"type":"string","enum":["folder","calendar","pipeline","wiki","document","tasks","spreadsheet","presentation","custom","analytics","strategy","drive"],"description":"What to make; tasks is a task list","examples":["spreadsheet"]},"name":{"type":"string","description":"Name of the item, and of what it opens","examples":["October budget"]},"parentId":{"type":"string","description":"ID of a folder in this space to put the item in; leave out for the top level","examples":["6a9f3c71b7e4a20f1c5d8e4c"]},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"}},"required":["id","name"]},"description":"Only for a pipeline: its stages, each with an id and a name (color, orderNum and isDefault are optional; orderNum defaults to the stage's place in the list). A JSON array in a string also works","examples":[[{"id":"new","name":"New","isDefault":true},{"id":"won","name":"Won","color":"#22c55e"}]]}},"required":["itemType","name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"spaceId":{"type":"string","description":"ID of the space it is in"},"itemType":{"type":"string","description":"What it is: folder, calendar, pipeline, wiki, document, tasks, spreadsheet, presentation, custom, analytics, strategy, drive. tasks is a task list"},"name":{"type":"string","description":"Name shown in the sidebar"},"icon":{"type":"string","description":"An emoji or icon name; each type has its own default, e.g. 📁 for a folder"},"parentId":{"type":"string","description":"ID of the folder it sits in; null at the top level"},"orderNum":{"type":"integer","description":"Position among the items in the same folder; 0 comes first"},"targetId":{"type":"string","description":"ID of the thing it opens: a pipeline, wiki, strategy, or a sheet or document. Absent for folders, task lists and other space-wide items"},"targetType":{"type":"string","description":"Kind of thing targetId points to: Pipeline, Wiki, WikiPage, UniverDocument (a sheet or document) or Strategy"},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"metadata":{"description":"Extra settings some item types keep, e.g. the dashboard an analytics item shows; null when none"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}},"target":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"string","description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"tags":{"type":"array","description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}},"description":"What was made for the item: for a sheet, document or presentation, the new one in the shape the Sheets & documents calls use (shown here); for a pipeline, wiki or strategy, the new one as its own calls return it; null for any other item type"}}},"example":{"item":{"id":"6ad0a0c7d5c26de56de949e1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"spreadsheet","name":"October budget","icon":"📊","parentId":"6a9f3c71b7e4a20f1c5d8e4c","orderNum":0,"targetId":"6ad0a0d2d5c26de56de949e6","targetType":"UniverDocument","isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T08:10:00.000Z"},"target":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":"66f1b2c3d4e5f60718293a4b","fileSize":289,"version":1,"collaborators":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","addedAt":"2026-10-15T08:10:00.000Z"}],"settings":{"isPublic":false,"allowComments":true,"allowExport":true},"tags":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T08:10:00.000Z","snapshotCount":0}}}}},"400":{"description":"spaceId or parentId is not a valid ID, parentId is not a folder in this space, itemType is not one of the known values, stages is not valid JSON, or making the item or what it opens failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available, so a sheet, document or presentation cannot be made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.spaceItems.create"]}],"x-required-scopes":["spaces.spaceItems.create"]}},"/spaces/{spaceId}/items/reorder":{"post":{"tags":["Spaces"],"summary":"Reorder sidebar items","description":"Puts sidebar items in the order you list them, in one folder or at the top level: the first ID gets position 0, the next 1, and so on. Every listed item is also moved into that folder, which must be a folder in this space; a folder cannot go inside itself or one of its own folders. IDs of items in other spaces are ignored. Needs the editor role or higher in the space, which must not be archived.\n\n**Permission:** `spaces.spaceItems.update` (Update space items).","operationId":"reorderSpaceItems","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string"},"description":"IDs of the items, in their new order (a JSON array in a string also works)","examples":[["6ad0a0c7d5c26de56de949e1","6ad0a10bd5c26de56de94a02"]]},"parentId":{"type":"string","description":"ID of the folder the items are in; leave out for the top level","examples":["6a9f3c71b7e4a20f1c5d8e4c"]}},"required":["itemIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"spaceId or parentId is not a valid ID, parentId is not a folder in this space, a folder would go inside itself or one of its own folders, or itemIds is not a list of IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No space with that ID, it is archived, or you are not an editor or owner of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.update"]}],"x-required-scopes":["spaces.spaceItems.update"]}},"/space-items/{itemId}/move":{"post":{"tags":["Spaces"],"summary":"Move a sidebar item","description":"Moves a sidebar item into a folder, or to the top level, at a given position; the other items there shift to make room. Needs the editor role or higher in the item's space, which must not be archived. A folder cannot go inside itself or one of its own folders.\n\n**Permission:** `spaces.spaceItems.update` (Update space items).","operationId":"moveSpaceItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sidebar item","example":"6ad0a0c7d5c26de56de949e1"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderNum":{"type":"integer","default":0,"description":"Its new position in that folder; 0 is the top","examples":[1]},"parentId":{"type":"string","description":"ID of the folder to move it into; leave out to move it to the top level","examples":["6a9f3c71b7e4a20f1c5d8e4c"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"spaceId":{"type":"string","description":"ID of the space it is in"},"itemType":{"type":"string","description":"What it is: folder, calendar, pipeline, wiki, document, tasks, spreadsheet, presentation, custom, analytics, strategy, drive. tasks is a task list"},"name":{"type":"string","description":"Name shown in the sidebar"},"icon":{"type":"string","description":"An emoji or icon name; each type has its own default, e.g. 📁 for a folder"},"parentId":{"description":"ID of the folder it sits in; null at the top level"},"orderNum":{"type":"integer","description":"Position among the items in the same folder; 0 comes first"},"targetId":{"type":"string","description":"ID of the thing it opens: a pipeline, wiki, strategy, or a sheet or document. Absent for folders, task lists and other space-wide items"},"targetType":{"type":"string","description":"Kind of thing targetId points to: Pipeline, Wiki, WikiPage, UniverDocument (a sheet or document) or Strategy"},"isExpanded":{"type":"boolean","description":"Whether a folder shows open in the sidebar"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"metadata":{"description":"Extra settings some item types keep, e.g. the dashboard an analytics item shows; null when none"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"item":{"id":"6ad0a0c7d5c26de56de949e1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","itemType":"spreadsheet","name":"October budget","icon":"📊","parentId":null,"orderNum":1,"targetId":"6ad0a0d2d5c26de56de949e6","targetType":"UniverDocument","isExpanded":true,"isArchived":false,"metadata":null,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T10:00:00.000Z"}}}}},"400":{"description":"itemId or parentId is not a valid ID, parentId is not a folder in this space, a folder would go inside itself, or the move failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the item's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sidebar item with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.spaceItems.update"]}],"x-required-scopes":["spaces.spaceItems.update"]}},"/events/{eventId}/respond":{"post":{"tags":["Calendar"],"summary":"Reply to an event invitation","description":"Sets your reply to an event you are invited to, and notifies its organizer. With occurrence, the reply is for that one upcoming occurrence of a repeating event only. It needs only permission to read the calendar.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"updateEventResponse","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event; for a repeating event, the series","example":"6ad1c0a2d5c26de56de94a10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"occurrence":{"type":"string","format":"date-time","description":"Original start of one occurrence of a repeating event: originalStartDate from a list row","examples":["2026-10-22T06:30:00.000Z"]},"status":{"type":"string","enum":["accepted","declined","tentative"],"description":"Your reply","examples":["accepted"]}},"required":["status"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"string","description":"ID of the organizer (firstName, lastName, email are not filled in here)"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"string"},"description":"IDs of the tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The event with your reply, its space filled in and people as IDs. With occurrence, that one occurrence instead, shaped as getEventOccurrenceCall shows it"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","attendees":[{"userId":"66f1b2c3d4e5f60718293a5c","status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":["6ad0a044d5c26de56de949a8"],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"eventId is not a valid ID; status is not accepted, declined or tentative; you are not invited; or the occurrence is not valid, has started or is no longer open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The event is kept by Kazee People, or (with occurrence) you cannot see that occurrence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation (or it was cancelled), or that occurrence no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]}},"/events/{eventId}/resolve":{"post":{"tags":["Calendar"],"summary":"Prepare one occurrence's call","description":"Makes sure one occurrence of an event with Kazee calls has its own call, setting it up in Kazee Chat if needed, and answers with that occurrence. Open to whoever may see the occurrence, as with getEvent; reading the calendar never sets calls up. An occurrence whose call is ready comes back unchanged.\n\n**Permission:** `spaces.calendar.read` (View calendar).","operationId":"getEventOccurrenceCall","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event (the series)","example":"6ad1c0b8d5c26de56de94a1c"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"occurrence":{"type":"string","format":"date-time","description":"Original start of the occurrence: originalStartDate from a list row","examples":["2026-10-22T06:30:00.000Z"]}},"required":["occurrence"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"_id":{"type":"string","description":"Row ID: the event ID, or <event ID>_rec_<original start> for an occurrence of a repeating event"},"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When this occurrence starts"},"endDate":{"type":"string","format":"date-time","description":"When this occurrence ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"}},"description":"The occurrence's own Kazee call. Each occurrence gets its own call; until it is set up this is { provider: kazee, status: pending } and meetingUrl is empty"},"spaceId":{"type":"object","properties":{"_id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"object","properties":{"_id":{"type":"string","description":"The organizer's user ID"},"firstName":{"type":"string","description":"The organizer's first name"},"lastName":{"type":"string","description":"The organizer's last name"},"email":{"type":"string","description":"The organizer's email address"}},"description":"The organizer"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"_id":{"type":"string","description":"The invited person's user ID"},"firstName":{"type":"string","description":"The invited person's first name"},"lastName":{"type":"string","description":"The invited person's last name"},"email":{"type":"string","description":"The invited person's email address"}},"description":"The invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"type":{"type":"string","description":"daily, weekly, monthly or yearly"},"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","items":{"type":"integer"},"description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"title":{"type":"string","description":"Title of the task"},"status":{"type":"string","description":"Status of the task"}}},"description":"Tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"occurrenceManaged":{"type":"boolean","description":"Whether the server plans this series' occurrences and their calls"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"__v":{"type":"integer","description":"Same as version"},"eventId":{"type":"string","description":"ID of the event the row comes from: the series, or the stored change of this one occurrence"},"seriesId":{"type":"string","description":"ID of the series (the event itself when it does not repeat)"},"occurrenceId":{"type":"string","description":"<series ID>:<original start>; stays the same when the occurrence is moved"},"originalStartDate":{"type":"string","format":"date-time","description":"When this occurrence was first due to start; send it as occurrence to getEvent, updateEventResponse and getEventOccurrenceCall, or as occurrenceDate to updateEvent and cancelEvent"},"isOccurrence":{"type":"boolean","description":"Always true on a dated row"},"isRecurring":{"type":"boolean","description":"Whether the row belongs to a repeating series"},"revision":{"type":"string","format":"date-time","description":"When the event last changed"},"version":{"type":"integer","description":"Version of the event the row comes from; send it as expectedRevision to updateEvent"},"seriesVersion":{"type":"integer","description":"Version of the series"},"eventUrl":{"type":"string","description":"Link that opens this occurrence in Spaces"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"},"id":{"type":"string","description":"Same as eventId"}},"description":"The occurrence, with its own Kazee call once that is ready"}}},"example":{"event":{"_id":"6ad1c0b8d5c26de56de94a1c_rec_2026-10-22T06:30:00.000Z","title":"Finance team stand-up","description":"What moved yesterday and what is blocked.","startDate":"2026-10-22T06:30:00.000Z","endDate":"2026-10-22T06:45:00.000Z","allDay":false,"timeZone":"Africa/Kampala","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c102e8b37a1d2c9f5b27","meeting":{"provider":"kazee","meetingId":"6ad1c102e8b37a1d2c9f5b27","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c102e8b37a1d2c9f5b27","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","managesAttendees":false,"occurrenceStartsAt":"2026-10-22T06:30:00.000Z","syncedAt":"2026-10-15T06:31:10.000Z"},"spaceId":{"_id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","color":"#3b82f6","icon":"💼"},"creatorId":{"_id":"66f1b2c3d4e5f60718293a4b","firstName":"Grace","lastName":"Namutebi","email":"grace.namutebi@example.com"},"attendees":[{"userId":{"_id":"66f1b2c3d4e5f60718293a5c","firstName":"Daniel","lastName":"Okello","email":"daniel.okello@example.com"},"status":"accepted","respondedAt":"2026-10-01T10:00:00.000Z"}],"color":"#22c55e","category":"meeting","recurrence":{"type":"weekly","interval":1,"daysOfWeek":[1,2,3,4,5],"weekOfMonth":[]},"reminders":[5],"recurrenceExceptions":[],"linkedTasks":[{"_id":"6ad0a044d5c26de56de949a8","title":"Send the October invoice","status":"in_progress"}],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"occurrenceManaged":true,"createdAt":"2026-10-01T09:00:00.000Z","updatedAt":"2026-10-14T16:20:00.000Z","__v":3,"eventId":"6ad1c0b8d5c26de56de94a1c","seriesId":"6ad1c0b8d5c26de56de94a1c","occurrenceId":"6ad1c0b8d5c26de56de94a1c:2026-10-22T06:30:00.000Z","originalStartDate":"2026-10-22T06:30:00.000Z","isOccurrence":true,"isRecurring":true,"revision":"2026-10-14T16:20:00.000Z","version":3,"seriesVersion":3,"eventUrl":"https://spaces.kazee.africa/calendar?event=6ad1c0b8d5c26de56de94a1c&occurrence=2026-10-22T06%3A30%3A00.000Z","meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T06:31:10.000Z","retryable":false},"id":"6ad1c0b8d5c26de56de94a1c"}}}}},"400":{"description":"eventId is not a valid ID, the event does not use Kazee calls, occurrence is not a valid date, or the series has over 500 changed occurrences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see that occurrence, the event is kept by Kazee People, or the call was made with a service token instead of a person's sign-in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation (or it was cancelled), or that occurrence no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Setting up the call is still under way; try again shortly","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Calls for single occurrences are not switched on for your organisation yet, and this occurrence has no call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.read"]}],"x-required-scopes":["spaces.calendar.read"]}},"/events/{eventId}/attendees":{"post":{"tags":["Calendar"],"summary":"Invite someone to an event","description":"Adds a person to an event's attendees with a pending reply and sends them an invitation notification (not when you add yourself); the Kazee call's members follow. Open to the organizer and to space members with the editor role or higher. Adding someone already invited changes nothing and sends no second invitation.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"addEventAttendee","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event; for a repeating event, the series","example":"6ad1c0a2d5c26de56de94a10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person to invite","examples":["66f1b2c3d4e5f60718293a5c"]}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"string","description":"ID of the organizer (firstName, lastName, email are not filled in here)"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"string"},"description":"IDs of the tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The event with its space filled in and people as IDs. For a call made in Kazee Chat (in organisations where Chat keeps those calls) it is the event before the change, which shows once Chat confirms it"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","attendees":[{"userId":"66f1b2c3d4e5f60718293a5c","status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":["6ad0a044d5c26de56de949a8"],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"eventId is not a valid ID, there is no active person with that userId, or the event has a Kazee call in a space and the person is not a member of the space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the event's organizer or a space member with the editor role or higher, or the event is kept by Kazee People and is read-only here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation, or it was cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The call was made in Kazee Chat and is not ready yet, or Kazee Chat refused the change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The call was made in Kazee Chat and Kazee Chat could not be reached to change it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]}},"/wikis/{wikiId}/import":{"post":{"tags":["Docs"],"summary":"Import pages from a Markdown zip","description":"Makes pages in a wiki from the .md files in a zip, such as an Outline export. Needs the contributor role in the wiki's space. Folders become nesting: the files in a folder go under the page made from the .md file of the same name beside it. A title is the file's first heading (else its first line, else the file name), an emoji at its start becomes the icon, and a title already used in the space gets (1), (2)... added; pages start with the wiki's settings.defaultPageStatus. If one page cannot be made, the call answers 400 and removes the pages it had already made, so nothing is imported.\n\n**Permission:** `spaces.wiki.admin` (Purge wikis).","operationId":"importWikiFromMarkdown","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileBase64":{"type":"string","format":"byte","description":"The zip file, base64-encoded. Only files ending in .md are read","examples":["UEsDBBQAAAAIAAAAIQBkJ3kE"]},"fileName":{"type":"string","description":"Name of the zip. Not used","examples":["staff-handbook-export.zip"]}},"required":["fileBase64"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"importedCount":{"type":"integer","description":"How many pages were made"},"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Page ID"},"title":{"type":"string","description":"Page title, with (1), (2)... added if the space already had it"},"icon":{"type":"string","description":"The emoji the title started with, else 📄"},"parentId":{"description":"ID of the page it was put under, or null at the top level"}}},"description":"The pages made, in the order they were made (shallowest first)"}}},"example":{"success":true,"importedCount":2,"pages":[{"id":"6ad1b1a2e4f5a6b7c8d9e192","title":"Travel policy","icon":"✈️","parentId":null},{"id":"6ad1b1a8e4f5a6b7c8d9e198","title":"Booking flights","icon":"📄","parentId":"6ad1b1a2e4f5a6b7c8d9e192"}]}}}},"400":{"description":"wikiId is not a valid ID, the file is not a zip or has no .md files, or a page could not be made (the pages made before it are removed again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the wiki's space with the contributor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.admin"]}],"x-required-scopes":["spaces.wiki.admin"]}},"/wiki/pages/{pageId}/move":{"post":{"tags":["Docs"],"summary":"Move a page","description":"Puts a page under another page of the same wiki or at the top level, and can set its position among the pages beside it. Needs the contributor role in its space. The pages under it move with it, and no other page's position changes. A page cannot go under itself or one of its own subpages.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"moveWikiPage","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderIndex":{"type":"number","description":"New position among the pages beside it; lower comes first. Leave it out to keep it","examples":[1]},"parentId":{"type":"string","description":"ID of the new parent page, in the same wiki. null moves the page to the top level; leave it out to keep its parent","examples":["6ad1b10ae4f5a6b7c8d9e101"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"parentId":{"type":"string","description":"ID of the page it sits under; absent on a top-level page"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the linking page"},"title":{"type":"string","description":"Its title when the link was recorded"}}},"description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds (at most 50)"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}}}},"example":{"page":{"title":"Leave policy","slug":"leave-policy","icon":"🌴","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager at least two weeks ahead, then log it in People."}]},{"type":"paragraph","content":[{"type":"text","text":"See Public holidays for the days everyone gets off."}]}]},"contentText":"How to ask for leave Ask your manager at least two weeks ahead, then log it in People. See Public holidays for the days everyone gets off.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"parentId":"6ad1b10ae4f5a6b7c8d9e101","orderIndex":1,"status":"published","backlinks":[{"pageId":"6ad1b10ae4f5a6b7c8d9e101","title":"People and HR"},{"pageId":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist"}],"outgoingLinks":["6ad1b12ee4f5a6b7c8d9e11e"],"linkedTasks":[],"coverImage":"https://images.example.com/covers/beach.jpg","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[{"userId":"66f1b2c3d4e5f60718293a5c","viewedAt":"2026-10-15T09:25:00.000Z","viewCount":5},{"userId":"66f1b2c3d4e5f60718293a4b","viewedAt":"2026-10-14T13:02:00.000Z","viewCount":2}],"totalViews":7,"createdAt":"2026-09-02T08:00:00.000Z","updatedAt":"2026-10-15T09:20:00.000Z","revision":6,"id":"6ad1b11ce4f5a6b7c8d9e10c","versionCount":4,"viewerCount":2}}}}},"400":{"description":"pageId or parentId is not a valid ID, the new parent is in another wiki or is the page itself or one of its subpages, or orderIndex is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the contributor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it or its wiki is archived, or the new parent page does not exist or is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]}},"/wiki/pages/{pageId}/versions/{versionId}/restore":{"post":{"tags":["Docs"],"summary":"Restore a version of a page","description":"Makes a saved copy's content the page's content again, and you its last editor; the page's revision goes up by one. The restored content is saved as a new copy with the note Restored from version <id>; the content from before stays in the history, so a restore can itself be undone. Needs the contributor role in its space. Backlinks are not updated.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"restoreWikiPageVersion","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the saved copy to bring back, from listWikiPageVersions","example":"6ad1b13fe4f5a6b7c8d9e12f"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"parentId":{"type":"string","description":"ID of the page it sits under; absent on a top-level page"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the linking page"},"title":{"type":"string","description":"Its title when the link was recorded"}}},"description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds (at most 50)"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}}}},"example":{"page":{"title":"Leave policy","slug":"leave-policy","icon":"🌴","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager, then log it in People."}]}]},"contentText":"How to ask for leave Ask your manager, then log it in People.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"parentId":"6ad1b10ae4f5a6b7c8d9e101","orderIndex":1,"status":"published","backlinks":[{"pageId":"6ad1b10ae4f5a6b7c8d9e101","title":"People and HR"},{"pageId":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist"}],"outgoingLinks":["6ad1b12ee4f5a6b7c8d9e11e"],"linkedTasks":[],"coverImage":"https://images.example.com/covers/beach.jpg","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[{"userId":"66f1b2c3d4e5f60718293a5c","viewedAt":"2026-10-15T09:25:00.000Z","viewCount":5},{"userId":"66f1b2c3d4e5f60718293a4b","viewedAt":"2026-10-14T13:02:00.000Z","viewCount":2}],"totalViews":7,"createdAt":"2026-09-02T08:00:00.000Z","updatedAt":"2026-10-15T11:05:00.000Z","revision":7,"id":"6ad1b11ce4f5a6b7c8d9e10c","versionCount":5,"viewerCount":2}}}}},"400":{"description":"pageId is not a valid ID, or the page has no saved copy with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the contributor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]}},"/wiki/pages/{pageId}/backlinks":{"post":{"tags":["Docs"],"summary":"Set the pages a page links to","description":"Sets which pages a page links to and keeps their backlinks in step: pages it no longer links to drop it from their backlinks, and newly linked pages that are in the same space and not archived add it to theirs. Needs the contributor role in the page's space. The editor calls this after saving a page; it does not read the page's content, so send the full list each time.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"updateWikiPageLinks","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page that holds the links","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of every page this page now links to, as a JSON list (an empty list removes all its links). A page in another space gets no backlink","examples":[["6ad1b12ee4f5a6b7c8d9e11e"]]}},"required":["outgoingLinks"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"pageId is not a valid ID, or outgoingLinks is not a list or holds an ID that is not valid; nothing is changed then","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the contributor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]}},"/wiki/pages/{pageId}/view":{"post":{"tags":["Docs"],"summary":"Record a view of a page","description":"Counts one view of a page by you: its total goes up by one, and your viewer entry gets the time and one more view. Open to members of its space, and to anyone if the space is public, unless the wiki is private: then only to the space's members.\n\n**Permission:** `spaces.wiki.read` (View wikis).","operationId":"markWikiPageViewed","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"totalViews":{"type":"integer","description":"How many times the page has now been viewed, repeat views included"},"viewerCount":{"type":"integer","description":"How many different people have now viewed it"}}},"example":{"success":true,"totalViews":8,"viewerCount":2}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the page's space (you are not a member and it is not public, or it is archived), or the wiki is private and you are not a member of its space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, it is archived, or its wiki is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.read"]}],"x-required-scopes":["spaces.wiki.read"]}},"/wiki/pages/{pageId}/restore":{"post":{"tags":["Docs"],"summary":"Restore an archived page","description":"Brings back a page archived with archiveWikiPage, together with the pages under it that were archived with it; pages under it archived earlier on their own stay archived. Needs the editor role in its space, as archiving does. Each page gets its status and slug from before archiving back (with -2, -3... added when another page has taken the slug since). When the page it sat under is archived or gone it comes back at the top level of the wiki instead: restoring never brings back pages you did not pick. The wiki's page count is updated.\n\n**Permission:** `spaces.wiki.delete` (Archive wikis).","operationId":"restoreWikiPage","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the archived page, from listArchivedWikiPages","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"restoredCount":{"type":"integer","description":"How many pages came back, the page itself included"},"movedToTop":{"type":"boolean","description":"true when the page it sat under is archived or gone, so it came back at the top level of the wiki"},"page":{"type":"object","properties":{"title":{"type":"string","description":"Page title"},"slug":{"type":"string","description":"The title in lower case, with a dash for each run of other characters, or 8 random letters and digits when the title has no letter a-z or digit; unique in the wiki"},"icon":{"type":"string","description":"Emoji shown with the page; 📄 unless set"},"content":{"type":"object","properties":{"type":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","properties":{"level":{"type":"integer"}}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}}}},"description":"The page body as editor JSON (TipTap / ProseMirror): { type: \"doc\", content: [...] }, a tree of nodes such as paragraph, heading, bulletList and text"},"contentText":{"type":"string","description":"The page's words without formatting, used for search"},"wikiId":{"type":"string","description":"ID of the wiki it is in"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who made it: id, firstName, lastName and email; null if that person is no longer on record"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last changed its content (the creator until then): id, firstName, lastName and email; null if that person is no longer on record"},"parentId":{"type":"string","description":"ID of the page it sits under; absent on a top-level page"},"orderIndex":{"type":"integer","description":"Position among the pages beside it; lower comes first, then by title"},"status":{"type":"string","description":"draft, published or archived. A label only: it does not hide the page"},"backlinks":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the linking page"},"title":{"type":"string","description":"Its title when the link was recorded"}}},"description":"Pages that link to this one, as updateWikiPageLinks on those pages records it; pages of a private wiki only if you are a member of the space"},"outgoingLinks":{"type":"array","items":{"type":"string"},"description":"IDs of the pages this page links to, as last set with updateWikiPageLinks"},"linkedTasks":{"type":"array","description":"Always empty: nothing links tasks to pages yet"},"coverImage":{"type":"string","description":"Address of the cover picture; absent when not set"},"isArchived":{"type":"boolean","description":"Always false here: archived pages are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"views":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person"},"viewedAt":{"type":"string","format":"date-time","description":"When they last viewed it"},"viewCount":{"type":"integer","description":"How many times they have viewed it"}}},"description":"One entry per person who has viewed it (markWikiPageViewed counts views)"},"totalViews":{"type":"integer","description":"How many times it has been viewed, repeat views included"},"createdAt":{"type":"string","format":"date-time","description":"When it was made"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"revision":{"type":"integer","description":"Goes up by one each time its content changes (an edit or a restore); send it back as updateWikiPage's baseRevision so a save made from older content is refused"},"id":{"type":"string","description":"Page ID"},"versionCount":{"type":"integer","description":"How many saved copies of its content its history holds (at most 50)"},"viewerCount":{"type":"integer","description":"How many different people have viewed it"}}}}},"example":{"success":true,"restoredCount":3,"movedToTop":false,"page":{"title":"Leave policy","slug":"leave-policy","icon":"🌴","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"How to ask for leave"}]},{"type":"paragraph","content":[{"type":"text","text":"Ask your manager at least two weeks ahead, then log it in People."}]},{"type":"paragraph","content":[{"type":"text","text":"See Public holidays for the days everyone gets off."}]}]},"contentText":"How to ask for leave Ask your manager at least two weeks ahead, then log it in People. See Public holidays for the days everyone gets off.","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"parentId":"6ad1b10ae4f5a6b7c8d9e101","orderIndex":1,"status":"published","backlinks":[{"pageId":"6ad1b10ae4f5a6b7c8d9e101","title":"People and HR"},{"pageId":"6ad1b134e4f5a6b7c8d9e124","title":"Onboarding checklist"}],"outgoingLinks":["6ad1b12ee4f5a6b7c8d9e11e"],"linkedTasks":[],"coverImage":"https://images.example.com/covers/beach.jpg","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","views":[{"userId":"66f1b2c3d4e5f60718293a5c","viewedAt":"2026-10-15T09:25:00.000Z","viewCount":5},{"userId":"66f1b2c3d4e5f60718293a4b","viewedAt":"2026-10-14T13:02:00.000Z","viewCount":2}],"totalViews":7,"createdAt":"2026-09-02T08:00:00.000Z","updatedAt":"2026-10-21T09:00:00.000Z","revision":6,"id":"6ad1b11ce4f5a6b7c8d9e10c","versionCount":4,"viewerCount":2}}}}},"400":{"description":"pageId is not a valid ID, or the page is not archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the page's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, or its wiki is archived or gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.delete"]}],"x-required-scopes":["spaces.wiki.delete"]}},"/wiki/comments/{commentId}/resolve":{"post":{"tags":["Docs"],"summary":"Resolve a comment on a page","description":"Marks a comment as resolved by you, so it drops out of the page's comment list unless includeResolved is true. Needs the contributor role in the comment's space. Resolving it again sets you and the time anew; its replies are not changed.\n\n**Permission:** `spaces.wikiComments.update` (Edit wiki comments).","operationId":"resolveWikiComment","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad1b170e4f5a6b7c8d9e160"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the page it is on"},"wikiId":{"type":"string","description":"ID of the page's wiki"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"authorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote it: id, firstName, lastName and email; null if that person is no longer on record"},"content":{"type":"string","description":"The comment text, up to 5,000 characters"},"selection":{"type":"object","properties":{"from":{"type":"integer","description":"Where the selected text starts, as a position in the page's editor document"},"to":{"type":"integer","description":"Where it ends"},"text":{"type":"string","description":"The selected words"}},"description":"The part of the page it is about; absent on a comment about the whole page"},"replyCount":{"type":"integer","description":"How many replies it has; a deleted reply comes off it"},"isResolved":{"type":"boolean","description":"Whether it is resolved"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was written"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"},"resolvedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who resolved it; only while it is resolved: id, firstName, lastName and email; null if that person is no longer on record"},"resolvedAt":{"type":"string","format":"date-time","description":"When it was resolved; only while it is resolved"}}}}},"example":{"comment":{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"content":"Does the two-week rule apply to sick leave too?","selection":{"from":42,"to":57,"text":"two weeks ahead"},"replyCount":1,"isResolved":true,"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:00:00.000Z","updatedAt":"2026-10-15T11:40:00.000Z","id":"6ad1b170e4f5a6b7c8d9e160","resolvedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"resolvedAt":"2026-10-15T11:40:00.000Z"}}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the comment's space with the contributor role or higher, its wiki no longer exists, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it is deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.update"]}],"x-required-scopes":["spaces.wikiComments.update"]}},"/wiki/comments/{commentId}/unresolve":{"post":{"tags":["Docs"],"summary":"Reopen a comment on a page","description":"Marks a resolved comment as open again and clears who resolved it and when. Needs the contributor role in the comment's space. Reopening an open comment changes nothing.\n\n**Permission:** `spaces.wikiComments.update` (Edit wiki comments).","operationId":"unresolveWikiComment","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad1b168e4f5a6b7c8d9e158"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"pageId":{"type":"string","description":"ID of the page it is on"},"wikiId":{"type":"string","description":"ID of the page's wiki"},"spaceId":{"type":"string","description":"ID of the wiki's space"},"authorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who wrote it: id, firstName, lastName and email; null if that person is no longer on record"},"content":{"type":"string","description":"The comment text, up to 5,000 characters"},"selection":{"type":"object","properties":{"from":{"type":"integer","description":"Where the selected text starts, as a position in the page's editor document"},"to":{"type":"integer","description":"Where it ends"},"text":{"type":"string","description":"The selected words"}},"description":"The part of the page it is about; absent on a comment about the whole page"},"replyCount":{"type":"integer","description":"How many replies it has; a deleted reply comes off it"},"isResolved":{"type":"boolean","description":"Whether it is resolved"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not shown"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was written"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}}}}},"example":{"comment":{"pageId":"6ad1b11ce4f5a6b7c8d9e10c","wikiId":"6ad1b0c2e4f5a6b7c8d9e0f1","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.co.ke","id":"66f1b2c3d4e5f60718293a5c"},"content":"Does the two-week rule apply to sick leave too?","selection":{"from":42,"to":57,"text":"two weeks ahead"},"replyCount":1,"isResolved":false,"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:00:00.000Z","updatedAt":"2026-10-15T12:00:00.000Z","id":"6ad1b170e4f5a6b7c8d9e160"}}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the comment's space with the contributor role or higher, its wiki no longer exists, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it is deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wikiComments.update"]}],"x-required-scopes":["spaces.wikiComments.update"]}},"/comments":{"post":{"tags":["Comments"],"summary":"Post a comment","description":"Posts a comment, or a reply when parentId is given, on a task, wiki page, pipeline, pipeline record or event, and answers 201. Needs the contributor, editor or owner role in the space the item is in. On a task, people who follow it may also post, whatever their place in the space; on a personal task (no space) its creator, assignees and followers may, and on a personal event its creator and attendees. An item in an archived space takes no new comments, edits, files or reactions. After the answer, the people mentioned, the author of the comment replied to, a task's followers and an event's creator and attendees are notified, and so is the author when their own AI assistant posted it for them (in the app, and by phone notification and email as their settings allow); the comment is also added to the activity feed and, when the item is in a space, shown live to people viewing it.\n\n**Permission:** `spaces.comments.create` (Add comments).","operationId":"createComment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attachments":{"type":"array","items":{"type":"object"},"description":"Files to attach: the attachment objects uploadCommentAttachment or confirmCommentAttachmentUpload returned for this same item, unchanged. A JSON array in a string also works","examples":[[{"fileName":"delivery-note-3f9c2a1b.jpg","originalName":"delivery-note.jpg","fileSize":482133,"mimeType":"image/jpeg","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","type":"image","uploadedAt":"2026-10-15T09:40:12.000Z"}]]},"content":{"type":"string","default":"","description":"The text: plain text, or a rich-text document as a JSON string; at most 50,000 characters, trimmed. May be empty when attachments are given","examples":["Sent the invoice to the client this morning. Photo of the signed delivery note attached."]},"mentions":{"type":"array","items":{"type":"string"},"default":[],"description":"IDs of the people mentioned; they are notified. IDs that match nobody are dropped. A JSON array in a string also works","examples":[["66f1b2c3d4e5f60718293a5c"]]},"parentId":{"type":"string","description":"ID of the comment this replies to; it must be on the same item. Replies to replies are allowed","examples":["6ad0a3c2d5c26de56de94a10"]},"targetId":{"type":"string","description":"ID of that task, wiki page, pipeline, pipeline record or event","examples":["6ad0a044d5c26de56de949a8"]},"targetType":{"type":"string","enum":["task","wiki_page","pipeline","pipeline_record","event"],"description":"What kind of item the comments are on","examples":["task"]}},"required":["targetId","targetType"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"targetType":{"type":"string","description":"What kind of item it is on: task, wiki_page, pipeline, pipeline_record or event"},"targetId":{"type":"string","description":"ID of that item"},"spaceId":{"type":"string","description":"ID of the space the item is in; absent for a personal task or event"},"authorId":{"type":"object","properties":{"name":{"type":"string","description":"Full name, when Kazee sign-in has one for them"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"},"id":{"type":"string","description":"Their ID"}},"description":"Who wrote it"},"kind":{"type":"string","description":"comment: written by a person. transition: a note added when someone moves a pipeline record through a stage transition with notes"},"content":{"type":"string","description":"The text: plain text, or a rich-text document as a JSON string"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with a short random code added, e.g. delivery-note-3f9c2a1b.jpg"},"originalName":{"type":"string","description":"Name of the file as it was uploaded"},"fileSize":{"type":"integer","description":"Size in bytes"},"mimeType":{"type":"string","description":"File type, e.g. image/jpeg"},"minioKey":{"type":"string","description":"Key of the stored file; pass it as minioKey to getCommentAttachmentUrl for a download link"},"bucketName":{"type":"string","description":"Which store holds the file; absent on older files"},"type":{"type":"string","description":"image, video or file, from the file type"},"uploadedAt":{"type":"string","format":"date-time","description":"When the file was stored"},"_id":{"type":"string","description":"ID of this file entry on the comment"}}},"description":"Files attached to it"},"replyCount":{"type":"integer","description":"How many direct replies it has"},"mentions":{"type":"array","items":{"type":"string"},"description":"IDs of the people mentioned in it"},"reactions":{"type":"array","description":"Emoji reactions, at most one per person"},"seenBy":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who saw it"},"seenAt":{"type":"string","format":"date-time","description":"When they first saw it"},"_id":{"type":"string","description":"ID of this entry"}}},"description":"Who has seen it, and when; the author counts as having seen it from the start"},"isDeleted":{"type":"boolean","description":"Always false here: deleted comments are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was posted"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Comment ID"}},"description":"The new comment"}}},"example":{"comment":{"targetType":"task","targetId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","authorId":{"name":"Amina Otieno","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke","id":"66f1b2c3d4e5f60718293a4b"},"kind":"comment","content":"Sent the invoice to the client this morning. Photo of the signed delivery note attached.","attachments":[{"fileName":"delivery-note-3f9c2a1b.jpg","originalName":"delivery-note.jpg","fileSize":482133,"mimeType":"image/jpeg","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","type":"image","uploadedAt":"2026-10-15T09:40:12.000Z","_id":"6ad0a3c2d5c26de56de94a11"}],"replyCount":0,"mentions":["66f1b2c3d4e5f60718293a5c"],"reactions":[],"seenBy":[{"userId":"66f1b2c3d4e5f60718293a4b","seenAt":"2026-10-15T09:41:00.000Z","_id":"6ad0a3c2d5c26de56de94a12"}],"isDeleted":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T09:41:00.000Z","updatedAt":"2026-10-15T09:41:00.000Z","id":"6ad0a3c2d5c26de56de94a10"}}}}},"400":{"description":"targetId or parentId is not a valid ID, parentId is not a comment (or it was deleted) or is on another item, attachments is not a valid JSON list, a file is not one uploaded for this item in your organisation's store, there is neither text nor a file, or the comment could not be saved (for example text over 50,000 characters, a malformed mention ID, or a file entry missing fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not post on the item (see above), targetType is not one listed, or the event is managed by Kazee People","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task, wiki page, pipeline, record or event, it is archived, or its wiki or space is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Files are attached and file storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comments.create"]}],"x-required-scopes":["spaces.comments.create"]}},"/comments/upload-attachment":{"post":{"tags":["Comments"],"summary":"Upload a file for a comment","description":"Stores a file of up to 200 MB for a comment you are about to post, and returns it to pass to createComment; nothing is attached until then. Needs the contributor, editor or owner role in the space the item is in. On a task, people who follow it may also post, whatever their place in the space; on a personal task (no space) its creator, assignees and followers may, and on a personal event its creator and attendees. An item in an archived space takes no new comments, edits, files or reactions. Browser requests through Kazee sign-in stop at 128 MB, so larger files go through requestCommentAttachmentUpload instead.\n\n**Permission:** `spaces.comments.create` (Add comments).","operationId":"uploadCommentAttachment","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"attachment":{"type":"string","format":"binary","description":"The file, sent as multipart form data; at most 200 MB"},"targetId":{"type":"string","description":"ID of that task, wiki page, pipeline, pipeline record or event","examples":["6ad0a044d5c26de56de949a8"]},"targetType":{"type":"string","enum":["task","wiki_page","pipeline","pipeline_record","event","media"],"description":"What kind of item the file is for. media is for an image put into a description before its item exists: then any signed-in person may upload, and targetId is only used in the file's key","examples":["task"]}},"required":["attachment","targetId","targetType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with a short random code added, e.g. delivery-note-3f9c2a1b.jpg"},"originalName":{"type":"string","description":"Name of the file as it was uploaded"},"fileSize":{"type":"integer","description":"Size in bytes"},"mimeType":{"type":"string","description":"File type, e.g. image/jpeg"},"minioKey":{"type":"string","description":"Key of the stored file; pass it as minioKey to getCommentAttachmentUrl for a download link"},"bucketName":{"type":"string","description":"Which store holds the file; absent on older files"},"type":{"type":"string","description":"image, video or file, from the file type"},"uploadedAt":{"type":"string","format":"date-time","description":"When the file was stored"}},"description":"The stored file; pass it in attachments to createComment"},"url":{"type":"string","description":"Download link for the file, valid for 7 days without sign-in; absent if a link could not be made"}}},"example":{"attachment":{"fileName":"delivery-note-3f9c2a1b.jpg","originalName":"delivery-note.jpg","fileSize":482133,"mimeType":"image/jpeg","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","type":"image","uploadedAt":"2026-10-15T09:40:12.000Z"},"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c"}}}},"400":{"description":"targetId is not a valid ID (any targetType but media), no file was sent, or it is over 200 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not post on the item (see above), targetType is not one listed, or the event is managed by Kazee People","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task, wiki page, pipeline, record or event, it is archived, or its wiki or space is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comments.create"]}],"x-required-scopes":["spaces.comments.create"]}},"/comments/attachment-upload":{"post":{"tags":["Comments"],"summary":"Start a large comment file upload","description":"First step of uploading a comment file of up to 200 MB straight to storage, for files too big to send through the API: returns a one-hour upload link and the key the file will have. PUT the file to uploadUrl, then call confirmCommentAttachmentUpload, and pass the attachment it returns to createComment. Needs the contributor, editor or owner role in the space the item is in. On a task, people who follow it may also post, whatever their place in the space; on a personal task (no space) its creator, assignees and followers may, and on a personal event its creator and attendees. An item in an archived space takes no new comments, edits, files or reactions. Nothing is saved by this call.\n\n**Permission:** `spaces.comments.create` (Add comments).","operationId":"requestCommentAttachmentUpload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file; in the stored key, characters other than letters, digits, dots, hyphens and underscores become underscores","examples":["delivery-note.jpg"]},"fileSize":{"type":"integer","description":"Size of the file in bytes, from 1 to 209715200 (200 MB); a number in a string also works","examples":[482133]},"mimeType":{"type":"string","description":"Not used by this call; give the file type to confirmCommentAttachmentUpload","examples":["image/jpeg"]},"targetId":{"type":"string","description":"ID of that task, wiki page, pipeline, pipeline record or event","examples":["6ad0a044d5c26de56de949a8"]},"targetType":{"type":"string","enum":["task","wiki_page","pipeline","pipeline_record","event","media"],"description":"What kind of item the file is for. media is for an image put into a description before its item exists: then any signed-in person may upload, and targetId is only used in the file's key","examples":["task"]}},"required":["fileName","fileSize","targetId","targetType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"type":"string","description":"Link to send the file to with an HTTP PUT, the file as the body; it works without sign-in until it expires"},"minioKey":{"type":"string","description":"Key the file will be stored under; pass it to confirmCommentAttachmentUpload"},"bucketName":{"type":"string","description":"Store the file goes to; pass it to confirmCommentAttachmentUpload"},"expiresIn":{"type":"integer","description":"Seconds until uploadUrl stops working (always 3600, one hour)"}}},"example":{"uploadUrl":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","expiresIn":3600}}}},"400":{"description":"targetId is not a valid ID (any targetType but media), fileName is empty, or fileSize is not a whole number above 0 or is over 200 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not post on the item (see above), targetType is not one listed, or the event is managed by Kazee People","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task, wiki page, pipeline, record or event, it is archived, or its wiki or space is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comments.create"]}],"x-required-scopes":["spaces.comments.create"]}},"/comments/attachment-upload/confirm":{"post":{"tags":["Comments"],"summary":"Finish a large comment file upload","description":"Second step of a large comment file upload: checks the file sent to the upload link is there, belongs to this item and is at most 200 MB, and returns it to pass to createComment. A file over 200 MB is deleted from storage. Needs the contributor, editor or owner role in the space the item is in. On a task, people who follow it may also post, whatever their place in the space; on a personal task (no space) its creator, assignees and followers may, and on a personal event its creator and attendees. An item in an archived space takes no new comments, edits, files or reactions.\n\n**Permission:** `spaces.comments.create` (Add comments).","operationId":"confirmCommentAttachmentUpload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bucketName":{"type":"string","description":"The bucketName requestCommentAttachmentUpload returned","examples":["org-66a4b275003d1b495212b5aa"]},"mimeType":{"type":"string","description":"File type, e.g. image/jpeg; it also sets type (image, video or file). Defaults to application/octet-stream","examples":["image/jpeg"]},"minioKey":{"type":"string","description":"The key requestCommentAttachmentUpload returned for the same item","examples":["spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg"]},"originalName":{"type":"string","description":"Name of the file to show; trimmed","examples":["delivery-note.jpg"]},"targetId":{"type":"string","description":"ID of that task, wiki page, pipeline, pipeline record or event","examples":["6ad0a044d5c26de56de949a8"]},"targetType":{"type":"string","enum":["task","wiki_page","pipeline","pipeline_record","event","media"],"description":"What kind of item the file is for. media is for an image put into a description before its item exists: then any signed-in person may upload, and targetId is only used in the file's key","examples":["task"]}},"required":["bucketName","minioKey","originalName","targetId","targetType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with a short random code added, e.g. delivery-note-3f9c2a1b.jpg"},"originalName":{"type":"string","description":"Name of the file as it was uploaded"},"fileSize":{"type":"integer","description":"Size in bytes, as stored"},"mimeType":{"type":"string","description":"File type, e.g. image/jpeg"},"minioKey":{"type":"string","description":"Key of the stored file; pass it as minioKey to getCommentAttachmentUrl for a download link"},"bucketName":{"type":"string","description":"Which store holds the file; absent on older files"},"type":{"type":"string","description":"image, video or file, from the file type"},"uploadedAt":{"type":"string","format":"date-time","description":"When the file was stored"}},"description":"The stored file; pass it in attachments to createComment"},"url":{"type":"string","description":"Download link for the file, valid for 7 days without sign-in; absent if a link could not be made"}}},"example":{"attachment":{"fileName":"delivery-note-3f9c2a1b.jpg","originalName":"delivery-note.jpg","fileSize":482133,"mimeType":"image/jpeg","minioKey":"spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg","bucketName":"org-66a4b275003d1b495212b5aa","type":"image","uploadedAt":"2026-10-15T09:40:12.000Z"},"url":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/comments/task/6ad0a044d5c26de56de949a8/7c4e2a91-0b3d-4f6e-a1c5-9d8e7f6a5b43-delivery-note.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c"}}}},"400":{"description":"targetId is not a valid ID (any targetType but media), the key is not one this item's uploads get in your organisation's store, nothing was uploaded under it, or the file is over 200 MB (it is then deleted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not post on the item (see above), targetType is not one listed, or the event is managed by Kazee People","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task, wiki page, pipeline, record or event, it is archived, or its wiki or space is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comments.create"]}],"x-required-scopes":["spaces.comments.create"]}},"/comments/mark-seen":{"post":{"tags":["Comments"],"summary":"Mark comments as seen","description":"Records that you have seen some comments on an item, with the time, and, when the item is in a space, shows that live. IDs that are not comments on this item, deleted ones and ones you have already seen are skipped. Open to members of the space the item is in (any role). On a task, people who follow it also get in, whatever their place in the space; a personal task (no space) is open to its creator, assignees and followers, and a personal event to its creator and attendees.\n\n**Permission:** `spaces.comments.update` (Edit comments).","operationId":"markCommentsSeen","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commentIds":{"type":"array","items":{"type":"string"},"description":"IDs of the comments or replies you have seen; a JSON array in a string also works","examples":[["6ad0a3c2d5c26de56de94a10","6ad0a3f8d5c26de56de94a1c"]]},"targetId":{"type":"string","description":"ID of that task, wiki page, pipeline, pipeline record or event","examples":["6ad0a044d5c26de56de949a8"]},"targetType":{"type":"string","enum":["task","wiki_page","pipeline","pipeline_record","event"],"description":"What kind of item the comments are on","examples":["task"]}},"required":["commentIds","targetId","targetType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"markedCount":{"type":"integer","description":"How many comments were newly marked; ones you had already seen are not counted"}}},"example":{"success":true,"markedCount":2}}}},"400":{"description":"targetId is not a valid ID, or commentIds is not a list, is empty or holds an ID that is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not read comments on the item (see above), targetType is not one listed, or the event is managed by Kazee People","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task, wiki page, pipeline, record or event, it is archived, or its wiki or space is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comments.update"]}],"x-required-scopes":["spaces.comments.update"]}},"/comments/{commentId}/reactions":{"post":{"tags":["Comments"],"summary":"React to a comment","description":"Sets your reaction on a comment; each person has at most one. Sending the emoji you already have removes it, and a different one replaces it. Needs the contributor, editor or owner role in the space the item is in. On a task, people who follow it may also post, whatever their place in the space; on a personal task (no space) its creator, assignees and followers may, and on a personal event its creator and attendees. An item in an archived space takes no new comments, edits, files or reactions. When a reaction is added, the comment's author is notified (unless it is you) and, when the item is in a space, the change is shown live.\n\n**Permission:** `spaces.comments.update` (Edit comments).","operationId":"updateCommentReaction","parameters":[{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the comment","example":"6ad0a3c2d5c26de56de94a10"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emoji":{"type":"string","description":"The emoji, e.g. 👍; any text is accepted","examples":["👍"]}},"required":["emoji"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"reactions":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"Who reacted"},"emoji":{"type":"string","description":"The emoji"},"createdAt":{"type":"string","format":"date-time","description":"When they reacted"},"_id":{"type":"string","description":"ID of this reaction entry"}}},"description":"All reactions on the comment now"},"action":{"type":"string","description":"added (your reaction is now emoji) or removed (you now have none)"}}},"example":{"reactions":[{"userId":"66f1b2c3d4e5f60718293a5c","emoji":"👍","createdAt":"2026-10-15T10:02:00.000Z","_id":"6ad0a41ad5c26de56de94a25"}],"action":"added"}}}},"400":{"description":"commentId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You may not post on the item (see above), or the item is gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No comment with that ID, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.comments.update"]}],"x-required-scopes":["spaces.comments.update"]}},"/notifications/settings/reset":{"post":{"tags":["Notifications"],"summary":"Reset my notification settings","description":"Puts all your notification settings back to the defaults: everything on, except emails for reactions.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"resetNotificationSettings","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"settings":{"type":"object","properties":{"task_assigned":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task is assigned to you: push (phone notification) and email, each true when on"},"task_updated":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task you're involved in is updated: push (phone notification) and email, each true when on"},"task_due":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for tasks approaching their due date: push (phone notification) and email, each true when on"},"mentions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone @mentions you: push (phone notification) and email, each true when on"},"comments":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone comments on your items: push (phone notification) and email, each true when on"},"replies":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone replies to your comments: push (phone notification) and email, each true when on"},"reactions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone reacts to your comment: push (phone notification) and email, each true when on"},"space_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to join a space: push (phone notification) and email, each true when on"},"event_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to an event or someone responds to your invite: push (phone notification) and email, each true when on"},"event_reminders":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for upcoming calendar events: push (phone notification) and email, each true when on"},"system":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Important system announcements: push (phone notification) and email, each true when on"}},"description":"Your settings now: the defaults"},"message":{"type":"string","description":"Always Notification settings reset to defaults"}}},"example":{"success":true,"settings":{"task_assigned":{"push":true,"email":true},"task_updated":{"push":true,"email":true},"task_due":{"push":true,"email":true},"mentions":{"push":true,"email":true},"comments":{"push":true,"email":true},"replies":{"push":true,"email":true},"reactions":{"push":true,"email":false},"space_invites":{"push":true,"email":true},"event_invites":{"push":true,"email":true},"event_reminders":{"push":true,"email":true},"system":{"push":true,"email":true}},"message":"Notification settings reset to defaults"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications/settings/toggle-all":{"post":{"tags":["Notifications"],"summary":"Turn push or email on or off","description":"Turns phone notifications (push) or email on or off for every category at once. In-app notifications are not affected.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"updateNotificationChannel","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["push","email"],"description":"push for phone notifications, or email","examples":["email"]},"enabled":{"type":"boolean","description":"true turns the channel on, false off; 1 and the text \"true\" or \"1\" also turn it on, and any other value turns it off","examples":[false]}},"required":["channel","enabled"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"channel":{"type":"string","description":"The channel you changed"},"enabled":{"type":"boolean","description":"Whether it is now on"},"settings":{"type":"object","properties":{"task_assigned":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task is assigned to you: push (phone notification) and email, each true when on"},"task_updated":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When a task you're involved in is updated: push (phone notification) and email, each true when on"},"task_due":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for tasks approaching their due date: push (phone notification) and email, each true when on"},"mentions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone @mentions you: push (phone notification) and email, each true when on"},"comments":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone comments on your items: push (phone notification) and email, each true when on"},"replies":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone replies to your comments: push (phone notification) and email, each true when on"},"reactions":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When someone reacts to your comment: push (phone notification) and email, each true when on"},"space_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to join a space: push (phone notification) and email, each true when on"},"event_invites":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"When you're invited to an event or someone responds to your invite: push (phone notification) and email, each true when on"},"event_reminders":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Reminders for upcoming calendar events: push (phone notification) and email, each true when on"},"system":{"type":"object","properties":{"push":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Important system announcements: push (phone notification) and email, each true when on"}},"description":"All your settings after the change"}}},"example":{"success":true,"channel":"email","enabled":false,"settings":{"task_assigned":{"push":true,"email":false},"task_updated":{"push":true,"email":false},"task_due":{"push":true,"email":false},"mentions":{"push":true,"email":false},"comments":{"push":true,"email":false},"replies":{"push":true,"email":false},"reactions":{"push":true,"email":false},"space_invites":{"push":true,"email":false},"event_invites":{"push":true,"email":false},"event_reminders":{"push":true,"email":false},"system":{"push":true,"email":false}}}}}},"400":{"description":"channel or enabled is missing, or channel is not push or email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications/test":{"post":{"tags":["Notifications"],"summary":"Send me a test email","description":"Sends a test notification email to your own address, to check that notification emails arrive. It ignores your notification settings and creates no notification in the app.\n\n**Permission:** `spaces.notifications.admin` (Send test notifications).","operationId":"sendTestNotification","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"message":{"type":"string","description":"Says where the email went"}}},"example":{"success":true,"message":"Test email sent to amina.otieno@acme.co.ke"}}}},"400":{"description":"Your account has no email address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"The email could not be sent; the answer is { success: false, error }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Email sending is not set up on the server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.notifications.admin"]}],"x-required-scopes":["spaces.notifications.admin"]}},"/notifications/{notificationId}/read":{"post":{"tags":["Notifications"],"summary":"Mark a notification as read","description":"Marks one of your notifications as read, with the time. Marking it again moves readAt to now.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"markNotificationAsRead","parameters":[{"name":"notificationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the notification","example":"6ad0a3f9d5c26de56de94a21"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"notification":{"type":"object","properties":{"_id":{"type":"string","description":"Notification ID"},"userId":{"type":"string","description":"Who it is for: you"},"actorId":{"type":"string","description":"ID of the person who caused it; absent when nobody did"},"category":{"type":"string","description":"The setting that governs it: task_assigned, task_updated, task_due, mentions, comments, replies, reactions, space_invites, event_invites, event_reminders or system"},"notificationType":{"type":"string","description":"mention, reply, reaction, task_assigned, task_updated, comment_added or system"},"title":{"type":"string","description":"Headline, e.g. Brian Mwangi replied to your comment"},"content":{"type":"string","description":"Body text"},"source":{"type":"string","description":"What it is about, as spaces:<kind>: spaces:task, spaces:wiki_page, spaces:pipeline, spaces:pipeline_record, spaces:event, spaces:comment, spaces:space or spaces:system"},"sourceEntityId":{"type":"string","description":"ID of that item; system for system notices"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"data":{"type":"object","properties":{"deepLink":{"type":"string","description":"Path in the Spaces web app that opens the item"},"payload":{"type":"object","properties":{"category":{"type":"string"},"recipientId":{"type":"string"},"actorId":{"type":"string"},"actorName":{"type":"string"},"organizationId":{"type":"string"},"targetType":{"type":"string"},"targetId":{"type":"string"},"targetTitle":{"type":"string"},"parentCommentId":{"type":"string"},"replyId":{"type":"string"},"replyContent":{"type":"string"},"spaceId":{"type":"string"},"deepLink":{"type":"string"}},"description":"Everything the notification was built from; its fields depend on the category"}},"description":"Extra detail"},"isRead":{"type":"boolean","description":"Whether you have read it"},"isArchived":{"type":"boolean","description":"Whether you archived it"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was sent"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Same as _id"},"readAt":{"type":"string","format":"date-time","description":"When you read it; absent while unread"}},"description":"The notification, now read"}}},"example":{"success":true,"notification":{"_id":"6ad0a3f9d5c26de56de94a21","userId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","category":"replies","notificationType":"reply","title":"Brian Mwangi replied to your comment","content":"Thanks, I'll file it with the October invoices.","source":"spaces:task","sourceEntityId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","data":{"deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c","payload":{"category":"replies","recipientId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","actorName":"Brian Mwangi","organizationId":"66a4b275003d1b495212b5aa","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","parentCommentId":"6ad0a3c2d5c26de56de94a10","replyId":"6ad0a3f8d5c26de56de94a1c","replyContent":"Thanks, I'll file it with the October invoices.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c"}},"isRead":true,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:01:46.000Z","updatedAt":"2026-10-15T10:05:00.000Z","id":"6ad0a3f9d5c26de56de94a21","readAt":"2026-10-15T10:05:00.000Z"}}}}},"400":{"description":"notificationId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No notification of yours has that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications/{notificationId}/unread":{"post":{"tags":["Notifications"],"summary":"Mark a notification as unread","description":"Marks one of your notifications as unread again and clears readAt.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"markNotificationAsUnread","parameters":[{"name":"notificationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the notification","example":"6ad0a3f9d5c26de56de94a21"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"notification":{"type":"object","properties":{"_id":{"type":"string","description":"Notification ID"},"userId":{"type":"string","description":"Who it is for: you"},"actorId":{"type":"string","description":"ID of the person who caused it; absent when nobody did"},"category":{"type":"string","description":"The setting that governs it: task_assigned, task_updated, task_due, mentions, comments, replies, reactions, space_invites, event_invites, event_reminders or system"},"notificationType":{"type":"string","description":"mention, reply, reaction, task_assigned, task_updated, comment_added or system"},"title":{"type":"string","description":"Headline, e.g. Brian Mwangi replied to your comment"},"content":{"type":"string","description":"Body text"},"source":{"type":"string","description":"What it is about, as spaces:<kind>: spaces:task, spaces:wiki_page, spaces:pipeline, spaces:pipeline_record, spaces:event, spaces:comment, spaces:space or spaces:system"},"sourceEntityId":{"type":"string","description":"ID of that item; system for system notices"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"data":{"type":"object","properties":{"deepLink":{"type":"string","description":"Path in the Spaces web app that opens the item"},"payload":{"type":"object","properties":{"category":{"type":"string"},"recipientId":{"type":"string"},"actorId":{"type":"string"},"actorName":{"type":"string"},"organizationId":{"type":"string"},"targetType":{"type":"string"},"targetId":{"type":"string"},"targetTitle":{"type":"string"},"parentCommentId":{"type":"string"},"replyId":{"type":"string"},"replyContent":{"type":"string"},"spaceId":{"type":"string"},"deepLink":{"type":"string"}},"description":"Everything the notification was built from; its fields depend on the category"}},"description":"Extra detail"},"isRead":{"type":"boolean","description":"Whether you have read it"},"isArchived":{"type":"boolean","description":"Whether you archived it"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was sent"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Same as _id"}},"description":"The notification, now unread"}}},"example":{"success":true,"notification":{"_id":"6ad0a3f9d5c26de56de94a21","userId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","category":"replies","notificationType":"reply","title":"Brian Mwangi replied to your comment","content":"Thanks, I'll file it with the October invoices.","source":"spaces:task","sourceEntityId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","data":{"deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c","payload":{"category":"replies","recipientId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","actorName":"Brian Mwangi","organizationId":"66a4b275003d1b495212b5aa","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","parentCommentId":"6ad0a3c2d5c26de56de94a10","replyId":"6ad0a3f8d5c26de56de94a1c","replyContent":"Thanks, I'll file it with the October invoices.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c"}},"isRead":false,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:01:46.000Z","updatedAt":"2026-10-15T10:01:46.000Z","id":"6ad0a3f9d5c26de56de94a21"}}}}},"400":{"description":"notificationId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No notification of yours has that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications/{notificationId}/archive":{"post":{"tags":["Notifications"],"summary":"Archive a notification","description":"Archives one of your notifications: it leaves the normal list and the unread count, and shows only when listing with isArchived true. Read or unread stays as it was; there is no call to unarchive.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"archiveNotification","parameters":[{"name":"notificationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the notification","example":"6ad0a3f9d5c26de56de94a21"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"notification":{"type":"object","properties":{"_id":{"type":"string","description":"Notification ID"},"userId":{"type":"string","description":"Who it is for: you"},"actorId":{"type":"string","description":"ID of the person who caused it; absent when nobody did"},"category":{"type":"string","description":"The setting that governs it: task_assigned, task_updated, task_due, mentions, comments, replies, reactions, space_invites, event_invites, event_reminders or system"},"notificationType":{"type":"string","description":"mention, reply, reaction, task_assigned, task_updated, comment_added or system"},"title":{"type":"string","description":"Headline, e.g. Brian Mwangi replied to your comment"},"content":{"type":"string","description":"Body text"},"source":{"type":"string","description":"What it is about, as spaces:<kind>: spaces:task, spaces:wiki_page, spaces:pipeline, spaces:pipeline_record, spaces:event, spaces:comment, spaces:space or spaces:system"},"sourceEntityId":{"type":"string","description":"ID of that item; system for system notices"},"spaceId":{"type":"string","description":"ID of the space it happened in, if any"},"data":{"type":"object","properties":{"deepLink":{"type":"string","description":"Path in the Spaces web app that opens the item"},"payload":{"type":"object","properties":{"category":{"type":"string"},"recipientId":{"type":"string"},"actorId":{"type":"string"},"actorName":{"type":"string"},"organizationId":{"type":"string"},"targetType":{"type":"string"},"targetId":{"type":"string"},"targetTitle":{"type":"string"},"parentCommentId":{"type":"string"},"replyId":{"type":"string"},"replyContent":{"type":"string"},"spaceId":{"type":"string"},"deepLink":{"type":"string"}},"description":"Everything the notification was built from; its fields depend on the category"}},"description":"Extra detail"},"isRead":{"type":"boolean","description":"Whether you have read it"},"isArchived":{"type":"boolean","description":"Whether you archived it"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was sent"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Same as _id"},"archivedAt":{"type":"string","format":"date-time","description":"When you archived it; absent until then"}},"description":"The notification, now archived"}}},"example":{"success":true,"notification":{"_id":"6ad0a3f9d5c26de56de94a21","userId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","category":"replies","notificationType":"reply","title":"Brian Mwangi replied to your comment","content":"Thanks, I'll file it with the October invoices.","source":"spaces:task","sourceEntityId":"6ad0a044d5c26de56de949a8","spaceId":"6a9f3c21b7e4a20f1c5d8e41","data":{"deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c","payload":{"category":"replies","recipientId":"66f1b2c3d4e5f60718293a4b","actorId":"66f1b2c3d4e5f60718293a5c","actorName":"Brian Mwangi","organizationId":"66a4b275003d1b495212b5aa","targetType":"task","targetId":"6ad0a044d5c26de56de949a8","targetTitle":"Send the October invoice","parentCommentId":"6ad0a3c2d5c26de56de94a10","replyId":"6ad0a3f8d5c26de56de94a1c","replyContent":"Thanks, I'll file it with the October invoices.","spaceId":"6a9f3c21b7e4a20f1c5d8e41","deepLink":"/spaces/6a9f3c21b7e4a20f1c5d8e41/tasks?task=6ad0a044d5c26de56de949a8&comment=6ad0a3f8d5c26de56de94a1c"}},"isRead":false,"isArchived":true,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T10:01:46.000Z","updatedAt":"2026-10-15T10:06:00.000Z","id":"6ad0a3f9d5c26de56de94a21","archivedAt":"2026-10-15T10:06:00.000Z"}}}}},"400":{"description":"notificationId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No notification of yours has that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications/mark-all-read":{"post":{"tags":["Notifications"],"summary":"Mark all notifications as read","description":"Marks all your unread notifications as read, or only those from one source. Archived ones are left as they are.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"markAllNotificationsAsRead","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Only notifications whose source starts with this text, e.g. spaces:task, spaces:event or spaces:system","examples":["spaces:task"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"modifiedCount":{"type":"integer","description":"How many notifications were marked read"}}},"example":{"success":true,"modifiedCount":4}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/notifications/archive-all":{"post":{"tags":["Notifications"],"summary":"Archive all notifications","description":"Archives all your notifications that are not archived yet, read or unread, or only those from one source.\n\n**Permission:** `spaces.notifications.update` (Manage notifications).","operationId":"archiveAllNotifications","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Only notifications whose source starts with this text, e.g. spaces:task, spaces:event or spaces:system","examples":["spaces:task"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"modifiedCount":{"type":"integer","description":"How many notifications were archived"}}},"example":{"success":true,"modifiedCount":37}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.notifications.update"]}],"x-required-scopes":["spaces.notifications.update"]}},"/users/fcm-token":{"post":{"tags":["People"],"summary":"Turn on phone notifications","description":"Registers a phone, tablet or browser to receive your Spaces notifications, using the notification token its app got from the device's notification service. It keeps getting them until the token is removed or stops working. Sending a token that is already registered is fine.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"addPushToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fcm_token":{"type":"string","description":"The device's notification token","examples":["dGVzdC1kZXZpY2UtdG9rZW46QVBBOTFiSEZ1cE5xX2s3cVZtWlJ4c0J3eWRhR3RvZzVQM0pYb0Q4cmtRZ0dfbUV0X2ZQ"]},"platform":{"type":"string","description":"What kind of app the token is for: ios, android, web or rn (the React Native app); leave out for the older apps. Other values are taken, but removePushToken cannot fully clear them","examples":["android"]}},"required":["fcm_token"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]},"delete":{"tags":["People"],"summary":"Turn off phone notifications","description":"Stops sending your notifications to a device, for example when you sign out on it. Removing a token that is not registered changes nothing.\n\n**Permission:** `spaces.users.update` (Update own profile).","operationId":"removePushToken","parameters":[{"name":"fcm_token","in":"query","required":true,"schema":{"type":"string"},"description":"The device's notification token, as sent to addPushToken","example":"dGVzdC1kZXZpY2UtdG9rZW46QVBBOTFiSEZ1cE5xX2s3cVZtWlJ4c0J3eWRhR3RvZzVQM0pYb0Q4cmtRZ0dfbUV0X2ZQ"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.update"]}],"x-required-scopes":["spaces.users.update"]}},"/users/photos":{"post":{"tags":["People"],"summary":"Get profile photos for several people","description":"Gets profile photo links for up to 500 people in your organisation in one call, for avatars. Links expire, so ask again rather than storing them.\n\n**Permission:** `spaces.users.read` (View users).","operationId":"getUserPhotos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"type":"array","items":{"type":"string"},"description":"IDs of the people, at most 500, as a JSON list","examples":[["66f1b2c3d4e5f60718293a4b"]]}},"required":["userIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"photos":{"type":"object","properties":{"66f1b2c3d4e5f60718293a4b":{"type":"string"}},"description":"Link to each person's photo from Kazee Chat, by user ID; people with no photo, or outside your organisation, are left out"}}},"example":{"photos":{"66f1b2c3d4e5f60718293a4b":"https://chat.kazee.africa/media/profiles/66f1b2c3d4e5f60718293a4b.jpg"}}}}},"400":{"description":"userIds is missing, not a list, has more than 500 IDs, or holds something that is not a user ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.users.read"]}],"x-required-scopes":["spaces.users.read"]}},"/calendar/connect":{"post":{"tags":["Calendar"],"summary":"Connect a Google calendar","description":"Connects your Google Calendar with the code Google returned after the link from getCalendarAuthUrl, reading your Google account's email and main calendar, and answers with status 201. Connecting again renews the same connection (same id), also after it was disconnected.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"connectCalendar","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The code Google added to redirectUri; it works once","examples":["4/0AVG7fiQx2vW9kLmP3sT8rYb6NcE1dHjU5aZqF0oKwIeR7tMgB2yXnV"]},"provider":{"type":"string","enum":["google"],"default":"google","description":"Calendar service; only google works"},"redirectUri":{"type":"string","description":"The same redirectUri given to getCalendarAuthUrl","examples":["https://spaces.kazee.africa/settings/calendar/callback"]}},"required":["code","provider","redirectUri"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"integration":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the person who connected it"},"provider":{"type":"string","description":"Which calendar service: google"},"tokenExpiry":{"type":"string","format":"date-time","description":"When Spaces' current access to the calendar runs out; it is renewed when needed"},"email":{"type":"string","description":"The Google account it is connected to"},"calendarId":{"type":"string","description":"Which Google calendar is read: the account's main one"},"selectedCalendars":{"type":"array","description":"Saved setting, not used yet: IDs of other Google calendars chosen for syncing"},"syncEnabled":{"type":"boolean","description":"Saved setting, not used yet: whether syncing is on"},"twoWaySync":{"type":"boolean","description":"Saved setting, not used yet: whether time blocks should also be written to Google"},"createEventsForTimeBlocks":{"type":"boolean","description":"Saved setting, not used yet: whether time blocks should become Google events"},"importEventsAsBlocking":{"type":"boolean","description":"Saved setting, not used yet: whether Google events should count as busy time"},"organizationId":{"type":"string","description":"ID of the organisation"},"isActive":{"type":"boolean","description":"Whether the connection is in use"},"createdAt":{"type":"string","format":"date-time","description":"When it was first connected"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Connection ID; use it as integrationId"}},"description":"The connection; Google's keys are kept by Spaces and never sent back"}}},"example":{"integration":{"userId":"66f1b2c3d4e5f60718293a4b","provider":"google","tokenExpiry":"2026-10-15T09:00:00.000Z","email":"grace.namutebi@gmail.com","calendarId":"grace.namutebi@gmail.com","selectedCalendars":[],"syncEnabled":true,"twoWaySync":false,"createEventsForTimeBlocks":true,"importEventsAsBlocking":true,"organizationId":"66a4b275003d1b495212b5aa","isActive":true,"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T08:00:00.000Z","id":"6ad1c3d8d5c26de56de94a55"}}}}},"400":{"description":"provider is not google, or Google refused the code (wrong, already used, or for another redirectUri)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Google could not be reached or failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]}},"/calendar/integrations/{integrationId}/sync":{"post":{"tags":["Calendar"],"summary":"Get events from a connected calendar","description":"Reads the events of one of your connected Google calendars between two dates and answers them in the calendar's own shape. Nothing is saved in Spaces; only the connection's lastSyncAt and lastSyncError change, and expired Google access is renewed on the way.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"listConnectedCalendarEvents","parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the calendar connection (id from listCalendarIntegrations)","example":"6ad1c3d8d5c26de56de94a55"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endDate":{"type":"string","format":"date-time","description":"End of the range","examples":["2026-10-26T00:00:00.000Z"]},"startDate":{"type":"string","format":"date-time","description":"Start of the range","examples":["2026-10-19T00:00:00.000Z"]}},"required":["endDate","startDate"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","description":"ID of the event in Google Calendar"},"externalProvider":{"type":"string","description":"Always google"},"title":{"type":"string","description":"The event's title in Google, or (No title)"},"description":{"type":"string","description":"Its notes in Google; absent when it has none"},"startDate":{"type":"string","format":"date-time","description":"When it starts; for an all-day event, the start of its day"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it is an all-day event in Google"},"location":{"type":"string","description":"Its location in Google; absent when it has none"},"category":{"type":"string","description":"Always meeting"},"color":{"type":"string","description":"Always #4285f4"},"metadata":{"type":"object","properties":{"googleEventId":{"type":"string","description":"Same as externalId"},"htmlLink":{"type":"string","description":"Link that opens the event in Google Calendar"}},"description":"Where it came from"}}},"description":"Events of the connected Google calendar in the range, earliest first, each repeat on its own; at most 2,500"},"truncated":{"type":"boolean","description":"Only when Google has more than 2,500 events in the range: true, and events holds the first 2,500; ask for a shorter range to get the rest"}}},"example":{"events":[{"externalId":"4k9v2m7q1r8s3t6u0w5x2y7z1a","externalProvider":"google","title":"Dentist","description":"Check-up","startDate":"2026-10-23T12:00:00.000Z","endDate":"2026-10-23T13:00:00.000Z","allDay":false,"location":"Kampala Road","category":"meeting","color":"#4285f4","metadata":{"googleEventId":"4k9v2m7q1r8s3t6u0w5x2y7z1a","htmlLink":"https://www.google.com/calendar/event?eid=NGs5djJtN3ExcjhzM3Q2dTB3NXgyeTd6MWE"}}],"truncated":true}}}},"400":{"description":"integrationId is not a valid ID; Google's access to the calendar has run out and cannot be renewed (connect it again); or Google refused the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No connection with that ID of yours that is in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Google could not be reached or failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]}},"/univer/documents/{documentId}/save":{"post":{"tags":["Sheets & documents"],"summary":"Save a sheet or document's content","description":"Replaces the content of a spreadsheet, document or presentation, raising its version by 1 and making you its last editor. With createSnapshot true, the content it had is kept first as an earlier version; the latest 50 are kept. Send baseVersion, the version you last loaded or saved, so that a save from a copy someone has since changed is refused (409) instead of replacing their changes; a save without it replaces whatever is there, as before. Needs the editor role or higher in its space, or the editor role on the document itself, given when it was shared; its creator's owner role counts only while they are an editor or owner of the space. Not while its space is archived.\n\n**Permission:** `spaces.univer.update` (Edit spreadsheets).","operationId":"updateDocumentContent","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseVersion":{"type":"integer","description":"The version you last loaded or saved (the document's version). When the document has another version now, someone else saved it since: the save is refused with 409. Leave it out to save whatever the version is","examples":[7]},"content":{"type":"object","description":"The new content, as the editor's JSON; a JSON text in a string also works","examples":[{"id":"6ad0a0d2d5c26de56de949e6","sheetOrder":["sheet1"],"name":"October budget","appVersion":"1.0.0","locale":"en-US","styles":{},"sheets":{"sheet1":{"id":"sheet1","name":"Sheet 1","rowCount":1000,"columnCount":26,"cellData":{"0":{"0":{"v":"Team"},"1":{"v":"Budget"}},"1":{"0":{"v":"Sales"},"1":{"v":18450}}},"rowData":{},"columnData":{}}}}]},"createSnapshot":{"type":"boolean","default":false,"description":"true first keeps the current content as an earlier version"},"snapshotSummary":{"type":"string","description":"A note for that earlier version","examples":["Before adding November"]}},"required":["content"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"string","description":"You, as a user ID"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}},"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":19021,"version":8,"collaborators":[{"userId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}}],"lastEditedBy":"66f1b2c3d4e5f60718293a4b","lastEditedAt":"2026-10-15T11:30:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":["budget"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:30:00.000Z","snapshotCount":4},"success":true}}}},"400":{"description":"documentId is not a valid ID, content is not the editor's content (a JSON object), or baseVersion is not a version number; nothing is saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of its space, nor an editor of the document; its creator counts only while an editor or owner of the space, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"baseVersion is not the document's current version: someone saved it since you loaded it (code VERSION_CONFLICT; the reply's currentVersion is the version it has now); nothing is saved, no earlier version is kept and the version stays","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.update"]}],"x-required-scopes":["spaces.univer.update"]}},"/univer/documents/{documentId}/versions/{versionId}/restore":{"post":{"tags":["Sheets & documents"],"summary":"Bring back an earlier version of a sheet or document","description":"Brings back the content an earlier version of a spreadsheet, document or presentation had. The content it has now is kept first as an earlier version (with the note \"Before restoring version N\"), so a restore can itself be undone; then the version's content becomes the current content, its version goes up by 1 and you become its last editor. The latest 50 earlier versions are kept. Needs the editor role or higher in its space, or the editor role on the document itself, given when it was shared; its creator's owner role counts only while they are an editor or owner of the space. Not while its space is archived.\n\n**Permission:** `spaces.univer.update` (Edit spreadsheets).","operationId":"restoreDocumentVersion","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the earlier version, from listDocumentVersions","example":"6ad0a0e9d5c26de56de949f0"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Its new version: 1 more than before the restore. Send it as baseVersion with the next save"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"string","description":"You, as a user ID"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}},"content":{"type":"object","properties":{"id":{"type":"string"},"sheetOrder":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"appVersion":{"type":"string"},"locale":{"type":"string"},"styles":{"type":"object","properties":{}},"sheets":{"type":"object","properties":{"sheet1":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rowCount":{"type":"integer"},"columnCount":{"type":"integer"},"cellData":{"type":"object","properties":{"0":{"type":"object","properties":{"0":{"type":"object","properties":{"v":{"type":"string"}}},"1":{"type":"object","properties":{"v":{"type":"string"}}}}},"1":{"type":"object","properties":{"0":{"type":"object","properties":{"v":{"type":"string"}}},"1":{"type":"object","properties":{"v":{"type":"integer"}}}}}}},"rowData":{"type":"object","properties":{}},"columnData":{"type":"object","properties":{}}}}}}},"description":"The content it has now: the restored version's"},"restoredVersion":{"type":"integer","description":"The version number the restored content had"},"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":18102,"version":8,"collaborators":[{"userId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}}],"lastEditedBy":"66f1b2c3d4e5f60718293a4b","lastEditedAt":"2026-10-15T11:30:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":["budget"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:30:00.000Z","snapshotCount":4},"content":{"id":"6ad0a0d2d5c26de56de949e6","sheetOrder":["sheet1"],"name":"October budget","appVersion":"1.0.0","locale":"en-US","styles":{},"sheets":{"sheet1":{"id":"sheet1","name":"Sheet 1","rowCount":1000,"columnCount":26,"cellData":{"0":{"0":{"v":"Team"},"1":{"v":"Budget"}},"1":{"0":{"v":"Sales"},"1":{"v":18450}}},"rowData":{},"columnData":{}}}},"restoredVersion":6,"success":true}}}},"400":{"description":"documentId or versionId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of its space, nor an editor of the document; its creator counts only while an editor or owner of the space, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, it is archived, or it has no earlier version with that ID (the latest 50 are kept)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"That version's stored content is not the editor's content (empty or not a JSON object), so it is not brought back; nothing changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The version's or the current content could not be read or stored; when the content could not be read nothing changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"File storage is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.univer.update"]}],"x-required-scopes":["spaces.univer.update"]}},"/univer/documents/{documentId}/collaborators":{"post":{"tags":["Sheets & documents"],"summary":"Add a collaborator to a sheet or document","description":"Adds a person to the collaborators of a spreadsheet, document or presentation, as an editor or viewer, and answers with the document. A viewer can then open it and read its content even outside its space, and an editor can change it too. Someone already on the list gets the new role instead; the owner's role cannot be changed. Needs the editor role or higher in its space, or the editor role on the document itself, given when it was shared; its creator's owner role counts only while they are an editor or owner of the space. Not while its space is archived.\n\n**Permission:** `spaces.univer.update` (Edit spreadsheets).","operationId":"addDocumentCollaborator","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["editor","viewer"],"default":"viewer","description":"Their role on the document","examples":["viewer"]},"userId":{"type":"string","description":"User ID of the person, or their email (matched ignoring case). A user ID is not checked against the people in the organisation","examples":["66f1b2c3d4e5f60718293a6d"]}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last saved it: a user ID, or filled in like creatorId"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":18734,"version":7,"collaborators":[{"userId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}},{"userId":{"firstName":"Grace","lastName":"Wanjiru","email":"grace.wanjiru@example.com","id":"66f1b2c3d4e5f60718293a6d"},"role":"viewer","addedAt":"2026-10-15T11:50:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}}],"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"lastEditedAt":"2026-10-15T11:05:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":["budget"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:50:00.000Z","snapshotCount":3}}}}},"400":{"description":"documentId is not a valid ID, role is not editor or viewer, the person is the document's owner, or saving failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of its space, nor an editor of the document; its creator counts only while an editor or owner of the space, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID (or it is archived), or no person with that email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.univer.update"]}],"x-required-scopes":["spaces.univer.update"]}},"/settings/ai-config/test":{"post":{"tags":["Settings"],"summary":"Test an AI provider key","description":"Sends a one-word request to the AI provider to check a key works: the key in this request, so you can test before saving, or else the saved one. Needs an organisation admin, and counts toward the limit of 10 AI setting changes or tests in a row. Nothing is saved; the test gives up after 15 seconds.\n\n**Permission:** `spaces.settings.admin` (Test AI config).","operationId":"testOrgAIConfig","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string","description":"Key to test, at least 8 characters. Leave out (or send a shorter one) to test the saved key","examples":["sk-fake-example-key-0000"]},"model":{"type":"string","description":"Model to test with. Defaults to the saved model when testing the saved key, then to the provider's default model","examples":["gpt-4.1"]},"provider":{"type":"string","enum":["openai","anthropic"],"description":"Which AI provider to test","examples":["openai"]}},"required":["provider"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"provider":{"type":"string","description":"The provider tested"},"model":{"type":"string","description":"The model the test used"}}},"example":{"ok":true,"provider":"openai","model":"gpt-4.1"}}}},"400":{"description":"provider is not openai or anthropic, no key is given or saved for it (code AI_NOT_CONFIGURED), or the provider rejected the key (code INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"You made 10 AI setting changes or tests in a row; wait a minute after the last one (code RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The saved key cannot be read, e.g. the server's encryption key changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The provider failed, or gave no answer within 15 seconds (code PROVIDER_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.settings.admin"]}],"x-required-scopes":["spaces.settings.admin"]}},"/integrations/yeastar/test":{"post":{"tags":["Settings"],"summary":"Test the phone system connection","description":"Logs in to the phone system to check the settings work: the saved ones, or the ones in this request when you pass baseUrl, clientId and clientSecret together, so you can test before saving. Needs an organisation admin. The phone system may be on a private network (10.x, 172.16-31.x, 192.168.x), but an address on the platform's own network (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names), by name or by what the name resolves to, is not tried (400, code INTERNAL_ADDRESS). A test of the saved settings records its result and the device details on them (getMyPhoneStatus only reports calling as available after a successful one); a test of unsaved settings records nothing.\n\n**Permission:** `spaces.integrations.admin` (Test integrations).","operationId":"testPhoneSystemConnection","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"apiPath":{"type":"string","description":"Path of its API; empty means the type's usual path. Only used with baseUrl, clientId and clientSecret","examples":[""]},"baseUrl":{"type":"string","description":"Address of the phone system to test; https:// is added when no scheme is given. Leave out to test the saved settings","examples":["https://pbx.example.com:8088"]},"clientId":{"type":"string","description":"API user name (K2 and S-Series) or client ID (P-Series) to test","examples":["fake-api-user"]},"clientSecret":{"type":"string","description":"API password (K2 and S-Series) or client secret (P-Series) to test","examples":["fake-api-password"]},"insecureTLS":{"type":"boolean","description":"true (or the string \"true\") to accept a self-signed certificate; otherwise the saved choice applies. Only used with baseUrl, clientId and clientSecret","examples":[true]},"pbxType":{"type":"string","enum":["p_series","k2_v2"],"description":"Phone system model to test with (k2_v2 or p_series); defaults to the saved type, then k2_v2. Only used with baseUrl, clientId and clientSecret","examples":["k2_v2"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"tokenExpiresIn":{"type":"integer","description":"Seconds the phone system's login lasts (1800 on K2 and S-Series)"},"pbxInfo":{"type":"object","properties":{"devicename":{"type":"string","description":"Device model name"},"serialNumber":{"type":"string","description":"Device serial number"},"firmwareVersion":{"type":"string","description":"Firmware version"},"systemTime":{"type":"string","description":"The device's clock, as it reports it"},"uptime":{"type":"string","description":"How long the device has been running, as it reports it"}},"description":"Device details the phone system reported (K2 and S-Series only); null when it gave none"}}},"example":{"ok":true,"tokenExpiresIn":1800,"pbxInfo":{"devicename":"S50","serialNumber":"3631A0000001","firmwareVersion":"30.12.0.16","systemTime":"2026-10-15 14:00:00","uptime":"12:04:31:10"}}}}},"400":{"description":"No login details are given or saved (code NOT_CONFIGURED); the address is on the platform's own network (code INTERNAL_ADDRESS); or the phone system rejected the login details (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The saved login details cannot be read, e.g. the server's encryption key changed (code DECRYPT_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The phone system failed or could not be reached (code PBX_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.admin"]}],"x-required-scopes":["spaces.integrations.admin"]}},"/integrations/yeastar/test-call":{"post":{"tags":["Settings"],"summary":"Place a test call","description":"Places a real call to check the phone system works end to end: it rings caller first and, once answered, connects to callee. Needs an organisation admin. Unlike click-to-call, any extension can be the caller, the call goes through even when calling is turned off in the settings, and nothing is logged.\n\n**Permission:** `spaces.integrations.admin` (Test integrations).","operationId":"testPhoneCall","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"autoAnswer":{"type":"boolean","default":false,"description":"true (or the string \"true\") to have the caller's phone answer by itself, if it supports that","examples":[true]},"callee":{"type":"string","description":"Extension or phone number to connect to; must differ from caller","examples":["2002"]},"caller":{"type":"string","description":"Extension to ring first","examples":["2001"]},"dialPermission":{"type":"string","description":"Extension whose call permissions apply; needed only when caller is not an extension (e.g. a ring group or queue). Passed to the phone system as is","examples":["2001"]}},"required":["callee","caller"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"callId":{"type":"string","description":"ID the phone system gave the call"},"caller":{"type":"string","description":"The extension that was rung first"},"callee":{"type":"string","description":"The extension or number it was connected to"}}},"example":{"ok":true,"callId":"1760536800.1234","caller":"2001","callee":"2002"}}}},"400":{"description":"caller or callee is only spaces, they are the same (code SAME_NUMBER), the phone system is not set up (code NOT_CONFIGURED), the saved address is on the platform's own network (code INTERNAL_ADDRESS; saved before addresses were checked), so nothing is called, or the phone system rejected the saved login details (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The saved login details cannot be read, e.g. the server's encryption key changed (code DECRYPT_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The phone system failed or could not be reached (code PBX_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.admin"]}],"x-required-scopes":["spaces.integrations.admin"]}},"/integrations/yeastar/call":{"post":{"tags":["Messages & calls"],"summary":"Call a phone number","description":"Places a call from your own linked extension: the phone system rings your phone first, then connects you to callee. Anyone with this permission and a linked extension may call; you cannot choose another extension to call from. For a pipeline record (pipelineId or recordId given), you must be able to see the pipeline's space, the record must be in that pipeline and calling must be on for the pipeline, and a refusal dials and logs nothing. Every dial attempt, placed or failed, is saved to the communication log, and to the record's activity when recordId is given.\n\n**Permission:** `spaces.comms.create` (Send communications).","operationId":"startPhoneCall","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"autoAnswer":{"type":"boolean","default":true,"description":"false (or the string \"false\") to have your phone ring normally instead of answering by itself","examples":[true]},"callee":{"type":"string","description":"Phone number or extension to call: 3 to 20 digits with an optional leading +; spaces, dashes, dots and brackets are removed","examples":["+254 712 345 678"]},"pipelineId":{"type":"string","description":"Pipeline of the record the call is about, kept with the log entry; the pipeline's rules apply, as the description says","examples":["6ad1b0c2e4f5a60718293b06"]},"recordId":{"type":"string","description":"Pipeline record the call is about; the call shows in its activity. Without pipelineId, the record's own pipeline's rules apply","examples":["6ad1b0c2e4f5a60718293b07"]}},"required":["callee"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"callId":{"type":"string","description":"ID the phone system gave the call"},"caller":{"type":"string","description":"Your extension, which was rung first"},"callee":{"type":"string","description":"The number called, with spaces and punctuation removed"}}},"example":{"ok":true,"callId":"1760536800.1235","caller":"2001","callee":"+254712345678"}}}},"400":{"description":"callee is only spaces (code MISSING_CALLEE), is not 3 to 20 digits (code INVALID_CALLEE) or is your own extension (code SAME_NUMBER), pipelineId or recordId is not a valid ID, the saved address is on the platform's own network (code INTERNAL_ADDRESS; saved before addresses were checked), so nothing is called, or the phone system rejected the saved login details (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The send is for a pipeline whose space you cannot see (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"There is no pipeline with that pipelineId (or it is archived), or no record with that recordId in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The phone system is not set up (code NOT_CONFIGURED) or calling is turned off (code PBX_DISABLED), you have no linked extension (code NO_EXTENSION), or calling is turned off for the pipeline (code CHANNEL_DISABLED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The saved login details cannot be read, e.g. the server's encryption key changed (code DECRYPT_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The phone system failed or could not be reached (code PBX_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comms.create"]}],"x-required-scopes":["spaces.comms.create"]}},"/integrations/yeastar/mappings/auto-map":{"post":{"tags":["Settings"],"summary":"Link people to extensions by email","description":"Fetches the phone system's extensions and links each one whose email address matches a person in the organisation (ignoring case, skipping deactivated people). Needs an organisation admin. People who already have a link are left alone and listed in conflicts unless overwrite is on, and an extension already linked to someone else is never taken over. Linked extensions also show on the people's profiles.\n\n**Permission:** `spaces.integrations.update` (Configure integrations).","operationId":"createPhoneExtensionMappingsByEmail","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overwrite":{"type":"boolean","default":false,"description":"true (or the string \"true\") to replace the links people already have","examples":[false]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","description":"How many new links were made"},"updated":{"type":"integer","description":"How many existing links were replaced (only with overwrite)"},"skippedNoMatch":{"type":"integer","description":"Extensions with no email address, or one that matches nobody"},"conflicts":{"type":"array","items":{"type":"object","properties":{"extensionNumber":{"type":"string","description":"The extension"},"email":{"type":"string","description":"Its email address, in lower case"},"reason":{"type":"string","description":"Why: \"extension already mapped to another user\", \"user already has a mapping (use overwrite=true to replace)\", or the error the save gave"}}},"description":"Extensions that matched someone but were not linked, with why"},"totalExtensions":{"type":"integer","description":"How many extensions the phone system has"}}},"example":{"created":4,"updated":0,"skippedNoMatch":6,"conflicts":[{"extensionNumber":"2003","email":"amina@example.com","reason":"user already has a mapping (use overwrite=true to replace)"}],"totalExtensions":11}}}},"400":{"description":"The phone system is not set up (code NOT_CONFIGURED), the saved address is on the platform's own network (code INTERNAL_ADDRESS; saved before addresses were checked), so nothing is called, or the phone system rejected the saved login details (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The saved login details cannot be read, e.g. the server's encryption key changed (code DECRYPT_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The phone system failed or could not be reached (code PBX_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.update"]}],"x-required-scopes":["spaces.integrations.update"]}},"/integrations/sms/test":{"post":{"tags":["Settings"],"summary":"Send a test SMS","description":"Sends a real text message to check SMS works: with the saved settings, or with the settings in this request when you pass provider, so you can test before saving. Needs an organisation admin. The provider may be on a private network (10.x, 172.16-31.x, 192.168.x), but an address on the platform's own network (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names), by name or by what the name resolves to, is not tried (400, code INTERNAL_ADDRESS). A test of the saved settings records its result on them (lastTestedAt, lastTestStatus, lastTestError); a test of unsaved settings records nothing.\n\n**Permission:** `spaces.integrations.admin` (Test integrations).","operationId":"testSmsProvider","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"celcom":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address texts are sent to; defaults to Celcom's send address; it may be on a private network (10.x, 172.16-31.x, 192.168.x), not on the platform's own (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names)"},"apiKey":{"type":"string","description":"Celcom API key, at least 8 characters"},"partnerId":{"type":"integer","description":"Celcom partner ID, above 0"},"passType":{"type":"string","description":"How the API key is passed; defaults to plain"}},"description":"With provider celcom: the Celcom details to test; apiKey is needed","examples":[{"apiKey":"fake-celcom-api-key-0000","partnerId":1234,"passType":"plain"}]},"defaultCountryCode":{"type":"string","description":"With provider: the country code for local numbers (a leading + is removed)","examples":["254"]},"generic":{"type":"object","properties":{"baseUrl":{"type":"string","description":"Address the request goes to; must start with http:// or https://; it may be on a private network (10.x, 172.16-31.x, 192.168.x), not on the platform's own (localhost, loopback, link-local or cloud metadata, IPv6 local, cluster names)"},"method":{"type":"string","enum":["POST","PUT"],"description":"Defaults to POST"},"contentType":{"type":"string","enum":["application/json","application/x-www-form-urlencoded"],"description":"Defaults to application/json"},"headersTemplate":{"type":"string","description":"Request headers, one \"Key: Value\" per line; {{authHeader}} stands for the secret"},"bodyTemplate":{"type":"string","description":"Request body; {{phone}}, {{message}} and {{senderId}} are filled in"},"authHeader":{"type":"string","description":"Secret for {{authHeader}}, stored encrypted"},"successPath":{"type":"string","description":"Dotted path of a field in the provider's reply; empty means any 2xx reply counts"},"successValue":{"type":"string","description":"Value that field must have for a send to count"}},"description":"With provider generic_http: the provider details to test, as in updateSmsProviderConfig; baseUrl is needed","examples":[{"baseUrl":"https://sms.example.com/api/send","bodyTemplate":"{\"to\":\"{{phone}}\",\"text\":\"{{message}}\"}","authHeader":"fake-bearer-token-0000","headersTemplate":"Authorization: Bearer {{authHeader}}"}]},"message":{"type":"string","description":"Text to send. Defaults to \"Test SMS from <your first name> workspace at <time>\"","examples":["Test from Example Ltd"]},"provider":{"type":"string","enum":["celcom","generic_http"],"description":"Pass to test the settings in this request instead of the saved ones. Leave out to test the saved settings","examples":["celcom"]},"senderId":{"type":"string","description":"With provider: the sender name or short code; needed for Celcom","examples":["ExampleCo"]},"to":{"type":"string","description":"Phone number to text; a local number gets the country code (see defaultCountryCode)","examples":["0712345678"]}},"required":["to"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"providerMessageId":{"type":"string","description":"ID the provider gave the message; empty if it gave none"},"normalisedTo":{"type":"string","description":"The number the text went to, after the country code was applied"}}},"example":{"ok":true,"providerMessageId":"88234710","normalisedTo":"+254712345678"}}}},"400":{"description":"to is only spaces; with provider: the Celcom apiKey or senderId, or the generic baseUrl, is missing; without provider: no settings are saved (code NOT_CONFIGURED) or the saved ones cannot be read; the provider's address is on the platform's own network (code INTERNAL_ADDRESS); or the provider rejected the credentials (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The provider failed or could not be reached (code PROVIDER_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"With provider: the server has no encryption key set up (code CRYPTO_NOT_CONFIGURED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.admin"]}],"x-required-scopes":["spaces.integrations.admin"]}},"/integrations/sms/send":{"post":{"tags":["Messages & calls"],"summary":"Send an SMS","description":"Sends a text message through the organisation's SMS provider, or the server's default Celcom account when it has no SMS settings; settings that are turned off send nothing. Anyone with this permission may send; for a pipeline record (pipelineId or recordId given), you must be able to see the pipeline's space, the record must be in that pipeline and SMS must be on for the pipeline, and a refusal sends and logs nothing. Every attempt, sent or failed, is saved to the communication log, and to the record's activity when recordId is given.\n\n**Permission:** `spaces.comms.create` (Send communications).","operationId":"sendSms","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":1000,"description":"Text to send, up to 1000 characters (spaces at the ends are removed)","examples":["Hello Jane, your installation is booked for Friday at 10:00."]},"pipelineId":{"type":"string","description":"Pipeline of the record the text is about, kept with the log entry; the pipeline's rules apply, as the description says","examples":["6ad1b0c2e4f5a60718293b06"]},"recordId":{"type":"string","description":"Pipeline record the text is about; the send shows in its activity. Without pipelineId, the record's own pipeline's rules apply","examples":["6ad1b0c2e4f5a60718293b07"]},"to":{"type":"string","description":"Phone number to text. A local number gets the organisation's country code: with 254, 0712345678 becomes +254712345678","examples":["+254712345678"]}},"required":["message","to"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"providerMessageId":{"type":"string","description":"ID the provider gave the message; empty if it gave none"}}},"example":{"ok":true,"providerMessageId":"88234711"}}}},"400":{"description":"to or message is only spaces (codes MISSING_TO, MISSING_MESSAGE), message is over 1000 characters (code MESSAGE_TOO_LONG), pipelineId or recordId is not a valid ID, the organisation's saved provider address is on the platform's own network (code INTERNAL_ADDRESS; saved before addresses were checked), so nothing is sent, or the provider rejected the organisation's credentials (code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The send is for a pipeline whose space you cannot see (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"There is no pipeline with that pipelineId (or it is archived), or no record with that recordId in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No SMS provider is set up (code NOT_CONFIGURED), SMS is turned off for the organisation (code SMS_DISABLED), or SMS is turned off for the pipeline (code CHANNEL_DISABLED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The organisation's SMS settings cannot be read, e.g. the server's encryption key changed (code DECRYPT_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The provider failed or could not be reached (code PROVIDER_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comms.create"]}],"x-required-scopes":["spaces.comms.create"]}},"/integrations/email/accounts/{accountId}/test":{"post":{"tags":["Settings"],"summary":"Test an email account","description":"Logs in to the account's mail server with its saved details to check they work, without sending an email. Needs an organisation admin. The result is saved on the account (lastTestedAt, lastTestStatus, lastTestError). A failed test answers ok false with the reason in error: status 400 when the mail server refused the login, 502 when it could not be reached.\n\n**Permission:** `spaces.integrations.admin` (Test integrations).","operationId":"testEmailAccount","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the account to test","example":"3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"true when the mail server accepted the login"}}},"example":{"ok":true}}}},"400":{"description":"The mail server refused the login. ok is false and error gives its reason","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The organisation has no email settings, or no account with that accountId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The account is turned off or has no password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The account's saved password cannot be read, e.g. the server's encryption key changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The mail server could not be reached or failed. ok is false and error gives the reason","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.integrations.admin"]}],"x-required-scopes":["spaces.integrations.admin"]}},"/integrations/email/send":{"post":{"tags":["Messages & calls"],"summary":"Send an email","description":"Sends an email from one of the organisation's email accounts, usually to a contact on a pipeline record. For a pipeline record (pipelineId or recordId given), you must be able to see the pipeline's space, the record must be in that pipeline, email must be on for the pipeline and, when the pipeline lists allowed accounts, the account must be one of them; a refusal sends and logs nothing. Every attempt, sent or failed, is saved to the communication log, and to the record's activity when recordId is given. An unknown account answers 404, and a turned-off or password-less one 409.\n\n**Permission:** `spaces.comms.create` (Send communications).","operationId":"sendEmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","description":"ID of the email account to send from (see getEmailProviderConfig)","examples":["3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90"]},"bcc":{"type":"string","description":"Blind copy addresses, in the same forms as to","examples":["sales-archive@example.com"]},"cc":{"type":"string","description":"Copy addresses, in the same forms as to","examples":["accounts@client.example"]},"html":{"type":"string","description":"Body as HTML. With serverRender, the template's body is used instead","examples":["<p>Hello Jane,</p><p>Here is your quote for the fibre link.</p>"]},"pipelineId":{"type":"string","description":"Pipeline of the record the email is about, kept with the log entry; the pipeline's rules apply, as the description says","examples":["6ad1b0c2e4f5a60718293b06"]},"recordId":{"type":"string","description":"Pipeline record the email is about; the send shows in its activity. Without pipelineId, the record's own pipeline's rules apply. Needed for serverRender","examples":["6ad1b0c2e4f5a60718293b07"]},"replyTo":{"type":"string","description":"Address replies go to. Defaults to the account's reply-to address, then its from address","examples":["support@example.com"]},"serverRender":{"type":"boolean","description":"true (or the string \"true\") to have the server fill the template's subject and bodies with the record's values, replacing subject, html and text. Needs templateId and recordId, and is ignored without them. Defaults to false","examples":[false]},"subject":{"type":"string","description":"Subject line; an empty one is sent as (no subject). With serverRender, the template's subject is used instead","examples":["Your quote from Example Ltd"]},"templateId":{"type":"string","description":"ID of the email template the email came from, kept with the log entry. With serverRender, the server fills in this template itself","examples":["6ad1b0c2e4f5a60718293b08"]},"text":{"type":"string","description":"Plain-text body. Without it, the HTML body with its tags removed is sent as the plain text. With serverRender, the template's text is used instead","examples":["Hello Jane, here is your quote for the fibre link."]},"to":{"type":"string","description":"Recipient address, or several separated by commas or semicolons (a JSON list of addresses also works)","examples":["jane@client.example"]}},"required":["accountId","subject","to"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when it worked"},"messageId":{"type":"string","description":"ID the mail server gave the email; empty if it gave none"}}},"example":{"ok":true,"messageId":"<0f6c2e9a-5b1d-4c3e-8a7f-2d9b4e6c1a30@example.com>"}}}},"400":{"description":"pipelineId or recordId is not a valid ID, or serverRender is on but the template or the record is not found in your organisation (code TEMPLATE_RENDER_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The send is for a pipeline whose space you cannot see (you are not a member and it is not public), or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The organisation has no email settings, or no account with that accountId (code ACCOUNT_NOT_FOUND); or no pipeline with that pipelineId (or it is archived), or no record with that recordId in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The account is turned off or has no password (code ACCOUNT_UNAVAILABLE), email is turned off for the pipeline (code CHANNEL_DISABLED), or the account is not one of the pipeline's allowed accounts (code ACCOUNT_NOT_ALLOWED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"description":"The account's saved password cannot be read, e.g. the server's encryption key changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"to holds no address, or the mail server refused the email or could not be reached (code SEND_FAILED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.comms.create"]}],"x-required-scopes":["spaces.comms.create"]}},"/pipelines/{pipelineId}/email-templates/{templateId}/preview":{"post":{"tags":["Pipelines"],"summary":"Preview an email template on a record","description":"Fills in a template's macros with a record's values and your own details, the way the email would be written, without sending anything. Without recordId, or with one that is not a record of this pipeline, record and field macros come out empty or as their fallback. You must be able to see the pipeline's space (a member, or it is public).\n\n**Permission:** `spaces.pipelines.read` (View pipelines).","operationId":"getPipelineEmailTemplatePreview","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"templateId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the template","example":"6ad1c2e0f3a4b5c6d7e8f903"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recordId":{"type":"string","description":"ID of a record of this pipeline whose values fill the macros","examples":["6ad1c2e0f3a4b5c6d7e8f902"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"preview":{"type":"object","properties":{"subject":{"type":"string","description":"Subject line"},"bodyHtml":{"type":"string","description":"HTML body"},"bodyText":{"type":"string","description":"Plain-text body; empty if the template has none"},"allowedAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts it may be sent from; empty means any the pipeline allows"}},"description":"The template with its macros filled in"}}},"example":{"preview":{"subject":"Your quote for Westlands office fit-out","bodyHtml":"<p>Hello Wanjiru,</p><p>Following up on the quote we sent on 2026-10-13. Reply to this email with any questions.</p><p>Amina</p>","bodyText":"Hello Wanjiru,\n\nFollowing up on the quote we sent on 2026-10-13. Reply to this email with any questions.\n\nAmina","allowedAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"]}}}}},"400":{"description":"pipelineId, templateId or recordId is not a valid ID (code INVALID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You cannot see the pipeline's space: you are not a member and it is not public (code FORBIDDEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with that ID in this pipeline (code NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.read"]}],"x-required-scopes":["spaces.pipelines.read"]}},"/code-functions/{functionId}/test":{"post":{"tags":["Pipelines"],"summary":"Test a code function","description":"Runs a code function once as a dry run, with its saved time and memory limits. Only organisation admins may call it. The changes it asks for (field writes, notifications, emails, chat messages, SMS, calls) are listed in sideEffects but not carried out; web requests it makes (up to 3) and records it reads are real. If the code does not compile or throws, the answer has status 400.\n\n**Permission:** `spaces.codeFunctions.admin` (Execute code functions).","operationId":"testCodeFunction","parameters":[{"name":"functionId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the code function","example":"6ad1c2e0f3a4b5c6d7e8f905"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recordId":{"type":"string","description":"Record to run it on, from any pipeline. Without it, or if it is not found, the code gets a made-up test record and pipeline","examples":["6ad1c2e0f3a4b5c6d7e8f902"]},"sourceCode":{"type":"string","description":"Unsaved code to try instead of the saved code; blank uses the saved code","examples":["const phone = ctx.record.fieldValues[\"phone\"];\nif (phone) {\n  await sendSms(phone, \"Welcome to iNet, \" + ctx.record.title + \"!\");\n  log(\"SMS queued for \" + phone);\n}"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the code compiled and ran without throwing"},"error":{"description":"Why it failed, or null"},"logs":{"type":"array","items":{"type":"string"},"description":"What the code logged with log(), at most 50 lines"},"sideEffects":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"setField, setFieldOn, notify, sendEmail, sendChatMessage, sendSms or initiateCall"},"phone":{"type":"string","description":"sendSms only: the number to text"},"message":{"type":"string","description":"sendSms, notify and sendChatMessage: the text to send"}}},"description":"Changes the code asked for, in order, not carried out: a type plus that change's details"},"compilationErrors":{"type":"array","description":"Compiler errors and warnings; empty when it compiled"},"duration":{"type":"integer","description":"Milliseconds the run took"}}},"example":{"success":true,"error":null,"logs":["SMS queued for +254712345678"],"sideEffects":[{"type":"sendSms","phone":"+254712345678","message":"Welcome to iNet, Westlands office fit-out!"}],"compilationErrors":[],"duration":38}}}},"400":{"description":"functionId or recordId is not a valid ID; or the code did not compile or threw while running, and the body is the usual reply with success false and error saying why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No code function with that ID (code NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.codeFunctions.admin"]}],"x-required-scopes":["spaces.codeFunctions.admin"]}},"/pipelines/{pipelineId}/custom-buttons":{"post":{"tags":["Pipelines"],"summary":"Add a custom button to a pipeline","description":"Adds a custom button to a pipeline: a button on its records that runs a list of actions without moving the record to another stage. Needs the editor role or higher in the pipeline's space, which must not be archived. The button goes after the pipeline's other buttons, and the reply is the whole updated pipeline.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"addPipelineCustomButton","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"},"description":"Actions to run, each { id, actionType, isActive, config, orderNum } as on transitions. actionType is email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms, and config holds that action's settings. A JSON array in a string also works","examples":[[{"id":"action-stamp-quote-date","actionType":"update_field","isActive":true,"config":{"fieldId":"quoteSentOn","useCurrentDate":true},"orderNum":0},{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}]]},"color":{"type":"string","description":"Button colour as hex. Defaults to #3b82f6","examples":["#3b82f6"]},"commentPrompt":{"type":"string","description":"What the app asks for when a comment is needed. Defaults to \"Please add a note\"","examples":["Say what the client agreed to"]},"conditions":{"type":"array","items":{"type":"object"},"description":"Conditions the record must meet for the button to run, each { id, fieldPath, fieldLabel, operator, value, logicOperator } as on transitions; they are checked against the record as it is before fieldValues are saved. A JSON array in a string also works","examples":[[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}]]},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean"},"prompt":{"type":"string"}},"description":"Whether the app asks before running it, and what it asks: { enabled, prompt }. The server does not ask. A JSON object in a string also works. Defaults to off, with the prompt \"Are you sure?\"","examples":[{"enabled":true,"prompt":"Send the quote to the client now?"}]},"description":{"type":"string","description":"What the button does","examples":["Stamps the quote date and tells the assignees"]},"icon":{"type":"string","description":"Name of the icon to show on the button","examples":["send"]},"id":{"type":"string","description":"ID for the button, not used by another button on the pipeline","examples":["send-quote"]},"isActive":{"type":"boolean","description":"false adds it turned off. Must be a JSON true or false: anything else, the text \"false\" too, leaves it on","examples":[true]},"label":{"type":"string","description":"Text on the button","examples":["Send quote"]},"requireComment":{"type":"boolean","description":"Whether running it needs notes. The text \"true\" or \"false\" also works. Defaults to false","examples":[false]},"requiredRole":{"type":"string","description":"admin: only organisation admins may run it. Any other value, or empty: anyone with the contributor role or higher in the space","examples":["admin"]},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"IDs of the stages where the button shows and may run; empty means every stage. A JSON array in a string also works","examples":[["quoted"]]}},"required":["id","label"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string","description":"Name of the pipeline"},"description":{"type":"string","description":"What it is for"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"orderNum":{"type":"integer"},"isDefault":{"type":"boolean"},"positionX":{"type":"integer"},"positionY":{"type":"integer"}}},"description":"Its stages (board columns): id, name, color, orderNum, isDefault, and positionX / positionY on the workflow map"},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"fromStageId":{"type":"string"},"toStageId":{"type":"string"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"strategy":{"type":"string"},"userPool":{"type":"array","items":{"type":"string"}}}},"orderNum":{"type":"integer"}}}},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"fieldPath":{"type":"string"},"fieldLabel":{"type":"string"},"operator":{"type":"string"},"value":{"type":"integer"},"logicOperator":{"type":"string"}}}},"requiredFieldIds":{"type":"array","items":{"type":"string"}},"requireComment":{"type":"boolean"},"commentPrompt":{"type":"string"},"isGlobal":{"type":"boolean"},"fromStageIds":{"type":"array"},"isActive":{"type":"boolean"}}},"description":"Allowed moves between stages, each with the actions it runs and the conditions and fields it needs"},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Button ID, as given when it was added"},"label":{"type":"string","description":"Text on the button"},"description":{"type":"string","description":"What the button does"},"icon":{"type":"string","description":"Name of the icon shown on the button"},"color":{"type":"string","description":"Button colour, as hex"},"visibleInStages":{"type":"array","items":{"type":"string"},"description":"IDs of the stages where the button shows and may run; empty means every stage"},"requiredRole":{"type":"string","description":"admin: only organisation admins may run it; empty: anyone who may run buttons"},"confirmation":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the app asks for confirmation first"},"prompt":{"type":"string","description":"The question it asks"}},"description":"Whether the app asks before running it, and what it asks"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action ID"},"actionType":{"type":"string","description":"email, webhook, assign, update_field, create_task, notify, kazee_chat, code or sms"},"isActive":{"type":"boolean","description":"Whether the action runs"},"config":{"type":"object","properties":{"fieldId":{"type":"string"},"useCurrentDate":{"type":"boolean"}},"description":"Settings for that kind of action, the same as on transitions"},"orderNum":{"type":"integer","description":"Run order; lower runs first"}}},"description":"What the button runs, in orderNum order; inactive actions are skipped"},"conditions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID"},"fieldPath":{"type":"string","description":"Record field it looks at: a custom field ID, or title, priority or stageName"},"fieldLabel":{"type":"string","description":"Name of that field as people see it"},"operator":{"type":"string","description":"How the field is compared, e.g. eq, gt, contains, isEmpty"},"value":{"type":"integer","description":"Value it is compared with"},"logicOperator":{"type":"string","description":"AND or OR: how it joins the condition before it"}}},"description":"Conditions saved with the button; running it through the API does not check them"},"requireComment":{"type":"boolean","description":"Whether running it needs a comment (notes)"},"commentPrompt":{"type":"string","description":"What the app asks for when a comment is needed"},"isActive":{"type":"boolean","description":"Whether the button can be run"},"orderNum":{"type":"integer","description":"Position among the pipeline's buttons; lower comes first"}}},"description":"Buttons that run a list of actions on a record without moving it"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isActive":{"type":"boolean"},"trigger":{"type":"object","properties":{"event":{"type":"string"},"config":{"type":"object","properties":{"stageId":{"type":"string"}}}}},"conditions":{"type":"array"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"}}},"orderNum":{"type":"integer"}}}},"orderNum":{"type":"integer"}}},"description":"Rules that run actions when something happens to a record (trigger.event, e.g. stage_entered)"},"fieldDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"sectionId":{"type":"string"},"colSpan":{"type":"integer"},"fieldType":{"type":"string"},"options":{"type":"array"},"isRequired":{"type":"boolean"},"placeholder":{"type":"string"},"description":{"type":"string"},"orderNum":{"type":"integer"},"showOnCard":{"type":"boolean"},"currencyCode":{"type":"string"},"validation":{"type":"object","properties":{"min":{"type":"integer"}}},"dependsOn":{"type":"object","properties":{"values":{"type":"array"},"requiredWhenVisible":{"type":"boolean"}}}}},"description":"Custom fields its records have"},"fieldSections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orderNum":{"type":"integer"}}},"description":"Groups the custom fields are shown in"},"config":{"type":"object","properties":{"showAvatars":{"type":"boolean"},"showBadges":{"type":"boolean"},"columnMinWidth":{"type":"integer"},"columnMaxWidth":{"type":"integer"},"cardSubtitleField":{"type":"string"},"cardBadgeField":{"type":"string"},"defaultStageId":{"type":"string"},"requireTransitions":{"type":"boolean"},"enableSLA":{"type":"boolean"},"stageSLAs":{"type":"array","items":{"type":"object","properties":{"stageId":{"type":"string"},"maxHours":{"type":"integer"},"warningHours":{"type":"integer"}}}},"stageRollups":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"function":{"type":"string"},"title":{"type":"string"}}}},"conditionFields":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array"}}}}},"description":"Board settings: card fields, default stage, whether moves must follow transitions, stage time limits (stageSLAs), column totals (stageRollups) and the fields conditions can use"},"roundRobinState":{"type":"object","properties":{"action-assign-owner":{"type":"integer"}},"description":"For round-robin assign actions: action ID to the position of the person assigned last"},"enabledEmailAccountIds":{"type":"array","items":{"type":"string"},"description":"Email accounts its records may send from; empty means any the organisation has"},"emailEnabled":{"type":"boolean","description":"Whether sending email is offered on its records"},"smsEnabled":{"type":"boolean","description":"Whether sending SMS is offered on its records"},"callEnabled":{"type":"boolean","description":"Whether calling is offered on its records"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Pipeline ID"}}}}},"example":{"pipeline":{"name":"Sales","description":"Deals from first contact to signed contract","spaceId":"6a9f3c21b7e4a20f1c5d8e41","stages":[{"id":"lead","name":"Lead","color":"#6b7280","orderNum":0,"isDefault":true,"positionX":80,"positionY":120},{"id":"quoted","name":"Quoted","color":"#3b82f6","orderNum":1,"isDefault":false,"positionX":360,"positionY":120},{"id":"won","name":"Won","color":"#22c55e","orderNum":2,"isDefault":false,"positionX":640,"positionY":120}],"transitions":[{"id":"lead-to-quoted","name":"Send quote","description":"The client has asked for a price","color":"#3b82f6","icon":"file-text","fromStageId":"lead","toStageId":"quoted","actions":[{"id":"action-assign-owner","actionType":"assign","isActive":true,"config":{"strategy":"round_robin","userPool":["66f1b2c3d4e5f60718293a4b","66f1b2c3d4e5f60718293a5c"]},"orderNum":0}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requiredFieldIds":["dealAmount"],"requireComment":false,"commentPrompt":"Please add a note for this transition","isGlobal":false,"fromStageIds":[],"isActive":true}],"customButtons":[{"id":"send-quote","label":"Send quote","description":"Stamps the quote date and tells the assignees","icon":"send","color":"#3b82f6","visibleInStages":["quoted"],"requiredRole":"","confirmation":{"enabled":true,"prompt":"Send the quote to the client now?"},"actions":[{"id":"action-stamp-quote-date","actionType":"update_field","isActive":true,"config":{"fieldId":"quoteSentOn","useCurrentDate":true},"orderNum":0},{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"conditions":[{"id":"cond-has-amount","fieldPath":"dealAmount","fieldLabel":"Deal amount","operator":"gt","value":0,"logicOperator":"AND"}],"requireComment":false,"commentPrompt":"Please add a note","isActive":true,"orderNum":0}],"automations":[{"id":"remind-stale-quote","name":"Remind on new quotes","description":"Tells the assignees when a deal reaches Quoted","isActive":true,"trigger":{"event":"stage_entered","config":{"stageId":"quoted"}},"conditions":[],"actions":[{"id":"action-tell-assignees","actionType":"notify","isActive":true,"config":{"to":"assignees","message":"The quote went out to the client"},"orderNum":1}],"orderNum":0}],"fieldDefinitions":[{"id":"dealAmount","name":"dealAmount","label":"Deal amount","sectionId":"deal","colSpan":3,"fieldType":"currency","options":[],"isRequired":true,"placeholder":"0","description":"Contract value before tax","orderNum":0,"showOnCard":true,"currencyCode":"KES","validation":{"min":0},"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"quoteSentOn","name":"quoteSentOn","label":"Quote sent on","sectionId":"deal","colSpan":3,"fieldType":"date","options":[],"isRequired":false,"orderNum":1,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}},{"id":"contactName","name":"contactName","label":"Contact name","sectionId":"deal","colSpan":3,"fieldType":"text","options":[],"isRequired":false,"orderNum":2,"showOnCard":false,"dependsOn":{"values":[],"requiredWhenVisible":false}}],"fieldSections":[{"id":"deal","name":"Deal","orderNum":0}],"config":{"showAvatars":true,"showBadges":true,"columnMinWidth":280,"columnMaxWidth":400,"cardSubtitleField":"dealAmount","cardBadgeField":"quoteSentOn","defaultStageId":"lead","requireTransitions":true,"enableSLA":true,"stageSLAs":[{"stageId":"quoted","maxHours":72,"warningHours":48}],"stageRollups":[{"fieldId":"dealAmount","function":"sum","title":"Total value"}],"conditionFields":[{"_id":"6ad1c2e0f3a4b5c6d7e8f909","path":"dealAmount","label":"Deal amount","type":"number","options":[]}]},"roundRobinState":{"action-assign-owner":1},"enabledEmailAccountIds":["7c2f9a4e-3b1d-4e8a-9f60-1d2c3b4a5e6f"],"emailEnabled":true,"smsEnabled":true,"callEnabled":false,"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-02T07:30:00.000Z","updatedAt":"2026-10-15T09:40:00.000Z","id":"6ad1c2e0f3a4b5c6d7e8f901"}}}}},"400":{"description":"pipelineId is not a valid ID, a JSON text input is not valid JSON, or the button does not pass the checks (e.g. an unknown condition operator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the pipeline's space, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The pipeline already has a button with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/pipelines/{pipelineId}/records/{recordId}/custom-buttons/{buttonId}/execute":{"post":{"tags":["Pipelines"],"summary":"Run a custom button on a record","description":"Runs a custom button's actions on a record, in order, without moving the record to another stage. Needs the contributor role or higher in the pipeline's space, which must not be archived; a button with requiredRole admin also needs an organisation admin. The record must meet the button's conditions. fieldValues are saved onto the record first so the actions can use them, the run is recorded in the pipeline's execution log, and notes is then posted as a comment on the record, as a transition's note is. Answers 200 even when actions fail, so check each result.\n\n**Permission:** `spaces.pipelines.update` (Update pipelines).","operationId":"runPipelineCustomButton","parameters":[{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the pipeline","example":"6ad1c2e0f3a4b5c6d7e8f901"},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the record to run it on; it must be in this pipeline and not archived","example":"6ad1c2e0f3a4b5c6d7e8f902"},{"name":"buttonId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the button","example":"send-quote"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldValues":{"type":"object","description":"Field values to save onto the record before the actions run, by field ID, merged into its current values. A JSON object in a string also works","examples":[{"quoteSentOn":"2026-10-15"}]},"notes":{"type":"string","description":"Note for the run, posted as a comment on the record under the button's label once the actions have run. Needed when the button has requireComment. It is not passed to the actions","examples":["Client approved the revised price"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true when the actions were run"},"results":{"type":"array","items":{"type":"object","properties":{"actionType":{"type":"string","description":"Kind of action, e.g. update_field or notify"},"success":{"type":"boolean","description":"Whether it worked"},"error":{"type":"string","description":"Why it failed; absent when it worked"}}},"description":"One entry per active action, in the order they ran"}}},"example":{"ok":true,"results":[{"actionType":"update_field","success":false,"error":"update_field: no field matches \"quoteSentOn\". Use a built-in (priority, dueDate, …) or a custom field id/name."},{"actionType":"notify","success":true}]}}}},"400":{"description":"pipelineId or recordId is not a valid ID, the button is turned off, or fieldValues is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a contributor or higher in the pipeline's space, the space is archived, or the button is for admins (code FORBIDDEN) and you are not an organisation admin, or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pipeline with that ID (or it is archived), no button with that ID on it, or no record with that ID in this pipeline that is not archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The button is not offered in the record's current stage (code STAGE_NOT_ALLOWED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A condition of the button is not met (\"Custom button blocked: Condition not met for ...\"), or the button needs a comment and notes is empty (code COMMENT_REQUIRED; the error is the button's comment prompt)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.pipelines.update"]}],"x-required-scopes":["spaces.pipelines.update"]}},"/spaces/{spaceId}/drive/folders":{"post":{"tags":["Files"],"summary":"Create a folder","description":"Creates a folder in a space's drive, at the top or inside another folder, and answers 201. Needs the contributor, editor or owner role in the space, which must not be archived. Names need not be unique.\n\n**Permission:** `spaces.drive.create` (Upload to drive).","operationId":"createDriveFolder","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the folder; trimmed","examples":["2026 Q3"]},"parentId":{"type":"string","description":"ID of the folder to create it in; leave it out for the top of the drive","examples":["6ad0a2b4d5c26de56de949f8"]}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}},"description":"The new folder"}}},"example":{"item":{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"2026 Q3","itemType":"folder","parentId":"6ad0a2b4d5c26de56de949f8","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T12:58:00.000Z","updatedAt":"2026-10-14T12:58:00.000Z","id":"6ad0a2e0d5c26de56de94a02"}}}}},"400":{"description":"spaceId or parentId is not a valid ID, name is empty, or parentId is a file, not a folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No space with that ID, it is archived, or you are not a contributor, editor or owner in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No folder with that parentId in this space's drive, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.drive.create"]}],"x-required-scopes":["spaces.drive.create"]}},"/spaces/{spaceId}/drive/upload":{"post":{"tags":["Files"],"summary":"Start a file upload","description":"First step of adding a file to a space's drive: creates the file with status pending, answers 201 with a one-hour upload link, and the file shows in the folder at once. PUT the file to uploadUrl, then call confirmDriveUpload to make it ready. Needs the contributor, editor or owner role in the space, which must not be archived. The 100 MB limit is checked on the declared fileSize here, and on the stored file by confirmDriveUpload.\n\n**Permission:** `spaces.drive.create` (Upload to drive).","operationId":"requestDriveUpload","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","description":"Name shown in the drive; trimmed. In the stored key, characters other than letters, digits, dots, hyphens and underscores become underscores","examples":["Q3 board pack.pdf"]},"fileSize":{"type":"integer","description":"Size of the file in bytes, at most 104857600 (100 MB); a number in a string also works","examples":[2483017]},"mimeType":{"type":"string","description":"File type, e.g. application/pdf","examples":["application/pdf"]},"parentId":{"type":"string","description":"ID of the folder to put it in; leave it out for the top of the drive","examples":["6ad0a2e0d5c26de56de94a02"]}},"required":["fileName","fileSize","mimeType"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}},"description":"The new file, with status pending until the upload is confirmed"},"uploadUrl":{"type":"string","description":"Link to send the file to with an HTTP PUT, the file as the body; it works without sign-in until it expires"},"expiresIn":{"type":"integer","description":"Seconds until uploadUrl stops working (always 3600, one hour)"}}},"example":{"item":{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack.pdf","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"pending","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-14T13:05:00.000Z","id":"6ad0a301d5c26de56de94a07"},"uploadUrl":"https://blobstore.inet.africa/org-66a4b275003d1b495212b5aa/spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261015T094100Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=4b7e2c9a1d3f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c","expiresIn":3600}}}},"400":{"description":"spaceId or parentId is not a valid ID, fileName or mimeType is empty, fileSize is not a number above 0 or is over 100 MB, or parentId is a file, not a folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"No space with that ID, it is archived, or you are not a contributor, editor or owner in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No folder with that parentId in this space's drive, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.drive.create"]}],"x-required-scopes":["spaces.drive.create"]}},"/drive/{itemId}/confirm":{"post":{"tags":["Files"],"summary":"Finish a file upload","description":"Second step of adding a file to a drive: checks the file sent to the upload link is in storage and at most 100 MB, records the size it has there as fileSize, and marks it ready, so it can be downloaded. Open to the person who started the upload while they are still a contributor, editor or owner of the space, and to its editors and owners; not in an archived space.\n\n**Permission:** `spaces.drive.create` (Upload to drive).","operationId":"confirmDriveUpload","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the file, from requestDriveUpload","example":"6ad0a301d5c26de56de94a07"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}},"description":"The file, now ready"}}},"example":{"item":{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack.pdf","itemType":"file","parentId":"6ad0a2e0d5c26de56de94a02","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-14T13:05:41.000Z","id":"6ad0a301d5c26de56de94a07"}}}}},"400":{"description":"itemId is not a valid ID, the item is not a pending upload, nothing has been uploaded to its link yet, or the stored file is over 100 MB (it is then deleted from storage, and the file stays pending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only the person who started the upload, while still a contributor, editor or owner of the space, or an editor or owner, can confirm it, and not in an archived space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No file with that ID, or it was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.drive.create"]}],"x-required-scopes":["spaces.drive.create"]}},"/drive/{itemId}/move":{"post":{"tags":["Files"],"summary":"Move a file or folder","description":"Moves a file or folder into another folder of the same space's drive, or to the top of the drive when newParentId is left out; a folder takes its contents with it. Needs the editor or owner role in the space, which must not be archived.\n\n**Permission:** `spaces.drive.update` (Manage drive items).","operationId":"moveDriveItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the file or folder to move","example":"6ad0a301d5c26de56de94a07"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"newParentId":{"type":"string","description":"ID of the folder to move it into; leave it out or empty to move it to the top of the drive","examples":["6ad0a2b4d5c26de56de949f8"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the space whose drive holds it"},"name":{"type":"string","description":"Name shown in the drive"},"itemType":{"type":"string","description":"file or folder"},"parentId":{"type":"string","description":"ID of the folder it is in; null at the top of the drive"},"mimeType":{"type":"string","description":"Files only: file type, e.g. application/pdf"},"fileSize":{"type":"integer","description":"Files only: size in bytes, as declared when the upload started"},"minioKey":{"type":"string","description":"Files only: key of the stored file"},"bucketName":{"type":"string","description":"Files only: which store holds it; absent on older files"},"status":{"type":"string","description":"pending until the upload is confirmed, then ready; folders are always ready"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string","description":"Their ID"},"firstName":{"type":"string","description":"First name"},"lastName":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address"}},"description":"Who created or uploaded it: id, firstName, lastName and email; null when that person is gone"},"isArchived":{"type":"boolean","description":"Always false here: deleted items are not returned"},"organizationId":{"type":"string","description":"ID of the organisation"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"ID of the file or folder"}},"description":"The file or folder in its new place"}}},"example":{"item":{"spaceId":"6a9f3c21b7e4a20f1c5d8e41","name":"Q3 board pack.pdf","itemType":"file","parentId":"6ad0a2b4d5c26de56de949f8","mimeType":"application/pdf","fileSize":2483017,"minioKey":"spaces/66a4b275003d1b495212b5aa/drive/6a9f3c21b7e4a20f1c5d8e41/6ad0a301d5c26de56de94a07/5e2d9c41-7a3b-4f80-b6d2-1c9e8a7f4d30-Q3_board_pack.pdf","bucketName":"org-66a4b275003d1b495212b5aa","status":"ready","uploadedBy":{"id":"66f1b2c3d4e5f60718293a4b","firstName":"Amina","lastName":"Otieno","email":"amina.otieno@acme.co.ke"},"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-14T13:05:00.000Z","updatedAt":"2026-10-15T08:14:00.000Z","id":"6ad0a301d5c26de56de94a07"}}}}},"400":{"description":"itemId or newParentId is not a valid ID, newParentId is the item itself, a file rather than a folder, or a folder inside the item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an editor or owner of the space whose drive holds it, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No file or folder with that itemId, no folder with that newParentId in the same drive, or either was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.drive.update"]}],"x-required-scopes":["spaces.drive.update"]}},"/settings/ai-config/{provider}":{"delete":{"tags":["Settings"],"summary":"Remove an AI provider key","description":"Deletes the saved API key and model for one AI provider. Needs an organisation admin, and counts toward the limit of 10 AI setting changes or tests in a row. If it was the default provider, the other one becomes the default when it has a key, otherwise openai does. With no AI settings saved it changes nothing.\n\n**Permission:** `spaces.settings.update` (Update AI settings).","operationId":"removeOrgAIProvider","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["openai","anthropic"]},"description":"Which AI provider's key to remove","example":"anthropic"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"defaultProvider":{"type":"string","description":"Provider AI features use unless told otherwise: openai or anthropic"},"openai":{"type":"object","properties":{"configured":{"type":"boolean","description":"Always true: a key is saved"},"hint":{"type":"string","description":"Always empty: no part of the key is ever shown (configured says a key is saved)"},"model":{"type":"string","description":"Model to use; empty means the provider's default model"},"configuredBy":{"type":"string","description":"ID of the admin who saved the key"},"configuredAt":{"type":"string","format":"date-time","description":"When the key was saved"}},"description":"OpenAI key details; null when no OpenAI key is saved"},"anthropic":{"description":"Anthropic key details; null when no Anthropic key is saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the AI settings last changed; null when none are saved"}},"description":"The AI settings after the removal"}}},"example":{"config":{"defaultProvider":"openai","openai":{"configured":true,"hint":"","model":"gpt-4.1","configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T12:00:00.000Z"},"anthropic":null,"updatedAt":"2026-10-15T08:45:00.000Z"}}}}},"400":{"description":"provider is not openai or anthropic","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"You made 10 AI setting changes or tests in a row; wait a minute after the last one (code RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.settings.update"]}],"x-required-scopes":["spaces.settings.update"]}},"/integrations/email/accounts/{accountId}":{"delete":{"tags":["Settings"],"summary":"Delete an email account","description":"Deletes one send-as email account and its saved password for good. Needs an organisation admin. An ID that matches no account changes nothing and still answers with the current settings.\n\n**Permission:** `spaces.integrations.delete` (Delete integrations).","operationId":"deleteEmailAccount","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the account to delete","example":"8d2e4b6a-1c3f-4e5a-b7d9-0f2a4c6e8b13"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Account ID; pass it as accountId to send from, test or delete the account"},"label":{"type":"string","description":"Name shown when picking the account"},"fromAddress":{"type":"string","description":"Address the emails come from"},"fromName":{"type":"string","description":"Sender name shown with the address; empty if none"},"replyTo":{"type":"string","description":"Address replies go to; empty means replies go to fromAddress"},"host":{"type":"string","description":"Mail server (SMTP) host"},"port":{"type":"integer","description":"Mail server port"},"secure":{"type":"boolean","description":"true: TLS from the start (usually port 465); false: STARTTLS (usually port 587)"},"username":{"type":"string","description":"User name for logging in to the mail server"},"isEnabled":{"type":"boolean","description":"Whether the account may send; a turned-off account cannot"},"configured":{"type":"boolean","description":"Whether a password is saved"},"passwordHint":{"type":"string","description":"Always empty: no part of the password is ever shown (configured says whether one is saved)"},"lastTestedAt":{"type":"string","format":"date-time","description":"When the account was last tested; null if never"},"lastTestStatus":{"type":"string","description":"Result of the last test: ok, error or untested"},"lastTestError":{"type":"string","description":"Why the last test failed; empty otherwise"},"createdAt":{"type":"string","format":"date-time","description":"When the account was added"},"updatedAt":{"type":"string","format":"date-time","description":"When the account last changed"}}},"description":"The organisation's send-as email accounts; empty when none are set up"},"configuredBy":{"type":"string","description":"ID of the admin who last saved an account; absent when nothing was ever saved"},"configuredAt":{"type":"string","format":"date-time","description":"When an account was last saved; absent when nothing was ever saved"},"updatedAt":{"type":"string","format":"date-time","description":"When the settings last changed; absent when nothing was ever saved"}},"description":"The organisation's email settings after the delete"}}},"example":{"config":{"accounts":[{"id":"3f6c1e2a-8b4d-4c7e-9a1f-5d2b8e7c6a90","label":"Sales","fromAddress":"sales@example.com","fromName":"Example Ltd Sales","replyTo":"support@example.com","host":"smtp.example.com","port":587,"secure":false,"username":"sales@example.com","isEnabled":true,"configured":true,"passwordHint":"","lastTestedAt":"2026-10-14T09:12:00.000Z","lastTestStatus":"ok","lastTestError":"","createdAt":"2026-10-01T08:00:00.000Z","updatedAt":"2026-10-14T09:10:00.000Z"}],"configuredBy":"66f1b2c3d4e5f60718293a4b","configuredAt":"2026-10-14T09:10:00.000Z","updatedAt":"2026-10-14T09:12:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not an organisation admin (code FORBIDDEN), or you are an assistant acting for one (code askFirst)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.integrations.delete"]}],"x-required-scopes":["spaces.integrations.delete"]}},"/spaces/{spaceId}/members/{userId}":{"delete":{"tags":["Spaces"],"summary":"Remove someone from a space","description":"Takes a person out of a space. Only the space's owner may do it, an owner cannot be removed, and an archived space's members stay as they are. They also leave the space's Kazee Chat room and, as far as that succeeds, the comment chats of the space's tasks; tasks assigned to them stay assigned.\n\n**Permission:** `spaces.members.delete` (Remove space members).","operationId":"removeSpaceMember","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID of the member to remove","example":"66f1b2c3d4e5f60718293a5c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"space":{"type":"object","properties":{"id":{"type":"string","description":"Space ID"},"name":{"type":"string","description":"Name of the space"},"description":{"type":"string","description":"What the space is for; absent if never set"},"icon":{"type":"string","description":"An emoji or icon name; absent if never set"},"color":{"type":"string","description":"Colour as a hex code; #3b82f6 unless another was chosen"},"visibility":{"type":"string","description":"private: only members can open it. public: anyone in the organisation can open it"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID of the member"},"role":{"type":"string","description":"owner, editor, contributor or viewer, from most rights to least"},"joinedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"Everyone in the space, with their role"},"ownerId":{"type":"string","description":"User ID of the person who created the space"},"documentProvider":{"description":"Outside file store linked to the space (google_drive, dropbox or onedrive); null when none"},"chatId":{"type":"string","description":"ID of the space's room in Kazee Chat; absent until the room is first made, e.g. when someone first opens the space's chat"},"isArchived":{"type":"boolean","description":"Whether the space is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"}}}}},"example":{"space":{"id":"6a9f3c21b7e4a20f1c5d8e41","name":"Finance","description":"Invoices, budgets and the month-end close.","icon":"💼","color":"#3b82f6","visibility":"private","members":[{"userId":"66f1b2c3d4e5f60718293a4b","role":"owner","joinedAt":"2026-09-01T07:30:00.000Z"}],"ownerId":"66f1b2c3d4e5f60718293a4b","documentProvider":null,"chatId":"6a9f3d02b7e4a20f1c5d8e59","isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-09-01T07:30:00.000Z","updatedAt":"2026-10-15T09:30:00.000Z"}}}}},"400":{"description":"spaceId is not a valid ID, or that person is not a member, or is the space's owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.members.delete"]}],"x-required-scopes":["spaces.members.delete"]}},"/spaces/{spaceId}/archived":{"delete":{"tags":["Spaces"],"summary":"Delete a space's archived content","description":"Deletes a space's archived wikis, wiki pages and tasks for good, with the comments on those pages and the files on those tasks. Deleting an archived wiki also deletes every page in it and its sidebar item. A task's stored files are deleted before the task; a task with a file that storage does not delete (every task with files, when storage is not available) is kept while the rest is deleted, and the answer is 503, so try again. Only the space's owner may do it. This cannot be undone.\n\n**Permission:** `spaces.admin` (Purge spaces archive).","operationId":"deleteArchivedContent","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"contentTypes","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["wikis","wikiPages","tasks"]}},"description":"Which archived content to delete. Defaults to all three. A text naming them, such as wikis,tasks, also works","example":["wikiPages","tasks"]}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked; a 503 reply carries false with the counts"},"deletedWikis":{"type":"integer","description":"Archived wikis deleted"},"deletedWikiPages":{"type":"integer","description":"Archived wiki pages deleted; pages that went with a deleted wiki are not counted"},"deletedTasks":{"type":"integer","description":"Archived tasks deleted"}}},"example":{"success":true,"deletedWikis":0,"deletedWikiPages":6,"deletedTasks":14}}}},"400":{"description":"spaceId is not a valid ID, or deleting failed part-way; whatever was already deleted stays deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"File storage is not available right now, or did not delete some archived tasks' files: those tasks were kept, everything else was deleted, and the counts in the reply (with success false) say what was. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.admin"]}],"x-required-scopes":["spaces.admin"]}},"/spaces/{spaceId}/apps/{integrationId}":{"delete":{"tags":["Spaces"],"summary":"Remove an app from a space","description":"The space's owner removes an app login from the space; it can no longer read or change the space's records. Removing an app that is not there changes nothing. Answers with the apps left.\n\n**Permission:** `spaces.members.create` (Add space members).","operationId":"removeSpaceApp","parameters":[{"name":"spaceId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the space","example":"6a9f3c21b7e4a20f1c5d8e41"},{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the app login in Central (integrationId from listAvailableSpaceApps)","example":"6ad1a0b1c2d3e4f5a6b7c801"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success"},"apps":{"type":"array","items":{"type":"object","properties":{"integrationId":{"type":"string","description":"ID of the app login in Central"},"principalId":{"type":"string","description":"The app's own user ID; records it adds or changes show this user"},"name":{"type":"string","description":"The app login's name, as set in Central"},"role":{"type":"string","description":"viewer (reads pipeline records) or contributor (also adds, edits and moves them)"},"addedBy":{"type":"string","description":"User ID of the owner who added it; null if not known"},"addedAt":{"type":"string","format":"date-time","description":"When it was added; null if not known"}}},"description":"The apps added to the space, oldest first"}}},"example":{"success":true,"apps":[{"integrationId":"6ad1a0b1c2d3e4f5a6b7c803","principalId":"6ad1a0b1c2d3e4f5a6b7c804","name":"Website enquiries","role":"viewer","addedBy":"66f1b2c3d4e5f60718293a4b","addedAt":"2026-10-15T08:30:00.000Z"}]}}}},"400":{"description":"spaceId or integrationId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the space's owner, or the caller is an app login","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No space with that ID that you are a member of, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.members.create"]}],"x-required-scopes":["spaces.members.create"]}},"/events/{eventId}/attendees/{userId}":{"delete":{"tags":["Calendar"],"summary":"Remove someone from an event","description":"Takes a person off an event's attendees; the Kazee call's members follow. Open to the organizer and to space members with the editor role or higher, and to any attendee taking themselves off. Removing someone who is not invited changes nothing.\n\n**Permission:** `spaces.calendar.update` (Update events).","operationId":"removeEventAttendee","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the event; for a repeating event, the series","example":"6ad1c0a2d5c26de56de94a10"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the person to take off","example":"66f1b2c3d4e5f60718293a5c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string","description":"What the event is"},"description":{"type":"string","description":"Longer notes on the event"},"startDate":{"type":"string","format":"date-time","description":"When it starts"},"endDate":{"type":"string","format":"date-time","description":"When it ends"},"allDay":{"type":"boolean","description":"Whether it takes the whole day"},"timeZone":{"type":"string","description":"IANA time zone it was planned in, e.g. Africa/Kampala; absent when none was given"},"location":{"type":"string","description":"Where it takes place"},"meetingUrl":{"type":"string","description":"Link to join its call: the Kazee call's join link, the event's own video room, or a link someone pasted"},"meeting":{"type":"object","properties":{"provider":{"type":"string","description":"kazee for a Kazee call"},"meetingId":{"type":"string","description":"ID of the call in Kazee Chat"},"joinUrl":{"type":"string","description":"Link to join the call"},"conversationId":{"type":"string","description":"ID of the Kazee Chat conversation the call belongs to"},"conversationTitle":{"type":"string","description":"Name of that conversation"},"callType":{"type":"string","description":"audio or video"},"status":{"type":"string","description":"The call's state in Kazee Chat, e.g. scheduled, started, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call matches the event"},"occurrenceStartsAt":{"type":"string","format":"date-time","description":"Start of the occurrence the call belongs to"},"managesAttendees":{"type":"boolean","description":"Whether the conversation was made for this event, so changing the attendees changes who is in it"}},"description":"The Kazee call behind the event, when it has one"},"spaceId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the space"},"color":{"type":"string","description":"Colour of the space"},"icon":{"type":"string","description":"Icon of the space"},"id":{"type":"string","description":"Space ID"}},"description":"The space it belongs to; absent for a personal event"},"creatorId":{"type":"string","description":"ID of the organizer (firstName, lastName, email are not filled in here)"},"attendees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"ID of the invited person"},"status":{"type":"string","description":"Their reply: pending, accepted, declined or tentative"},"respondedAt":{"type":"string","format":"date-time","description":"When they replied; absent until they do"}}},"description":"People invited, apart from the organizer"},"color":{"type":"string","description":"Colour shown on the calendar, e.g. #3b82f6"},"category":{"type":"string","description":"Kind of event: meeting, deadline, milestone, reminder, other"},"recurrence":{"type":"object","properties":{"interval":{"type":"integer","description":"Repeats every this many days, weeks, months or years"},"daysOfWeek":{"type":"array","description":"Weekdays it falls on, 0 (Sunday) to 6"},"weekOfMonth":{"type":"array","description":"Which weeks of the month (1 to 5), for a monthly event"}},"description":"How it repeats. type (daily, weekly, monthly or yearly) is absent when it does not repeat; interval is every how many days, weeks, months or years; daysOfWeek (0 is Sunday) and weekOfMonth (1 to 5) refine it"},"reminders":{"type":"array","items":{"type":"integer"},"description":"Minutes before the start when attendees are reminded; 0 is at the start"},"recurrenceExceptions":{"type":"array","description":"Original start times of occurrences taken out of the series"},"linkedTasks":{"type":"array","items":{"type":"string"},"description":"IDs of the tasks linked to the event"},"decisions":{"type":"array","description":"Decisions recorded in the meeting"},"isArchived":{"type":"boolean","description":"Whether it was deleted (cancelled); always false in these replies"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"metadata":{"type":"object","properties":{"jitsiEnabled":{"type":"boolean","description":"Whether the event has its own video room, joined with getEventCallToken"}},"description":"Extra data other features keep on the event"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"id":{"type":"string","description":"Event ID"},"version":{"type":"integer","description":"Version of the event; send it as expectedRevision to updateEvent so a stale edit is refused"},"meetingReadiness":{"type":"object","properties":{"contract":{"type":"integer","description":"Always 1"},"state":{"type":"string","description":"none (no Kazee call), pending (being set up or changed), ready, failed, live, ended or cancelled"},"syncedAt":{"type":"string","format":"date-time","description":"When Kazee Chat last confirmed the call"},"retryable":{"type":"boolean","description":"Whether asking for another attempt could help (only after a failure nothing retries any more)"}},"description":"Where the event's Kazee call stands, worked out from the event"}},"description":"The event with its space filled in and people as IDs. For a call made in Kazee Chat (in organisations where Chat keeps those calls) it is the event before the change, which shows once Chat confirms it"}}},"example":{"event":{"title":"October finance review","description":"Go through the October invoices and the cash forecast.","startDate":"2026-10-21T07:00:00.000Z","endDate":"2026-10-21T08:00:00.000Z","allDay":false,"timeZone":"Africa/Kampala","location":"Board room, 3rd floor","meetingUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","meeting":{"provider":"kazee","meetingId":"6ad1c0f4e8b37a1d2c9f5b21","joinUrl":"https://chat.kazee.africa/?meeting=6ad1c0f4e8b37a1d2c9f5b21","conversationId":"6ad1c11ae8b37a1d2c9f5b30","conversationTitle":"Finance","callType":"video","status":"scheduled","syncedAt":"2026-10-15T08:00:02.000Z","occurrenceStartsAt":"2026-10-21T07:00:00.000Z","managesAttendees":false},"spaceId":{"name":"Finance","color":"#3b82f6","icon":"💼","id":"6a9f3c21b7e4a20f1c5d8e41"},"creatorId":"66f1b2c3d4e5f60718293a4b","attendees":[{"userId":"66f1b2c3d4e5f60718293a5c","status":"accepted","respondedAt":"2026-10-15T09:12:00.000Z"}],"color":"#3b82f6","category":"meeting","recurrence":{"interval":1,"daysOfWeek":[],"weekOfMonth":[]},"reminders":[15,0],"recurrenceExceptions":[],"linkedTasks":["6ad0a044d5c26de56de949a8"],"decisions":[],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","metadata":{"jitsiEnabled":false},"createdAt":"2026-10-15T08:00:00.000Z","updatedAt":"2026-10-15T09:12:00.000Z","id":"6ad1c0a2d5c26de56de94a10","version":2,"meetingReadiness":{"contract":1,"state":"ready","syncedAt":"2026-10-15T08:00:02.000Z","retryable":false}}}}}},"400":{"description":"eventId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the event's organizer, a space member with the editor role or higher, or an attendee taking yourself off; or the event is kept by Kazee People and is read-only here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event with that ID in your organisation, or it was cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The call was made in Kazee Chat and is not ready yet, or Kazee Chat refused the change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The call was made in Kazee Chat and Kazee Chat could not be reached to change it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["spaces.calendar.update"]}],"x-required-scopes":["spaces.calendar.update"]}},"/wikis/{wikiId}/templates/{templateId}":{"delete":{"tags":["Docs"],"summary":"Remove a page template from a wiki","description":"Removes a page template from a wiki; the four a wiki starts with can be removed too. Needs the editor role in its space. Pages already made from it do not change.\n\n**Permission:** `spaces.wiki.update` (Update wikis).","operationId":"removeWikiTemplate","parameters":[{"name":"wikiId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the wiki","example":"6ad1b0c2e4f5a6b7c8d9e0f1"},{"name":"templateId","in":"path","required":true,"schema":{"type":"string"},"description":"_id of the template","example":"6ad1b0d8e4f5a6b7c8d9e0f9"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"}}},"example":{"success":true}}}},"400":{"description":"wikiId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not a member of the wiki's space with the editor role or higher, or the space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No wiki with that ID, it is archived, or it has no template with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.update"]}],"x-required-scopes":["spaces.wiki.update"]}},"/wiki/pages/{pageId}/permanent":{"delete":{"tags":["Docs"],"summary":"Delete a page for good","description":"Deletes a page, every page under it at any depth and all their comments, for good. Needs the owner role in its space. Archived pages and pages of an archived wiki can be deleted too. The wiki's page count is updated.\n\n**Permission:** `spaces.wiki.admin` (Purge wikis).","operationId":"deleteWikiPage","parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the page","example":"6ad1b11ce4f5a6b7c8d9e10c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true when it worked"},"deletedCount":{"type":"integer","description":"How many pages were deleted, the page itself included"}}},"example":{"success":true,"deletedCount":3}}}},"400":{"description":"pageId is not a valid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the owner of the page's space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that ID, or its wiki no longer exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.wiki.admin"]}],"x-required-scopes":["spaces.wiki.admin"]}},"/univer/documents/{documentId}/collaborators/{userId}":{"delete":{"tags":["Sheets & documents"],"summary":"Remove a collaborator from a sheet or document","description":"Takes a person off the collaborators of a spreadsheet, document or presentation (never its owner), and answers with the document. Someone who is not on the list changes nothing. Only the owner of its space, or the document's creator while still an editor or owner of the space, may call it. Not while its space is archived.\n\n**Permission:** `spaces.univer.update` (Edit spreadsheets).","operationId":"removeDocumentCollaborator","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"ID of the sheet, document or presentation","example":"6ad0a0d2d5c26de56de949e6"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID of the collaborator","example":"66f1b2c3d4e5f60718293a5c"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"},"name":{"type":"string","description":"Name of the sheet or document"},"type":{"type":"string","description":"spreadsheet, document or presentation"},"spaceId":{"type":"string","description":"ID of the space it belongs to"},"creatorId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who created it: a user ID, or { firstName, lastName, email, id } where the call fills people in"},"fileSize":{"type":"integer","description":"Size of the saved content in bytes"},"version":{"type":"integer","description":"Current version: 1 when created, plus 1 for each save and each restore of an earlier version"},"collaborators":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"The person: a user ID, or filled in like creatorId"},"role":{"type":"string","description":"owner (its creator; counts only while they are an editor or owner of the space), editor or viewer"},"addedAt":{"type":"string","format":"date-time","description":"When they were added"}}},"description":"People added to the document itself, with their role. Everyone but the creator also has addedBy: who added them, as a user ID or filled in like creatorId"},"lastEditedBy":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"}},"description":"Who last saved it: a user ID, or filled in like creatorId"},"lastEditedAt":{"type":"string","format":"date-time","description":"When it was last saved"},"settings":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Meant to share it beyond the space"},"allowComments":{"type":"boolean","description":"Whether comments are allowed"},"allowExport":{"type":"boolean","description":"Whether it may be exported"}},"description":"Sharing settings the apps read; the server stores them but does not enforce them"},"description":{"type":"string","description":"Longer notes; absent if never set"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels on it"},"isArchived":{"type":"boolean","description":"Whether it is archived"},"organizationId":{"type":"string","description":"ID of the organisation it belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When it was created"},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed"},"snapshotCount":{"type":"integer","description":"How many earlier versions it keeps (at most 50)"}}}}},"example":{"document":{"id":"6ad0a0d2d5c26de56de949e6","name":"October budget","type":"spreadsheet","spaceId":"6a9f3c21b7e4a20f1c5d8e41","creatorId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"fileSize":18734,"version":7,"collaborators":[{"userId":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"},"role":"owner","addedAt":"2026-10-15T08:10:00.000Z"},{"userId":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"role":"editor","addedAt":"2026-10-15T08:40:00.000Z","addedBy":{"firstName":"Amina","lastName":"Otieno","email":"amina.otieno@example.com","id":"66f1b2c3d4e5f60718293a4b"}}],"lastEditedBy":{"firstName":"Brian","lastName":"Mwangi","email":"brian.mwangi@example.com","id":"66f1b2c3d4e5f60718293a5c"},"lastEditedAt":"2026-10-15T11:05:00.000Z","settings":{"isPublic":false,"allowComments":true,"allowExport":true},"description":"Spending against budget, by team.","tags":["budget"],"isArchived":false,"organizationId":"66a4b275003d1b495212b5aa","createdAt":"2026-10-15T08:10:00.000Z","updatedAt":"2026-10-15T11:05:00.000Z","snapshotCount":3}}}}},"400":{"description":"documentId is not a valid ID, the person is the document's owner, or removing failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"You are not the owner of its space, nor the document's creator while still an editor or owner of the space, or its space is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sheet or document with that ID, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["spaces.univer.update"]}],"x-required-scopes":["spaces.univer.update"]}}},"components":{"schemas":{"Error":{"type":"object","description":"Every error reply. The HTTP status says what kind of error it is.","properties":{"error":{"type":"string","description":"What went wrong, in words"}},"required":["error"]}},"responses":{"BadRequest":{"description":"The request was refused, for example an ID in the wrong form","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"No sign-in, or the token has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Signed in, but without the permission or access this needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Nothing found with that ID, or you cannot see it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidInput":{"description":"A required input is missing or an input is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"kazee":{"type":"http","scheme":"bearer","bearerFormat":"Kazee token","description":"Send `Authorization: Bearer <token>` with a token from Kazee sign-in."}}},"security":[{"kazee":[]}],"x-tagGroups":[{"name":"Work","tags":["Spaces","Tasks","Docs","Sheets & documents","Files","Comments","Messages & calls"]},{"name":"Plan","tags":["Calendar","Pipelines","Strategies"]},{"name":"Find","tags":["Search","Saved views","Notifications","Activity"]},{"name":"Organisation","tags":["People","Settings"]}],"servers":[{"url":"https://api.spaces.kazee.africa/api"}]}