Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
{
"openapi": "3.1.0",
"info": {
"title": "document_storage_service",
"description": "",
"termsOfService": "https://macro.com/terms",
"license": {
"name": ""
},
"version": "0.1.0"
},
"paths": {
"/account-managers": {
"get": {
"tags": ["account-managers"],
"summary": "List the managers of the caller's account.",
"operationId": "list_account_managers",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountManagersList"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["account-managers"],
"summary": "Ask another account for manager access, in your DM with them.",
"operationId": "request_account_manager",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestAccountManagerBody"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountManagerGrant"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/account-managers/{id}": {
"get": {
"tags": ["account-managers"],
"summary": "Read a grant the caller is part of.",
"operationId": "get_account_manager_grant",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Grant id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountManagerGrant"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["account-managers"],
"summary": "End a grant. Either side may withdraw it.",
"operationId": "revoke_account_manager_grant",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Grant id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountManagerGrant"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/account-managers/{id}/response": {
"post": {
"tags": ["account-managers"],
"summary": "Approve or decline a request the caller didn't make.",
"operationId": "respond_to_account_manager_request",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Grant id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespondToAccountManagerRequestBody"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountManagerGrant"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/account-managers/{id}/token": {
"post": {
"tags": ["account-managers"],
"summary": "Issue the credential to the manager. Works once. A POST, so link previews\nand crawlers can't use it up.",
"operationId": "claim_account_manager_token",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Grant id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClaimedAccountManagerToken"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/agents": {
"get": {
"tags": ["agents"],
"summary": "Handler for `GET /agents`.",
"operationId": "list_agents",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["agents"],
"summary": "Handler for `POST /agents`.",
"operationId": "create_agent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAgentRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/agents/{agent_id}": {
"put": {
"tags": ["agents"],
"summary": "Handler for `PUT /agents/{agent_id}`.",
"operationId": "update_agent",
"parameters": [
{
"name": "agent_id",
"in": "path",
"description": "Agent bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAgentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/annotations/anchors": {
"delete": {
"tags": ["annotations::delete_anchor"],
"summary": "Deletes a highlight and any attached discussion under the annotation policy.",
"operationId": "delete_anchor",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteUnthreadedAnchorRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteUnthreadedAnchorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["annotations::edit_anchor"],
"summary": "Edits a single anchor for a document",
"operationId": "edit_anchor",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditAnchorRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditAnchorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/annotations/anchors/document/{document_id}": {
"get": {
"tags": ["annotations::get"],
"summary": "Gets a set of comment anchors for a document",
"operationId": "get_document_anchors",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnchorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["annotations::create_anchor"],
"summary": "Creates an unthreaded anchor for a document\nAttach a discussion through the shared message API.",
"operationId": "create_anchor",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "The document id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUnthreadedAnchorRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUnthreadedAnchorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /bots`: the bots the caller can manage.",
"operationId": "list_bots",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Bot"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["bots"],
"summary": "Handler for `POST /bots`.",
"operationId": "create_bot",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBotRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/me": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /bots/me`.",
"operationId": "get_self_bot",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/profiles": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /bots/profiles`.",
"description": "Returns display fields and the sponsor for each requested bot. Not a\nmanageability check: any authenticated user or internal caller may look up\nids they already have.",
"operationId": "get_bot_owner_profiles",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "Bot ids. Repeat the key: `?ids=<uuid>&ids=<uuid>`.",
"required": false,
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BotId"
}
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BotOwnerProfile"
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/{bot_id}": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /bots/{bot_id}`.",
"operationId": "get_bot",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["bots"],
"summary": "Handler for `DELETE /bots/{bot_id}`.",
"operationId": "delete_bot",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["bots"],
"summary": "Handler for `PATCH /bots/{bot_id}`.",
"operationId": "patch_bot",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchBotRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/{bot_id}/channels": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /bots/{bot_id}/channels`.",
"operationId": "list_bot_channels",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BotChannel"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/{bot_id}/channels/{channel_id}": {
"delete": {
"tags": ["bots"],
"summary": "Handler for `DELETE /bots/{bot_id}/channels/{channel_id}`.",
"operationId": "remove_bot_from_channel_by_bot",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
},
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/{bot_id}/tokens": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /bots/{bot_id}/tokens`.",
"operationId": "list_bot_tokens",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BotToken"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["bots"],
"summary": "Handler for `POST /bots/{bot_id}/tokens`.",
"operationId": "create_bot_token",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBotTokenRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBotTokenResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/bots/{bot_id}/tokens/{token_id}": {
"delete": {
"tags": ["bots"],
"summary": "Handler for `DELETE /bots/{bot_id}/tokens/{token_id}`.",
"operationId": "revoke_bot_token",
"parameters": [
{
"name": "bot_id",
"in": "path",
"description": "Bot ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/BotId"
}
},
{
"name": "token_id",
"in": "path",
"description": "Token ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/calendar-events": {
"get": {
"tags": ["calendar_events"],
"summary": "Return calendar occurrences visible to the authenticated requester.",
"operationId": "list_occurrences",
"parameters": [
{
"name": "start",
"in": "query",
"description": "Inclusive UTC viewport start.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "end",
"in": "query",
"description": "Exclusive UTC viewport end.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "startDate",
"in": "query",
"description": "Inclusive local date boundary for all-day events.",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "endDate",
"in": "query",
"description": "Exclusive local date boundary for all-day events.",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of occurrences, from 1 through 2,000.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"maximum": 2000,
"minimum": 1
}
},
{
"name": "cursor",
"in": "query",
"description": "Opaque continuation cursor returned by the previous page.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Calendar occurrences in the requested viewport",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarOccurrenceResponse"
}
}
}
},
"400": {
"description": "Invalid or unsupported calendar viewport"
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "Calendar query failed"
}
}
}
},
"/calendar-events/preview": {
"post": {
"tags": ["calendar_events"],
"summary": "Resolve mentioned calendar events to the requester's own projections.",
"operationId": "mention_previews",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarMentionPreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Requester-relative previews for the mentioned events",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarMentionPreviewResponse"
}
}
}
},
"400": {
"description": "Too many events in one request"
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "Calendar query failed"
}
}
}
},
"/calendar-events/team": {
"get": {
"tags": ["calendar_events"],
"summary": "Query authorized projections in a bounded viewport.",
"operationId": "list_team_calendar",
"parameters": [
{
"name": "start",
"in": "query",
"description": "Inclusive instant.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "end",
"in": "query",
"description": "Exclusive instant.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "cursor",
"in": "query",
"description": "Continuation returned by the preceding page.",
"required": false,
"schema": {
"type": ["string", "null"]
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum source occurrences, at most 2,000. Zero returns the roster only.",
"required": false,
"schema": {
"type": ["integer", "null"],
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamCalendarPage"
}
}
}
}
}
}
},
"/calendar-events/team-out-of-office": {
"get": {
"tags": ["calendar_events"],
"summary": "Return teammates' out-of-office occurrences in the requested viewport.",
"operationId": "list_team_out_of_office",
"parameters": [
{
"name": "start",
"in": "query",
"description": "Inclusive UTC viewport start.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "end",
"in": "query",
"description": "Exclusive UTC viewport end.",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "startDate",
"in": "query",
"description": "Inclusive local date boundary for all-day events.",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "endDate",
"in": "query",
"description": "Exclusive local date boundary for all-day events.",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of occurrences, from 1 through 2,000.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"maximum": 2000,
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "Teammates' out-of-office occurrences in the requested viewport",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamOutOfOfficeResponse"
}
}
}
},
"400": {
"description": "Invalid or unsupported calendar viewport"
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "Calendar query failed"
}
}
}
},
"/calendar-events/{event_id}/ics": {
"get": {
"tags": ["calendar_events"],
"summary": "Export an event the requester can see — their own, or one shared with a\nchannel they belong to — as an iCalendar file named after its title.",
"operationId": "event_ics",
"parameters": [
{
"name": "event_id",
"in": "path",
"description": "Calendar event entity id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The event as an iCalendar document",
"content": {
"text/calendar": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Event not found or not visible to the requester"
},
"500": {
"description": "Calendar query failed"
}
}
}
},
"/calendar-events/{event_id}/join-requests": {
"get": {
"tags": ["calendar_events"],
"summary": "List pending requests to join an event the requester can change.",
"operationId": "list_join_requests",
"parameters": [
{
"name": "event_id",
"in": "path",
"description": "Calendar event entity id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Pending join requests, oldest first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequestsResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Event not found or not editable by the requester",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequestApiError"
}
}
}
},
"500": {
"description": "Listing failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequestApiError"
}
}
}
}
}
},
"post": {
"tags": ["calendar_events"],
"summary": "Ask the person who shared an event with one of the requester's channels\nto add them as a guest. Asking again while the request is pending or\naccepted changes nothing; a declined request stands, so asking after a\ndecline is refused with `request_declined`.",
"operationId": "request_to_join",
"parameters": [
{
"name": "event_id",
"in": "path",
"description": "Shared calendar event entity id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The requester's join request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequest"
}
}
}
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Event not found or not shared with the requester",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequestApiError"
}
}
}
},
"409": {
"description": "Already on the requester's calendar, the sharer cannot add guests, or the sharer declined the requester's earlier request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequestApiError"
}
}
}
},
"500": {
"description": "Join request failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalendarJoinRequestApiError"
}
}
}
}
}
}
},
"/call/active": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `GET /call/active`.",
"description": "Lists all active calls in channels the caller is an active member of,\nnewest first. Calls with no active participants (orphaned by dropped RTC\nwebhooks) are excluded.",
"operationId": "get_active_calls",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActiveCallsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/active/all": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "List all channel and standalone calls this account can join.",
"operationId": "get_live_calls",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LiveCallsResponse"
}
}
}
}
}
}
},
"/call/guest-chat/{call_id}": {
"get": {
"tags": ["messages::inbound::guest_chat"],
"summary": "Read the live call discussion as a verified guest.",
"operationId": "guest_call_chat_read",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuestChatPage"
}
}
}
},
"403": {
"description": ""
}
}
},
"post": {
"tags": ["messages::inbound::guest_chat"],
"summary": "Append text to the same saved discussion used by account participants.",
"operationId": "guest_call_chat_post",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuestChatPost"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuestChatMessage"
}
}
}
},
"403": {
"description": ""
}
}
}
},
"/call/join/{token}": {
"get": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `GET /call/join/{token}` through the call domain service.",
"operationId": "meeting_lookup",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Meeting"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `POST /call/join/{token}` through the call domain service.",
"operationId": "meeting_guest_join",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GuestJoinRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTokenResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/join/{token}/leave": {
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `POST /call/join/{token}/leave` through the call domain service.",
"operationId": "meeting_leave",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LeaveCallResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/join/{token}/participants": {
"get": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Read a standalone meeting preview without admitting a guest to the room.",
"operationId": "meeting_guest_participants",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeetingParticipants"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings": {
"get": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `GET /call/meetings` through the call domain service.",
"operationId": "meeting_list",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeetingsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `POST /call/meetings` through the call domain service.",
"operationId": "meeting_create",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMeetingRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Meeting"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/active": {
"get": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "List the authenticated actor's active quick calls.",
"operationId": "meeting_list_active",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActiveMeetingsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/invite/{token}": {
"get": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Read the authenticated caller's invitation capability without exposing the creator.",
"operationId": "meeting_invite_permissions",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeetingInvitePermissions"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Queue an owner-authorized guest invitation email.",
"operationId": "meeting_invite",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InviteMeetingRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/invite/{token}/users": {
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Ring registered teammates selected by the standalone meeting owner.",
"operationId": "meeting_invite_users",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InviteMeetingUsersRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/join/{token}": {
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `POST /call/meetings/join/{token}` through the call domain service.",
"operationId": "meeting_join",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JoinCallRequest"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTokenResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/join/{token}/participants": {
"get": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Read the participant preview for an authenticated invitation holder.",
"operationId": "meeting_participants",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeetingParticipants"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/prepare": {
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Reserve a room while the authenticated caller configures a new call.",
"operationId": "meeting_prepare",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeetingPreparation"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/prepare/{preparation_id}": {
"delete": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Cancel an unused room; the domain owns ownership and activation checks.",
"operationId": "meeting_cancel_preparation",
"parameters": [
{
"name": "preparation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/meetings/{meeting_id}": {
"delete": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `DELETE /call/meetings/{meeting_id}` through the call domain service.",
"operationId": "meeting_cancel",
"parameters": [
{
"name": "meeting_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle owner-authorized meeting title and schedule edits.",
"operationId": "meeting_update",
"parameters": [
{
"name": "meeting_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateMeetingRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Meeting"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/preview": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `POST /call/record/preview`.",
"description": "Batch-fetches lightweight previews for a list of call ids. Mirrors the\n`POST /documents/preview` endpoint: no per-id access checks, duplicate\nids are deduplicated server-side, and missing ids come back as\n`CallRecordPreview::DoesNotExist` rather than producing an error.",
"operationId": "get_batch_call_record_preview",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchCallRecordPreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchCallRecordPreviewResponse"
}
}
}
},
"400": {
"description": "call_ids exceeds MAX_BATCH_CALL_IDS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `GET /call/record/{call_id}`.",
"description": "Returns the full [`CallRecord`] (metadata + participants + transcript)\nfor a call identified by its own id. Covers both active and archived calls.\nAccess is validated via channel membership (MemberParticipantRole).",
"operationId": "get_call_record",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallRecord"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `DELETE /call/record/{call_id}`.",
"description": "Deletes a call record (and its participants/transcripts via cascade).\nAccess is validated via channel membership (MemberParticipantRole).",
"operationId": "delete_call_record",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Call record deleted"
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `PATCH /call/record/{call_id}`.",
"description": "Edits a call record: link/channel share permissions, display name, and\nteam sharing. Edit access (channel membership) is required for the request.\n`sharePermission.teamShareAccessLevel` only accepts `view` or `null`; while\nthe call is live it sets the pending share-with-team toggle, and once the\ncall is archived it is additionally authorized against the call's creator.",
"operationId": "edit_call_record",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditCallRecordRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Call record updated"
},
"400": {
"description": "Invalid team-share level, contradictory inputs, or the creator has no team",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Team sharing of an archived call may only be changed by its creator",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Team-sharing facts changed, or the call was archived mid-request; reload and retry",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/decline": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `POST /call/record/{call_id}/decline`.",
"description": "Declines the identified active call for the caller without joining it.\nBound to `call_id` so a stale incoming-call UI cannot decline a newer call\nthat replaced it in the same channel. The caller's other devices are told\nto stop ringing (`call_declined`); the call continues for everyone else.",
"operationId": "decline_call",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Decline recorded"
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "The call is no longer active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/join": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Join a live call by its session id.",
"operationId": "join_call",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JoinCallRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTokenResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": ""
},
"410": {
"description": ""
}
}
}
},
"/call/record/{call_id}/leave": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Leave a specific live call.",
"operationId": "leave_call",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LeaveCallResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/link": {
"post": {
"tags": ["call::inbound::axum_router::meetings"],
"summary": "Handle `POST /call/record/{call_id}/link` through the call domain service.",
"operationId": "meeting_share",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Meeting"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/participants": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Read live participants and track state for a joinable call.",
"operationId": "get_call_participants",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LiveCallParticipantsResponse"
}
}
}
},
"403": {
"description": ""
},
"404": {
"description": ""
}
}
}
},
"/call/record/{call_id}/recording": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Stream the recording bytes for a call record the caller may view.",
"operationId": "get_call_recording",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"video/mp4": {
"schema": {
"$ref": "#/components/schemas/RecordingBytes"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/ring": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Read this account's ring state for a call.",
"operationId": "get_call_ring_state",
"parameters": [
{
"name": "call_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RingStatusResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/share-with-team/toggle": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `POST /call/record/{call_id}/share-with-team/toggle`.",
"description": "Flips the live call's share-with-team toggle and returns the new value as\nthe JSON body. The toggle is applied as canonical team sharing (View for\nthe creator's team) when the call is archived; archived calls answer 409\nand are edited through `PATCH /call/record/{call_id}` instead.",
"operationId": "toggle_share_with_team",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "New value of the share-with-team toggle",
"content": {
"application/json": {
"schema": {
"type": "boolean"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "The call is no longer active",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/record/{call_id}/transcript": {
"patch": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `PATCH /call/record/{call_id}/transcript`.",
"description": "Applies per-diarized-speaker `custom_speaker` overrides to the call's\narchived transcript rows. Auth uses the same `EditAccessLevel` extractor\nas `edit_call_record_handler`.",
"operationId": "edit_call_transcript",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditCallTranscriptRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Transcript updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/ring-status/{call_id}": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `GET /call/ring-status/{call_id}`.",
"description": "Reports whether the authenticated user should keep ringing for the call.\nPolled by native clients while the CallKit incoming-call UI is showing, so\na ring can be cancelled when the user answers on another device\n(`answered`) or the call ends before anyone answers (`ended`).\n\nOutside the user-auth layer: the bearer credential is the recipient's\nLiveKit JWT from the VoIP push payload, verified with the LiveKit secret.",
"operationId": "get_ring_status",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RingStatusResponse"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/ring-status/{call_id}/decline": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `POST /call/ring-status/{call_id}/decline`.",
"description": "Declines a ringing call from a native client, e.g. the iPhone lock-screen\ndecline button, so the user's other devices stop ringing. Authorized like\n[`ring_status_handler`]: the bearer credential is the recipient's LiveKit\nJWT from the VoIP push payload, which identifies both the room and the\ndeclining user.",
"operationId": "decline_ring",
"parameters": [
{
"name": "call_id",
"in": "path",
"description": "Call ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Decline recorded"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "The call is no longer ringing",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/webhook": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `POST /call/webhook`.",
"description": "Receives webhook events from the RTC provider (e.g. LiveKit).\nThe `Authorization` header contains the webhook auth token\nand the body contains the raw event payload.",
"operationId": "call_webhook",
"responses": {
"200": {
"description": "Event processed"
},
"401": {
"description": "Invalid webhook signature"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/{channel_id}": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `GET /call/{channel_id}`.",
"description": "Gets or creates a call for the channel. If a call already exists, joins it;\notherwise creates a new one. Always returns a join token.",
"operationId": "get_or_create_call",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTokenResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Start or join a channel call explicitly.",
"operationId": "start_call",
"parameters": [
{
"name": "channel_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JoinCallRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTokenResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": ""
}
}
},
"delete": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `DELETE /call/{channel_id}`.",
"operationId": "leave_or_end_call",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LeaveCallResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "No active call",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/{channel_id}/active": {
"get": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `GET /call/{channel_id}/active`.",
"description": "Returns 200 with call info if an active call exists, or 204 No Content if not.",
"operationId": "check_active_call",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallActiveResponse"
}
}
}
},
"204": {
"description": "No active call"
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/call/{room_name}/transcript": {
"post": {
"tags": ["call::inbound::axum_router"],
"summary": "Handler for `POST /call/{channel_id}/transcript`.",
"description": "Receives transcript segments from the transcription agent.\nAuthenticated via the `x-macro-internal-call` shared secret.\nDuplicate segments (same `segment_id`) are ignored.",
"operationId": "ingest_transcript",
"parameters": [
{
"name": "room_name",
"in": "path",
"description": "RTC room name; the transcription agent passes its LiveKit room verbatim",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TranscriptSegmentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Segment ingested"
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "No active call",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channel-labels": {
"get": {
"tags": ["channel_labels"],
"summary": "List the caller's shared or private labels.",
"operationId": "list_channel_labels",
"parameters": [
{
"name": "scope",
"in": "query",
"description": "`personal` selects private labels; `team` requires team membership.",
"required": false,
"schema": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelLabelsList"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["channel_labels"],
"summary": "Create a label for the caller's authorized scope.",
"operationId": "create_channel_label",
"parameters": [
{
"name": "scope",
"in": "query",
"description": "`personal` selects private labels; `team` requires team membership.",
"required": false,
"schema": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelLabelRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelLabel"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channel-labels/channels/{channel_id}": {
"put": {
"tags": ["channel_labels"],
"summary": "Move a channel into a label of the caller's authorized scope, or out of any label.",
"operationId": "set_channel_label",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "The channel id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "scope",
"in": "query",
"description": "`personal` selects private labels; `team` requires team membership.",
"required": false,
"schema": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetChannelLabelRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channel-labels/preview": {
"post": {
"tags": ["channel_labels"],
"summary": "Preview visible channels matched by a smart tag, without creating it.",
"operationId": "preview_smart_tag",
"parameters": [
{
"name": "scope",
"in": "query",
"description": "`personal` selects private labels; `team` requires team membership.",
"required": false,
"schema": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelLabelRule"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartTagPreview"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channel-labels/{label_id}": {
"delete": {
"tags": ["channel_labels"],
"summary": "Delete a label of the caller's authorized scope. Its channels return to the plain list.",
"operationId": "delete_channel_label",
"parameters": [
{
"name": "label_id",
"in": "path",
"description": "The label id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "scope",
"in": "query",
"description": "`personal` selects private labels; `team` requires team membership.",
"required": false,
"schema": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["channel_labels"],
"summary": "Update a label, optionally moving it to another authorized scope.",
"operationId": "rename_channel_label",
"parameters": [
{
"name": "label_id",
"in": "path",
"description": "The label id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "scope",
"in": "query",
"description": "`personal` selects private labels; `team` requires team membership.",
"required": false,
"schema": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameChannelLabelRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelLabel"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels`.",
"operationId": "create_channel",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/activity": {
"get": {
"tags": ["channels"],
"summary": "Handler for `GET /channels/activity`.",
"operationId": "get_activity",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiActivity"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/activity`.",
"operationId": "post_activity",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostActivityRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiActivity"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/attachments/{entity_type}/{entity_id}/references": {
"get": {
"tags": ["channels::inbound::axum_router"],
"summary": "Handler for `GET /channels/attachments/{entity_type}/{entity_id}/references`.",
"operationId": "get_attachment_references",
"parameters": [
{
"name": "entity_type",
"in": "path",
"description": "Type of the attachment entity",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "entity_id",
"in": "path",
"description": "Id of the attachment entity",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetAttachmentReferencesResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/get_or_create_dm": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/get_or_create_dm`.",
"operationId": "get_or_create_dm",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetOrCreateDmRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetOrCreateChannelResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/get_or_create_private": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/get_or_create_private`.",
"operationId": "get_or_create_private",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetOrCreatePrivateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetOrCreateChannelResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/join/{join_code}": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/join/{join_code}`.",
"operationId": "join_channel_by_code",
"parameters": [
{
"name": "join_code",
"in": "path",
"description": "Channel join code",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/mentions": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/mentions`.",
"operationId": "create_entity_mention",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEntityMentionRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEntityMentionResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/mentions/{mention_id}": {
"delete": {
"tags": ["channels"],
"summary": "Handler for `DELETE /channels/mentions/{mention_id}`.",
"operationId": "delete_entity_mention",
"parameters": [
{
"name": "mention_id",
"in": "path",
"description": "Entity mention id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteEntityMentionResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/preview": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/preview`.",
"operationId": "get_batch_channel_preview",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchChannelPreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchChannelPreviewResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}": {
"get": {
"tags": ["channels::inbound::axum_router"],
"summary": "Handler for `GET /channels/{channel_id}`.",
"operationId": "get_channel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiChannelDetail"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["channels"],
"summary": "Handler for `DELETE /channels/{channel_id}`.",
"operationId": "delete_channel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["channels"],
"summary": "Handler for `PATCH /channels/{channel_id}`.",
"operationId": "patch_channel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchChannelRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/access-requests/mine": {
"get": {
"tags": ["channels"],
"summary": "Handler for `GET /channels/{channel_id}/access-requests/mine`.",
"operationId": "get_my_channel_access_request",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelAccessRequestState"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["channels"],
"summary": "Handler for `PUT /channels/{channel_id}/access-requests/mine`.",
"operationId": "request_channel_access",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelAccessRequest"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["channels"],
"summary": "Handler for `DELETE /channels/{channel_id}/access-requests/mine`.",
"operationId": "cancel_channel_access_request",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/access-requests/{request_id}": {
"get": {
"tags": ["channels"],
"summary": "Handler for `GET /channels/{channel_id}/access-requests/{request_id}`.",
"operationId": "get_channel_access_request",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "request_id",
"in": "path",
"description": "Access request ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelAccessRequest"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/access-requests/{request_id}/resolve": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/{channel_id}/access-requests/{request_id}/resolve`.",
"operationId": "resolve_channel_access_request",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "request_id",
"in": "path",
"description": "Access request ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveChannelAccessRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelAccessRequest"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/attachments": {
"get": {
"tags": ["channels::inbound::axum_router"],
"summary": "Handler for `GET /channels/{channel_id}/attachments`.",
"operationId": "get_channel_attachments",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"description": "Page size (1-500, default 50)",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "cursor",
"in": "query",
"description": "Base64 encoded cursor value",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "attachment_type",
"in": "query",
"description": "Filter by type: 'static' for images/videos, 'dss' for documents",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiChannelAttachmentsPage"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/bots": {
"get": {
"tags": ["bots"],
"summary": "Handler for `GET /channels/{channel_id}/bots`.",
"operationId": "list_channel_bots",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Bot"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["bots"],
"summary": "Handler for `POST /channels/{channel_id}/bots`.",
"operationId": "add_channel_bot",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddChannelBotRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/bots/scoped": {
"post": {
"tags": ["bots"],
"summary": "Handler for `POST /channels/{channel_id}/bots/scoped`.",
"operationId": "create_channel_scoped_bot",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelScopedBotRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelScopedBotResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/join": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/{channel_id}/join`.",
"operationId": "join_channel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/join-link": {
"get": {
"tags": ["channels"],
"summary": "Handler for `GET /channels/{channel_id}/join-link`.",
"operationId": "get_channel_join_link",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelJoinCodeResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/leave": {
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/{channel_id}/leave`.",
"operationId": "leave_channel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/participants": {
"get": {
"tags": ["channels::inbound::axum_router"],
"summary": "Handler for `GET /channels/{channel_id}/participants`.",
"operationId": "get_channel_participants",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiChannelParticipant"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["channels"],
"summary": "Handler for `POST /channels/{channel_id}/participants`.",
"operationId": "add_participants",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddParticipantsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["channels"],
"summary": "Handler for `DELETE /channels/{channel_id}/participants`.",
"operationId": "remove_participants",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveParticipantsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/profile_picture": {
"put": {
"tags": ["channels::inbound::axum_router::profile_picture"],
"summary": "Set a channel or group chat profile picture. Requires channel participation.",
"operationId": "set_channel_picture",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetChannelPictureRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Picture updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/channels/{channel_id}/webhook": {
"post": {
"tags": ["bots"],
"summary": "Handler for `POST /channels/{channel_id}/webhook`.",
"operationId": "post_channel_bot_webhook",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "x-macro-bot-token",
"in": "header",
"description": "Preferred bot authentication token",
"required": false,
"schema": {
"type": ["string", "null"]
}
},
{
"name": "x-macro-channel-bot-token",
"in": "header",
"description": "Legacy channel-scoped bot authentication token",
"required": false,
"deprecated": true,
"schema": {
"type": ["string", "null"]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelWebhookRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelWebhookResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/collab_surfaces/{id}": {
"get": {
"tags": ["collab_surfaces"],
"summary": "Fetch a collab surface.",
"operationId": "get_collab_surface",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The surface id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollabSurfaceResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["collab_surfaces"],
"summary": "Idempotently ensure a collab surface exists (load-or-create).",
"description": "The id is caller-supplied, so an embedding surface can hold a stable id\nand blindly ensure it on mount: the first ensure creates and initializes\nthe session, every later one (including concurrent ones) returns the same\nsurface. A soft-deleted id is `410 Gone` and never comes back.",
"operationId": "ensure_collab_surface",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The surface id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnsureCollabSurfaceRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollabSurfaceResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No access to the parent entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "The parent entity does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "The surface id is already in use",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "The surface id was deleted and cannot be reused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Malformed request body (plain text)"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["collab_surfaces"],
"summary": "Soft-delete a collab surface.",
"operationId": "delete_collab_surface",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The surface id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/collab_surfaces/{id}/token": {
"post": {
"tags": ["collab_surfaces"],
"summary": "Mint a sync-service connection token for a surface.",
"operationId": "create_collab_surface_token",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The surface id.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollabSurfaceTokenResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "The surface is not initialized yet, or its id is in use",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/comms/channels": {
"get": {
"tags": ["channels"],
"summary": "Handle channel list requests for `GET /comms/channels`.",
"operationId": "get_channels",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Page size (1-100, default 100)",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "cursor",
"in": "query",
"description": "Opaque cursor for the next page",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiChannelListPage"
}
}
}
},
"400": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"500": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/crm/blocked-domains": {
"get": {
"tags": ["crm::inbound::axum_router::blocked_domains"],
"summary": "List the domains the caller's team keeps out of email sync,\nalphabetically. Any team member may read.",
"operationId": "list_crm_blocked_domains",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CrmBlockedDomainResponse"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/blocked-domains/{domain}": {
"put": {
"tags": ["crm::inbound::axum_router::blocked_domains"],
"summary": "Block a domain: email sync stops creating or updating CRM records for\nit, and the company and contacts the CRM holds for it are hidden.\nIdempotent. Requires an admin/owner team role (403).",
"operationId": "block_crm_domain",
"parameters": [
{
"name": "domain",
"in": "path",
"description": "A bare domain like acme.com",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["crm::inbound::axum_router::blocked_domains"],
"summary": "Unblock a domain: email sync resumes for it, and what blocking hid is\nshown again. Idempotent. Requires an admin/owner team role (403).",
"operationId": "unblock_crm_domain",
"parameters": [
{
"name": "domain",
"in": "path",
"description": "A bare domain like acme.com",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/companies": {
"post": {
"tags": ["crm::inbound::axum_router::create_company"],
"summary": "Manually create a CRM company for the caller's team. Any team member\nmay create one. A domain, when given, must not already be tracked by the team\n(409), and the team's CRM killswitch must be on (403). Returns the\ncreated company in the same shape as `GET /crm/companies/{id}` (its\ncontact list is empty until emails populate it).",
"operationId": "create_crm_company",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCrmCompanyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmCompanyResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/companies/{company_id}": {
"get": {
"tags": ["crm::inbound::axum_router::get_company"],
"summary": "Fetch a single CRM company by id, hydrated with its domains, the\nprimary domain's directory display metadata (name + description),\nand the company's contacts. Access is enforced by\n[`CrmCompanyAccessLevelExtractor`]: the user must be on the team\nthat owns the company, and hidden companies are invisible to plain\nmembers. Admin/owner callers see hidden companies and contacts so\nthey can render the right unhide UI.",
"operationId": "get_company",
"parameters": [
{
"name": "company_id",
"in": "path",
"description": "The CRM company to fetch",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmCompanyResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/companies/{company_id}/contacts": {
"get": {
"tags": ["crm::inbound::axum_router::list_company_contacts"],
"summary": "List the contacts of a CRM company. Access is enforced by\n[`CrmCompanyAccessLevelExtractor`]: the user must be on the team that\nowns the company. Hidden companies and hidden contacts are invisible\nto plain members; admin/owner callers see hidden rows so they can\nrender the right unhide UI.",
"operationId": "list_company_contacts",
"parameters": [
{
"name": "company_id",
"in": "path",
"description": "The CRM company whose contacts to list",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CrmContactResponse"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["crm::inbound::axum_router::create_contact"],
"summary": "Manually create a contact under a CRM company. Access is enforced by\n[`CrmCompanyAccessLevelExtractor`]: the caller must be on the team\nthat owns the company (hidden companies are reachable for\nadmin/owner only, and the new contact then inherits `hidden`). The\ncompany must not already track the email (409), and the team's CRM\nkillswitch must be on (403).",
"operationId": "create_crm_contact",
"parameters": [
{
"name": "company_id",
"in": "path",
"description": "The CRM company to add the contact to",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCrmContactRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmContactResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/companies/{company_id}/email-sync": {
"put": {
"tags": ["crm::inbound::axum_router::set_email_sync"],
"summary": "Toggle `email_sync` on a CRM company. Purely a visibility flag —\nit gates whether team members can see each other's emails with\nthis company. Existing CRM data is unaffected.",
"operationId": "set_email_sync",
"parameters": [
{
"name": "company_id",
"in": "path",
"description": "The CRM company to update",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetEmailSyncRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Company is hidden; un-hide before enabling email sync",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/companies/{company_id}/hidden": {
"put": {
"tags": ["crm::inbound::axum_router::set_company_hidden"],
"summary": "Toggle `hidden` on a CRM company. Hiding also disables\n`email_sync` and soft-hides every contact under the company.\nUn-hide restores contact visibility only; `email_sync` is left\nuntouched (the team must re-enable it explicitly). Contact rows\nand contact sources survive the cycle.",
"operationId": "set_company_hidden",
"parameters": [
{
"name": "company_id",
"in": "path",
"description": "The CRM company to update",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetCompanyHiddenRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/companies/{company_id}/name": {
"put": {
"tags": ["crm::inbound::axum_router::set_company_name"],
"summary": "Rename a CRM company. Access is enforced by\n[`CrmCompanyAccessLevelExtractor`]: the caller must be on the team\nthat owns the company (hidden companies are reachable for\nadmin/owner only). The name is a team-scoped override\n(`custom_name`) and never touches the global domain directory.",
"operationId": "set_crm_company_name",
"parameters": [
{
"name": "company_id",
"in": "path",
"description": "The CRM company to rename",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetCompanyNameRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/contacts": {
"get": {
"tags": ["crm::inbound::axum_router::search_contacts"],
"summary": "Search the caller's team's CRM contacts by email or name. Any team member\nmay search visible contacts; admin/owner callers also match hidden\ncontacts and contacts under hidden companies.",
"operationId": "search_contacts",
"parameters": [
{
"name": "query",
"in": "query",
"description": "Text the contact's email or name must contain (case-insensitive).\nEmpty lists the most recently interacted contacts.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum contacts to return (1-500, default 20).",
"required": false,
"schema": {
"type": ["integer", "null"],
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchContactsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["crm::inbound::axum_router::create_team_contact"],
"summary": "Manually create a contact without a company for the caller's team.\nAny team member may create one. The team must not already have a\ncompany-less contact with the email (409), and the team's CRM\nkillswitch must be on (403).",
"operationId": "create_crm_team_contact",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCrmTeamContactRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmContactResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/contacts/by-email": {
"get": {
"tags": ["crm::inbound::axum_router::get_contact_by_email"],
"summary": "Look up a CRM contact by email in the caller's team. Returns a null\n`contact` when no visible contact exists. Any team member may resolve a\nvisible contact; admin/owner callers may also resolve hidden contacts and\ncontacts under hidden companies. Returns 400 when several visible contacts\nmatch; callers must choose an explicit contact ID instead.",
"operationId": "get_contact_by_email",
"parameters": [
{
"name": "email",
"in": "query",
"description": "The contact email to resolve within the caller's team.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The matching contact, or a null contact when none is visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetContactByEmailResponse"
}
}
}
},
"400": {
"description": "Invalid email or multiple visible contacts match; choose a contact ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/contacts/{contact_id}": {
"get": {
"tags": ["crm::inbound::axum_router::get_contact"],
"summary": "Fetch a single CRM contact by id. Access is enforced by\n[`CrmContactAccessLevelExtractor`]: the user must be on the team that\nowns the contact's parent company, and hidden contacts are invisible\nto plain members. Admin/owner callers see hidden contacts so they can\nrender the right unhide UI.",
"operationId": "get_contact",
"parameters": [
{
"name": "contact_id",
"in": "path",
"description": "The CRM contact to fetch",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmContactResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/contacts/{contact_id}/hidden": {
"put": {
"tags": ["crm::inbound::axum_router::set_contact_hidden"],
"summary": "Toggle `hidden` on a CRM contact. Hiding is a display-only opt-out\nscoped to the team that owns the contact's company.",
"operationId": "set_contact_hidden",
"parameters": [
{
"name": "contact_id",
"in": "path",
"description": "The CRM contact to update",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetContactHiddenRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/contacts/{contact_id}/name": {
"put": {
"tags": ["crm::inbound::axum_router::set_contact_name"],
"summary": "Rename a CRM contact. Access is enforced by\n[`CrmContactAccessLevelExtractor`]: the caller must be on the team\nthat owns the contact's company (hidden contacts are reachable for\nadmin/owner only). The name overwrites the team-scoped\n`crm_contacts.name` column.",
"operationId": "set_crm_contact_name",
"parameters": [
{
"name": "contact_id",
"in": "path",
"description": "The CRM contact to rename",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetContactNameRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/pipelines": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "List the caller's live pipelines in their CRM.",
"operationId": "list_crm_pipelines",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessiblePipeline"
}
}
}
}
}
}
},
"post": {
"tags": ["crm::inbound::pipelines"],
"summary": "Create a private or team-shared pipeline.",
"operationId": "create_crm_pipeline",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePipeline"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessiblePipeline"
}
}
}
}
}
}
},
"/crm/pipelines/{id}": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "Read one pipeline by its entity identity.",
"operationId": "get_crm_pipeline",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessiblePipeline"
}
}
}
}
}
}
},
"/crm/pipelines/{id}/name": {
"put": {
"tags": ["crm::inbound::pipelines"],
"summary": "Rename a pipeline.",
"operationId": "rename_crm_pipeline",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenamePipeline"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/crm/pipelines/{id}/ops": {
"post": {
"tags": ["crm::inbound::pipelines"],
"summary": "Edit pipeline schema or records with the common typed operations.",
"operationId": "apply_crm_pipeline_ops",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpBatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppliedOps"
}
}
}
}
}
}
},
"/crm/pipelines/{id}/permissions": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "Read the owner, team grant and channel recipients of a pipeline the caller can edit.",
"operationId": "get_crm_pipeline_permissions",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
}
}
},
"patch": {
"tags": ["crm::inbound::pipelines"],
"summary": "Share a pipeline the caller can edit with channels, or change or remove\ntheir access. Team access changes through `/sharing`; there is no share link.",
"operationId": "update_crm_pipeline_permissions",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSharePermissionRequestV2"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
}
}
}
},
"/crm/pipelines/{id}/rows": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "Read pipeline records through pipeline access.",
"operationId": "get_crm_pipeline_rows",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "after",
"in": "query",
"description": "Continue after this row identity.",
"required": false,
"schema": {
"type": ["string", "null"],
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StorageRows"
}
}
}
}
}
},
"post": {
"tags": ["crm::inbound::pipelines"],
"summary": "Query rows through pipeline access using the shared view protocol.",
"operationId": "query_crm_pipeline_rows",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StorageRowsQuery"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StorageRows"
}
}
}
}
}
}
},
"/crm/pipelines/{id}/sharing": {
"put": {
"tags": ["crm::inbound::pipelines"],
"summary": "Update sharing.",
"operationId": "share_crm_pipeline",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePipeline"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/crm/pipelines/{id}/stage-requirements": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "Read requirements by stable stage and field identities.",
"operationId": "get_crm_pipeline_stage_requirements",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StageRequirement"
}
}
}
}
}
}
},
"put": {
"tags": ["crm::inbound::pipelines"],
"summary": "Replace the required fields for one stage. An empty list removes its rule.",
"operationId": "set_crm_pipeline_stage_requirement",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StageRequirement"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/crm/pipelines/{id}/table": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "Read the host-owned table schema.",
"operationId": "get_crm_pipeline_table",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TableDetail"
}
}
}
}
}
}
},
"/crm/pipelines/{id}/trash": {
"put": {
"tags": ["crm::inbound::pipelines"],
"summary": "Trash or restore a pipeline.",
"operationId": "trash_crm_pipeline",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrashPipeline"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/crm/pipelines/{id}/views/{view}/positions": {
"get": {
"tags": ["crm::inbound::pipelines"],
"summary": "Read saved board positions through pipeline access.",
"operationId": "get_crm_pipeline_view_positions",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "view",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CardPosition"
}
}
}
}
}
}
}
},
"/crm/settings": {
"get": {
"tags": ["crm::inbound::axum_router::team_settings"],
"summary": "Read the caller's team CRM configuration. Any team member may read;\nteams without a settings row get the defaults.",
"operationId": "get_crm_team_settings",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmTeamSettingsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["crm::inbound::axum_router::team_settings"],
"summary": "Partially update the caller's team CRM configuration. Any team\nmember may update the views fields (`team_views`,\n`default_team_view_id`); the governance fields (permission\nthresholds, `closed_stage_ids`, `exclude_personal_emails`) require an admin/owner team role\n(403 otherwise). Omitted fields keep their current values;\n`team_views` is replaced whole. Returns the resulting settings.",
"operationId": "put_crm_team_settings",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCrmTeamSettingsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmTeamSettingsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crm/stages": {
"put": {
"tags": ["crm::inbound::axum_router::stages"],
"summary": "Replace the team's deal stages; requires `edit_stages_role` (403 otherwise).",
"operationId": "put_crm_team_stages",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceCrmStagesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrmStagesResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["crm::inbound::axum_router::stages"],
"summary": "Reset the team's deal stages to the defaults; gated like `PUT /crm/stages`.",
"operationId": "reset_crm_team_stages",
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases": {
"get": {
"tags": ["databases"],
"summary": "List the caller's databases.",
"operationId": "list_databases",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListedDatabase"
}
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["databases"],
"summary": "Create a database owned by the caller; its first table, \"Table 1\", holds a\n\"Name\" text column.",
"operationId": "create_database",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDatabaseRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Database"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/queries": {
"post": {
"tags": ["databases"],
"summary": "Save an immutable query. Editing a question saves a new one.",
"operationId": "save_database_query",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SaveQueryRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SavedQuery"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "The database is missing or not visible",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "The query is too long",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/queries/{query_id}": {
"get": {
"tags": ["databases"],
"summary": "A saved query's definition, for its creator or a viewer of its database.",
"operationId": "get_database_query",
"parameters": [
{
"name": "query_id",
"in": "path",
"description": "Saved query id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SavedQuery"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Missing, or not readable by the caller",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/query": {
"post": {
"tags": ["databases"],
"summary": "Run one statement as the authenticated user. The viewer's catalog authorizes reads;\nthe SQL domain service obtains an edit receipt for every written database.",
"operationId": "query_databases",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatabaseQueryRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SqlOutcome"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/starter": {
"post": {
"tags": ["databases"],
"summary": "Create a small example once for the authenticated user, if they have no databases.",
"operationId": "ensure_starter_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StarterDatabase"
}
}
}
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "Provisioning failed; safe to retry"
}
}
}
},
"/databases/webhooks/{token}": {
"post": {
"tags": ["databases"],
"summary": "Insert rows through a webhook. The body is a JSON object, one row, or\nan array of up to 100 objects, one row each. Keys name columns by name\n(ignoring case) or id; `null` leaves a cell empty. Values may be loose:\n`\"45\"` for a number, `\"true\"` for a checkbox, a label or labels for a\nselect, `2026-10-09` for a date. Nothing is written unless every row fits.",
"operationId": "deliver_database_webhook",
"parameters": [
{
"name": "token",
"in": "path",
"description": "The webhook's secret token",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "A row, or an array of rows",
"content": {
"application/json": {
"schema": {}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatabaseWebhookDeliveryResponse"
}
}
}
},
"400": {
"description": "The payload does not fit the table; nothing was written",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvalidDatabaseWebhookPayloadResponse"
}
}
}
},
"403": {
"description": "The webhook's creator can no longer edit the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "No such webhook",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}": {
"get": {
"tags": ["databases"],
"summary": "Schema detail of one database.",
"operationId": "get_database",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatabaseDetail"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/awareness": {
"put": {
"tags": ["databases"],
"summary": "Tell a database's other viewers where the caller is.",
"operationId": "share_database_awareness",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Awareness"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Relayed to the database's other viewers"
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/changes/{change}/undo": {
"post": {
"tags": ["databases"],
"summary": "Undo one of your own committed changes: its inverse applies as a new,\njournaled batch, under the table's lock, guarded against what others\nchanged since. A cell someone changed since is left alone and listed; a\nrow or column you added that someone else wrote since, or a name, option,\norder, view or card place changed since, refuses the undo. Others'\nchanges always stay. Redo by undoing the undo's change.",
"operationId": "undo_database_change",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "change",
"in": "path",
"description": "The change's journal id",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UndoChangeResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No edit access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "No such change in this database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "The table kept moving under the undo",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/duplicate": {
"post": {
"tags": ["databases"],
"summary": "Copy a database, with its tables, columns, views and rows, into a new one\nthe caller owns. Its sharing, forms, webhooks and history stay behind.",
"operationId": "duplicate_database",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DuplicateDatabaseRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Database"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/import": {
"post": {
"tags": ["databases"],
"summary": "Import a new table and every row atomically; retries carry the same request ID.",
"operationId": "import_database_table",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportTable"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Table"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/ops": {
"post": {
"tags": ["databases"],
"summary": "Apply a batch of typed ops, the one write surface of a database: add,\nrename, remove and order tables and columns, change a column's type, add\nand change options, insert, update and delete rows, and write views and a\nboard's card places. The ops apply in order in one transaction, so a\nlater op may name a table, column, option or view an earlier one created\nunder the id its client minted. Ops are last-write-wins unless the batch names\nbase versions. A refused op, named by its index (and row and column where\nrelevant), leaves the whole batch unwritten.",
"operationId": "apply_database_ops",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyOpsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyOpsResponse"
}
}
}
},
"400": {
"description": "An op was refused; nothing was written",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpRefusalResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No edit access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "A table moved from its base version, or a schema change raced another",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/permissions": {
"get": {
"tags": ["databases"],
"summary": "Read recipients and the team share for a database owned by the caller.\nLink sharing is always `null`: databases do not support it.",
"operationId": "get_database_permissions",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["databases"],
"summary": "Update channel recipients and the team share after proving database\nownership. Turning on link sharing is refused; ownership cannot be\nchanged here. Only the actual owner may change the team share, and a 409\nmeans sharing changed since the request was authorized.",
"operationId": "update_database_permissions",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSharePermissionRequestV2"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/tables/{table_id}/changes": {
"get": {
"tags": ["databases"],
"summary": "What changed in a table since a version, from the change journal: the\nrows that changed, each once as it stands now (`insert`, `update` or\n`delete`), and the columns. A reader holding the table at `since` reads\njust those rows; it reads the table whole when a column changed, the\njournal is not `complete`, or the rows are `truncated`.",
"operationId": "get_database_table_changes",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "table_id",
"in": "path",
"description": "Table id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "since",
"in": "query",
"description": "The table version the reader last read.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TableChanges"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/tables/{table_id}/columns/{column_id}/casts": {
"get": {
"tags": ["databases"],
"summary": "What changing one column to each type of the type menu would do to its\nvalues: safe, checked (with how many values would not convert and a few\nof them), or never (with why). Changes nothing.",
"operationId": "list_database_column_casts",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "table_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "column_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnCast"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/tables/{table_id}/columns/{column_id}/conversion": {
"post": {
"tags": ["databases"],
"summary": "What one column's values become under another type: the values that\nconvert, with the options they need, for a new column of that type beside\nit. The column itself is left as it is: a client writes the conversion as\none ops batch, a `create_column` then an `update_rows`, with the answered\ntable version as its base version. Changes nothing.",
"operationId": "convert_database_column",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "table_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "column_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnConversionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnConversion"
}
}
}
},
"400": {
"description": "No value of the column converts to the type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/tables/{table_id}/columns/{column_id}/infer-type": {
"post": {
"tags": ["databases"],
"summary": "Settle a new empty text column's type.",
"operationId": "infer_database_column_type",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "table_id",
"in": "path",
"description": "Table id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "column_id",
"in": "path",
"description": "Column id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferColumnTypeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferColumnTypeOutcome"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/tables/{table_id}/rows/{row_id}/history": {
"get": {
"tags": ["databases"],
"summary": "A row's history, from the change journal: every committed change that\ntouched it, newest first, with who made it, when, and the values of the\ncolumns it touched before and after. It reads after the row is removed,\nso a removed row's last values stay readable.",
"operationId": "get_database_row_history",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "table_id",
"in": "path",
"description": "Table id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "row_id",
"in": "path",
"description": "Row id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RowHistoryResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/views/{view_id}/positions": {
"get": {
"tags": ["databases"],
"summary": "Where a board's cards sit, for drawing it: the views come with the\ndatabase's detail, their cards' places from here.",
"operationId": "get_database_view_positions",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "view_id",
"in": "path",
"description": "View id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewPositionsResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/webhooks": {
"get": {
"tags": ["databases"],
"summary": "The database's webhooks.",
"operationId": "list_database_webhooks",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDatabaseWebhooksResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No edit access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["databases"],
"summary": "Create a webhook: a secret URL whose calls insert rows into one of the\ndatabase's tables, writing with the creator's access.",
"operationId": "create_database_webhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDatabaseWebhookRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedDatabaseWebhookResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No edit access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "No such table in the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/databases/{id}/webhooks/{webhook_id}": {
"delete": {
"tags": ["databases"],
"summary": "Delete a webhook; its URL stops working.",
"operationId": "delete_database_webhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Database id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "webhook_id",
"in": "path",
"description": "Webhook id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "No edit access to the database",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/dictation/transcribe": {
"post": {
"tags": ["dictation"],
"summary": "Transcribe a transient recording with OpenAI Whisper.",
"description": "Available to every signed-in user on every plan; does not consume chat\ncredits. Audio and transcripts are never persisted.",
"operationId": "transcribe_dictation",
"parameters": [
{
"name": "language",
"in": "query",
"description": "ISO 639-1 language hint",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Encoded WebM, MP4, Ogg, or WAV audio up to 8 MiB and five minutes",
"content": {
"audio/webm": {
"schema": {
"type": "string",
"format": "binary",
"description": "OpenAPI representation of the raw encoded audio body extracted as `Bytes`."
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TranscribeResponse"
}
}
}
},
"400": {
"description": "Empty, oversized, or malformed request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Only signed-in users may dictate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"413": {
"description": "Body exceeds 8 MiB"
},
"415": {
"description": "Unsupported audio container",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Per-user hourly rate limit exceeded"
},
"502": {
"description": "Provider failure",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "Transcription capacity exhausted; retry after the Retry-After delay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents": {
"get": {
"tags": ["document"],
"summary": "Gets the users documents to populate their recent document list",
"operationId": "get_user_documents_handler",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "The maximum number of documents to retreive. Default 10, max 100.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "offset",
"in": "query",
"description": "The offset to start from. Default 0.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "file_type",
"in": "query",
"description": "The file type to filter by. Default all.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDocumentsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["document"],
"summary": "Handler for `POST /documents`.",
"description": "Creates a new document, generates an S3 presigned upload URL, and returns\nthe document metadata with the URL for the client to upload to.",
"operationId": "create_document",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDocumentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/DocumentResponse",
"description": "Document metadata and upload URL."
},
{
"type": "object",
"required": ["contentType"],
"properties": {
"contentType": {
"type": "string",
"description": "Content type of the document converted from file type."
},
"fileType": {
"type": ["string", "null"],
"description": "The file type of the document."
}
}
}
],
"description": "Create document response data with content lifecycle metadata."
}
],
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Document name exceeds the maximum length",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/create_canvas": {
"post": {
"tags": ["document"],
"summary": "Creates and initializes a Canvas in one backend-owned lifecycle.",
"operationId": "create_canvas_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCanvasDocumentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for creating a native Canvas.",
"required": ["documentId", "documentMetadata", "token"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created native Canvas"
},
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Metadata for the created document"
},
"token": {
"type": "string",
"description": "A pre-generated permission token that you can use for SS"
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/create_markdown": {
"post": {
"tags": ["document"],
"summary": "Creates and initializes a markdown document in one backend-owned lifecycle.",
"operationId": "create_markdown_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMarkdownDocumentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for creating a markdown document.",
"required": ["documentId", "documentMetadata", "token"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created markdown document"
},
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Metadata for the created document"
},
"token": {
"type": "string",
"description": "A pre-generated permission token that you can use for SS"
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/create_skill": {
"post": {
"tags": ["document"],
"summary": "Creates a skill document with initialized markdown content and its\nrouting description in one backend-owned lifecycle. Skills are markdown documents containing\ninstructions that AI reads and follows when the skill is referenced in an\nAI input.",
"operationId": "create_skill_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSkillRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for creating a skill.",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created skill."
}
}
}
}
}
},
"400": {
"description": "The description is blank, longer than one line or 300 characters, or does not start \"Use when\"",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/create_snippet": {
"post": {
"tags": ["document"],
"summary": "Creates a snippet document with initialized markdown content in one\nbackend-owned lifecycle. Snippets are created personal; team sharing is\ntoggled separately via `PUT /documents/{document_id}/team_share`.",
"operationId": "create_snippet_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSnippetRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for creating a snippet.",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created snippet."
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/create_task": {
"post": {
"tags": ["document"],
"summary": "Creates a task document with properties and initialized markdown content in\none backend-owned lifecycle.",
"operationId": "create_task_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTaskRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for creating a task.",
"required": [
"documentId",
"documentMetadata",
"token",
"initialSnapshot"
],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created task."
},
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Metadata for the created document"
},
"initialSnapshot": {
"type": "string",
"description": "Base64-encoded canonical Loro snapshot used to initialize the task."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The team this task number is scoped to."
},
"teamTaskId": {
"type": ["integer", "null"],
"format": "int32",
"description": "The task number assigned within the team."
},
"token": {
"type": "string",
"description": "A pre-generated permission token that you can use for SS"
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/github_prs/tasks": {
"post": {
"tags": ["document"],
"summary": "Handler for `POST /documents/github_prs/tasks`.",
"description": "Returns the task documents each of up to 100 GitHub pull requests references, for the pull\nrequests the caller can see.",
"operationId": "get_github_pull_request_tasks",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GithubPullRequestTasksRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GithubPullRequestTasksResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/initialize_user_documents": {
"post": {
"tags": ["document"],
"operationId": "initialize_user_documents",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericSuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/list": {
"get": {
"tags": ["document"],
"summary": "Gets a list of all the user's documents so they are able to be searched on",
"operationId": "get_document_list_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDocumentSearchResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/permissions_token/validate": {
"post": {
"tags": ["document"],
"summary": "Validates the provided document permissions token",
"operationId": "validate_document_permissions_token",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentPermissionsTokenRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentPermissionsToken"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/permissions_token/{document_id}": {
"post": {
"tags": ["document"],
"summary": "Generates a document permissions token for a provided document id",
"operationId": "get_document_permissions_token",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentPermissionsTokenResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/presave/{document_id}": {
"put": {
"tags": ["document"],
"summary": "Takes the docx document bom parts and generates presigned urls to upload\nany new content",
"operationId": "presave_document_handler",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreSaveDocumentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreSaveDocumentResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
},
"deprecated": true
}
},
"/documents/preview": {
"post": {
"tags": ["document"],
"operationId": "get_batch_preview_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchPreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchPreviewResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/similarity_search": {
"post": {
"tags": ["document"],
"summary": "Handler for `POST /documents/similarity_search`.",
"description": "Returns existing tasks similar to an unsaved draft. Runs vector retrieval +\nrerank only and persists nothing.",
"operationId": "task_similarity_search_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskSimilaritySearchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for searching tasks similar to an unsaved draft.",
"required": ["results"],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskSimilarityResult"
},
"description": "Existing tasks similar to the draft."
}
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/slug/{slug}": {
"get": {
"tags": ["document"],
"summary": "Handler for `GET /documents/slug/{slug}`.",
"description": "Returns document metadata, user access level, and view location.",
"operationId": "get_document_by_team_slug",
"parameters": [
{
"name": "slug",
"in": "path",
"description": "Team-task reference, such as ENG-42",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TypedSuccessResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/starter_docs": {
"get": {
"tags": ["document"],
"summary": "Resolves the current user's starter documents.",
"operationId": "handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StarterDocumentsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/system_skills": {
"get": {
"tags": ["document"],
"summary": "Lists the built-in system skills. System skills are static, code-defined\nAI instructions (see the `system_skills` crate); they surface in the\nskills menu and AI skill tools like user skills, but have no document\nbehind them, so clients must not offer to open them.",
"operationId": "get_system_skills_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response listing the built-in system skills.",
"required": ["skills"],
"properties": {
"skills": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SystemSkillSummary"
},
"description": "Every system skill, in display order."
}
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/upload": {
"post": {
"tags": ["document"],
"summary": "Upload a file's bytes as a new document, up to 25 MiB.",
"description": "The body is the raw file content. Preview generation and indexing may\nfinish after the response.",
"operationId": "upload_file",
"parameters": [
{
"name": "fileName",
"in": "query",
"description": "Filename including its extension, such as `report.pdf`; the extension\nsets the file type. No directory components.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "projectId",
"in": "query",
"description": "Destination project. Requires edit access; omit for top-level files.",
"required": false,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "The file's bytes, at most 25 MiB.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadFileResponse"
}
}
}
},
"400": {
"description": "Invalid filename or content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "No edit access to the destination project",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The caller cannot create documents"
},
"413": {
"description": "The file exceeds 25 MiB"
},
"422": {
"description": "Document name exceeds the maximum length",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}": {
"get": {
"tags": ["document"],
"summary": "Handler for `GET /documents/{document_id}`.",
"description": "Returns document metadata, user access level, and view location.",
"operationId": "get_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TypedSuccessResponse_GetDocumentResponseData"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["document"],
"summary": "Creates a new version of a document",
"operationId": "save_document_handler",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SaveDocumentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SaveDocumentResponse"
}
}
}
},
"304": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["document"],
"summary": "Handler for `DELETE /documents/{document_id}`.",
"description": "Soft-deletes a document (only owners can delete).",
"operationId": "delete_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericSuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["document"],
"summary": "Handler for `PATCH /documents/{document_id}`.",
"description": "Edits document metadata such as name or project, and modifies\nthe document's share permissions. Requires edit access to the document,\nand edit access to the target project if moving the document.",
"operationId": "edit_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditDocumentServiceArgs"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditDocumentResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/ai-edit": {
"post": {
"tags": ["document"],
"summary": "Edit a markdown document or task by instructions with the caller's edit\naccess. Runs EditDocument's pipeline as a live collaborator, with its AI\nadmission and billing.",
"description": "A client that disconnects aborts the edit: axum drops this handler's\nfuture, which drops the in-flight request to the editing worker, and the\nworker aborts on its request signal. Steps already acknowledged stay.",
"operationId": "edit_document_with_ai",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAiEditRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAiEdited"
}
}
}
},
"400": {
"description": "Not a markdown document, or empty instructions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"402": {
"description": "AI allowance exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AiAdmissionErrorBody"
}
}
}
},
"403": {
"description": "Document edit access denied"
},
"404": {
"description": "Document not found"
},
"422": {
"description": "The editor could not do the edit; nothing changed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAiEditRefused"
}
}
}
},
"500": {
"description": "The edit could not start",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"502": {
"description": "The edit failed and may have partly applied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentAiEditFailed"
}
}
}
},
"503": {
"description": "AI usage validation unavailable; retry later",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AiAdmissionErrorBody"
}
}
}
}
}
}
},
"/documents/{document_id}/branch_name": {
"get": {
"tags": ["document"],
"summary": "Handler for `GET /documents/{document_id}/branch_name`.",
"description": "Returns the short UUID and git branch name for a task document.\nReturns 400 if the document is not a task.",
"operationId": "get_document_branch_name",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BranchNameResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/copy": {
"post": {
"tags": ["document"],
"summary": "Handler for `POST /documents/{document_id}/copy`.",
"description": "Copies an existing document, creating a new document with the same content.\nDoes not require re-uploading the document file.",
"operationId": "copy_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "version_id",
"in": "query",
"description": "The version id of the document to copy. Defaults to copying the latest version of the document.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CopyDocumentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CopyDocumentResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/design": {
"get": {
"tags": ["document"],
"summary": "Read a Figma (.fig) design as text with the caller's view access: its\npages, each page's top-level frames and sections with their text, the\ncomponents their instances use, and the file's components, styles and\nvariables.",
"operationId": "read_design",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "1-based page numbers to read; omit for the whole design.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesignFileDescription"
}
}
}
},
"400": {
"description": "Not a readable Figma design, or too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Document access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/export": {
"get": {
"tags": ["document"],
"summary": "Generates a presigned url to download the raw content of the document\nFor files with modification layers, they will not be applied in the downloaded file.",
"operationId": "export_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportDocumentResponse"
}
}
}
},
"304": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"409": {
"description": "DOCX upload is still processing; retry the export.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/github_prs": {
"get": {
"tags": ["document"],
"summary": "Handler for `GET /documents/{document_id}/github_prs`.",
"description": "Returns GitHub pull requests associated with a task document.\nReturns 400 if the document is not a task.",
"operationId": "get_document_github_pull_requests",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GithubPullRequestsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/illustrator": {
"get": {
"tags": ["document"],
"summary": "Read an Illustrator (.ai) document as text with the caller's view access:\nits artboards, its layer tree from top to bottom, and the text of its\ntext objects.",
"operationId": "read_illustrator_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesignFileDescription"
}
}
}
},
"400": {
"description": "Not a readable Illustrator document, or too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Document access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/location": {
"get": {
"tags": ["document"],
"summary": "Gets the presigned url(s) for the document. aka location",
"operationId": "get_location_handler",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "document_version_id",
"in": "query",
"description": "A specific document version id to get the location for.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "get_converted_docx_url",
"in": "query",
"description": "If true, this will return the converted docx url.",
"required": true,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocationResponseData"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"410": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/location_v3": {
"get": {
"tags": ["document"],
"summary": "Handler for `GET /documents/{document_id}/location_v3`.",
"description": "Returns a presigned URL or sync service content for accessing the document.",
"operationId": "get_document_location_v3",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "document_version_id",
"in": "query",
"description": "A specific document version id to get the location for.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "get_converted_docx_url",
"in": "query",
"description": "If true, this will return the converted docx url.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocationResponseV3"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/permanent": {
"delete": {
"tags": ["document"],
"summary": "Permanently deletes a document.",
"operationId": "permanently_delete_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/photoshop": {
"get": {
"tags": ["document"],
"summary": "Read a Photoshop (.psd or .psb) document as text with the caller's view\naccess: its canvas, its layer tree from top to bottom with each layer's\nsettings, and the text of its text layers.",
"operationId": "read_photoshop_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DesignFileDescription"
}
}
}
},
"400": {
"description": "Not a readable Photoshop document, or too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Document access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/presentation": {
"get": {
"tags": ["document"],
"summary": "Read a PowerPoint deck as text with the caller's view access: every\nslide's id and shapes with their ids, positions and text. Edits address\nslides and shapes by these ids, which are not slide numbers.",
"operationId": "read_presentation",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slide",
"in": "query",
"description": "1-based slide numbers to read; omit for the whole deck.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresentationDescription"
}
}
}
},
"400": {
"description": "Not a readable PowerPoint presentation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Document access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/presentation/copy": {
"post": {
"tags": ["document"],
"summary": "Create an edited copy of a PowerPoint deck as a new presentation, leaving\nthe original unchanged. Needs view access to the deck and edit access to\nthe destination project; the outcome's `documentId` is the copy.",
"operationId": "copy_presentation",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresentationCopyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresentationEditOutcome"
}
}
}
},
"400": {
"description": "Not a PowerPoint presentation, an empty name, more than 100 operations, or an operation the deck rejected; nothing was created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "No edit access to the destination project",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Document access denied, or the caller cannot create documents"
},
"404": {
"description": "Document not found"
},
"422": {
"description": "Document name exceeds the maximum length"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/presentation/edits": {
"post": {
"tags": ["document"],
"summary": "Apply a batch of edit operations to a PowerPoint deck atomically with the\ncaller's edit access, saved as a new version. If any operation fails,\nnothing is saved.",
"operationId": "edit_presentation",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresentationEditRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PresentationEditOutcome"
}
}
}
},
"400": {
"description": "Not a PowerPoint presentation, a batch outside 1 to 100 operations, or an operation the deck rejected; nothing was saved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Document edit access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/processing": {
"get": {
"tags": ["document"],
"summary": "Fetches the document pdf processing result for a given document id",
"operationId": "get_document_processing_result",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDocumentProcessingResultResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/processing/{job_id}": {
"get": {
"tags": ["document"],
"summary": "Fetches the document processing result for a given document id and job id",
"operationId": "job_processing_result_handler",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "job_id",
"in": "path",
"description": "Job ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDocumentProcessingResultResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/revert_delete": {
"put": {
"tags": ["document"],
"summary": "Deletes a specific document",
"operationId": "revert_delete_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/short_id": {
"get": {
"tags": ["document"],
"summary": "Handler for `GET /documents/{document_id}/short_id`.",
"description": "Returns the short UUID for a document.",
"operationId": "get_document_short_id",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/simple_save": {
"put": {
"tags": ["document"],
"summary": "For any file that isn't PDF or DOCX, use this endpoint for saving.\nThis endpoint will allow you to save the document by providing the file content as part of a multipart request. Use key 'file' along with the file bytes.\nsimple_save is different than the save_document endpoint because it does not return a presigned URL, Instead, it simply saves the file to S3 directly (and returns the document metadata).",
"operationId": "simple_save",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SaveDocumentResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/skill_description": {
"get": {
"tags": ["document"],
"summary": "Gets when to use a skill. `description` is absent for a skill created\nbefore descriptions existed.",
"operationId": "get_skill_description",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Skill document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillDescriptionBody"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["document"],
"summary": "Sets when to use a skill: one line starting \"Use when\", at most 300\ncharacters. Agents choose skills for a request by it.",
"operationId": "set_skill_description",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Skill document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetSkillDescriptionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillDescriptionBody"
}
}
}
},
"400": {
"description": "The document is not a skill, or the description is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/team_share": {
"get": {
"tags": ["document"],
"summary": "Gets the team-share state of a document. The team is resolved from the\ndocument owner's team membership; `teamId` is omitted when the owner does\nnot belong to a team.",
"operationId": "get_document_team_share",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentTeamShareResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["document"],
"summary": "Sets explicit team sharing. Requires a verified acting identity matching\nthe persisted document owner, not merely effective Edit or Owner access.\nInitial enable defaults to Edit; repeated enable preserves the chosen level.\nClear removes only the managed direct grant, not inherited team access.",
"operationId": "set_document_team_share",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetDocumentTeamShareRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentTeamShareResponse"
}
}
}
},
"400": {
"description": "Owner has no team",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Acting identity is absent or is not the actual owner",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Sharing facts changed or an untracked grant conflicts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/text-content": {
"get": {
"tags": ["document"],
"summary": "Read current Markdown or extracted file text with the document's view receipt.",
"operationId": "get_document_text_content",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentTextContent"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Document access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "Document text unavailable"
}
}
}
},
"/documents/{document_id}/views": {
"get": {
"tags": ["document"],
"summary": "Gets the list of users who have viewed a given document",
"operationId": "get_document_views_handler",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserViewsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/word": {
"get": {
"tags": ["document"],
"summary": "Read an uploaded Word document as it stands now, including edits made in\nMacro, with the caller's view access: every paragraph, table cell and\ncontent control with its stable id, style and text, tracked changes, and\nWord comments. Long documents are paged.",
"operationId": "read_word_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "start",
"in": "query",
"description": "First block to show, 1-based; omit to start at the beginning.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "count",
"in": "query",
"description": "Most blocks to show; omit for as many as fit.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WordDocumentResponse"
}
}
}
},
"400": {
"description": "Not an uploaded Word document, or still being processed after upload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required, or a bot with no acting user"
},
"403": {
"description": "Document access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/word/edits": {
"post": {
"tags": ["document"],
"summary": "Apply a batch of edits to an uploaded Word document's live copy\natomically with the caller's edit access. Nothing changes if any\noperation fails. Returns the changed blocks as they now read.",
"operationId": "edit_word_document",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document identity",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WordDocumentEditRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WordDocumentResponse"
}
}
}
},
"400": {
"description": "Not an uploaded Word document, a batch outside 1 to 50 operations, an invalid author, or operations the editor refused; nothing changed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required, or a bot with no acting user"
},
"403": {
"description": "Document edit access denied"
},
"404": {
"description": "Document not found"
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/documents/{document_id}/{document_version_id}": {
"get": {
"tags": ["document"],
"summary": "Gets a particular document by its id",
"operationId": "get_document_version",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "document_version_id",
"in": "path",
"description": "Document Version ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDocumentResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/entities/{entity_type}/{entity_id}/access-requests": {
"get": {
"tags": ["access-requests"],
"summary": "State access request state through the domain service.",
"operationId": "access_requests_state",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "offset",
"in": "query",
"description": "Offset into pending requests; page size is bounded by the service.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessRequestState"
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
}
},
"/entities/{entity_type}/{entity_id}/access-requests/mine": {
"put": {
"tags": ["access-requests"],
"summary": "Submit access request state through the domain service.",
"operationId": "access_requests_submit",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestAccess"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessRequest"
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
},
"delete": {
"tags": ["access-requests"],
"summary": "Cancel access request state through the domain service.",
"operationId": "access_requests_cancel",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "revision",
"in": "query",
"description": "Last observed request revision.",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"default": null
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
}
},
"/entities/{entity_type}/{entity_id}/access-requests/{request_id}/resolve": {
"post": {
"tags": ["access-requests"],
"summary": "Resolve access request state through the domain service.",
"operationId": "access_requests_resolve",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "request_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessRequest"
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
}
},
"/entities/{entity_type}/{entity_id}/direct-access": {
"get": {
"tags": ["access-requests"],
"summary": "Direct access request state through the domain service.",
"operationId": "access_requests_direct",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DirectAccess"
}
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
}
},
"/entities/{entity_type}/{entity_id}/direct-access/{user_id}": {
"put": {
"tags": ["access-requests"],
"summary": "Set direct access request state through the domain service.",
"operationId": "access_requests_set_direct",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "user_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetDirectAccess"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"default": null
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
},
"delete": {
"tags": ["access-requests"],
"summary": "Remove direct access request state through the domain service.",
"operationId": "access_requests_remove_direct",
"parameters": [
{
"name": "entity_type",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ShareEntityType"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "user_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"default": null
}
}
}
},
"400": {
"description": ""
},
"403": {
"description": ""
},
"404": {
"description": ""
},
"409": {
"description": ""
},
"429": {
"description": ""
},
"500": {
"description": ""
}
}
}
},
"/entity/{entity_type}/{entity_id}/permissions": {
"get": {
"tags": ["entity::get_entity_permission"],
"summary": "Get the current user's permission for a given entity.",
"operationId": "get_entity_permission",
"parameters": [
{
"name": "entity_type",
"in": "path",
"description": "Entity type (document, chat, project, thread, email_thread, channel)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "entity_id",
"in": "path",
"description": "Entity ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityPermissionResponse"
}
}
}
},
"400": {
"description": "Bad request"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Entity not found"
}
}
}
},
"/external-chats": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "List external chats the caller can view, including without a provider account.",
"operationId": "external_chats",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalChatSummary"
}
}
}
}
}
}
},
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Add one of the caller's provider chats as their own external chat.",
"operationId": "external_chat_add",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatAdd"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatAdded"
}
}
}
}
}
}
},
"/external-chats/{chat_id}": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "An external chat the caller can read.",
"operationId": "external_chat",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatDetail"
}
}
}
}
}
},
"delete": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Stop syncing the chat, locally. Owner only, in their own session.",
"operationId": "external_chat_remove",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
}
}
}
},
"/external-chats/{chat_id}/attachments": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Stage one attachment for a later media send in this chat.",
"operationId": "external_chat_upload",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/ExternalChatUploadRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatUploadedAttachment"
}
}
}
}
}
}
},
"/external-chats/{chat_id}/delivery": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "The caller's send progress for intents or messages.",
"operationId": "external_chat_delivery",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalChatSendProgress"
}
}
}
}
}
}
}
},
"/external-chats/{chat_id}/messages": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Newest-first timeline through ordinary view access.",
"operationId": "external_chat_messages",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "before",
"in": "query",
"description": "Last message id in the previous page.",
"required": false,
"schema": {
"type": ["string", "null"],
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"description": "Page size, up to [`PAGE_LIMIT`]; [`DEFAULT_PAGE`] when absent.",
"required": false,
"schema": {
"type": ["integer", "null"],
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatMessages"
}
}
}
}
}
}
},
"/external-chats/{chat_id}/messages/attachments": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Attachment states of messages, by message id (at most 100).",
"operationId": "external_chat_message_attachments",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalChatMessageAttachments"
}
}
}
}
}
}
}
},
"/external-chats/{chat_id}/messages/{message_id}": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "One message of the timeline, as the timeline shows it.",
"operationId": "external_chat_message",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "message_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatMessage"
}
}
}
}
}
}
},
"/external-chats/{chat_id}/permissions": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Generic Share dialog policy.",
"operationId": "external_chat_permissions",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
}
}
},
"patch": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "The owner, in their own session, updates link, team and channel sharing.",
"operationId": "external_chat_update_permissions",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSharePermissionRequestV2"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/external-chats/{chat_id}/read": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Advance this viewer's read position.",
"operationId": "external_chat_read",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MarkRead"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/external-chats/{chat_id}/sends": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Caller-owned pending, failed and uncertain sends.",
"operationId": "external_chat_sends",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalChatSendProgress"
}
}
}
}
}
}
},
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Send to the chat from the caller's own provider account (one request per second per user).",
"operationId": "external_chat_send",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatSendReply"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalChatSendProgress"
}
}
}
},
"429": {
"description": "One send request per second per user; Retry-After: 1"
}
}
}
},
"/favorites": {
"get": {
"tags": ["favorites"],
"summary": "List the caller's favorites.",
"operationId": "list_favorites",
"parameters": [
{
"name": "entityType",
"in": "query",
"description": "Restrict to favorites whose entity is one of these types.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"description": "The type of an entity in Macro",
"enum": [
"user",
"chat",
"channel",
"channel_message",
"document",
"project",
"email_thread",
"calendar_event",
"team",
"call",
"foreign_entity",
"static_file",
"crm_company",
"crm_contact",
"crm_pipeline",
"reminder",
"skill",
"agent_session",
"scheduled_action",
"initiative",
"database",
"database_row",
"form",
"external_chat"
]
}
},
"style": "form",
"explode": true
},
{
"name": "entityId",
"in": "query",
"description": "Restrict to favorites whose entity is one of these ids.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FavoritesList"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["favorites"],
"summary": "Favorite an entity in the caller's collection.",
"operationId": "add_favorite",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddFavoriteRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Favorite"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/favorites/reorder": {
"patch": {
"tags": ["favorites"],
"summary": "Persist a manual order for the caller's favorites.",
"operationId": "reorder_favorites",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReorderFavoritesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"default": null
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/favorites/{entity_type}/{entity_id}": {
"delete": {
"tags": ["favorites"],
"summary": "Remove a favorite by entity.",
"operationId": "remove_favorite_by_entity",
"parameters": [
{
"name": "entity_type",
"in": "path",
"description": "The type of the favorited entity.",
"required": true,
"schema": {
"type": "string",
"description": "The type of an entity in Macro",
"enum": [
"user",
"chat",
"channel",
"channel_message",
"document",
"project",
"email_thread",
"calendar_event",
"team",
"call",
"foreign_entity",
"static_file",
"crm_company",
"crm_contact",
"crm_pipeline",
"reminder",
"skill",
"agent_session",
"scheduled_action",
"initiative",
"database",
"database_row",
"form",
"external_chat"
]
}
},
{
"name": "entity_id",
"in": "path",
"description": "The id of the favorited entity.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"default": null
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/foreign_entity/by_source/{source}/{foreign_entity_id}": {
"get": {
"tags": ["foreign_entity"],
"summary": "Get a visible foreign entity by the identifier its source system assigned.",
"description": "`foreign_entity_id` is a wildcard path segment: sources store slashes inside\nthe identifier, for example `owner/repo/pull/12`.\n\nAuthorization matches the by-id route. Internal service callers see every\nrecord; an authenticated user sees a record only when they have view access\nto it, and records they cannot view are reported as `404` so the route never\nreveals that a mapping exists. Bot tokens are not accepted here — they use\nthe by-id route, which mints a bot-scoped receipt.",
"operationId": "get_foreign_entity_by_source",
"parameters": [
{
"name": "source",
"in": "path",
"description": "Foreign entity source, e.g. github_pull_request",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "foreign_entity_id",
"in": "path",
"description": "Identifier assigned by the source system; may contain slashes",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForeignEntity"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/foreign_entity/{id}": {
"get": {
"tags": ["foreign_entity"],
"summary": "Get a visible foreign entity by its internal ID.",
"operationId": "get_foreign_entity",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Foreign entity ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForeignEntity"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/forms": {
"get": {
"tags": ["forms"],
"summary": "The live forms over a database the caller can see, for the grid's chip\nand the delete-table confirmation.",
"operationId": "list_forms",
"parameters": [
{
"name": "databaseId",
"in": "query",
"description": "The database.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Form"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["forms"],
"summary": "Create a form owned by the caller: over a new database named like it, or\nover an existing table of a database the caller owns. Database Edit is\nnot enough to attach a form: the form's editors gain Edit on the\ndatabase through it.",
"operationId": "create_form",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateForm"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormDetail"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/accessible": {
"get": {
"tags": ["forms"],
"summary": "Every live form the caller holds a grant on, newest first, with their\nlevel: what Drive and Quick Access list. Public forms reached only by\ntheir link are not listed.",
"operationId": "list_accessible_forms",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListedForm"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}": {
"get": {
"tags": ["forms"],
"summary": "A form with its layout, each question joined with its column's title,\ntype and options. Never rows. Readable by anyone when the form is public.",
"operationId": "get_form",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormDetail"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["forms"],
"summary": "Change a form's facts. The description and confirmation message take\nedit; who responds, open or closed, the closing time and tallies take\nits owner.",
"operationId": "update_form",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateForm"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Form"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/collaboration": {
"post": {
"tags": ["forms"],
"summary": "Open the editor-only collaborative layout, or publish its latest valid\nrevision. Content stays in the existing collaboration surface.",
"operationId": "collaborate_form",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormCollaboration"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/layout": {
"put": {
"tags": ["forms"],
"summary": "Save a validated replacement in the shared layout and report publication.\nA 200 response with `publicationError` means the draft is saved, while\nrespondents still see `detail`. Retrying collaboration retries publication.",
"operationId": "put_form_layout",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormLayout"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormCollaboration"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/permissions": {
"get": {
"tags": ["forms"],
"summary": "A form's recipients, for its owner. Link and team sharing are always\n`null`: a form's public audience is its own setting.",
"operationId": "get_form_permissions",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["forms"],
"summary": "Change a form's channel recipients, for its owner. Turning on link or\nteam sharing is refused.",
"operationId": "update_form_permissions",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSharePermissionRequestV2"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/responses": {
"post": {
"tags": ["forms"],
"summary": "Respond to a form. A gate that stops the response answers `stopped` and\nwrites nothing to the table. A public form takes anonymous responses.",
"operationId": "submit_form_response",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Submission"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmissionOutcome"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/responses/mine": {
"get": {
"tags": ["forms"],
"summary": "The signed-in caller's own response, with the row's current cells.",
"operationId": "get_my_form_response",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["forms"],
"summary": "Replace the signed-in caller's answers while the form is open. A gate\nthat stops the edit leaves the saved response as it was.",
"operationId": "edit_my_form_response",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Submission"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmissionOutcome"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/responses/summary": {
"get": {
"tags": ["forms"],
"summary": "Response counts for the form's editors.",
"operationId": "get_form_response_summary",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseSummary"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/forms/{id}/tally": {
"get": {
"tags": ["forms"],
"summary": "Option counts of the form's choice questions: for respondents when the\nowner shows them, for editors always.",
"operationId": "get_form_tally",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormTally"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormErrorResponse"
}
}
}
}
}
}
},
"/github/install-sync": {
"get": {
"tags": ["github::inbound::github_sync_router"],
"summary": "Redirects an authenticated user to the github sync app installation page.",
"operationId": "install_sync",
"responses": {
"307": {
"description": "Temporary redirect to the GitHub sync app installation page"
},
"401": {
"description": "Authentication failed"
}
}
}
},
"/github_pull_requests/facets": {
"get": {
"tags": ["github_pull_requests"],
"summary": "List the repositories and authors among the GitHub pull requests visible to the caller.",
"operationId": "get_github_pull_request_facets",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GithubPullRequestFacets"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/github_pull_requests/{id}": {
"get": {
"tags": ["github_pull_requests"],
"summary": "Get the pull request behind a foreign entity record the caller can view.",
"operationId": "get_github_pull_request",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The caller's foreign entity record for the pull request",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoredGithubPullRequest"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/github_pull_requests/{id}/changes": {
"get": {
"tags": ["github_pull_requests"],
"summary": "Get the changes of the pull request behind a foreign entity record the caller can view.",
"operationId": "get_github_pull_request_changes",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The caller's foreign entity record for the pull request",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GithubPullRequestChangesResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/github_pull_requests/{id}/changes/patch": {
"get": {
"tags": ["github_pull_requests"],
"summary": "Get the patch of changes of the pull request behind a foreign entity record the caller can\nview.",
"operationId": "get_github_pull_request_changes_patch",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The caller's foreign entity record for the pull request",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "changeset",
"in": "query",
"description": "The changeset whose patch to read",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GithubPullRequestChangesPatchResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harness-pairings": {
"post": {
"tags": ["harnesses"],
"summary": "Handler for `POST /harness-pairings`.",
"description": "Unauthenticated by design: the daemon has no credential yet - obtaining one\nis the point. The pairing releases nothing until a signed-in user approves\nit, and creation is throttled in the domain service.",
"operationId": "create_harness_pairing",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePairingRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedPairing"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harness-pairings/{code}": {
"get": {
"tags": ["harnesses"],
"summary": "Handler for `GET /harness-pairings/{code}`.",
"operationId": "get_harness_pairing",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Pairing code",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PairingDetails"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harness-pairings/{code}/approve": {
"post": {
"tags": ["harnesses"],
"summary": "Handler for `POST /harness-pairings/{code}/approve`.",
"operationId": "approve_harness_pairing",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Pairing code",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApprovePairingRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Harness"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harness-pairings/{pairing_id}/claim": {
"post": {
"tags": ["harnesses"],
"summary": "Handler for `POST /harness-pairings/{pairing_id}/claim`.",
"description": "Unauthenticated like pairing creation; the device secret minted alongside\nthe pairing is the credential, and the pairing id (not the short user\ncode) addresses it.",
"operationId": "claim_harness_pairing",
"parameters": [
{
"name": "pairing_id",
"in": "path",
"description": "Pairing ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClaimPairingRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClaimedPairing"
}
}
}
},
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingClaimResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harnesses": {
"get": {
"tags": ["harnesses"],
"summary": "Handler for `GET /harnesses`.",
"operationId": "list_harnesses",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Harness"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harnesses/me": {
"get": {
"tags": ["harnesses"],
"summary": "Handler for `GET /harnesses/me`.",
"operationId": "get_self_harness",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Harness"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["harnesses"],
"summary": "Handler for `DELETE /harnesses/me`.",
"description": "A daemon retiring itself: the valid credential is the authorization.",
"operationId": "delete_self_harness",
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harnesses/me/agents": {
"get": {
"tags": ["harnesses"],
"summary": "Handler for `GET /harnesses/me/agents`.",
"operationId": "list_harness_agents",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HarnessAgent"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harnesses/me/sessions": {
"get": {
"tags": ["harnesses"],
"summary": "Handler for `GET /harnesses/me/sessions`.",
"operationId": "list_harness_sessions",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HarnessSession"
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/harnesses/{harness_id}": {
"delete": {
"tags": ["harnesses"],
"summary": "Handler for `DELETE /harnesses/{harness_id}`.",
"operationId": "delete_harness",
"parameters": [
{
"name": "harness_id",
"in": "path",
"description": "Harness ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/HarnessId"
}
}
],
"responses": {
"204": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["harnesses"],
"summary": "Handler for `PATCH /harnesses/{harness_id}`.",
"operationId": "patch_harness",
"parameters": [
{
"name": "harness_id",
"in": "path",
"description": "Harness ID",
"required": true,
"schema": {
"$ref": "#/components/schemas/HarnessId"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchHarnessRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Harness"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/health": {
"get": {
"tags": ["health"],
"summary": "Health check",
"operationId": "health_handler",
"responses": {
"200": {
"description": "health",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/history": {
"get": {
"tags": ["history::get_history"],
"summary": "Gets the users history",
"operationId": "get_history_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetUserHistoryResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/history/{item_type}/{item_id}": {
"post": {
"tags": ["history::upsert_history"],
"summary": "Upserts an item into the user's history and performs other necessary tracking actions",
"operationId": "upsert_history_handler",
"parameters": [
{
"name": "item_type",
"in": "path",
"description": "Type of the item",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "item_id",
"in": "path",
"description": "ID of the item",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["history::delete_history"],
"summary": "Deletes an item from the user's history",
"operationId": "delete_history_handler",
"parameters": [
{
"name": "item_type",
"in": "path",
"description": "Type of the item",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "item_id",
"in": "path",
"description": "ID of the item",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/initiatives": {
"get": {
"tags": ["initiative"],
"summary": "List initiatives the caller can view.",
"operationId": "list_initiatives",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiativeList"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["initiative"],
"summary": "Create an initiative owned by the caller.",
"operationId": "create_initiative",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateInitiativeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiativeDetail"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Name exceeds the maximum length",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/initiatives/{initiative_id}": {
"get": {
"tags": ["initiative"],
"summary": "Fetch one initiative the caller can view.",
"operationId": "get_initiative",
"parameters": [
{
"name": "initiative_id",
"in": "path",
"description": "Initiative identifier.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiativeDetail"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["initiative"],
"summary": "Delete the initiative the caller owns.",
"operationId": "delete_initiative",
"parameters": [
{
"name": "initiative_id",
"in": "path",
"description": "Initiative identifier.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericSuccessResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["initiative"],
"summary": "Update fields the caller can edit.",
"operationId": "update_initiative",
"parameters": [
{
"name": "initiative_id",
"in": "path",
"description": "Initiative identifier.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateInitiativeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiativeDetail"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Name exceeds the maximum length",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/instructions": {
"get": {
"tags": ["instructions::get_instructions"],
"summary": "Gets the instructions document for the current user",
"operationId": "get_instructions_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetInstructionsDocumentResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "User does not have an instructions document",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["instructions::create_instructions"],
"summary": "Creates an instructions document for the current user",
"operationId": "create_instructions_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateInstructionsDocumentResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"409": {
"description": "User already has instructions document",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/items/soup": {
"get": {
"tags": ["soup::inbound::axum_router"],
"summary": "Gets the items the user has access to",
"operationId": "get_items_soup",
"parameters": [
{
"name": "expand",
"in": "query",
"description": "Whether to expand projects. Defaults to true.",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"description": "Limit the number of items returned. Defaults to 20. Max 500.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
{
"name": "sort_method",
"in": "query",
"description": "Sort method. Property ordering supports DATE, NUMBER, BOOLEAN, SELECT and TAG.\nMissing definitions, unsupported types, and mismatched values sort as missing.\nFlat property sorts omit calendar events, email, channels, calls, companies, and agent sessions.\nDefaults to viewed_at.",
"required": false,
"schema": {
"$ref": "#/components/schemas/SoupApiSort"
}
},
{
"name": "sort_property_definition_id",
"in": "query",
"description": "Property definition selected for numeric property sorting.",
"required": false,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "sort_direction",
"in": "query",
"description": "Sort direction. Options are asc, desc. Defaults to desc.\n\nTimestamp sorts require this parameter again on each page. Property\ncursors preserve their direction and always put missing values last.\nAscending frecency, touched-by-me, and notified-at sorts are unsupported.",
"required": false,
"schema": {
"$ref": "#/components/schemas/SoupApiSortDirection"
}
},
{
"name": "cursor",
"in": "query",
"description": "Base64 encoded cursor value.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SoupPage"
}
}
}
},
"403": {
"description": "CRM-scoped queries require team membership, or requesting hidden CRM companies requires admin/owner team role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["soup::inbound::axum_router"],
"summary": "Gets the items the user has access to",
"operationId": "post_items_soup",
"parameters": [
{
"name": "cursor",
"in": "query",
"description": "Base64 encoded cursor value.",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostSoupRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SoupPage"
}
}
}
},
"403": {
"description": "CRM-scoped queries require team membership, or requesting hidden CRM companies requires admin/owner team role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/items/soup/ast": {
"post": {
"tags": ["soup::inbound::axum_router"],
"summary": "Gets the items the user has access to using AST filters",
"operationId": "post_items_soup_ast",
"parameters": [
{
"name": "cursor",
"in": "query",
"description": "Base64 encoded cursor value.",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostSoupAstRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SoupPage"
}
}
}
},
"403": {
"description": "CRM-scoped queries require team membership, or requesting hidden CRM companies requires admin/owner team role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "The CRM record named by `crma` or a document `crm` literal is not visible to the caller",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/items/soup/ast/grouped": {
"post": {
"tags": ["soup::inbound::axum_router"],
"summary": "Gets the items grouped by the specified field using AST filters.",
"operationId": "post_items_soup_ast_grouped",
"parameters": [
{
"name": "cursor",
"in": "query",
"description": "Base64 encoded cursor value.",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostGroupedSoupAstRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupedSoupPage"
}
}
}
},
"403": {
"description": "CRM-scoped queries require team membership, or requesting hidden CRM companies requires admin/owner team role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "The CRM record named by `crma` or a document `crm` literal is not visible to the caller",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}": {
"get": {
"tags": ["messages::inbound::axum_router"],
"summary": "Read a bounded timeline with lazy thread previews.",
"operationId": "message_timeline",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "selection",
"in": "query",
"description": "Serialized MessageTimelineQuery; absent selects the latest roots.",
"required": false,
"schema": {
"type": ["string", "null"]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessagePage"
}
}
}
}
}
},
"post": {
"tags": ["messages::inbound::axum_router"],
"summary": "Create a root message or reply.",
"operationId": "entity_message_create",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostMessage"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}/items/{id}": {
"get": {
"tags": ["messages::inbound::axum_router"],
"summary": "Resolve a message within its parent.",
"operationId": "entity_message_get_message",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
},
"delete": {
"tags": ["messages::inbound::axum_router"],
"summary": "Tombstone one message; deleting a discussion's root deletes the discussion.",
"operationId": "entity_message_delete_message",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "nonce",
"in": "query",
"description": "Client nonce.",
"required": false,
"schema": {
"type": ["string", "null"]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
},
"patch": {
"tags": ["messages::inbound::axum_router"],
"summary": "Edit an owned message.",
"operationId": "entity_message_edit",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessagePatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}/items/{id}/reactions": {
"post": {
"tags": ["messages::inbound::axum_router"],
"summary": "Change the caller's reaction.",
"operationId": "entity_message_react",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReactionInput"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}/legacy/{legacy_id}": {
"get": {
"tags": ["messages::inbound::axum_router"],
"summary": "Resolve an old link under current parent permissions.",
"operationId": "entity_message_legacy",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "legacy_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "thread",
"in": "query",
"description": "Resolve a thread id instead of a comment id.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}/threads/{id}": {
"get": {
"tags": ["messages::inbound::axum_router"],
"summary": "Open a specific discussion from a link or annotation.",
"operationId": "entity_message_get_thread",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageThread"
}
}
}
}
}
},
"delete": {
"tags": ["messages::inbound::axum_router"],
"summary": "Explicitly remove a discussion.",
"operationId": "entity_message_delete_thread",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "nonce",
"in": "query",
"description": "Client nonce.",
"required": false,
"schema": {
"type": ["string", "null"]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadState"
}
}
}
}
}
},
"patch": {
"tags": ["messages::inbound::axum_router"],
"summary": "Update a discussion's lifecycle and placement.",
"operationId": "entity_message_patch_thread",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadState"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}/timeline": {
"get": {
"tags": ["messages::inbound::axum_router"],
"summary": "Read a bounded window of messages and the parent's activity, ordered by the server.",
"operationId": "message_timeline_entries",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "selection",
"in": "query",
"description": "Serialized MessageTimelineQuery; absent selects the latest roots.",
"required": false,
"schema": {
"type": ["string", "null"]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageTimelinePage"
}
}
}
}
}
}
},
"/messages/{parent_type}/{parent_id}/typing": {
"post": {
"tags": ["messages::inbound::axum_router"],
"summary": "Broadcast typing within an authorized discussion.",
"operationId": "entity_message_typing",
"parameters": [
{
"name": "parent_type",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "parent_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TypingInput"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
},
"/pins": {
"get": {
"tags": ["pins::get_pins"],
"summary": "Gets the users pinned items",
"operationId": "get_pins_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPinsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["pins::reorder_pins"],
"summary": "Saves the updated order of the pins for the user",
"operationId": "reorder_pins_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReorderPinRequest"
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/pins/{pinned_item_id}": {
"post": {
"tags": ["pins::add_pin"],
"summary": "Pins the item for the user",
"operationId": "add_pin_handler",
"parameters": [
{
"name": "pinned_item_id",
"in": "path",
"description": "ID of the pinned item",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddPinRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["pins::remove_pin"],
"summary": "Deletes the pin for the user",
"operationId": "remove_pin_handler",
"parameters": [
{
"name": "pinned_item_id",
"in": "path",
"description": "ID of the pinned item",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects": {
"get": {
"tags": ["project"],
"summary": "List projects visible to the authenticated user.",
"operationId": "get_projects_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProjectsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["project"],
"summary": "Create a project, optionally beneath an existing project.",
"operationId": "create_project_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProjectRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProjectResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/pending": {
"get": {
"tags": ["project"],
"summary": "List pending root projects owned by the authenticated user.",
"operationId": "get_pending_projects_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"oneOf": [
{
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Project"
},
{
"type": "object",
"required": ["documentStatuses"],
"properties": {
"documentStatuses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectDocumentStatus"
}
}
}
}
]
}
}
],
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/preview": {
"post": {
"tags": ["project"],
"summary": "Get previews for a batch of project IDs.",
"operationId": "get_batch_project_preview",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchProjectPreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBatchProjectPreviewResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/upload": {
"post": {
"tags": ["projects_hex::inbound::axum_router::upload_folder"],
"summary": "Upload a folder tree and create its upload destinations.",
"operationId": "upload_folder_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadFolderRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"required": ["fileSystem", "destinationMap"],
"properties": {
"destinationMap": {
"$ref": "#/components/schemas/HashMap",
"description": "maps document id to presigned url (external) or s3 info (internal)"
},
"fileSystem": {
"$ref": "#/components/schemas/FileSystemNodeWithIds",
"description": "file system with project ids and document ids"
}
}
}
],
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/upload_extract": {
"post": {
"tags": ["project"],
"summary": "Create a request for extracting an uploaded folder archive.",
"operationId": "upload_extract_folder_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadExtractFolderRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"required": ["requestId", "presignedUrl"],
"properties": {
"presignedUrl": {
"type": "string"
},
"requestId": {
"type": "string"
}
}
}
],
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/{id}": {
"get": {
"tags": ["projects_hex::inbound::axum_router::get_project"],
"summary": "Get project metadata.",
"operationId": "get_project_handler",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProjectResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["project"],
"summary": "Soft-delete a project and all of its children.",
"operationId": "delete_project_handler",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"description": "Identifiers affected by a recursive project soft deletion.",
"required": [
"project_ids",
"document_ids",
"chat_ids"
],
"properties": {
"chat_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Deleted chats."
},
"document_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Deleted documents."
},
"project_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Deleted projects, including the requested root."
}
}
}
],
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/{id}/access_level": {
"get": {
"tags": ["project"],
"summary": "Get the caller's project access level.",
"operationId": "get_project_user_access_level",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessLevel"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/{id}/content": {
"get": {
"tags": ["project"],
"summary": "Get a project's immediate children.",
"operationId": "get_project_content_handler",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProjectContentResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/{id}/permanent": {
"delete": {
"tags": ["project"],
"summary": "Permanently delete a soft-deleted project and all of its children.",
"operationId": "permanently_delete_project",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/{id}/permissions": {
"get": {
"tags": ["project"],
"summary": "Get a project's share permissions.",
"operationId": "get_project_permissions_v2",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharePermissionV2"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/projects/{id}/revert_delete": {
"put": {
"tags": ["project"],
"summary": "Restore a soft-deleted project and its children.",
"operationId": "revert_delete_project",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/recents/deleted": {
"get": {
"tags": ["recents"],
"summary": "Gets the users recently deleted items.",
"operationId": "recently_deleted",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TypedSuccessResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/reminders/email/collection": {
"get": {
"tags": ["reminders"],
"summary": "List original email threads with caller-private reminder work.",
"operationId": "list_email_reminders",
"parameters": [
{
"name": "inboxIds",
"in": "query",
"description": "Selected inboxes; omission selects all accessible inboxes.",
"required": false,
"schema": {
"type": ["array", "null"],
"items": {
"type": "string",
"format": "uuid"
}
}
},
{
"name": "noInboxes",
"in": "query",
"description": "Explicitly empty inbox selection.",
"required": false,
"schema": {
"type": ["boolean", "null"]
}
},
{
"name": "done",
"in": "query",
"description": "Email archive filter, independent of reminder completion.",
"required": false,
"schema": {
"type": ["boolean", "null"]
}
},
{
"name": "read",
"in": "query",
"description": "Email read status.",
"required": false,
"schema": {
"type": ["boolean", "null"]
}
},
{
"name": "calendar",
"in": "query",
"description": "Restrict to calendar mail.",
"required": false,
"schema": {
"type": ["boolean", "null"]
}
},
{
"name": "tags",
"in": "query",
"description": "Repeated property-definition:select-option UUID pairs.",
"required": false,
"schema": {
"type": ["array", "null"],
"items": {
"type": "string"
}
}
},
{
"name": "attachments",
"in": "query",
"description": "Repeated attachment categories: pdf, image, document.",
"required": false,
"schema": {
"type": ["array", "null"],
"items": {
"type": "string"
}
}
},
{
"name": "cursor",
"in": "query",
"description": "Continuation from the previous page.",
"required": false,
"schema": {
"type": ["string", "null"]
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum rows (1–100).",
"required": false,
"schema": {
"type": ["integer", "null"],
"format": "int32",
"maximum": 100,
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailReminderPage"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/reminders/email/{thread_id}": {
"get": {
"tags": ["reminders"],
"summary": "Read an email follow-up and reconcile inbound reply cancellation.",
"operationId": "get_email_followup",
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailFollowupResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": ["reminders"],
"summary": "Schedule, edit or remove one email follow-up as an idempotent operation.",
"operationId": "set_email_followup",
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailFollowupCommand"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailFollowup"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/saved_views": {
"get": {
"tags": ["saved_views"],
"operationId": "get_views_handler",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["saved_views"],
"operationId": "create_view_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateViewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/View"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/saved_views/exclude_default": {
"post": {
"tags": ["saved_views"],
"operationId": "exclude_default_view_handler",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExcludeDefaultViewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/saved_views/{saved_view_id}": {
"delete": {
"tags": ["saved_views"],
"operationId": "delete_view_handler",
"parameters": [
{
"name": "saved_view_id",
"in": "path",
"description": "The id of the saved view to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["saved_views"],
"operationId": "patch_view_handler",
"parameters": [
{
"name": "saved_view_id",
"in": "path",
"description": "The id of the saved view to patch",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ViewPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": ""
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/slack/imports": {
"get": {
"tags": ["slack"],
"summary": "List this administrator's team receipts, effective server limits and source binding.",
"operationId": "list_slack_imports",
"parameters": [
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/JobId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportPage"
}
}
}
}
}
},
"post": {
"tags": ["slack"],
"summary": "Create or replay a job using a scoped idempotency token and full selected metadata.\nMissing creation timestamps and unknown message counts are represented as null.",
"operationId": "create_slack_import",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SlackCreateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportProgress"
}
}
}
},
"401": {
"description": "Authentication or team administrator access required"
},
"403": {
"description": "Team administrator required"
},
"413": {
"description": "Metadata limit exceeded"
},
"503": {
"description": "Slack imports disabled or temporarily unavailable"
}
}
}
},
"/slack/imports/{job_id}": {
"get": {
"tags": ["slack"],
"summary": "Read sanitized progress; foreign jobs are indistinguishable from missing jobs.",
"operationId": "get_slack_import",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/JobId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportProgress"
}
}
}
},
"404": {
"description": "Unknown or inaccessible job"
}
}
}
},
"/slack/imports/{job_id}/cancel": {
"post": {
"tags": ["slack"],
"summary": "Stop unclaimed work. Active leases may settle; cancellation does not roll back history.",
"operationId": "cancel_slack_import",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/JobId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportProgress"
}
}
}
},
"404": {
"description": "Unknown or inaccessible job"
}
}
}
},
"/slack/imports/{job_id}/finalize": {
"post": {
"tags": ["slack"],
"summary": "Close registration idempotently; never-ready conversations are skipped, not queued work.",
"operationId": "finalize_slack_import",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/JobId"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportProgress"
}
}
}
},
"404": {
"description": "Unknown or inaccessible job"
}
}
}
},
"/slack/imports/{job_id}/uploads": {
"post": {
"tags": ["slack"],
"summary": "Issue short-lived, checksum/length-bound, create-only PUT grants. Do not log or persist URLs.\nRetry a PUT returning 412 by completing/verifying the existing object, not overwriting it.",
"operationId": "register_slack_import_uploads",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/JobId"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SlackRegisterRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadGrant"
}
}
}
}
},
"404": {
"description": "Unknown or inaccessible job"
},
"413": {
"description": "Body limit exceeded"
},
"503": {
"description": "Slack imports disabled"
}
}
}
},
"/slack/imports/{job_id}/uploads/complete": {
"post": {
"tags": ["slack"],
"summary": "Verify storage checksums and lengths for registered objects. A seal fixes the ENTIRE\ndescriptor set (contiguous indices, sizes and hashes), not just this completion batch.\nEmpty uploads with a zero-part seal support shape-only or empty-history imports.\nWork becomes ready only after verified users metadata, a seal and every required part.",
"operationId": "complete_slack_import_uploads",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/JobId"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SlackCompleteRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportProgress"
}
}
}
},
"404": {
"description": "Unknown or inaccessible job"
},
"409": {
"description": "Immutable manifest conflict"
},
"413": {
"description": "Body limit exceeded"
},
"422": {
"description": "Object verification failed"
},
"503": {
"description": "Slack imports disabled"
}
}
}
},
"/sync_service/wakeup": {
"post": {
"tags": ["sync_service"],
"operationId": "bulk_wakeup_sync_service_documents",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkWakeupRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Wakeups accepted for fire-and-forget dispatch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkWakeupResponse"
}
}
}
},
"401": {
"description": "Authentication required (JSON error response)"
}
}
}
},
"/threads/{thread_id}": {
"patch": {
"tags": ["threads"],
"summary": "Edits the share permissions of a thread.",
"operationId": "edit_thread_v2",
"parameters": [
{
"name": "thread_id",
"in": "path",
"description": "thread ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchThreadRequestV2"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/user-api-keys": {
"get": {
"tags": ["user-api-keys"],
"summary": "List the caller's API keys.",
"operationId": "list_user_api_keys",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserApiKeysList"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["user-api-keys"],
"summary": "Mint a new API key for the caller.",
"operationId": "create_user_api_key",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserApiKeyRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedUserApiKey"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/user-api-keys/{id}": {
"delete": {
"tags": ["user-api-keys"],
"summary": "Delete one of the caller's API keys.",
"operationId": "delete_user_api_key",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Opaque key identifier.",
"required": true,
"schema": {
"$ref": "#/components/schemas/UserApiKeyId"
}
}
],
"responses": {
"204": {
"description": "API key deleted"
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/user_document_view_location/{document_id}": {
"get": {
"tags": [
"user_document_view_location::get_user_document_view_location"
],
"summary": "Gets a UserPdfDocumentLocation entry",
"operationId": "get_user_document_view_location",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDocumentViewLocationResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"user_document_view_location::upsert_user_document_view_location"
],
"operationId": "upsert_user_document_view_location",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpsertUserDocumentViewLocationRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"user_document_view_location::delete_user_document_view_location"
],
"summary": "Deletes a document location for the user",
"operationId": "delete_user_document_view_location",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/v2/documents/{document_id}/permissions": {
"get": {
"tags": ["document"],
"summary": "Gets the current documents share permissions",
"operationId": "get_document_permissions_v2",
"parameters": [
{
"name": "document_id",
"in": "path",
"description": "Document ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDocumentPermissionsResponseDataV2"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/v2/projects/{id}": {
"patch": {
"tags": ["project"],
"summary": "Edit project metadata and sharing settings.",
"operationId": "edit_project_v2",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchProjectRequestV2"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponse"
}
}
}
}
}
}
},
"/webhook/events/stream": {
"get": {
"tags": ["webhook"],
"summary": "Stream matching broker events to the caller over Server-Sent Events.",
"operationId": "stream_events",
"parameters": [
{
"name": "scope",
"in": "query",
"description": "Personal or team workspace whose webhook lifecycle events are delivered.",
"required": true,
"schema": {
"$ref": "#/components/schemas/WebhookScope"
}
},
{
"name": "filters",
"in": "query",
"description": "URL-encoded JSON array of webhook filters, identical to the persisted\nwebhook `filters` field.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Server-Sent Events stream of matching broker events",
"content": {
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/webhook/webhooks": {
"get": {
"tags": ["webhook"],
"summary": "List the caller's webhooks.",
"operationId": "list_webhooks",
"responses": {
"200": {
"description": "Webhooks",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListWebhooksResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": ["webhook"],
"summary": "Create a webhook.",
"operationId": "create_webhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Webhook created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookResponse"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Namespace already used in the workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/webhook/webhooks/{webhook_id}": {
"get": {
"tags": ["webhook"],
"summary": "Get a webhook.",
"operationId": "get_webhook",
"parameters": [
{
"name": "webhook_id",
"in": "path",
"description": "Webhook id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Webhook",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": ["webhook"],
"summary": "Delete a webhook.",
"operationId": "delete_webhook",
"parameters": [
{
"name": "webhook_id",
"in": "path",
"description": "Webhook id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Webhook deleted"
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": ["webhook"],
"summary": "Patch a webhook.",
"operationId": "patch_webhook",
"parameters": [
{
"name": "webhook_id",
"in": "path",
"description": "Webhook id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchWebhookRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Webhook updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/webhook/webhooks/{webhook_id}/validate": {
"post": {
"tags": ["webhook"],
"summary": "Validate a webhook endpoint.",
"operationId": "validate_webhook",
"parameters": [
{
"name": "webhook_id",
"in": "path",
"description": "Webhook id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Webhook validation result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidateWebhookResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limited",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/whatsapp/account": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "The caller's own account.",
"operationId": "whatsapp_account",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppAccountView"
}
}
}
}
}
}
},
"/whatsapp/chats": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "The caller's WhatsApp chat list (groups and direct chats), newest\nactivity first, with what can be added to Macro.",
"operationId": "whatsapp_chats",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppChats"
}
}
}
}
}
}
},
"/whatsapp/connect": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Start or resume the caller's pairing transaction.",
"operationId": "whatsapp_connect",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppConnect"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppPairing"
}
}
}
}
}
}
},
"/whatsapp/disconnect": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "End the caller's observation consent.",
"operationId": "whatsapp_disconnect",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppDisconnectRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppDisconnect"
}
}
}
}
}
}
},
"/whatsapp/history-import": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Import earlier messages of the caller's chats that wait for their phone\n(`backfill.state` `waiting_for_phone`). WhatsApp must be open on the phone.",
"operationId": "whatsapp_import_history",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppHistoryImport"
}
}
}
}
}
}
},
"/whatsapp/lookups": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Ask whether a phone number has a WhatsApp account, to start a direct chat\nwith it; poll the lookup until it is no longer `pending`. Found numbers\njoin the chat list, so `POST /external-chats` adds them.",
"operationId": "whatsapp_start_lookup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppLookupRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppLookup"
}
}
}
}
}
}
},
"/whatsapp/lookups/{id}": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Poll the caller's phone-number lookup.",
"operationId": "whatsapp_lookup",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppLookup"
}
}
}
}
}
}
},
"/whatsapp/pairing/{id}": {
"get": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Poll the caller's pairing transaction, including its current QR code.",
"operationId": "whatsapp_pairing",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppPairState"
}
}
}
}
}
},
"delete": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Cancel the caller's pairing transaction.",
"operationId": "whatsapp_cancel_pairing",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": ""
}
}
}
},
"/whatsapp/pairing/{id}/passkey": {
"post": {
"tags": ["whatsapp_linked::inbound::router"],
"summary": "Forward the owner's WebAuthn assertion to the pairing replica.",
"operationId": "whatsapp_passkey",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"required": true
},
"responses": {
"204": {
"description": ""
}
}
}
}
},
"components": {
"schemas": {
"AccentColor": {
"type": "string",
"description": "A color as `#rrggbb`, kept in lowercase.",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"AccessLevel": {
"type": "string",
"description": "Ordered from least to most access top -> bottom",
"enum": ["view", "comment", "edit", "owner"]
},
"AccessRequest": {
"type": "object",
"description": "Latest request for one person and one entity.",
"required": [
"id",
"requesterId",
"requestedLevel",
"status",
"revision",
"createdAt",
"updatedAt"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Start of this request attempt."
},
"grantedLevel": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AccessLevel",
"description": "Level selected by the reviewer."
}
]
},
"id": {
"type": "string",
"format": "uuid",
"description": "Stable request identity across revisions."
},
"requestedLevel": {
"$ref": "#/components/schemas/AccessLevel",
"description": "Requested upgrade."
},
"requesterId": {
"type": "string",
"description": "Person requesting access."
},
"resolvedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the request stopped being pending."
},
"retryAfter": {
"type": ["string", "null"],
"format": "date-time",
"description": "Earliest next submission or level change; cancellation preserves this deadline.\nSubmissions wait one minute, denials wait 24 hours, and approval clears it."
},
"revision": {
"type": "integer",
"format": "int32",
"description": "Optimistic concurrency token."
},
"status": {
"$ref": "#/components/schemas/RequestStatus",
"description": "Current outcome."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Most recent change."
}
}
},
"AccessRequestState": {
"type": "object",
"description": "Share state visible to one authenticated viewer.",
"required": [
"canReview",
"supportedLevels",
"requests",
"pendingCount"
],
"properties": {
"accessLevel": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AccessLevel",
"description": "Current effective permission, absent when requesting initial access."
}
]
},
"canReview": {
"type": "boolean",
"description": "Whether this viewer can resolve requests and manage direct grants."
},
"mine": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AccessRequest",
"description": "This viewer's last request, if any."
}
]
},
"nextOffset": {
"type": ["integer", "null"],
"format": "int32",
"description": "Next page offset, absent at the end.",
"minimum": 0
},
"owner": {
"type": ["string", "null"],
"description": "Recorded owner principal, visible to reviewers and callers with access."
},
"pendingCount": {
"type": "integer",
"format": "int64",
"description": "Total outstanding requests, for the Share badge."
},
"requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessRequest"
},
"description": "Reviewer-only pending page, oldest first."
},
"supportedLevels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessLevel"
},
"description": "Permitted access choices for this surface."
}
}
},
"AccessiblePipeline": {
"allOf": [
{
"$ref": "#/components/schemas/Pipeline",
"description": "Pipeline metadata."
},
{
"type": "object",
"required": ["grant"],
"properties": {
"grant": {
"$ref": "#/components/schemas/AccessLevel",
"description": "Highest effective access."
}
}
}
],
"description": "Metadata together with the caller's effective grant."
},
"AccountManagerDecision": {
"type": "string",
"description": "A response to a request.",
"enum": ["approve", "decline"]
},
"AccountManagerGrant": {
"type": "object",
"description": "A request for manager access and what became of it.",
"required": [
"id",
"managedUserId",
"managerUserId",
"requestedBy",
"status",
"createdAt"
],
"properties": {
"claimedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the manager claimed the credential."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the request was made."
},
"expiresAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the pending request or unclaimed approval stops being usable."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Grant id."
},
"lastUsedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the credential was last used, to the minute."
},
"managedUserId": {
"type": "string",
"description": "The account being managed."
},
"managerUserId": {
"type": "string",
"description": "The agent account doing the managing."
},
"requestedBy": {
"$ref": "#/components/schemas/AccountManagerRole",
"description": "The side that asked."
},
"status": {
"$ref": "#/components/schemas/AccountManagerGrantStatus",
"description": "Lifecycle status."
}
}
},
"AccountManagerGrantStatus": {
"type": "string",
"description": "Where a grant is in its lifecycle.",
"enum": [
"pending",
"approved",
"declined",
"active",
"revoked",
"expired"
]
},
"AccountManagerRole": {
"type": "string",
"description": "One side of a grant.",
"enum": ["managed", "manager"]
},
"AccountManagersList": {
"type": "object",
"description": "The managers of the caller's account.",
"required": ["grants"],
"properties": {
"grants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountManagerGrant"
},
"description": "Approved and active grants on the caller's account."
}
}
},
"ActiveCallSummary": {
"type": "object",
"description": "A currently active call, as returned by the batch active-calls listing.",
"required": [
"callId",
"channelId",
"createdBy",
"createdAt",
"participantCount"
],
"properties": {
"callId": {
"type": "string",
"format": "uuid",
"description": "The call identifier."
},
"channelId": {
"type": "string",
"format": "uuid",
"description": "The channel this call belongs to."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the call was created."
},
"createdBy": {
"type": "string",
"description": "User who created the call."
},
"participantCount": {
"type": "integer",
"format": "int64",
"description": "Number of active participants. Always >= 1 — calls with no active\nparticipants (e.g. orphaned by a dropped RTC webhook) are excluded."
}
}
},
"ActiveCallsResponse": {
"type": "object",
"description": "Response listing all active calls in channels the caller is a member of.",
"required": ["calls"],
"properties": {
"calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ActiveCallSummary"
},
"description": "The active calls, newest first."
}
}
},
"ActiveMeeting": {
"allOf": [
{
"$ref": "#/components/schemas/Meeting",
"description": "Existing meeting metadata, with the same fields as other meeting responses."
},
{
"type": "object",
"required": ["createdBy"],
"properties": {
"createdBy": {
"type": "string",
"description": "Creator identity for displaying the caller in the authenticated active list."
}
}
}
],
"description": "Active quick-call metadata available to its authenticated owner or attendees."
},
"ActiveMeetingsResponse": {
"type": "object",
"description": "The authenticated actor's active quick calls, including their creators.",
"required": ["meetings"],
"properties": {
"meetings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ActiveMeeting"
},
"description": "Persistent meeting invitations for currently active sessions."
}
}
},
"ActivityType": {
"type": "string",
"description": "The kind of activity a user performs in a channel.",
"enum": ["view", "interact"]
},
"AddChannelBotRequest": {
"type": "object",
"description": "Request to add a bot to a channel.",
"required": ["bot_id"],
"properties": {
"bot_id": {
"$ref": "#/components/schemas/BotId",
"description": "Bot id."
}
}
},
"AddFavoriteRequest": {
"type": "object",
"description": "Request body for favoriting an entity.",
"required": ["entityType", "entityId"],
"properties": {
"entityId": {
"type": "string",
"description": "The id of the entity to favorite."
},
"entityType": {
"oneOf": [
{
"type": "string",
"description": "The type of an entity in Macro",
"enum": [
"user",
"chat",
"channel",
"channel_message",
"document",
"project",
"email_thread",
"calendar_event",
"team",
"call",
"foreign_entity",
"static_file",
"crm_company",
"crm_contact",
"crm_pipeline",
"reminder",
"skill",
"agent_session",
"scheduled_action",
"initiative",
"database",
"database_row",
"form",
"external_chat"
]
}
],
"description": "The type of the entity to favorite."
}
}
},
"AddParticipantsRequest": {
"type": "object",
"description": "Request to add participants.",
"required": ["participants"],
"properties": {
"participants": {
"type": "array",
"items": {
"type": "string"
},
"description": "User ids to add.",
"uniqueItems": true
}
}
},
"AddPinRequest": {
"type": "object",
"required": ["pinType", "pinIndex"],
"properties": {
"pinIndex": {
"type": "integer",
"format": "int32",
"description": "The index of the pin"
},
"pinType": {
"type": "string",
"description": "The type of the pin"
}
}
},
"Agent": {
"type": "object",
"description": "A persisted user- or team-owned AI agent.",
"required": [
"bot",
"instructions",
"harness",
"default_model",
"channel_scope",
"channel_ids",
"mcp",
"is_coding"
],
"properties": {
"auto_accept_permissions": {
"type": ["boolean", "null"],
"description": "Whether the agent's sessions approve ACP permission requests without\nasking. `None` means always prompt. Bypass also requires the harness's opt-in."
},
"bot": {
"$ref": "#/components/schemas/Bot",
"description": "The bot identity used for mentions and channel participation."
},
"channel_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Selected channel ids. Empty for a global agent."
},
"channel_scope": {
"$ref": "#/components/schemas/AgentChannelScope",
"description": "Whether the agent is global or channel-specific."
},
"default_model": {
"type": "string",
"description": "Model selected specifically for this agent."
},
"harness": {
"type": "string",
"description": "Harness used to run the agent."
},
"harness_id": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/HarnessId",
"description": "Registered harness the agent runs on, when `harness` is `macrod`."
}
]
},
"instructions": {
"type": "string",
"description": "Instructions supplied to the agent at the start of a conversation."
},
"is_coding": {
"type": "boolean",
"description": "Whether the agent works in a repository, which decides how it answers\na channel mention: a coding agent posts a magic chip into its live\nsession, a chat agent replies in the thread. Chosen in the agent's\nsettings; the persona's word, not the runtime's."
},
"mcp": {
"$ref": "#/components/schemas/AgentMcpServers",
"description": "Which MCP servers sessions of this agent are handed."
}
}
},
"AgentActionId": {
"type": "string",
"format": "uuid",
"description": "Identifies one accepted [`AgentAction`] end to end: returned by the\ncontrol endpoint, written as the JSON-RPC request id on the action's wire\nframe, and read back off that frame as `request_id` on the folded message\nit derives.\n\nA v7 uuid, so ids sort by mint time. Minted by the server at accept time,\nor by a client that speculated the action and named it in the control\nrequest - either way the server is the only writer of runtime-bound\nframes, so a uuid-shaped request id remains the whole ownership test. The\nmachine's own handshake request ids (`agent_session:{session}:{n}`) are\nnot uuids and stay `None`."
},
"AgentChannelScope": {
"type": "string",
"description": "Whether an agent is available everywhere or only in selected channels.",
"enum": ["all", "selected"]
},
"AgentDmProfile": {
"type": "object",
"description": "Historical persona identity displayed beside a private conversation.",
"required": ["bot_id", "name"],
"properties": {
"avatar_url": {
"type": ["string", "null"],
"description": "Persona avatar, when supplied."
},
"bot_id": {
"type": "string",
"description": "Persona id without the bot principal prefix."
},
"name": {
"type": "string",
"description": "Persona display name."
}
}
},
"AgentMcpServer": {
"type": "object",
"description": "One Pipedream app an agent lists under [`AgentMcpServers::Selected`].\n\nOnly the catalog identity is stored. Whether a given person has connected\nthe app is theirs, resolved at call time by the egress proxy, never here.",
"required": ["app_slug", "server_name"],
"properties": {
"app_slug": {
"type": "string",
"description": "Pipedream app slug, e.g. `linear`."
},
"server_name": {
"type": "string",
"description": "Display name, e.g. `Linear`."
}
}
},
"AgentMcpServers": {
"oneOf": [
{
"type": "object",
"description": "Whatever apps the person running the session has connected.",
"required": ["scope"],
"properties": {
"scope": {
"type": "string",
"enum": ["owner_connections"]
}
}
},
{
"type": "object",
"description": "Exactly these apps, connected or not.",
"required": ["servers", "scope"],
"properties": {
"scope": {
"type": "string",
"enum": ["selected"]
},
"servers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentMcpServer"
},
"description": "The apps, in the order the agent's author picked them."
}
}
}
],
"description": "Which Pipedream MCP servers an agent's sessions are handed.\n\nOne value for the whole choice, so a selection can never travel without\nits scope or a scope without its selection. Serialized with a `scope` tag,\nwhich the generated TypeScript sees as a discriminated union."
},
"AgentPullRequestState": {
"type": "string",
"description": "Last synchronized state of a session's linked GitHub pull request.",
"enum": ["open", "draft", "closed", "merged"]
},
"AgentSessionArchiveCause": {
"type": "string",
"description": "Who or what archived an agent session.",
"enum": ["user", "pull_request_merged", "runtime_closed"]
},
"AgentSessionFilters": {
"type": "object",
"description": "Filters for agent sessions.",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Agent session ids to filter by. Empty to include all accessible sessions."
},
"include": {
"type": "boolean",
"description": "Opt this query into agent sessions at all. Agent sessions are off by\ndefault — see [`crate::ast::agent_session::AgentSessionLiteral::Include`].\nAsking for specific `ids` or `owners` also opts in."
},
"owners": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by session owner principal — a user ('macro|[email protected]'), a bot\n('bot|<uuid>'), or a team (a bare hyphenated uuid). Empty to include every\nowner."
}
}
},
"AgentSessionLifecycleEvent": {
"oneOf": [
{
"type": "object",
"description": "A session was created.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.opened"]
},
"metadata": {
"$ref": "#/components/schemas/SessionOpenedMetadata",
"description": "A session was created."
}
}
},
{
"type": "object",
"description": "A prompt was delivered to the runtime.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.turn_started"]
},
"metadata": {
"$ref": "#/components/schemas/TurnStartedMetadata",
"description": "A prompt was delivered to the runtime."
}
}
},
{
"type": "object",
"description": "The runtime answered a turn.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.turn_ended"]
},
"metadata": {
"$ref": "#/components/schemas/TurnEndedMetadata",
"description": "The runtime answered a turn."
}
}
},
{
"type": "object",
"description": "An accepted command was refused before runtime execution.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.command_rejected"]
},
"metadata": {
"$ref": "#/components/schemas/CommandRejectedMetadata",
"description": "An accepted command was refused before runtime execution."
}
}
},
{
"type": "object",
"description": "A turn ended with nothing queued behind it.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.settled"]
},
"metadata": {
"$ref": "#/components/schemas/SessionSettledMetadata",
"description": "A turn ended with nothing queued behind it."
}
}
},
{
"type": "object",
"description": "The agent is blocked on a question to its owner.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.waiting_for_input"]
},
"metadata": {
"$ref": "#/components/schemas/WaitingForInputMetadata",
"description": "The agent is blocked on a question to its owner."
}
}
},
{
"type": "object",
"description": "The question was answered or withdrawn.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.input_received"]
},
"metadata": {
"$ref": "#/components/schemas/InputReceivedMetadata",
"description": "The question was answered or withdrawn."
}
}
},
{
"type": "object",
"description": "A prompt named other users who can open the session.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.mentioned"]
},
"metadata": {
"$ref": "#/components/schemas/SessionMentionedMetadata",
"description": "A prompt named other users who can open the session."
}
}
},
{
"type": "object",
"description": "The session's live actor is gone.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.stopped"]
},
"metadata": {
"$ref": "#/components/schemas/SessionStoppedMetadata",
"description": "The session's live actor is gone."
}
}
},
{
"type": "object",
"description": "The session was renamed.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.renamed"]
},
"metadata": {
"$ref": "#/components/schemas/SessionRenamedMetadata",
"description": "The session was renamed."
}
}
},
{
"type": "object",
"description": "The session was deleted.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["agent_session.deleted"]
},
"metadata": {
"$ref": "#/components/schemas/SessionDeletedMetadata",
"description": "The session was deleted."
}
}
}
],
"description": "Events publishable to [`MacroAgentSessionLifecycleTopic`].\n\nThe serde tag and [`AgentSessionLifecycleEventName`] spell the same wire\nnames: subscribers filter on them, so they are API. The\n`event_names_match_the_wire` test holds the two in step. Exhaustive on\npurpose: a consumer's match should break when a variant is added."
},
"AgentSessionSource": {
"type": "string",
"description": "Who started an agent session. The string form is the\n`agent_session.source` column's.",
"enum": ["user", "agent", "routine"]
},
"AgentSessionVisibility": {
"type": "string",
"description": "Where an agent session is shown. The string form is the\n`agent_session.visibility` column's.",
"enum": ["listed", "unlisted", "hidden"]
},
"AgentTyping": {
"type": "object",
"description": "An agent session typing through its bot.",
"required": ["session_id", "phase"],
"properties": {
"phase": {
"$ref": "#/components/schemas/AgentTypingPhase",
"description": "What the agent is doing. Deliberately coarse: a typing event reaches\neveryone in the conversation, and which tool runs on what is for\nviewers who can read the session itself."
},
"session_id": {
"type": "string",
"format": "uuid",
"description": "The session whose turn the bot is speaking for."
}
}
},
"AgentTypingPhase": {
"type": "string",
"description": "What a typing agent is doing.",
"enum": ["thinking", "writing", "working", "waiting"]
},
"AiAdmissionErrorBody": {
"type": "object",
"description": "Public admission error payload. Handlers with additional fields can reuse the\ndomain error's code and message and [`admission_status`].",
"required": ["error", "code"],
"properties": {
"code": {
"type": "string",
"description": "Stable denial or unavailability code."
},
"error": {
"type": "string",
"description": "Human-readable explanation, without internal billing diagnostics."
}
}
},
"Anchor": {
"oneOf": [
{
"$ref": "#/components/schemas/PdfAnchor"
}
]
},
"AnchorId": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/PdfAnchorId"
},
{
"type": "object",
"required": ["fileType"],
"properties": {
"fileType": {
"type": "string",
"enum": ["pdf"]
}
}
}
]
}
]
},
"AnchorResponse": {
"type": "object",
"required": ["data"],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Anchor"
}
}
}
},
"AnimationClass": {
"type": "string",
"description": "An animation's effect group (PowerPoint's Entrance, Emphasis, Exit, and\nMotion Paths galleries).",
"enum": ["entrance", "emphasis", "exit", "path", "media", "other"]
},
"AnimationRepeat": {
"oneOf": [
{
"type": "number",
"format": "float",
"description": "Plays this many times in all (`1` = once, no repeat; fractions such as 2.5 are allowed)."
},
{
"$ref": "#/components/schemas/RepeatUntil",
"description": "Repeats until an event."
}
],
"description": "How often an animation plays."
},
"AnimationSpec": {
"type": "object",
"description": "One animation of a slide, for [`EditOp::SetAnimations`] and\n[`EditOp::AddAnimation`]. Omitted (or null) fields take the effect's\ndefaults, or keep the values of the existing animation it matches.",
"required": ["shapeId", "class", "effect"],
"properties": {
"class": {
"$ref": "#/components/schemas/AnimationClass",
"description": "Effect group: `entrance`, `emphasis`, `exit`, or `path` (`media` and\n`other` can only keep animations the slide already has)."
},
"delayMs": {
"type": ["integer", "null"],
"format": "int32",
"description": "Wait in milliseconds after the animation's start (click, previous\nanimation's start, or its end) before it plays, 0-60000 (default 0).",
"minimum": 0
},
"direction": {
"type": ["string", "null"],
"description": "Effect option (default: the first listed). `flyIn`, `flyOut` (edge it\nflies in from or out to): `bottom`, `left`, `right`, `top`,\n`bottomLeft`, `bottomRight`, `topLeft`, `topRight`; `wipe` (edge it\nstarts from): `bottom`, `left`, `right`, `top`; `split` (entrance):\n`verticalOut`, `horizontalOut`, `verticalIn`, `horizontalIn` (exit:\nthe `In` ones first); `shape` (entrance): `circleOut`, `circleIn`,\n`boxOut`, `boxIn`, `diamondOut`, `diamondIn`, `plusOut`, `plusIn`\n(exit: `circleIn` first); `wheel`: `spokes1`, `spokes2`, `spokes3`,\n`spokes4`, `spokes8`; `randomBars`: `horizontal`, `vertical`; `zoom`:\n`objectCenter`, `slideCenter`; `floatIn`: `up`, `down`; `floatOut`:\n`down`, `up`; `spin`: `clockwise`, `counterclockwise`; `path`: `down`,\n`left`, `right`, `up` (a straight line a quarter of the slide long)."
},
"durationMs": {
"type": ["integer", "null"],
"format": "int32",
"description": "Duration of one play in milliseconds, 10-60000 (default: the\neffect's, e.g. 500 for fade, flyIn, wipe, and zoom, 1000 for floatIn\nand teeter, 2000 for spin, growShrink, shape, wheel, and paths).\n`appear` and `disappear` are instant and ignore it.",
"minimum": 0
},
"effect": {
"type": "string",
"description": "Effect name. Entrance: `appear`, `fade`, `flyIn`, `floatIn`, `split`,\n`wipe`, `shape`, `wheel`, `randomBars`, `growTurn`, `zoom`, `swivel`,\n`bounce`. Emphasis: `pulse`, `colorPulse`, `teeter`, `spin`,\n`growShrink`, `desaturate`, `darken`, `lighten`, `transparency`,\n`boldFlash`, `wave`. Exit: `disappear`, `fadeOut`, `flyOut`,\n`floatOut`, `split`, `wipe`, `shape`, `wheel`, `randomBars`,\n`shrinkTurn`, `zoom`, `swivel`, `bounce`. Path: `path`. Other names\nthe slide's outline reports (and `custom`) only keep an existing\nanimation of that name on the same shape."
},
"paragraph": {
"type": ["integer", "null"],
"format": "int32",
"description": "Animate only this paragraph of the shape's text (0-based); omit to\nanimate the whole shape. One animation per paragraph builds a list\nparagraph by paragraph.",
"minimum": 0
},
"path": {
"type": ["string", "null"],
"description": "`path` class only: a motion path of its own instead of a direction,\nin PowerPoint's syntax with coordinates as fractions of the slide's\nwidth and height relative to the shape's position (`M 0 0 L 0.25 0.1 E`;\ncommands `M`, `L`, `C`, `Z`, and `E` for the end)."
},
"repeat": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AnimationRepeat",
"description": "How often it plays: a count (`2`, `3`...; `1` = no repeat),\n`untilNextClick`, or `untilEndOfSlide`."
}
]
},
"shapeId": {
"type": "integer",
"format": "int32",
"description": "Id of the shape to animate. A group member's id animates only that member.",
"minimum": 0
},
"start": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AnimationStart",
"description": "`onClick` (the default for a new animation), `withPrevious`, or `afterPrevious`."
}
]
}
},
"additionalProperties": false
},
"AnimationStart": {
"type": "string",
"description": "When an animation starts.",
"enum": ["onClick", "withPrevious", "afterPrevious"]
},
"AnnotationIncrementalUpdate": {
"oneOf": [
{
"type": "object",
"required": ["payload", "updateType"],
"properties": {
"payload": {
"type": "object",
"required": ["sender", "documentId", "response"],
"properties": {
"documentId": {
"type": "string"
},
"response": {
"$ref": "#/components/schemas/CreateUnthreadedAnchorResponse"
},
"sender": {
"type": "string"
}
}
},
"updateType": {
"type": "string",
"enum": ["create-anchor"]
}
}
},
{
"type": "object",
"required": ["payload", "updateType"],
"properties": {
"payload": {
"type": "object",
"required": ["sender", "documentId", "response"],
"properties": {
"documentId": {
"type": "string"
},
"response": {
"$ref": "#/components/schemas/EditAnchorResponse"
},
"sender": {
"type": "string"
}
}
},
"updateType": {
"type": "string",
"enum": ["edit-anchor"]
}
}
},
{
"type": "object",
"required": ["payload", "updateType"],
"properties": {
"payload": {
"type": "object",
"required": ["sender", "documentId", "response"],
"properties": {
"documentId": {
"type": "string"
},
"response": {
"$ref": "#/components/schemas/DeleteUnthreadedAnchorResponse"
},
"sender": {
"type": "string"
}
}
},
"updateType": {
"type": "string",
"enum": ["delete-anchor"]
}
}
}
]
},
"Answer": {
"type": "object",
"description": "One question's answer: a value for its column, typed as the column's\ncells are.",
"required": ["question", "value"],
"properties": {
"question": {
"type": "string",
"format": "uuid",
"description": "The question."
},
"value": {
"$ref": "#/components/schemas/CellValue",
"description": "The value; `clear` for no answer."
}
}
},
"ApiActivity": {
"type": "object",
"description": "A user's activity (view/interaction) within a channel.",
"required": ["id", "user_id", "channel_id", "created_at", "updated_at"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the activity row was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Activity id."
},
"interacted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "The last time the user interacted with the channel."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the activity row was last updated."
},
"user_id": {
"type": "string",
"description": "User id."
},
"viewed_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "The last time the user viewed the channel."
}
}
},
"ApiAttachmentChannelReference": {
"type": "object",
"description": "A reference to an attachment entity from a channel message.",
"required": [
"channel_id",
"message_id",
"sender_id",
"message_content",
"message_created_at",
"attachment_created_at"
],
"properties": {
"attachment_created_at": {
"type": "string",
"format": "date-time",
"description": "When the attachment row was created."
},
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel that contains the message."
},
"channel_name": {
"type": ["string", "null"],
"description": "Optional channel name (DMs do not have a name)."
},
"message_content": {
"type": "string",
"description": "Full message content (might be used for preview/snippet)."
},
"message_created_at": {
"type": "string",
"format": "date-time",
"description": "When the message itself was created."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Message that contains the attachment reference."
},
"sender_id": {
"type": "string",
"description": "Sender of the message."
},
"thread_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "If the message belongs to a thread this is the parent id."
}
}
},
"ApiAttachmentCommentReference": {
"type": "object",
"description": "A reference to an attachment entity from a comment on a non-channel entity.",
"required": [
"parent_entity_type",
"parent_entity_id",
"message_id",
"sender_id",
"message_content",
"message_created_at",
"attachment_created_at"
],
"properties": {
"attachment_created_at": {
"type": "string",
"format": "date-time",
"description": "When the mention or attachment row was created."
},
"message_content": {
"type": "string",
"description": "Full message content (might be used for preview/snippet)."
},
"message_created_at": {
"type": "string",
"format": "date-time",
"description": "When the message itself was created."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Message that contains the reference."
},
"parent_entity_id": {
"type": "string",
"description": "Id of the entity the comment belongs to."
},
"parent_entity_type": {
"type": "string",
"description": "Stored type of the entity the comment belongs to\n(`document`, `initiative`, `crm_company`, `crm_contact`, or `call`)."
},
"sender_id": {
"type": "string",
"description": "Sender of the message."
},
"thread_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "If the message belongs to a thread this is the parent id."
}
}
},
"ApiAttachmentEntityReference": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/ApiAttachmentChannelReference",
"description": "Referenced from a channel message."
},
{
"type": "object",
"required": ["reference_type"],
"properties": {
"reference_type": {
"type": "string",
"enum": ["channel"]
}
}
}
],
"description": "Referenced from a channel message."
},
{
"allOf": [
{
"$ref": "#/components/schemas/ApiAttachmentCommentReference",
"description": "Referenced from a comment on a document, initiative, CRM record, or call."
},
{
"type": "object",
"required": ["reference_type"],
"properties": {
"reference_type": {
"type": "string",
"enum": ["comment"]
}
}
}
],
"description": "Referenced from a comment on a document, initiative, CRM record, or call."
},
{
"allOf": [
{
"$ref": "#/components/schemas/ApiAttachmentGenericReference",
"description": "Referenced from any non-message source entity."
},
{
"type": "object",
"required": ["reference_type"],
"properties": {
"reference_type": {
"type": "string",
"enum": ["generic"]
}
}
}
],
"description": "Referenced from any non-message source entity."
}
],
"description": "An attachment reference, tagged by source kind."
},
"ApiAttachmentGenericReference": {
"type": "object",
"description": "A reference to an attachment entity from a non-message source.",
"required": [
"source_entity_type",
"source_entity_id",
"entity_type",
"entity_id",
"created_at"
],
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "When this reference was created."
},
"entity_id": {
"type": "string",
"description": "ID of the referenced entity."
},
"entity_type": {
"type": "string",
"description": "Type of the referenced entity."
},
"source_entity_id": {
"type": "string",
"description": "ID of the source entity."
},
"source_entity_type": {
"type": "string",
"description": "Type of the source entity (e.g., \"document\", \"chat\", etc.)."
},
"user_id": {
"type": ["string", "null"],
"description": "User who created this reference (optional for non-user sources)."
}
}
},
"ApiChannelAttachment": {
"type": "object",
"description": "A channel-level attachment.",
"required": [
"id",
"channel_id",
"message_id",
"sender_id",
"entity_type",
"entity_id",
"created_at"
],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the attachment was created."
},
"entity_id": {
"type": "string",
"description": "Entity id."
},
"entity_type": {
"type": "string",
"description": "Type of entity."
},
"height": {
"type": ["integer", "null"],
"format": "int32",
"description": "Height (for images)."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Attachment id."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Message id this attachment belongs to."
},
"sender_id": {
"type": "string",
"description": "The user who sent the message containing this attachment."
},
"width": {
"type": ["integer", "null"],
"format": "int32",
"description": "Width (for images)."
}
}
},
"ApiChannelAttachmentsPage": {
"type": "object",
"description": "Paginated response of channel attachments.",
"required": ["items"],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiChannelAttachment"
},
"description": "Attachments on this page."
},
"next_cursor": {
"type": ["string", "null"],
"description": "Cursor for the next page, null if no more pages."
}
}
},
"ApiChannelDetail": {
"type": "object",
"description": "Channel detail: metadata and active participants.\n\nMessages are read through `/messages/channel/{channel_id}`.",
"required": [
"channel_id",
"channel_type",
"channel_name",
"participants"
],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"channel_name": {
"type": "string",
"description": "Resolved display name from the viewer's perspective."
},
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Channel type."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiChannelParticipant"
},
"description": "Active participants."
}
}
},
"ApiChannelListMessage": {
"type": "object",
"description": "Channel message in API responses.",
"required": [
"message_id",
"sender_id",
"content",
"created_at",
"updated_at",
"mentions"
],
"properties": {
"content": {
"type": "string",
"description": "Message content."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"deleted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Deletion timestamp, if deleted."
},
"mentions": {
"type": "array",
"items": {
"type": "string"
},
"description": "message mentions formatted as `{ENTITY_TYPE}:{ENTITY_ID}`"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Message id."
},
"sender_id": {
"type": "string",
"description": "Sender user id."
},
"thread_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Thread id, if the message is a reply."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Update timestamp."
}
}
},
"ApiChannelListPage": {
"type": "object",
"description": "A cursor-paginated channel list response.",
"required": ["items"],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiChannelWithLatest"
},
"description": "Channels in this page."
},
"next_cursor": {
"type": ["string", "null"],
"description": "Opaque cursor for the next page, if one exists."
}
}
},
"ApiChannelListParticipant": {
"type": "object",
"description": "Channel participant in API responses.",
"required": ["channel_id", "user_id", "role", "joined_at"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "id of the channel"
},
"joined_at": {
"type": "string",
"format": "date-time",
"description": "timestamp of when the user joined the channel"
},
"left_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "timestamp of when the user left the channel"
},
"role": {
"$ref": "#/components/schemas/ApiParticipantListRole",
"description": "type of the participant"
},
"user_id": {
"type": "string",
"description": "id of the user"
}
}
},
"ApiChannelListType": {
"type": "string",
"description": "Channel type in API responses.",
"enum": ["public", "private", "direct_message", "team"]
},
"ApiChannelParticipant": {
"type": "object",
"description": "A channel participant.",
"required": ["channel_id", "user_id", "role", "joined_at"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"joined_at": {
"type": "string",
"format": "date-time",
"description": "When the user joined."
},
"role": {
"$ref": "#/components/schemas/ApiParticipantRole",
"description": "Role in the channel."
},
"user_id": {
"type": "string",
"description": "User id."
}
}
},
"ApiChannelWithLatest": {
"type": "object",
"description": "Channel list response item.",
"required": [
"id",
"channel_type",
"auto_join_team",
"created_at",
"updated_at",
"owner_id",
"participants",
"is_participant"
],
"properties": {
"agent_dm": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AgentDmProfile",
"description": "Persona identity when this is the viewer's private agent DM."
}
]
},
"auto_join_team": {
"type": "boolean",
"description": "Whether team members automatically join the channel."
},
"channel_type": {
"$ref": "#/components/schemas/ApiChannelListType",
"description": "Channel type."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Channel creation timestamp."
},
"frecency_score": {
"type": ["number", "null"],
"format": "double",
"description": "Aggregate frecency score."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"interacted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Last interaction timestamp for requesting user."
},
"is_participant": {
"type": "boolean",
"description": "Whether the requesting user is an active participant of the channel."
},
"latest_message": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ApiChannelListMessage",
"description": "Latest message including thread replies."
}
]
},
"latest_non_thread_message": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ApiChannelListMessage",
"description": "Latest top-level non-thread message."
}
]
},
"name": {
"type": ["string", "null"],
"description": "Channel name."
},
"org_id": {
"type": ["integer", "null"],
"format": "int32",
"description": "Organization id.",
"minimum": 0
},
"owner_id": {
"type": "string",
"description": "Channel owner user id."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiChannelListParticipant"
},
"description": "Active participants."
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team id."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Channel last-updated timestamp."
},
"viewed_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Last viewed timestamp for requesting user."
}
}
},
"ApiEntityFilterAst": {
"type": "object",
"description": "Wire-format entity filter AST accepted by soup AST endpoints.",
"properties": {
"asf": {
"description": "Filters applied to agent sessions (wire key `asf`). An empty or\nomitted filter returns **no** agent sessions: they are opt-in, so the\ncaller must send `inc`, an id, or an owner to get any."
},
"calf": {
"description": "filters applied to canonical calendar events"
},
"callf": {
"description": "the filters that should be applied to the call entity"
},
"ccf": {
"description": "Filters applied to the crm_company entity (wire key `ccf`).\nEmpty/omitted = team's full visible list."
},
"cf": {
"description": "the filters that should be applied to the chat entity"
},
"chanf": {
"description": "the filters that should be applied to the channel entity"
},
"crma": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CrmAssociation",
"description": "Restrict every entity type to items associated with this CRM record\n(wire key `crma`): its Companies or Contacts property names the\nrecord, or it references the record. A company also matches through\nits contacts. Unknown or inaccessible records answer 404; requests\nrequire expanded queries sorted by a timestamp or selected numeric property."
}
]
},
"crmf": {
"description": "Opt-in filters for viewer-accessible CRM contacts (wire key `crmf`)."
},
"cthf": {
"description": "the filters that should be applied to the channel-thread entity"
},
"df": {
"description": "the filters that should be applied to the document entity"
},
"eca": {
"type": "array",
"items": {
"type": "string"
},
"description": "CRM-scoped address filter (wire key: `eca`). Symmetric counterpart\nto `ecd` for fully-qualified email addresses."
},
"ecd": {
"type": "array",
"items": {
"type": "string"
},
"description": "CRM-scoped domain filter (wire key: `ecd`). Parallel to the\nfreeform `ef` AST. Expanded by the router into an any-direction\nOR sub-tree AND-merged into `ef`, plus a `CrmScope` tag stamped\non the resulting [`item_filters::ast::EmailFilterAst::crm_scope`].\nDrives the per-team CRM authorization pre-check and candidate-set\nwidening downstream. Mutually exclusive with `eca`."
},
"ef": {
"description": "the filters that should be applied to the email entity (raw AST\ntree only; CRM scope is carried by the `ecd` / `eca` sibling\nfields). On this endpoint the email filter stays a bare tree,\nunlike the materialized [`EntityFilterAst`] used for cursors."
},
"favorites_only": {
"type": ["boolean", "null"],
"description": "Restrict to the authenticated viewer's favorites before pagination when true."
},
"fef": {
"description": "the filters that should be applied to foreign entity records"
},
"ghprf": {
"description": "the filters that should be applied to GitHub pull request records, on top of `fef`"
},
"if": {
"description": "Filters applied to initiatives (wire key `if`). Opt-in like agent\nsessions: an omitted filter returns no initiatives, and any literal,\na notification state included, opts them in."
},
"pf": {
"description": "the filters that should be applied to the project entity"
},
"propf": {
"description": "the filters that should be applied based on entity properties"
}
}
},
"ApiGroupByField": {
"oneOf": [
{
"type": "string",
"description": "Smart date buckets: Today, Yesterday, This Week, Last Week, This Month, Last Month, Older",
"enum": ["date"]
},
{
"type": "string",
"description": "Group by entity type (document, email, channel, etc.)",
"enum": ["entity_type"]
},
{
"type": "string",
"description": "Group by project",
"enum": ["project"]
},
{
"type": "object",
"description": "Group by a property value (e.g., status, priority, or custom properties)",
"required": ["property"],
"properties": {
"property": {
"type": "object",
"description": "Group by a property value (e.g., status, priority, or custom properties)",
"required": ["property_definition_id"],
"properties": {
"bucketing": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/PropertyBucketing",
"description": "Caller-defined date partition; non-DATE values enter the missing bucket."
}
]
},
"entity_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ApiPropertyEntityType",
"description": "Optional entity type filter for the property lookup"
}
]
},
"property_definition_id": {
"type": "string",
"format": "uuid",
"description": "The property definition UUID to group by"
}
}
}
}
}
],
"description": "API representation of group-by field."
},
"ApiGroupMeta": {
"type": "object",
"description": "API representation of group metadata.\n\nItems belonging to this group are referenced by `item_ids`, each of which\nlooks up an entry in `GroupedSoupPage.items` (a normalized pool).",
"required": ["key", "label", "total_count", "item_ids"],
"properties": {
"display_order": {
"type": ["integer", "null"],
"format": "int32",
"description": "Display order for sorting groups (lower = first)"
},
"item_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Ordered ids of items in this group for the current page.\nEach id keys into `GroupedSoupPage.items`."
},
"key": {
"type": "string",
"description": "Group key - format depends on group_by field"
},
"label": {
"type": "string",
"description": "Human-readable label for the group"
},
"next_cursor": {
"type": ["string", "null"],
"description": "Cursor to load more items specifically from this group"
},
"total_count": {
"type": "integer",
"format": "int32",
"description": "Total count of items in this group across all pages",
"minimum": 0
}
}
},
"ApiParticipantListRole": {
"type": "string",
"description": "Participant role in API responses.",
"enum": ["owner", "admin", "member"]
},
"ApiParticipantRole": {
"type": "string",
"description": "Participant role in a channel.",
"enum": ["owner", "admin", "member"]
},
"ApiPropertyEntityType": {
"type": "string",
"description": "Entity type for property lookups (API representation).",
"enum": [
"CALL_RECORD",
"CALENDAR_EVENT",
"DATABASE_ROW",
"INITIATIVE",
"CHANNEL",
"CHAT",
"COMPANY",
"DOCUMENT",
"PROJECT",
"TASK",
"THREAD",
"USER"
]
},
"AppliedOps": {
"type": "object",
"description": "What a committed batch answers: a result per op, and the journal's change\nfor each table version it produced.",
"required": ["results", "changes"],
"properties": {
"changes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommittedChange"
},
"description": "The journal's changes."
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OpResult"
},
"description": "One result per op, in order."
}
}
},
"ApplyOpsRequest": {
"type": "object",
"description": "A batch of ops for one database, applied in order, in one transaction,\ntogether or not at all.",
"required": ["ops"],
"properties": {
"baseVersions": {
"type": "object",
"description": "The version each named table must still be at, as the caller read\nit. A table that moved refuses the batch as a conflict, so a schema\nedit made against what the caller saw does not overwrite another's.\nLeft out, ops are last-write-wins.",
"additionalProperties": {
"$ref": "#/components/schemas/TableVersion"
},
"propertyNames": {
"type": "string"
}
},
"ops": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DatabaseOp"
},
"description": "The ops, in the order they apply, each grouped by the resource it\nchanges (`table`, `column`, `rows`, `view`, `reorder_tables`) with a\n`change` saying how. Every one names a table of this database, or one\nan earlier op of the batch creates: tables, columns, options and\nviews carry ids the client mints (UUIDv7), so a later op can name\nthem. An id that already names something refuses the batch."
}
}
},
"ApplyOpsResponse": {
"type": "object",
"description": "What each op of a batch did.",
"required": ["results", "changes"],
"properties": {
"changes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommittedChange"
},
"description": "The journal's change for each table version the batch produced: the\nids `POST /databases/{id}/changes/{change}/undo` takes."
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OpResult"
},
"description": "One result per op, in the order the ops were sent. Each is grouped as\nits op is: the same outer `kind`, naming the same ids, with a\n`change` saying what happened."
}
}
},
"ApprovePairingRequest": {
"type": "object",
"description": "Request to approve a pairing and register the harness.",
"properties": {
"allow_permission_bypass": {
"type": "boolean",
"description": "Whether agents may bypass ACP permission requests on this harness."
},
"name": {
"type": ["string", "null"],
"description": "Display name override. Defaults to the daemon's requested name."
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Owning team. Omit for a private, user-owned harness."
}
}
},
"AttachmentChange": {
"oneOf": [
{
"type": "object",
"description": "Keep current attachments.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["preserve"]
}
}
},
{
"type": "object",
"description": "Replace all attachments.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["replace"]
},
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewAttachment"
},
"description": "Replace all attachments."
}
}
},
{
"type": "object",
"description": "Remove stored attachment identities and append new references.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["delta"]
},
"value": {
"type": "object",
"description": "Remove stored attachment identities and append new references.",
"required": ["remove", "add"],
"properties": {
"add": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewAttachment"
},
"description": "New attachments to append."
},
"remove": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Existing attachment UUIDs to remove."
}
}
}
}
}
],
"description": "Attachment changes interpreted by the common command boundary."
},
"AttendeeResponseStatus": {
"type": "string",
"description": "RSVP state for an attendee.",
"enum": ["needs_action", "accepted", "declined", "tentative"]
},
"Audience": {
"type": "string",
"description": "Who may respond to a form.",
"enum": ["members", "public"]
},
"Awareness": {
"type": "object",
"description": "Where one viewer is inside a database right now: ephemeral, relayed to\nthe other viewers and never stored. A missing row or column means the\nviewer is on the table but on no cell. Optional end row and column IDs\nmark the opposite corner of a rectangular cell selection.",
"required": ["tableId"],
"properties": {
"columnId": {
"type": "string",
"format": "uuid",
"description": "The column placement of the focused cell, if any."
},
"editing": {
"type": "boolean",
"description": "Whether the cell is open for editing."
},
"endColumnId": {
"type": "string",
"format": "uuid",
"description": "The opposite column corner of a selected rectangle, if any."
},
"endRowId": {
"type": "string",
"format": "uuid",
"description": "The opposite row corner of a selected rectangle, if any."
},
"left": {
"type": "boolean",
"description": "Whether the viewer left the database; other viewers drop their state."
},
"peerId": {
"type": "string",
"format": "uuid",
"description": "This mounted client's random peer id, distinct from its authenticated user.\nOlder clients omit it and remain visible as one peer per user."
},
"rowId": {
"type": "string",
"format": "uuid",
"description": "The row of the focused cell, if any."
},
"tableId": {
"type": "string",
"format": "uuid",
"description": "The table the viewer is looking at."
}
}
},
"AwarenessRelay": {
"type": "object",
"description": "The [`AWARENESS_MESSAGE_TYPE`] payload: one viewer's awareness, stamped\nwhen the server relayed it so receivers can drop older relays.",
"required": ["databaseId", "userId", "canEdit", "state", "relayedAt"],
"properties": {
"canEdit": {
"type": "boolean",
"description": "Whether the viewer's grant lets them edit; a viewer who cannot is\nshown as viewing."
},
"databaseId": {
"type": "string",
"format": "uuid",
"description": "The database the viewer is in."
},
"relayedAt": {
"type": "integer",
"format": "int64",
"description": "When the server relayed it, in milliseconds since the Unix epoch."
},
"state": {
"$ref": "#/components/schemas/Awareness",
"description": "Where the viewer is."
},
"userId": {
"type": "string",
"description": "The viewer."
}
}
},
"BTreeMap": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"propertyNames": {
"type": "string"
}
},
"BasicDocument": {
"type": "object",
"required": ["id", "documentVersionId", "owner", "name"],
"properties": {
"branchedFromId": {
"type": ["string", "null"],
"description": "The id of the document this document branched from"
},
"branchedFromVersionId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The id of the version this document branched from\nThis could be either DocumentInstance or DocumentBom id depending on\nthe file type"
},
"createdAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document was created"
},
"deletedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document was deleted"
},
"documentFamilyId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The id of the document family this document belongs to"
},
"documentVersionId": {
"type": "integer",
"format": "int64",
"description": "The version of the document\nThis could be the document_instance_id or document_bom_id depending on\nthe file type"
},
"fileType": {
"type": ["string", "null"],
"description": "The file type of the document (e.g. pdf, docx)"
},
"id": {
"type": "string",
"description": "The document id"
},
"name": {
"type": "string",
"description": "The name of the document"
},
"owner": {
"type": "string",
"description": "The owner of the document"
},
"projectId": {
"type": ["string", "null"],
"description": "The id of the project that this document belongs to"
},
"sha": {
"type": ["string", "null"],
"description": "If the document is a PDF, this is the SHA of the pdf\nIf the document is a DOCX, this will not be present"
},
"subType": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BasicDocumentSubType",
"description": "The sub type of the document if present.\nTask-related properties are encoded within the variant."
}
]
},
"updatedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document instance / document BOM was updated"
}
}
},
"BasicDocumentSubType": {
"oneOf": [
{
"type": "object",
"description": "A task document with its associated properties",
"required": ["is_completed", "type"],
"properties": {
"is_completed": {
"type": "boolean",
"description": "Whether the task is completed.\nTrue if the Status property is set to \"Completed\"."
},
"type": {
"type": "string",
"enum": ["task"]
}
}
},
{
"type": "object",
"description": "A snippet document — reusable markdown",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["snippet"]
}
}
},
{
"type": "object",
"description": "A skill document — markdown instructions for AI",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["skill"]
}
}
},
{
"type": "object",
"description": "The description document of an initiative",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["initiative_description"]
}
}
}
],
"description": "Sub type of a document with associated properties encoded in each variant.\nThis ensures type-safety: task properties only exist when the document is a task."
},
"BodyPatch": {
"type": "object",
"description": "Text box (body) changes.",
"properties": {
"anchor": {
"type": ["string", "null"],
"description": "`top`, `middle`, `bottom`.",
"default": null
},
"autofit": {
"type": ["string", "null"],
"description": "`none`, `shrink` (shrink text on overflow), `resize` (resize shape to fit).",
"default": null
},
"columns": {
"type": ["integer", "null"],
"format": "int32",
"description": "Number of columns.",
"default": null,
"minimum": 0
},
"direction": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/TextDirection",
"description": "Text direction (PowerPoint's Text Direction): `horz` (horizontal),\n`vert` (rotate all text 90°: lines run top to bottom, stacking right\nto left), `vert270` (rotate all text 270°: lines run bottom to top,\nstacking left to right), `wordArtVert` (stacked: upright letters one\nunder another), `eaVert` (East Asian vertical: CJK upright, other\ntext rotated 90°), `mongolianVert` (like `eaVert`, lines stacking\nleft to right), or `wordArtVertRtl` (stacked, lines stacking right to\nleft). Insets stay on the shape's sides; `anchor` `top` is where the\nfirst line goes (the right edge for `vert`). Switching a text box that\nresizes to fit its text between horizontal and vertical swaps its\nwidth and height first. Applies to table cells too. Omitted or null\nkeeps the direction."
}
],
"default": null
},
"insets": {
"type": ["array", "null"],
"items": {
"type": "number",
"format": "float"
},
"description": "Insets `[left, top, right, bottom]` in points.",
"default": null
},
"wrap": {
"type": ["boolean", "null"],
"description": "Wrap text at the box width.",
"default": null
}
},
"additionalProperties": false
},
"BomPart": {
"type": "object",
"required": ["id", "sha", "path"],
"properties": {
"id": {
"type": "string",
"description": "The uuid of the bom part"
},
"path": {
"type": "string",
"description": "The file path of the bom part content"
},
"sha": {
"type": "string",
"description": "The sha of the bom part content\nThere is an index on sha for more performant queries based on it."
}
}
},
"BookingTarget": {
"type": "object",
"description": "An existing native Macro scheduling event offered after an accepted response.",
"required": ["profileId", "eventTypeId"],
"properties": {
"eventTypeId": {
"type": "string",
"format": "uuid",
"description": "The event type to book."
},
"profileId": {
"type": "string",
"format": "uuid",
"description": "The scheduling profile that owns the event."
}
}
},
"BorderEdges": {
"type": "string",
"description": "Which borders of a cell range [`EditOp::FormatCells`](super::EditOp::FormatCells) changes. A border\nbetween two cells is shared, so both cells get the change.",
"enum": [
"all",
"outside",
"inside",
"top",
"bottom",
"left",
"right",
"insideHorizontal",
"insideVertical"
]
},
"BorderLine": {
"type": "object",
"description": "A table border change (`None` = leave unchanged). A border that did not\nexist yet becomes a solid 1 pt `tx1` line unless the change says otherwise.",
"properties": {
"color": {
"type": ["string", "null"],
"description": "Color (`RRGGBB` or theme name).",
"default": null
},
"dash": {
"type": ["string", "null"],
"description": "Preset dash (`solid`, `dash`, `dot`, `dashDot`, `lgDash`, `sysDash`, `sysDot`).",
"default": null
},
"none": {
"type": "boolean",
"description": "Remove the border (no line).",
"default": false
},
"width": {
"type": ["number", "null"],
"format": "float",
"description": "Width in points.",
"default": null
}
},
"additionalProperties": false
},
"Bot": {
"type": "object",
"description": "Bot row.\n\nClients deserialize this, so both derives are used.",
"required": [
"id",
"kind",
"name",
"handle",
"created_at",
"updated_at",
"has_agent"
],
"properties": {
"avatar_url": {
"type": ["string", "null"],
"description": "Optional avatar URL."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"created_by": {
"type": ["string", "null"],
"description": "User that created this bot."
},
"deleted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Soft-delete timestamp."
},
"description": {
"type": ["string", "null"],
"description": "Optional description."
},
"handle": {
"type": "string",
"description": "Stable handle."
},
"has_agent": {
"type": "boolean",
"description": "Whether this bot runs as an AI agent: mentions and DMs start an agent session."
},
"id": {
"$ref": "#/components/schemas/BotId",
"description": "Bot id."
},
"kind": {
"$ref": "#/components/schemas/BotKind",
"description": "Bot kind."
},
"name": {
"type": "string",
"description": "Display name."
},
"owner": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BotOwner",
"description": "Owner for owned bots."
}
]
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Update timestamp."
}
}
},
"BotChannel": {
"type": "object",
"description": "Channel containing a bot.",
"required": ["channel_id", "channel_type", "joined_at"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"channel_type": {
"$ref": "#/components/schemas/BotChannelType",
"description": "Channel type."
},
"joined_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the bot joined the channel."
},
"name": {
"type": ["string", "null"],
"description": "Channel display name."
}
}
},
"BotChannelType": {
"type": "string",
"description": "Channel type for a channel containing a bot.",
"enum": ["public", "private", "direct_message", "team"]
},
"BotId": {
"type": "string"
},
"BotKind": {
"type": "string",
"description": "Bot kind.",
"enum": ["owned", "system"]
},
"BotOwner": {
"oneOf": [
{
"type": "object",
"description": "User-owned bot.",
"required": ["user_id", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["user"]
},
"user_id": {
"type": "string",
"description": "Owner user id."
}
}
},
{
"type": "object",
"description": "Team-owned bot.",
"required": ["team_id", "type"],
"properties": {
"team_id": {
"type": "string",
"format": "uuid",
"description": "Owner team id."
},
"type": {
"type": "string",
"enum": ["team"]
}
}
}
],
"description": "Bot owner."
},
"BotOwnerProfile": {
"type": "object",
"description": "Bot identity for rendering, including the sponsor and soft-delete time.\n\n`owner` is none only for a registry system bot. A persisted row always has\na sponsor.",
"required": ["id", "name"],
"properties": {
"avatar_url": {
"type": ["string", "null"],
"description": "Avatar URL. Registry system bots have none."
},
"deleted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Soft-delete time. Absent for an active bot and for a registry system bot."
},
"id": {
"$ref": "#/components/schemas/BotId",
"description": "Bot id."
},
"name": {
"type": "string",
"description": "Display name."
},
"owner": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BotOwner",
"description": "Sponsor. None only for a registry system bot."
}
]
}
}
},
"BotSenderProfile": {
"type": "object",
"description": "Public bot profile attached to bot-authored messages.",
"required": ["name"],
"properties": {
"avatar_url": {
"type": ["string", "null"],
"description": "Bot avatar URL."
},
"name": {
"type": "string",
"description": "Bot display name."
}
}
},
"BotToken": {
"type": "object",
"description": "Bot token metadata.",
"required": ["id", "bot_id", "token_prefix", "created_at"],
"properties": {
"bot_id": {
"$ref": "#/components/schemas/BotId",
"description": "Owning bot id."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"expires_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Expiration timestamp."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Token id."
},
"label": {
"type": ["string", "null"],
"description": "Optional token label."
},
"last_used_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Last successful use."
},
"revoked_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Revocation timestamp."
},
"token_prefix": {
"type": "string",
"description": "Display prefix of the bearer token. The raw secret is never stored here."
}
}
},
"BranchNameResponse": {
"type": "object",
"description": "Branch name response.",
"required": ["shortId", "branchName"],
"properties": {
"branchName": {
"type": "string",
"description": "The git branch name for the task document."
},
"shortId": {
"type": "string",
"description": "The short id of the document."
}
}
},
"BulkWakeupRequest": {
"type": "object",
"required": ["document_ids"],
"properties": {
"document_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BulkWakeupResponse": {
"type": "object",
"required": ["dispatched"],
"properties": {
"dispatched": {
"type": "integer",
"minimum": 0
}
}
},
"BulletSpec": {
"oneOf": [
{
"type": "object",
"description": "No bullet.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["none"]
}
}
},
{
"type": "object",
"description": "Inherit from the layout/master (removes explicit bullet settings).",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["inherit"]
}
}
},
{
"type": "object",
"description": "A character bullet.",
"required": ["char", "kind"],
"properties": {
"char": {
"type": "string",
"description": "The bullet character."
},
"kind": {
"type": "string",
"enum": ["char"]
}
}
},
{
"type": "object",
"description": "Automatic numbering (`arabicPeriod`, `romanUcPeriod`, `alphaLcParenR`...).",
"required": ["scheme", "kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["number"]
},
"scheme": {
"type": "string",
"description": "Numbering scheme."
},
"start": {
"type": "integer",
"format": "int32",
"description": "First number.",
"minimum": 0
}
}
}
],
"description": "Bullet style for paragraphs."
},
"CalendarAttendee": {
"type": "object",
"description": "An attendee on a calendar event.",
"required": [
"email",
"responseStatus",
"isOrganizer",
"isOptional",
"isSelf"
],
"properties": {
"comment": {
"type": ["string", "null"],
"description": "Optional attendee comment."
},
"displayName": {
"type": ["string", "null"],
"description": "Provider display name."
},
"email": {
"type": "string",
"description": "Normalized email address."
},
"isOptional": {
"type": "boolean",
"description": "Whether attendance is optional."
},
"isOrganizer": {
"type": "boolean",
"description": "Whether this attendee is the organizer."
},
"isSelf": {
"type": "boolean",
"description": "Whether this attendee is one of the viewing requester's inboxes."
},
"responseStatus": {
"$ref": "#/components/schemas/AttendeeResponseStatus",
"description": "RSVP state."
}
}
},
"CalendarEvent": {
"type": "object",
"description": "A stable, first-class Macro calendar event entity.\n\nContent fields hold the canonical source's values: the account's primary\ncalendar copy when one is synced, else the freshest remaining copy.",
"required": [
"id",
"ownerId",
"icalUid",
"title",
"status",
"visibility",
"transparency",
"time",
"recurrenceLines",
"sequence",
"isReadOnly",
"attendees",
"guestPolicy",
"isSnapshot",
"viewerCan",
"createdAt",
"updatedAt"
],
"properties": {
"attendees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CalendarAttendee"
},
"description": "Attendees, keyed by email during persistence."
},
"calendarId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Calendar the canonical source belongs to, when known. Absent only in\nprojections stored before calendars were attributed."
},
"conferenceProvider": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ConferenceProvider",
"description": "Which conferencing system backs `conference_url`. `None` whenever no\nconference is attached."
}
]
},
"conferenceUrl": {
"type": ["string", "null"],
"description": "Direct join URL when known."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Entity creation time."
},
"creatorEmail": {
"type": ["string", "null"],
"description": "Provider-reported creator email. Distinct from the organizer when\nsomeone writes onto a calendar they do not own. Omitted from stored\nprojections when unknown so events ingested before this field still\ncompare equal."
},
"creatorName": {
"type": ["string", "null"],
"description": "Provider-reported creator display name."
},
"description": {
"type": ["string", "null"],
"description": "Optional event body."
},
"eventType": {
"$ref": "#/components/schemas/EventType",
"description": "Provider event type. Skipped when it is the regular type so\nprojections stored before event types were modeled still compare\nequal."
},
"guestPolicy": {
"$ref": "#/components/schemas/GuestPolicy",
"description": "What the organizer lets guests do: the canonical copy's values, or\nGoogle's defaults for an event synced before the policy was modeled."
},
"icalUid": {
"type": "string",
"description": "RFC 5545 UID used to reconcile provider and email sources."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Macro entity identifier."
},
"isReadOnly": {
"type": "boolean",
"description": "Whether the canonical source's calendar prohibits editing it."
},
"isSnapshot": {
"type": "boolean",
"description": "Whether this is a snapshot of a meeting shared with the owner, which\nMacro added to their calendar as a private copy: the meeting's changes\nnever reach it, and nothing done to it reaches the meeting."
},
"location": {
"type": ["string", "null"],
"description": "Optional physical or virtual location label."
},
"organizerEmail": {
"type": ["string", "null"],
"description": "Organizer email."
},
"organizerName": {
"type": ["string", "null"],
"description": "Organizer display name."
},
"ownerId": {
"type": "string",
"description": "Macro user who owns this event entity."
},
"recurrenceLines": {
"type": "array",
"items": {
"type": "string"
},
"description": "Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`)."
},
"reminders": {
"$ref": "#/components/schemas/EventReminders",
"description": "Per-user reminder configuration. Skipped when it is the provider\ndefault so projections stored before reminders were modeled still\ncompare equal."
},
"sequence": {
"type": "integer",
"format": "int32",
"description": "Provider/iCalendar sequence number.",
"minimum": 0
},
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CalendarEventSourceContent"
},
"description": "Content of every active copy of this event, canonical first: the\nprimary calendar's copy, then the freshest. A client picks the copy\nwhose calendar it is showing and falls back to the first. Populated\nonly on the read path, so stored projections omit it."
},
"status": {
"$ref": "#/components/schemas/EventStatus",
"description": "Event status."
},
"time": {
"$ref": "#/components/schemas/EventTime",
"description": "Timed or all-day shape."
},
"title": {
"type": "string",
"description": "Display title."
},
"transparency": {
"$ref": "#/components/schemas/EventTransparency",
"description": "Availability behavior."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Entity update time."
},
"viewerCan": {
"$ref": "#/components/schemas/ViewerCapabilities",
"description": "What the viewing requester may do with the event. Resolved only on\nthe read path, alongside each attendee's `is_self`; nothing when no\nviewer is known. Source projections never store it."
},
"visibility": {
"$ref": "#/components/schemas/EventVisibility",
"description": "Event visibility."
}
}
},
"CalendarEventFilters": {
"type": "object",
"description": "Filters for canonical calendar-event entities.",
"properties": {
"attendees": {
"type": "array",
"items": {
"type": "string"
},
"description": "Attendee email addresses."
},
"calendar_event_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Canonical event ids."
},
"ends_after": {
"type": ["string", "null"],
"format": "date-time",
"description": "Include master events ending after this instant."
},
"organizers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Organizer email addresses."
},
"starts_before": {
"type": ["string", "null"],
"format": "date-time",
"description": "Include master events starting before this instant."
},
"statuses": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event statuses such as `confirmed`, `tentative`, or `cancelled`."
}
}
},
"CalendarEventSourceContent": {
"type": "object",
"description": "The content one provider copy of an event carries.\n\nGoogle keeps these fields per calendar copy: a shared calendar's copy of a\nmember's event can have its own title, type, reminders, and access role.\nThe entity holds its canonical source's values. Every other copy's values\nare read from here so a client can show the copy that belongs to the\ncalendar being viewed.",
"required": [
"calendarId",
"title",
"eventType",
"visibility",
"transparency",
"isReadOnly",
"reminders"
],
"properties": {
"calendarId": {
"type": "string",
"format": "uuid",
"description": "Calendar this copy lives on."
},
"creatorEmail": {
"type": ["string", "null"],
"description": "Provider-reported creator email."
},
"creatorName": {
"type": ["string", "null"],
"description": "Provider-reported creator display name."
},
"description": {
"type": ["string", "null"],
"description": "Optional event body."
},
"eventType": {
"$ref": "#/components/schemas/EventType",
"description": "Provider event type."
},
"isReadOnly": {
"type": "boolean",
"description": "Whether the calendar's access role prohibits editing this copy."
},
"location": {
"type": ["string", "null"],
"description": "Optional physical or virtual location label."
},
"reminders": {
"$ref": "#/components/schemas/EventReminders",
"description": "Reminder configuration of this copy."
},
"title": {
"type": "string",
"description": "Display title."
},
"transparency": {
"$ref": "#/components/schemas/EventTransparency",
"description": "Availability behavior."
},
"visibility": {
"$ref": "#/components/schemas/EventVisibility",
"description": "Event visibility."
}
}
},
"CalendarJoinRequest": {
"type": "object",
"description": "A channel member's request to be added as a guest of an event they see\nonly through a channel share.",
"required": [
"id",
"eventId",
"requesterId",
"requesterEmail",
"status",
"createdAt"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the request was made."
},
"eventId": {
"type": "string",
"format": "uuid",
"description": "The sharer's event entity that was shared with the channel."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Request identifier."
},
"requesterEmail": {
"type": "string",
"description": "Address the sharer invites when accepting."
},
"requesterId": {
"type": "string",
"description": "Macro user asking to join."
},
"status": {
"$ref": "#/components/schemas/CalendarJoinRequestStatus",
"description": "Where the request stands."
}
}
},
"CalendarJoinRequestApiError": {
"type": "object",
"description": "HTTP error body returned by join-request endpoints.",
"required": ["code", "message"],
"properties": {
"code": {
"$ref": "#/components/schemas/CalendarJoinRequestErrorCode",
"description": "Machine-readable failure category."
},
"message": {
"type": "string",
"description": "Human-readable failure description."
}
}
},
"CalendarJoinRequestErrorCode": {
"type": "string",
"description": "Machine-readable join-request failure category.",
"enum": [
"not_found",
"already_on_calendar",
"sharer_cannot_invite",
"request_declined",
"internal"
]
},
"CalendarJoinRequestStatus": {
"type": "string",
"description": "Lifecycle of a request to be added as a guest of a shared event.",
"enum": ["pending", "accepted", "declined"]
},
"CalendarJoinRequestsResponse": {
"type": "object",
"description": "Pending requests to join one event.",
"required": ["requests"],
"properties": {
"requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CalendarJoinRequest"
},
"description": "Oldest first."
}
}
},
"CalendarMentionEvent": {
"type": "object",
"description": "Meeting-level fields shown in a calendar event mention preview, taken from\nthe requester's own projection of the meeting, or — when the requester has\nnone — from the mentioned projection a channel they belong to was given.",
"required": [
"title",
"time",
"isRecurring",
"attendeeCount",
"updatedAt"
],
"properties": {
"attendeeCount": {
"type": "integer",
"description": "Number of attendees on the previewed copy.",
"minimum": 0
},
"canRequestToJoin": {
"type": "boolean",
"description": "For a channel-shared preview, whether the person who shared it can\nadd the requester as a guest. Always false for the requester's own\ncopy."
},
"description": {
"type": ["string", "null"],
"description": "Provider description, plain text or HTML, truncated for the preview.\nClients must sanitize it before rendering."
},
"isRecurring": {
"type": "boolean",
"description": "Whether the event repeats."
},
"joinRequestStatus": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CalendarJoinRequestStatus",
"description": "For a channel-shared preview, the requester's request to join, if any."
}
]
},
"location": {
"type": ["string", "null"],
"description": "Location label, when set."
},
"occurrenceKey": {
"type": ["string", "null"],
"description": "Key of the previewed instance, absent when no occurrence is\nmaterialized."
},
"organizerEmail": {
"type": ["string", "null"],
"description": "Organizer email."
},
"organizerName": {
"type": ["string", "null"],
"description": "Organizer display name."
},
"time": {
"$ref": "#/components/schemas/EventTime",
"description": "Time of the previewed instance: the requested occurrence when it\nexists, else the next upcoming one, else the latest past one, else the\nseries start."
},
"title": {
"type": "string",
"description": "Display title."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Entity update time of the previewed copy."
},
"viewerCalendarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The calendars holding `viewer_event_id`, the canonical copy's first."
},
"viewerCopy": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CalendarMentionViewerCopy",
"description": "How the requester holds the meeting through `viewer_event_id`; absent\nexactly when that is."
}
]
},
"viewerEventId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The requester's own event entity for the mentioned meeting. Differs\nfrom the mentioned id when the mention came from another attendee.\nAbsent when the meeting is on none of the requester's calendars and\nthey see it only because it was shared with one of their channels:\nthat preview is read-only and there is no event of theirs to open."
}
}
},
"CalendarMentionPreviewItem": {
"type": "object",
"description": "Resolution of one mentioned event, in request order.",
"required": ["eventId", "type"],
"properties": {
"event": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CalendarMentionEvent",
"description": "Preview of the requester's own copy, or of the channel-shared copy,\npresent only with access."
}
]
},
"eventId": {
"type": "string",
"format": "uuid",
"description": "The mentioned event id, echoed from the request."
},
"type": {
"$ref": "#/components/schemas/CalendarMentionPreviewKind",
"description": "Visibility of the mentioned event to the requester."
}
}
},
"CalendarMentionPreviewKind": {
"type": "string",
"description": "Requester-relative visibility of one mentioned event.",
"enum": ["access", "no_access", "does_not_exist"]
},
"CalendarMentionPreviewRequest": {
"type": "object",
"description": "Batch calendar mention preview request.",
"required": ["items"],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CalendarMentionPreviewRequestItem"
},
"description": "Mentioned events to resolve, at most 100."
}
}
},
"CalendarMentionPreviewRequestItem": {
"type": "object",
"description": "One mentioned event to resolve for the requester.",
"required": ["eventId"],
"properties": {
"eventId": {
"type": "string",
"format": "uuid",
"description": "Mentioned calendar event id."
},
"occurrenceKey": {
"type": ["string", "null"],
"description": "Occurrence the mention points at, when it targets one instance."
}
}
},
"CalendarMentionPreviewResponse": {
"type": "object",
"description": "Batch calendar mention preview response.",
"required": ["items"],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CalendarMentionPreviewItem"
}
}
}
},
"CalendarMentionViewerCopy": {
"type": "string",
"description": "How a requester holds a mentioned meeting on their own calendar, decided\nby the copy's own inbox, the way viewer capabilities decide organizer and\nguest.",
"enum": ["snapshot", "invitation", "event"]
},
"CalendarOccurrence": {
"type": "object",
"description": "A materialized recurrence instance optimized for range queries.",
"required": ["eventId", "occurrenceKey", "time", "isCancelled"],
"properties": {
"eventId": {
"type": "string",
"format": "uuid",
"description": "Owning event entity."
},
"isCancelled": {
"type": "boolean",
"description": "Whether the instance was cancelled."
},
"occurrenceKey": {
"type": "string",
"description": "Stable key within the event."
},
"recurrenceId": {
"type": ["string", "null"],
"description": "Provider recurrence identifier, when applicable."
},
"time": {
"$ref": "#/components/schemas/EventTime",
"description": "Instance time."
}
}
},
"CalendarOccurrenceItem": {
"type": "object",
"description": "One materialized occurrence paired with its stable calendar event entity.",
"required": ["event", "occurrence"],
"properties": {
"event": {
"$ref": "#/components/schemas/CalendarEvent"
},
"occurrence": {
"$ref": "#/components/schemas/CalendarOccurrence"
}
}
},
"CalendarOccurrenceResponse": {
"type": "object",
"description": "Paginated calendar occurrence viewport response.",
"required": ["items", "hasMore", "syncStatus"],
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CalendarOccurrenceItem"
}
},
"nextCursor": {
"type": ["string", "null"]
},
"syncStatus": {
"$ref": "#/components/schemas/CalendarSyncStatus",
"description": "Aggregate ingestion state; clients render a skeleton while `syncing`."
}
}
},
"CalendarSyncStatus": {
"type": "string",
"description": "Aggregate ingestion state across every calendar account visible to a\nrequester, letting clients render progressively while sources build.",
"enum": ["syncing", "ready"]
},
"CallActiveResponse": {
"type": "object",
"description": "Response indicating whether an active call exists for a channel.",
"required": ["callId", "channelId", "createdBy", "createdAt"],
"properties": {
"callId": {
"type": "string",
"format": "uuid",
"description": "The call identifier."
},
"channelId": {
"type": "string",
"format": "uuid",
"description": "The channel this call belongs to."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the call was created."
},
"createdBy": {
"type": "string",
"description": "User who created the call."
}
}
},
"CallDiscussion": {
"oneOf": [
{
"type": "object",
"description": "A thread in the call's channel, rooted at the message with the call's id.",
"required": ["channel_id", "root_id", "kind"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "The channel holding the thread."
},
"kind": {
"type": "string",
"enum": ["channel_thread"]
},
"root_id": {
"type": "string",
"format": "uuid",
"description": "The thread's root message."
}
}
},
{
"type": "object",
"description": "The call's own thread on the call parent.",
"required": ["call_id", "kind"],
"properties": {
"call_id": {
"type": "string",
"format": "uuid",
"description": "The call owning the thread."
},
"kind": {
"type": "string",
"enum": ["call_chat"]
}
}
}
],
"description": "Where a call's discussion lives, decided once when the call is created.\n`channel_id` cannot decide this: past channel calls keep their own thread."
},
"CallEntryStatus": {
"oneOf": [
{
"type": "object",
"description": "The call has not ended.",
"required": ["state"],
"properties": {
"state": {
"type": "string",
"enum": ["live"]
}
}
},
{
"type": "object",
"description": "The call ended.",
"required": ["ended_at", "duration_ms", "state"],
"properties": {
"duration_ms": {
"type": "integer",
"format": "int64",
"description": "How long it lasted."
},
"ended_at": {
"type": "string",
"format": "date-time",
"description": "When it ended."
},
"state": {
"type": "string",
"enum": ["ended"]
}
}
},
{
"type": "object",
"description": "The call's record was deleted; its discussion stays in the channel.",
"required": ["state"],
"properties": {
"state": {
"type": "string",
"enum": ["record_deleted"]
}
}
}
],
"description": "A channel call's life, as its timeline row shows it."
},
"CallFilters": {
"type": "object",
"description": "Filters for call records.",
"properties": {
"attended": {
"type": ["boolean", "null"],
"description": "Legacy filter by whether the requesting user attended the call.\nPrefer [`CallFilters::status`] for new callers.\n`None` = no filter, `Some(true)` = only calls the user joined,\n`Some(false)` = only calls the user did not join."
},
"call_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Call record IDs to filter by. Empty to include all calls."
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel IDs to filter calls by. Empty to include all calls."
},
"speaker_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Speaker macro user ids. Empty to include all."
},
"status": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CallStatus",
"description": "Filter by the requesting user's viewer-relative call status."
}
]
}
}
},
"CallNotificationEvent": {
"oneOf": [
{
"type": "object",
"description": "A call started.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.started"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "A call started."
}
}
},
{
"type": "object",
"description": "A call ended.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.ended"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "A call ended."
}
}
},
{
"type": "object",
"description": "A participant entered the RTC room.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.participant_joined"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "A participant entered the RTC room."
}
}
},
{
"type": "object",
"description": "A participant left the RTC room.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.participant_left"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "A participant left the RTC room."
}
}
},
{
"type": "object",
"description": "A recording became available.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.recording_ready"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "A recording became available."
}
}
},
{
"type": "object",
"description": "A summary became available.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.summarized"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "A summary became available."
}
}
},
{
"type": "object",
"description": "The recipient is being rung.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.ringing"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "The recipient is being rung."
}
}
},
{
"type": "object",
"description": "The recipient answered.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.answered"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "The recipient answered."
}
}
},
{
"type": "object",
"description": "The recipient declined.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.declined"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "The recipient declined."
}
}
},
{
"type": "object",
"description": "The recipient was invited.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["call.invited"]
},
"metadata": {
"$ref": "#/components/schemas/CallNotificationMetadata",
"description": "The recipient was invited."
}
}
}
],
"description": "Public call events. Private variants carry a recipient on the broker only."
},
"CallNotificationMetadata": {
"type": "object",
"description": "Identifiers and actors for a public call notification. Optional fields are\nabsent when they do not apply to the event.",
"required": ["call_id"],
"properties": {
"call_id": {
"type": "string",
"format": "uuid",
"description": "Call identifier."
},
"channel_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Channel containing the call, if any."
},
"created_by": {
"type": ["string", "null"],
"description": "User who created the call."
},
"identity": {
"type": ["string", "null"],
"description": "Room identity of the joining or departing participant."
},
"invited_by": {
"type": ["string", "null"],
"description": "User who sent an invitation."
},
"meeting_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Meeting associated with an invitation."
},
"user_id": {
"type": ["string", "null"],
"description": "Account identifier of the participant or answering user."
}
}
},
"CallProvider": {
"type": "string",
"description": "Supported call and transcript providers. Add variants as integrations grow.",
"enum": ["macro", "granola"]
},
"CallRecord": {
"type": "object",
"description": "Full record of a call, unifying rows from `calls` (active) and\n`call_records` (archived) into a single response shape.",
"required": [
"callId",
"discussion",
"createdBy",
"startedAt",
"shareWithTeam",
"isActive",
"participants",
"guests",
"transcript"
],
"properties": {
"callId": {
"type": "string",
"format": "uuid",
"description": "The call identifier."
},
"channelId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The channel this call belongs to."
},
"channelName": {
"type": ["string", "null"],
"description": "Resolved display name for the channel."
},
"createdBy": {
"type": "string",
"description": "User who created the call."
},
"customName": {
"type": ["string", "null"],
"description": "User-supplied or AI-generated display name for the call. Only set on\narchived `call_records`; active calls always return `None`."
},
"discussion": {
"$ref": "#/components/schemas/CallDiscussion",
"description": "Where this call's discussion lives."
},
"durationMs": {
"type": ["integer", "null"],
"format": "int64",
"description": "Call duration in milliseconds (None if still active)."
},
"egressId": {
"type": ["string", "null"],
"description": "Recording egress ID, if any."
},
"endedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the call ended (None if still active)."
},
"guests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallRecordGuest"
},
"description": "Non-account guests (both active and historic). Guests only ever exist\non standalone meeting calls, never on channel calls."
},
"isActive": {
"type": "boolean",
"description": "Whether the call is currently active (from `calls` table)."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallRecordParticipant"
},
"description": "Macro-account participants (both active and historic)."
},
"recordingPreviewUrl": {
"type": ["string", "null"],
"description": "Presigned URL for the call recording preview image, if available."
},
"recordingStartedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the egress recording actually began. `None` until the\n`egress_started` webhook arrives (typically a few seconds after\n`started_at`). Frontend should anchor transcript-to-audio sync to\nthis value when present, falling back to `started_at` otherwise."
},
"recordingUrl": {
"type": ["string", "null"],
"description": "Presigned URL for the call recording, if available."
},
"roomName": {
"type": ["string", "null"],
"description": "The RTC room name. `None` for imported calls, which never had a room."
},
"shareWithTeam": {
"type": "boolean",
"description": "Whether the call is shared with the creator's team. While the call is\nlive this is the pending toggle applied at archive; afterwards it\nmirrors `team_share_access_level`."
},
"source": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CallRecordSource",
"description": "External provenance for calls imported from another provider; `None`\nfor calls recorded in Macro."
}
]
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When the call started (created_at for active, started_at for archived)."
},
"status": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CallStatus",
"description": "Viewer-relative call status when fetched in the context of a specific user."
}
]
},
"summary": {
"type": ["string", "null"],
"description": "AI-generated summary of the call. Only set on archived `call_records`\nonce summarization has run; active calls always return `None`."
},
"teamShareAccessLevel": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AccessLevel",
"description": "The canonical access level granted to the creator's team, or `None`\nwhen the call is not shared with the team. Calls only ever grant\n`View`, and only once archived: while the call is live this is `None`\nand `share_with_team` carries the pending toggle."
}
]
},
"transcript": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallRecordTranscriptSegment"
},
"description": "Transcript segments ordered by `sequence_num`."
},
"userAccessLevel": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AccessLevel",
"description": "The caller's effective access level on this call. Set only on the\nsingle-record read; `None` in list contexts."
}
]
},
"viewerHasDeclined": {
"type": "boolean",
"description": "Whether the authenticated viewer has declined this call on any device.\nSet on the single-record read so clients that missed `call_declined`\ncan still stop ringing via reconciliation; `false` in list contexts."
}
}
},
"CallRecordGuest": {
"type": "object",
"description": "A non-account guest as returned in a [`CallRecord`].",
"required": ["id", "displayName", "joinedAt"],
"properties": {
"displayName": {
"type": "string",
"description": "Guest-provided display name."
},
"id": {
"$ref": "#/components/schemas/GuestId",
"description": "Opaque guest identity; matches the guest's transcript `speaker_id`."
},
"joinedAt": {
"type": "string",
"format": "date-time",
"description": "When the guest joined the call."
},
"leftAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the guest left (None if still in an active call)."
}
}
},
"CallRecordParticipant": {
"type": "object",
"description": "A participant as returned in a [`CallRecord`] (historic — includes `left_at`).",
"required": ["userId", "joinedAt"],
"properties": {
"joinedAt": {
"type": "string",
"format": "date-time",
"description": "When the user joined the call."
},
"leftAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the user left (None if still in an active call)."
},
"userId": {
"type": "string",
"description": "The Macro user id."
}
}
},
"CallRecordPreview": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/CallRecordPreviewData",
"description": "The call exists (in either the active or archived table)."
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["exists"]
}
}
}
],
"description": "The call exists (in either the active or archived table)."
},
{
"allOf": [
{
"$ref": "#/components/schemas/WithCallId",
"description": "No call with this id exists in either the active or archived tables."
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["does_not_exist"]
}
}
}
],
"description": "No call with this id exists in either the active or archived tables."
}
],
"description": "Lightweight preview of a call record, returned by the batch preview endpoint.\n\nEach requested id resolves to one of two outcomes: the call exists\n(`Exists`) or it does not (`DoesNotExist`). The endpoint does not perform\naccess checks, so there is no separate \"not authorized\" variant."
},
"CallRecordPreviewData": {
"type": "object",
"description": "Preview payload returned for each found call id.",
"required": ["callId", "startedAt"],
"properties": {
"callId": {
"type": "string",
"format": "uuid",
"description": "The call identifier."
},
"channelId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The channel this call belongs to."
},
"channelName": {
"type": ["string", "null"],
"description": "Resolved display name for the channel."
},
"customName": {
"type": ["string", "null"],
"description": "User-supplied or AI-generated display name for the call. Only set on\narchived `call_records`; active calls always return `None`."
},
"endedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the call ended (None if still active)."
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When the call started (created_at for active, started_at for archived)."
}
}
},
"CallRecordSource": {
"type": "object",
"description": "Where an imported call came from.",
"required": ["provider"],
"properties": {
"externalUrl": {
"type": ["string", "null"],
"description": "Link to the call in the provider's app, if it has one."
},
"provider": {
"$ref": "#/components/schemas/CallProvider",
"description": "Provider that supplied the call."
}
}
},
"CallRecordTranscriptSegment": {
"type": "object",
"description": "A transcript segment as returned in a [`CallRecord`].",
"required": [
"transcriptId",
"speakerId",
"content",
"startedAt",
"sequenceNum"
],
"properties": {
"content": {
"type": "string",
"description": "The transcribed text content."
},
"diarizedSpeakerId": {
"type": ["string", "null"],
"description": "Stable per-speaker identifier produced by the STT provider's diarization\npass. Unique across tracks in the call. `None` when the provider didn't\nreturn a speaker label."
},
"endedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the speaker stopped (if known)."
},
"segmentId": {
"type": ["string", "null"],
"description": "LiveKit segment ID (nullable for archived records)."
},
"sequenceNum": {
"type": "integer",
"format": "int32",
"description": "Ordering within the call."
},
"speakerId": {
"type": "string",
"description": "The speaker's user ID."
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When the speaker started this segment."
},
"transcriptId": {
"type": "string",
"format": "uuid",
"description": "Stable DB-row id for the segment."
}
}
},
"CallStatus": {
"type": "string",
"description": "Viewer-relative attendance status for a call record.\nSerializes as `ATTENDED`, `MISSED`, or `UNATTENDED`.",
"enum": ["ATTENDED", "MISSED", "UNATTENDED"]
},
"CallTokenResponse": {
"type": "object",
"description": "Response returned when creating or joining a call.",
"required": [
"started",
"participantId",
"callId",
"token",
"roomName",
"serverUrl"
],
"properties": {
"callId": {
"type": "string",
"format": "uuid",
"description": "The call identifier."
},
"channelId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The channel this call is associated with."
},
"participantId": {
"type": "string",
"description": "RTC participant identity."
},
"roomName": {
"type": "string",
"description": "The RTC room name."
},
"serverUrl": {
"type": "string",
"description": "The RTC server URL for the frontend SDK to connect to."
},
"shareToken": {
"type": ["string", "null"],
"description": "Meeting link capability, when joined using a link."
},
"started": {
"type": "boolean",
"description": "Whether this request allocated the call."
},
"token": {
"type": "string",
"description": "The RTC token for connecting to the room."
}
}
},
"CardPosition": {
"type": "object",
"description": "Where one card sits on a board: its lane, and its fractional key there.\nA card whose row has since moved to another lane has no place until it is\nmoved again.",
"required": ["row", "lane", "position"],
"properties": {
"lane": {
"$ref": "#/components/schemas/LaneKey",
"description": "The lane."
},
"position": {
"type": "string",
"description": "The card's key in that lane."
},
"row": {
"type": "string",
"format": "uuid",
"description": "The card's row."
}
}
},
"CastVerdict": {
"type": "string",
"description": "Whether a column's values convert to a type.",
"enum": ["safe", "checked", "never"]
},
"CellBorders": {
"type": "object",
"description": "Borders to change in [`EditOp::FormatCells`](super::EditOp::FormatCells).",
"required": ["edges", "line"],
"properties": {
"edges": {
"$ref": "#/components/schemas/BorderEdges",
"description": "Which borders."
},
"line": {
"$ref": "#/components/schemas/BorderLine",
"description": "The change applied to each of them."
}
},
"additionalProperties": false
},
"CellRef": {
"type": "object",
"description": "A table cell inside a graphic frame (0-based).",
"required": ["row", "col"],
"properties": {
"col": {
"type": "integer",
"description": "Column index.",
"minimum": 0
},
"row": {
"type": "integer",
"description": "Row index.",
"minimum": 0
}
},
"additionalProperties": false
},
"CellValue": {
"oneOf": [
{
"type": "object",
"description": "Free text.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["text"]
},
"value": {
"type": "string",
"description": "Free text."
}
}
},
{
"type": "object",
"description": "A finite number.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["number"]
},
"value": {
"type": "number",
"format": "double",
"description": "A finite number."
}
}
},
{
"type": "object",
"description": "A checkbox.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["boolean"]
},
"value": {
"type": "boolean",
"description": "A checkbox."
}
}
},
{
"type": "object",
"description": "A date-time.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["date"]
},
"value": {
"type": "string",
"format": "date-time",
"description": "A date-time."
}
}
},
{
"type": "object",
"description": "A span of time; its end may not come before its start.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["date_range"]
},
"value": {
"$ref": "#/components/schemas/DateRange",
"description": "A span of time; its end may not come before its start."
}
}
},
{
"type": "object",
"description": "Complete http or https URLs; at most one for a single-valued column.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["link"]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "Complete http or https URLs; at most one for a single-valued column."
}
}
},
{
"type": "object",
"description": "Options of a select or tag column; at most one for a single-valued\ncolumn.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["options"]
},
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OptionRef"
},
"description": "Options of a select or tag column; at most one for a single-valued\ncolumn."
}
}
},
{
"type": "object",
"description": "References to Macro entities of the kind the column points at; at\nmost one for a single-valued column.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["entities"]
},
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRef"
},
"description": "References to Macro entities of the kind the column points at; at\nmost one for a single-valued column."
}
}
},
{
"type": "object",
"description": "Rows of the table a relation column points at.",
"required": ["value", "type"],
"properties": {
"type": {
"type": "string",
"enum": ["rows"]
},
"value": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Rows of the table a relation column points at."
}
}
},
{
"type": "object",
"description": "No value: the cell is emptied.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["clear"]
}
}
}
],
"description": "A cell's value. It must fit the column's type: text for a text column,\noptions of the column for a select, and so on."
},
"CellWrite": {
"type": "object",
"description": "One cell of a row: which column, and its new value.",
"required": ["column", "value"],
"properties": {
"column": {
"type": "string",
"format": "uuid",
"description": "The column placement."
},
"value": {
"$ref": "#/components/schemas/CellValue",
"description": "The value, or [`CellValue::Clear`] to empty the cell."
}
}
},
"ChangedFileDto": {
"type": "object",
"description": "One changed file.\n\nClients deserialize this, so both derives are used.",
"required": [
"path",
"kind",
"additions",
"deletions",
"binary",
"patchOmitted"
],
"properties": {
"additions": {
"type": "integer",
"format": "int32",
"description": "Lines added.",
"minimum": 0
},
"binary": {
"type": "boolean",
"description": "The diff carries no text for this file."
},
"deletions": {
"type": "integer",
"format": "int32",
"description": "Lines removed.",
"minimum": 0
},
"kind": {
"$ref": "#/components/schemas/FileChangeKindDto",
"description": "What happened to the file."
},
"patchOmitted": {
"type": "boolean",
"description": "The file's hunks were left out of the patch to fit the size budget."
},
"path": {
"type": "string",
"description": "The file's path after the change, or before it for a deletion."
},
"previousPath": {
"type": ["string", "null"],
"description": "Where a renamed file came from."
}
}
},
"ChangesetDto": {
"type": "object",
"description": "One changeset: the files a patch touches and what happened to each.\n\nClients deserialize this, so both derives are used.",
"required": [
"id",
"source",
"base",
"head",
"files",
"additions",
"deletions",
"patchBytes",
"truncated",
"capturedAt"
],
"properties": {
"additions": {
"type": "integer",
"format": "int32",
"description": "Lines added across all files.",
"minimum": 0
},
"base": {
"$ref": "#/components/schemas/GitRefDto",
"description": "The side the work started from."
},
"capturedAt": {
"type": "string",
"format": "date-time",
"description": "When the diff was taken."
},
"deletions": {
"type": "integer",
"format": "int32",
"description": "Lines removed across all files.",
"minimum": 0
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChangedFileDto"
},
"description": "Every changed file, in patch order."
},
"head": {
"$ref": "#/components/schemas/GitRefDto",
"description": "The side carrying the work."
},
"id": {
"type": "string",
"format": "uuid",
"description": "The changeset's id; a different id means different changes."
},
"patchBytes": {
"type": "integer",
"format": "int64",
"description": "Size of the patch the matching patch route serves; zero when nothing\nchanged.",
"minimum": 0
},
"repository": {
"type": ["string", "null"],
"description": "`https://github.com/owner/name`, when known."
},
"source": {
"$ref": "#/components/schemas/ChangesetSourceDto",
"description": "Where the diff was read from."
},
"truncated": {
"type": "boolean",
"description": "Some files' hunks were left out of the patch."
}
}
},
"ChangesetSourceDto": {
"type": "string",
"description": "The source of a changeset's diff, on the wire.",
"enum": ["github_pull_request"]
},
"Channel": {
"type": "object",
"description": "Channel metadata in soup payloads.",
"required": [
"id",
"channel_type",
"created_at",
"updated_at",
"owner_id"
],
"properties": {
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Channel type."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Channel id."
},
"name": {
"type": ["string", "null"],
"description": "Channel display name."
},
"org_id": {
"type": ["integer", "null"],
"format": "int32",
"description": "Organization id.",
"minimum": 0
},
"owner_id": {
"type": "string",
"description": "Channel owner."
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team id."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Update timestamp."
}
}
},
"ChannelAccessDecision": {
"type": "string",
"description": "A participant's answer to a pending request.",
"enum": ["approve", "deny"]
},
"ChannelAccessRequest": {
"type": "object",
"description": "One attempt to join a channel. Attempts are never reused, so each timeline\nentry keeps showing the outcome of the attempt it announced.",
"required": [
"id",
"channel_id",
"requester_id",
"status",
"created_at"
],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel the requester asked to join."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the requester asked."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Attempt id."
},
"requester_id": {
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "Person asking to join."
},
"resolved_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "When the attempt stopped being pending."
},
"resolved_by": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "Participant who approved or denied it."
}
]
},
"status": {
"$ref": "#/components/schemas/ChannelAccessRequestStatus",
"description": "Current outcome."
}
}
},
"ChannelAccessRequestState": {
"type": "object",
"description": "A requester's view of their access to a channel they cannot read.",
"required": ["can_request"],
"properties": {
"can_request": {
"type": "boolean",
"description": "Whether this channel accepts requests."
},
"request": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ChannelAccessRequest",
"description": "The caller's latest attempt, if any."
}
]
},
"retry_after": {
"type": ["string", "null"],
"format": "date-time",
"description": "Earliest time the caller may ask again, while they must wait."
}
}
},
"ChannelAccessRequestStatus": {
"type": "string",
"description": "Outcome of one attempt to join.",
"enum": ["pending", "approved", "denied", "cancelled"]
},
"ChannelAccessRequestedMetadata": {
"type": "object",
"description": "Metadata for [`ChannelTopicEvent::AccessRequested`].",
"required": ["channel_id", "request_id", "requester_id"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel the requester asked to join."
},
"request_id": {
"type": "string",
"format": "uuid",
"description": "The attempt; channel participants read its current outcome by id."
},
"requester_id": {
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "Person asking to join."
}
}
},
"ChannelCreatedMetadata": {
"type": "object",
"description": "Metadata for [`ChannelTopicEvent::Created`].",
"required": [
"channel_id",
"actor",
"channel_type",
"participant_user_ids"
],
"properties": {
"actor": {
"$ref": "#/components/schemas/ChannelSender",
"description": "Actor that created the channel (channel owner)."
},
"channel_id": {
"type": "string",
"format": "uuid",
"description": "The id of the created channel."
},
"channel_name": {
"type": ["string", "null"],
"description": "Stored channel name; `None` for direct message / unnamed channels."
},
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Type of channel that was created."
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "User the actor created the channel for, when the actor is a bot."
}
]
},
"participant_user_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MacroUserIdStr"
},
"description": "Active participants after creation (including the owner)."
}
}
},
"ChannelDeletedMetadata": {
"type": "object",
"description": "Metadata for [`ChannelTopicEvent::Deleted`].",
"required": ["channel_id", "actor"],
"properties": {
"actor": {
"$ref": "#/components/schemas/ChannelSender",
"description": "Actor that deleted the channel."
},
"channel_id": {
"type": "string",
"format": "uuid",
"description": "The id of the deleted channel."
}
}
},
"ChannelFilters": {
"type": "object",
"description": "The channel message filters used to filter down what channel messages you search over.",
"properties": {
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel IDs to search within. Examples: ['general']. Empty to search all accessible channels."
},
"channel_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel types to filter by. Examples: ['public'], ['direct_message', 'private']. Empty to search all channel types."
},
"importance": {
"type": ["boolean", "null"],
"description": "Filter by channel importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing."
},
"is_participant": {
"type": ["boolean", "null"],
"description": "Filter by whether the requesting user is an active participant of the channel.\nPresence of this filter also widens the candidate set to team channels of the\nuser's teams that they have not joined, so `false` matches those channels.\nNone to ignore (participant channels only, today's default)."
},
"mentions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel user mentions to search for. Examples: ['@username']. Empty if not filtering by mentions."
},
"notification_filters": {
"$ref": "#/components/schemas/NotificationFilters",
"description": "Filter by channel notification state."
},
"org_id": {
"type": ["integer", "null"],
"format": "int64",
"description": "Channel organization ID to search within. Empty to ignore organization filtering."
},
"sender_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sender IDs to search within. Examples: ['user1']. Empty to search all accessible senders."
},
"team_id": {
"type": ["string", "null"],
"description": "Channel team ID to search within. Empty to ignore team filtering."
},
"thread_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel thread IDs to search within. Examples: ['thread123']. Empty to search all threads."
}
}
},
"ChannelJoinCodeResponse": {
"type": "object",
"description": "Response containing a channel's reusable join code.",
"required": ["join_code"],
"properties": {
"join_code": {
"type": "string",
"format": "uuid",
"description": "Reusable code for joining the channel."
}
}
},
"ChannelLabel": {
"type": "object",
"description": "A shared or account-private label grouping chat channels in the sidebar.\n\n`channel_ids` is viewer-relative: it lists only the labelled channels the\nrequesting user participates in. `channel_count` counts every channel in\nthe label so clients can warn accurately before a delete.",
"required": [
"id",
"name",
"sortOrder",
"channelIds",
"channelCount",
"createdAt",
"updatedAt"
],
"properties": {
"channelCount": {
"type": "integer",
"format": "int64",
"description": "All assignments for a manual label; visible matches for a smart tag."
},
"channelIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Channels in this label that the requesting user participates in."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the label was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Stable label id."
},
"name": {
"type": "string",
"description": "Display name, unique within the scope (case-insensitive)."
},
"rule": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ChannelLabelRule",
"description": "Automatic membership rule, or `None` for a manually managed label."
}
]
},
"sortOrder": {
"type": "number",
"format": "double",
"description": "Manual ordering value within the scope; lower sorts first."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Owning team, or `None` for account-private labels."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "When the label's name, rule, scope, or order last changed."
}
}
},
"ChannelLabelRule": {
"oneOf": [
{
"type": "object",
"description": "Case-insensitive, literal substring matching on the channel name.",
"required": ["contains", "attribute"],
"properties": {
"attribute": {
"type": "string",
"enum": ["name"]
},
"contains": {
"type": "string",
"description": "The substring to find anywhere in the name."
}
}
}
],
"description": "An attribute rule that automatically groups matching channels."
},
"ChannelLabelScopeSelection": {
"type": "string",
"description": "Requested label namespace. Omission retains the deployed automatic selection.",
"enum": ["personal", "team"]
},
"ChannelLabelsList": {
"type": "object",
"description": "The authorized scope's labels in manual order.",
"required": ["scope", "labels"],
"properties": {
"labels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelLabel"
},
"description": "Every label of the scope, whether or not the caller sees channels in it."
},
"scope": {
"$ref": "#/components/schemas/ChannelLabelScopeSelection",
"description": "Resolved label namespace."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team scope, or `None` for private labels."
}
}
},
"ChannelMessage": {
"type": "object",
"description": "Lightweight channel message for soup payloads.",
"required": [
"message_id",
"sender_id",
"content",
"created_at",
"updated_at",
"mentions"
],
"properties": {
"content": {
"type": "string",
"description": "Message content."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"deleted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Deletion timestamp."
},
"mentions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Message mentions formatted as `{ENTITY_TYPE}:{ENTITY_ID}`."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Message id."
},
"sender_id": {
"type": "string",
"description": "Sender id."
},
"thread_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Thread parent id."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Update timestamp."
}
}
},
"ChannelParticipant": {
"type": "object",
"description": "A user's membership in a channel.",
"required": ["channel_id", "user_id", "role", "joined_at"],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel id for the participant membership."
},
"joined_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the participant joined the channel."
},
"left_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Timestamp when the participant left the channel, if any."
},
"role": {
"$ref": "#/components/schemas/ParticipantRole",
"description": "Participant role in the channel."
},
"user_id": {
"type": "string",
"description": "Participant user id."
}
}
},
"ChannelParticipantAddedMetadata": {
"type": "object",
"description": "Metadata for [`ChannelTopicEvent::ParticipantAdded`].",
"required": [
"channel_id",
"channel_type",
"added_by",
"added_user_ids"
],
"properties": {
"added_by": {
"$ref": "#/components/schemas/ChannelSender",
"description": "Actor who added the participants; equals the sole added user for a\nself-service join."
},
"added_user_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MacroUserIdStr"
},
"description": "Users added by this mutation."
},
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel receiving new participants."
},
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Type of channel that received participants."
}
}
},
"ChannelParticipantRemovedMetadata": {
"type": "object",
"description": "Metadata for [`ChannelTopicEvent::ParticipantRemoved`].",
"required": [
"channel_id",
"channel_type",
"removed_by",
"removed_user_ids"
],
"properties": {
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel the participants were removed from."
},
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Type of channel the participants were removed from."
},
"removed_by": {
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "Actor who removed the participants; equals the sole removed user for a\nself-service leave."
},
"removed_user_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MacroUserIdStr"
},
"description": "Users removed by this mutation."
}
}
},
"ChannelPictureChangedMetadata": {
"type": "object",
"description": "Metadata for a channel picture update, including removals.",
"required": ["channel_id", "actor"],
"properties": {
"actor": {
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "User who changed the picture."
},
"channel_id": {
"type": "string",
"format": "uuid",
"description": "Channel whose picture changed."
}
}
},
"ChannelPreview": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/ChannelPreviewData",
"description": "Viewer can access the channel."
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["access"]
}
}
}
],
"description": "Viewer can access the channel."
},
{
"allOf": [
{
"$ref": "#/components/schemas/WithChannelId",
"description": "Viewer cannot access the channel."
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["no_access"]
}
}
}
],
"description": "Viewer cannot access the channel."
},
{
"allOf": [
{
"$ref": "#/components/schemas/WithChannelId",
"description": "Channel does not exist."
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["does_not_exist"]
}
}
}
],
"description": "Channel does not exist."
}
],
"description": "Preview entry for a single channel id."
},
"ChannelPreviewData": {
"type": "object",
"description": "Preview payload returned for accessible channels.",
"required": ["channel_id", "channel_name", "channel_type"],
"properties": {
"channel_id": {
"type": "string",
"description": "Channel id."
},
"channel_name": {
"type": "string",
"description": "Resolved channel display name."
},
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Channel type."
},
"profile_picture_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Static image file used as the channel's profile picture, when accessible."
}
}
},
"ChannelSender": {
"type": "string"
},
"ChannelSharePermission": {
"type": "object",
"description": "The channel share permission",
"required": ["channel_id", "access_level"],
"properties": {
"access_level": {
"$ref": "#/components/schemas/AccessLevel",
"description": "The access level for the channel"
},
"channel_id": {
"type": "string",
"description": "The channel id"
}
}
},
"ChannelThreadFilters": {
"type": "object",
"description": "The channel thread filters used to filter down channel-thread entities.",
"properties": {
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel IDs containing the thread. Empty to include threads from all accessible channels."
},
"participant_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Thread participant user IDs. A participant is the root message sender, anyone\nwho replied in the thread, or anyone @-mentioned in the thread (group mentions\nlike @here count through their per-user expansion at send time). Empty to\ninclude threads regardless of participants."
},
"root_sender_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sender IDs for the root thread message. Empty to include all root senders."
},
"thread_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel thread parent message IDs to include. Empty to include all accessible threads."
}
}
},
"ChannelTopicEvent": {
"oneOf": [
{
"type": "object",
"description": "A channel's profile picture changed.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.picture_changed"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelPictureChangedMetadata",
"description": "A channel's profile picture changed."
}
}
},
{
"type": "object",
"description": "A channel was created.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.created"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelCreatedMetadata",
"description": "A channel was created."
}
}
},
{
"type": "object",
"description": "A channel's metadata was updated (rename).",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.updated"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelUpdatedMetadata",
"description": "A channel's metadata was updated (rename)."
}
}
},
{
"type": "object",
"description": "A channel was deleted.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.deleted"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelDeletedMetadata",
"description": "A channel was deleted."
}
}
},
{
"type": "object",
"description": "Participants were added to a channel (admin invite or self-join).",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.participant_added"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelParticipantAddedMetadata",
"description": "Participants were added to a channel (admin invite or self-join)."
}
}
},
{
"type": "object",
"description": "Participants were removed from a channel (admin removal or self-leave).",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.participant_removed"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelParticipantRemovedMetadata",
"description": "Participants were removed from a channel (admin removal or self-leave)."
}
}
},
{
"type": "object",
"description": "Someone outside a channel asked to join it.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["channel.access_requested"]
},
"metadata": {
"$ref": "#/components/schemas/ChannelAccessRequestedMetadata",
"description": "Someone outside a channel asked to join it."
}
}
}
],
"description": "Events that can be published to [`MacroChannelsTopic`]."
},
"ChannelType": {
"type": "string",
"description": "Type of channel.",
"enum": ["public", "private", "direct_message", "team"]
},
"ChannelUpdatedMetadata": {
"type": "object",
"description": "Metadata for [`ChannelTopicEvent::Updated`].",
"required": ["channel_id", "actor"],
"properties": {
"actor": {
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The user who updated the channel."
},
"channel_id": {
"type": "string",
"format": "uuid",
"description": "The id of the updated channel."
},
"channel_name": {
"type": ["string", "null"],
"description": "New channel name."
},
"previous_name": {
"type": ["string", "null"],
"description": "Stored channel name before the update."
}
}
},
"ChannelWebhookRequest": {
"type": "object",
"description": "Request to post a channel webhook message.",
"required": ["content"],
"properties": {
"content": {
"type": "string",
"description": "Message body."
}
}
},
"ChannelWebhookResponse": {
"type": "object",
"description": "Response returned after posting a channel webhook message.",
"required": ["message_id"],
"properties": {
"message_id": {
"type": "string",
"description": "Created message id."
}
}
},
"ChannelWithParticipants": {
"type": "object",
"description": "Channel metadata together with its participants.",
"required": ["channel", "participants"],
"properties": {
"channel": {
"$ref": "#/components/schemas/Channel",
"description": "Channel metadata."
},
"is_participant": {
"type": "boolean",
"description": "Whether the requesting user is an active participant of the channel.\nFalse for team channels of the user's teams they have not joined."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelParticipant"
},
"description": "Participants in the channel."
}
}
},
"ChartSeriesColor": {
"type": "object",
"description": "A series color for [`EditOp::FormatChart`](super::EditOp::FormatChart).",
"required": ["series", "color"],
"properties": {
"color": {
"type": "string",
"description": "`RRGGBB`, or a theme color name (`accent1`, `tx1`...)."
},
"series": {
"type": "integer",
"format": "int32",
"description": "Series index in plot order (0-based).",
"minimum": 0
}
},
"additionalProperties": false
},
"ChartSeriesData": {
"type": "object",
"description": "One series of chart data.",
"required": ["name", "values"],
"properties": {
"name": {
"type": "string",
"description": "Series name (legend text)."
},
"values": {
"type": "array",
"items": {
"type": ["number", "null"],
"format": "double"
},
"description": "One value per category (`null` for a blank)."
}
},
"additionalProperties": false
},
"Chat": {
"type": "object",
"required": ["id", "name", "userId", "isPersistent"],
"properties": {
"createdAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the chat was created"
},
"deletedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the chat was deleted"
},
"id": {
"type": "string",
"description": "The chat uuid"
},
"isPersistent": {
"type": "boolean"
},
"model": {
"type": ["string", "null"],
"description": "The model used to generate the chat"
},
"name": {
"type": "string",
"description": "The name of the chat"
},
"projectId": {
"type": ["string", "null"],
"description": "The project id of the chat"
},
"tokenCount": {
"type": ["integer", "null"],
"format": "int64"
},
"updatedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the chat was last updated"
},
"userId": {
"type": "string",
"description": "Who the chat belongs to"
}
}
},
"ChatFilters": {
"type": "object",
"description": "The chat filters used to filter down what chats you search over.",
"properties": {
"chat_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Chat ids to search over. Examples: ['chat1'], ['chat1', 'chat2']. When provided, chat search will only match results on these chats. Empty to search all accessible chats."
},
"importance": {
"type": ["boolean", "null"],
"description": "Filter by chat importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing."
},
"notification_filters": {
"$ref": "#/components/schemas/NotificationFilters",
"description": "Filter by chat notification state."
},
"owners": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by chat owner principal — a user ('macro|[email protected]'), a bot\n('bot|<uuid>'), or a team (a bare hyphenated uuid). Examples:\n['macro|[email protected]'], ['macro|[email protected]', 'bot|0199...']. Empty to\nsearch all owners."
},
"project_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of project ids to search within. Examples: ['project1']. Empty to ignore project filtering."
},
"role": {
"type": "array",
"items": {
"type": "string"
},
"description": "Chat message roles to search. Examples: ['user'], ['assistant']. Empty to search all roles."
}
}
},
"ClaimPairingRequest": {
"type": "object",
"description": "Request to claim an approved pairing's credential.\n\nThe daemon serializes this, so both derives are used.",
"required": ["device_secret"],
"properties": {
"device_secret": {
"type": "string",
"description": "The claim credential returned when the pairing was created."
}
}
},
"ClaimedAccountManagerToken": {
"type": "object",
"description": "The credential, returned only by the claim that issued it.",
"required": ["grant", "token"],
"properties": {
"grant": {
"$ref": "#/components/schemas/AccountManagerGrant",
"description": "The grant, now active."
},
"token": {
"type": "string",
"description": "The secret. Shown only once."
}
}
},
"ClaimedPairing": {
"type": "object",
"description": "The credential released to the daemon when a pairing is claimed.",
"required": ["harness", "token"],
"properties": {
"harness": {
"$ref": "#/components/schemas/Harness",
"description": "The registered harness."
},
"token": {
"type": "string",
"description": "The raw harness bearer token. Shown only here; only its hash is stored."
}
}
},
"CloudStorageItemType": {
"type": "string",
"enum": ["document", "chat", "project"]
},
"CollabSurfaceResponse": {
"type": "object",
"description": "A collab surface, as returned by the API.",
"required": ["id", "parentEntityType", "parentEntityId", "state"],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The surface id — also the sync-service session key."
},
"parentEntityId": {
"type": "string",
"description": "Id of the parent entity."
},
"parentEntityType": {
"oneOf": [
{
"type": "string",
"description": "The type of an entity in Macro",
"enum": [
"user",
"chat",
"channel",
"channel_message",
"document",
"project",
"email_thread",
"calendar_event",
"team",
"call",
"foreign_entity",
"static_file",
"crm_company",
"crm_contact",
"crm_pipeline",
"reminder",
"skill",
"agent_session",
"scheduled_action",
"initiative",
"database",
"database_row",
"form",
"external_chat"
]
}
],
"description": "Type of the parent entity."
},
"state": {
"$ref": "#/components/schemas/SurfaceState",
"description": "Lifecycle state (`ready` for every surface visible via the API)."
}
}
},
"CollabSurfaceTokenResponse": {
"type": "object",
"description": "Response carrying a freshly minted sync-service connection token.",
"required": ["token"],
"properties": {
"token": {
"type": "string",
"description": "The signed JWT to pass to the sync-service websocket connect."
}
}
},
"Column": {
"type": "object",
"description": "A column: the placement of a property definition on a table.\n\nThe definition carries name, [`DataType`], multi-select flag, and options;\nthis carries only where it appears and column-kind configuration.",
"required": [
"id",
"table_id",
"property_definition_id",
"position",
"config",
"display_name",
"infer_type"
],
"properties": {
"config": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ColumnConfig",
"description": "Column-kind specific configuration."
}
]
},
"display_name": {
"type": ["string", "null"],
"description": "The placement's own label, which also names it in SQL; `None` shows\nthe definition's name."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Identifier of the placement."
},
"infer_type": {
"type": "boolean",
"description": "Whether the first nonempty value may settle this new text column's type."
},
"nullable": {
"type": "boolean",
"description": "Whether a row may omit this cell; empty collections also count as absent."
},
"position": {
"type": "string",
"description": "Fractional index for column ordering."
},
"property_definition_id": {
"type": "string",
"format": "uuid",
"description": "The bound property definition."
},
"protections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnProtection"
},
"description": "Schema operations reserved by a feature; ordinary edits cannot clear them."
},
"table_id": {
"type": "string",
"format": "uuid",
"description": "Table the column appears on."
}
}
},
"ColumnCast": {
"type": "object",
"description": "What changing a column to one type would do to its values: the dry run\nof a type change, for one target.",
"required": [
"data_type",
"is_multi_select",
"specific_entity_type",
"relation",
"cast",
"reason",
"failures",
"summary",
"examples"
],
"properties": {
"cast": {
"$ref": "#/components/schemas/CastVerdict",
"description": "Whether the values convert."
},
"data_type": {
"$ref": "#/components/schemas/DataType",
"description": "The target property type."
},
"examples": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to three of the values that would not convert."
},
"failures": {
"type": "integer",
"description": "For a `checked` cast, how many cells would not convert.",
"minimum": 0
},
"is_multi_select": {
"type": "boolean",
"description": "Whether the target holds several values."
},
"reason": {
"type": ["string", "null"],
"description": "Why nothing converts, for a `never` cast."
},
"relation": {
"type": "boolean",
"description": "Whether the target is a relation to another table's rows."
},
"specific_entity_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/EntityType",
"description": "The target's entity kind, for a reference column."
}
]
},
"summary": {
"type": ["string", "null"],
"description": "For a `checked` cast with failures, what is wrong with them, as in\n`3 values aren't numbers`."
}
}
},
"ColumnChange": {
"oneOf": [
{
"type": "object",
"description": "Add the column to the table: a new property the database owns, or an\nexisting one bound into the table.",
"required": ["definition", "kind"],
"properties": {
"after": {
"type": "string",
"format": "uuid",
"description": "The column it goes right after; left out, it goes after the\ntable's last column."
},
"definition": {
"$ref": "#/components/schemas/NewColumn",
"description": "What the column holds."
},
"kind": {
"type": "string",
"enum": ["create"]
}
}
},
{
"type": "object",
"description": "Rename the column. Its id, type and cells stay; SQL names it by its\nnew name.",
"required": ["name", "kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["rename"]
},
"name": {
"type": "string",
"description": "Its new name, unique within the table ignoring case."
},
"previousName": {
"type": "string",
"description": "The name the caller saw. Given, the rename is refused if the\ncolumn goes by another one now."
}
}
},
{
"type": "object",
"description": "Convert the column to another type, converting its cells; its id\nsurvives the change. A value that does not fit refuses the change,\ncounting and quoting the misfits: a type change never empties a\ncell. To keep the original, create a column of the new type and\nwrite it the values that convert.",
"required": ["to", "kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["change_type"]
},
"to": {
"$ref": "#/components/schemas/ColumnKind",
"description": "The type it becomes."
}
}
},
{
"type": "object",
"description": "Remove the column and its cells. The views naming it forget it; a\nboard grouped by it must go or regroup first. A property shared\nbeyond the database stays, unbound here.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["delete"]
}
}
},
{
"type": "object",
"description": "Add options to a select or tag column, after its others. An option\nwhose label the column already has, ignoring case, is left out, so\nre-sending a list adds only what is new. Like\n[`ColumnChange::UpdateOption`], an option of a property shared beyond\nthe database goes everywhere it is used.",
"required": ["options", "kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["add_options"]
},
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NewOption"
},
"description": "The options, each under an id the client mints."
}
}
},
{
"type": "object",
"description": "Relabel or recolour one option of a select or tag column. Every cell\nholding it keeps it. A column bound to a property shared outside the\ndatabase changes wherever that property is used, so it takes the\nright to edit that property.",
"required": ["option", "kind"],
"properties": {
"color": {
"type": ["string", "null"],
"description": "Its new colour, a hex string like `#RRGGBB`, or `null` to clear\nit; left out, it keeps its own. A tag option always has one."
},
"kind": {
"type": "string",
"enum": ["update_option"]
},
"label": {
"type": "string",
"description": "Its new label; left out, it keeps its own. Labels are unique\nwithin a column, ignoring case."
},
"option": {
"type": "string",
"format": "uuid",
"description": "The option."
}
}
},
{
"type": "object",
"description": "Give a derived column a new formula. Its cells follow at once: it\nstores none.",
"required": ["formula", "kind"],
"properties": {
"formula": {
"$ref": "#/components/schemas/Formula",
"description": "The formula, over the table's other columns."
},
"kind": {
"type": "string",
"enum": ["set_formula"]
}
}
},
{
"type": "object",
"description": "Remove one option of a select or tag column, and take it out of every\ncell holding it: a single-valued cell is emptied, a multi-valued one\nkeeps its other options. Like [`ColumnChange::UpdateOption`], an\noption of a shared property goes everywhere it is used.",
"required": ["option", "kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["delete_option"]
},
"option": {
"type": "string",
"format": "uuid",
"description": "The option."
}
}
}
],
"description": "A change to one column."
},
"ColumnChangeKind": {
"type": "string",
"description": "How a change touched a column.",
"enum": [
"create",
"rename",
"change_type",
"set_formula",
"delete",
"add_options",
"update_option",
"delete_option",
"reorder",
"infer_type",
"related"
]
},
"ColumnConfig": {
"oneOf": [
{
"type": "object",
"description": "A relation column: its cells reference rows of another table.",
"required": ["database_id", "table_id", "kind"],
"properties": {
"database_id": {
"type": "string",
"format": "uuid",
"description": "Target database."
},
"kind": {
"type": "string",
"enum": ["link"]
},
"table_id": {
"type": "string",
"format": "uuid",
"description": "Target table."
}
}
},
{
"type": "object",
"description": "A derived column: its cells are computed from the row's others, and\nits definition, a number or date one, never holds a value.",
"required": ["formula", "kind"],
"properties": {
"formula": {
"$ref": "#/components/schemas/Formula",
"description": "How its cells are computed."
},
"kind": {
"type": "string",
"enum": ["derived"]
}
}
}
],
"description": "Column-kind specific configuration stored on the placement."
},
"ColumnConversion": {
"type": "object",
"description": "What a column's values become under another type, for a new column of\nthat type beside it: the values that convert, the options they need,\nand how many do not convert. Nothing is changed by reading it.",
"required": ["tableVersion", "options", "cells", "misfits"],
"properties": {
"cells": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConvertedCell"
},
"description": "Each row whose value converts, with that value, options named by\nlabel."
},
"misfits": {
"type": "integer",
"format": "int32",
"description": "How many values do not convert, and are left out.",
"minimum": 0
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"description": "The option labels a new select or tag column needs, in order."
},
"tableVersion": {
"$ref": "#/components/schemas/TableVersion",
"description": "The table's version the cells were read at; a batch writing the new\ncolumn sends it as its base version."
}
}
},
"ColumnConversionRequest": {
"type": "object",
"description": "The type a column's values are converted to.",
"required": ["to"],
"properties": {
"to": {
"$ref": "#/components/schemas/ColumnKind",
"description": "The type of the column the values would go to."
}
}
},
"ColumnDetail": {
"type": "object",
"description": "One column placement with the definition behind it.",
"required": [
"column",
"sql_name",
"definition",
"writable",
"shared_outside_database"
],
"properties": {
"column": {
"$ref": "#/components/schemas/Column",
"description": "The placement."
},
"definition": {
"$ref": "#/components/schemas/PropertyDefinitionWithOptions",
"description": "The bound definition (name, type, options)."
},
"shared_outside_database": {
"type": "boolean",
"description": "Whether the definition belongs to something beyond this database (a\nperson's, a team's or a system property), so changing its options\nchanges them everywhere that property is used."
},
"sql_name": {
"type": "string",
"description": "The name SQL refers to the column by: its display name, quoted."
},
"writable": {
"type": "boolean",
"description": "Whether SQL may write this column."
}
}
},
"ColumnId": {
"type": "string",
"format": "uuid",
"description": "Identifier of a column placement within a table."
},
"ColumnKind": {
"oneOf": [
{
"type": "object",
"description": "Free text.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["text"]
}
}
},
{
"type": "object",
"description": "A number.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["number"]
}
}
},
{
"type": "object",
"description": "A checkbox.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["boolean"]
}
}
},
{
"type": "object",
"description": "A date-time.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["date"]
}
}
},
{
"type": "object",
"description": "A span from one date-time to another.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["date_range"]
}
}
},
{
"type": "object",
"description": "A URL.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["link"]
}
}
},
{
"type": "object",
"description": "Text options.",
"required": ["multi", "type"],
"properties": {
"multi": {
"type": "boolean",
"description": "Whether a cell holds several options."
},
"type": {
"type": "string",
"enum": ["select"]
}
}
},
{
"type": "object",
"description": "Numeric options.",
"required": ["multi", "type"],
"properties": {
"multi": {
"type": "boolean",
"description": "Whether a cell holds several options."
},
"type": {
"type": "string",
"enum": ["select_number"]
}
}
},
{
"type": "object",
"description": "Colored labels; always several per cell.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["tag"]
}
}
},
{
"type": "object",
"description": "References to Macro entities.",
"required": ["target", "multi", "type"],
"properties": {
"multi": {
"type": "boolean",
"description": "Whether a cell holds several references."
},
"target": {
"$ref": "#/components/schemas/EntityKind",
"description": "What the references point at."
},
"type": {
"type": "string",
"enum": ["entity"]
}
}
},
{
"type": "object",
"description": "Rows of another table.",
"required": ["database", "table", "type"],
"properties": {
"database": {
"type": "string",
"format": "uuid",
"description": "The database of the related table."
},
"table": {
"type": "string",
"format": "uuid",
"description": "The related table."
},
"type": {
"type": "string",
"enum": ["relation"]
}
}
}
],
"description": "A type a column can have."
},
"ColumnProtection": {
"type": "string",
"description": "A schema operation reserved by a feature using a column.",
"enum": ["delete", "change_type"]
},
"ColumnResult": {
"oneOf": [
{
"type": "object",
"description": "It was added.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["created"]
}
}
},
{
"type": "object",
"description": "It was renamed.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["renamed"]
}
}
},
{
"type": "object",
"description": "Its type changed, and its cells with it.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["type_changed"]
}
}
},
{
"type": "object",
"description": "It was removed.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["deleted"]
}
}
},
{
"type": "object",
"description": "It gained options.",
"required": ["added", "kind"],
"properties": {
"added": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The options created, in order: those sent, less any whose label\nthe column already had."
},
"kind": {
"type": "string",
"enum": ["options_added"]
}
}
},
{
"type": "object",
"description": "One of its options was relabelled or recoloured.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["option_updated"]
}
}
},
{
"type": "object",
"description": "One of its options was removed.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["option_deleted"]
}
}
},
{
"type": "object",
"description": "Its formula changed.",
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["formula_set"]
}
}
}
],
"description": "What happened to a column."
},
"CommandFailure": {
"type": "object",
"description": "Sanitized public details of a command refused before runtime execution.",
"required": ["code", "message", "retryable"],
"properties": {
"code": {
"type": "string",
"description": "Stable public denial or unavailability code."
},
"message": {
"type": "string",
"description": "Public explanation, never an internal error report."
},
"retryable": {
"type": "boolean",
"description": "Whether retrying later may succeed without a policy change."
}
}
},
"CommandRejectedMetadata": {
"type": "object",
"description": "An accepted command was refused before it could start a runtime turn.",
"required": ["identity", "action_id", "failure"],
"properties": {
"action_id": {
"$ref": "#/components/schemas/AgentActionId",
"description": "The command that will not execute."
},
"actor": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "Who submitted the command, if acting on a user's behalf."
}
]
},
"announcement_message_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "The command's thread announcement, when one was created."
},
"failure": {
"$ref": "#/components/schemas/CommandFailure",
"description": "Safe details for clients and downstream consumers."
},
"identity": {
"$ref": "#/components/schemas/SessionIdentity",
"description": "The session."
}
}
},
"CommittedChange": {
"type": "object",
"description": "One change a committed batch journaled: a table, the version the batch\nproduced, and the journal's id for it.",
"required": ["table", "version", "change"],
"properties": {
"change": {
"type": "integer",
"format": "int64",
"description": "The journal's id of the change."
},
"table": {
"type": "string",
"format": "uuid",
"description": "The table."
},
"version": {
"$ref": "#/components/schemas/TableVersion",
"description": "The version the batch produced."
}
}
},
"CompleteUploads": {
"type": "object",
"description": "Explicit upload completion; a seal can be submitted separately with an empty list.",
"required": ["uploads"],
"properties": {
"seal": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ConversationSeal",
"description": "Optional immutable expected part set; identical retries are idempotent."
}
]
},
"uploads": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadId"
},
"description": "Registered identities to verify against storage (at most 50).",
"maxItems": 50
}
},
"additionalProperties": false
},
"ConferenceProvider": {
"type": "string",
"description": "The conferencing system backing an event's join URL.\n\nCalendars can create Google Meet or Microsoft Teams according to their\ncapabilities. Imported third-party conferences are labeled separately.\nOmitting a conference change preserves the current conference; explicit\nchanges still require provider and calendar capability validation.",
"enum": ["microsoft_teams", "google_meet", "other"]
},
"Conjunction": {
"type": "string",
"description": "How a group's conditions combine.",
"enum": ["and", "or"]
},
"ConversationId": {
"type": "string",
"description": "Source Slack conversation ID (C, G or D prefix); unique only within a source."
},
"ConversationKind": {
"type": "string",
"description": "Slack conversation kind. Public Slack channels map to Macro Team, never Public.",
"enum": [
"public_channel",
"private_channel",
"direct_message",
"group_direct_message"
]
},
"ConversationMetadata": {
"type": "object",
"description": "Full selected conversation metadata, persisted before granting any uploads.",
"required": [
"slackChannelId",
"kind",
"name",
"folder",
"memberIds",
"archived"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Source archived flag (does not silently archive a reused Macro target)."
},
"createdAt": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SlackTimestamp",
"description": "Missing time is resolved once from earliest message or persisted job time."
}
]
},
"creatorId": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SlackUserId",
"description": "Source creator when available."
}
]
},
"folder": {
"$ref": "#/components/schemas/KeySegment",
"description": "Single archive folder name, not a backend object key."
},
"kind": {
"$ref": "#/components/schemas/ConversationKind",
"description": "Source conversation kind."
},
"memberIds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SlackUserId"
},
"description": "Complete source member list, including members unknown to Macro."
},
"messageCount": {
"type": ["integer", "null"],
"format": "int64",
"description": "Advisory only; null means not yet counted, not zero.",
"minimum": 0
},
"name": {
"type": "string",
"description": "Original display name; not a storage key."
},
"slackChannelId": {
"$ref": "#/components/schemas/ConversationId",
"description": "Stable Slack identity."
}
},
"additionalProperties": false
},
"ConversationProgress": {
"type": "object",
"description": "Admin-visible progress for one selected conversation.",
"required": [
"slackChannelId",
"name",
"kind",
"archived",
"status",
"verifiedParts",
"counters",
"search",
"warnings"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Whether the selected source conversation was archived."
},
"channelId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Authorized target only; absent for inaccessible reused targets."
},
"counters": {
"$ref": "#/components/schemas/ImportCounters",
"description": "Durably committed record counts."
},
"error": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ImportError",
"description": "Sanitized terminal or retry diagnostic."
}
]
},
"kind": {
"$ref": "#/components/schemas/ConversationKind",
"description": "Persisted source kind."
},
"name": {
"type": "string",
"description": "Persisted source display name, never the reused Macro target's name."
},
"partCount": {
"type": ["integer", "null"],
"format": "int32",
"description": "Null until sealed; zero is a valid sealed empty manifest.",
"minimum": 0
},
"search": {
"$ref": "#/components/schemas/SearchState",
"description": "Independent indexing state."
},
"slackChannelId": {
"$ref": "#/components/schemas/ConversationId",
"description": "Source identity (always visible to the importing team's administrator)."
},
"status": {
"$ref": "#/components/schemas/ConversationStatus",
"description": "Durable state."
},
"verifiedParts": {
"type": "integer",
"format": "int32",
"description": "Number of parts whose object identity has been verified.",
"minimum": 0
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ImportWarning"
},
"description": "Non-fatal metadata/skip explanations."
}
}
},
"ConversationSeal": {
"type": "object",
"description": "Complete immutable expected part set for one conversation, including zero parts.",
"required": ["slackChannelId", "partCount", "manifestSha256"],
"properties": {
"manifestSha256": {
"$ref": "#/components/schemas/Sha256Digest",
"description": "SHA-256 of canonical descriptor lines; zero parts hash the empty byte string."
},
"partCount": {
"type": "integer",
"format": "int32",
"description": "Exact number of registered parts, starting at index zero.",
"minimum": 0
},
"slackChannelId": {
"$ref": "#/components/schemas/ConversationId",
"description": "Selected source conversation."
}
},
"additionalProperties": false
},
"ConversationStatus": {
"type": "string",
"description": "Durable per-conversation lifecycle.",
"enum": [
"awaiting_uploads",
"queued",
"importing",
"completed",
"skipped",
"failed"
]
},
"ConvertedCell": {
"type": "object",
"description": "One row's converted value.",
"required": ["row", "value"],
"properties": {
"row": {
"type": "string",
"format": "uuid",
"description": "The row."
},
"value": {
"$ref": "#/components/schemas/CellValue",
"description": "Its value under the new type."
}
}
},
"CopyDocumentQueryParams": {
"type": "object",
"description": "Query parameters for the copy document endpoint.",
"properties": {
"version_id": {
"type": ["integer", "null"],
"format": "int64",
"description": "The DB version id of the document to copy. Defaults to latest."
}
}
},
"CopyDocumentRequest": {
"type": "object",
"description": "Request body for copying a document.",
"required": ["documentName"],
"properties": {
"documentName": {
"type": "string",
"description": "The name of the new document (without extension)."
},
"versionId": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SyncServiceVersionID",
"description": "Optional sync service version ID for MD documents."
}
]
}
}
},
"CopyDocumentResponse": {
"type": "object",
"description": "Response wrapper for the copy document endpoint.",
"required": ["error", "data"],
"properties": {
"data": {
"$ref": "#/components/schemas/DocumentResponse",
"description": "The copied document data."
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred."
}
}
},
"CountedReaction": {
"type": "object",
"description": "Reaction emoji and the users who added it.",
"required": ["emoji", "users"],
"properties": {
"emoji": {
"type": "string",
"description": "Emoji being reacted with."
},
"users": {
"type": "array",
"items": {
"type": "string"
},
"description": "User identifiers."
}
}
},
"CreateAgentRequest": {
"type": "object",
"description": "Request to create a persisted AI agent.",
"required": [
"name",
"handle",
"instructions",
"harness",
"default_model",
"channel_scope",
"is_coding"
],
"properties": {
"auto_accept_permissions": {
"type": ["boolean", "null"],
"description": "Whether the agent's sessions approve ACP permission requests without\nasking. Omit to always prompt."
},
"avatar_url": {
"type": ["string", "null"],
"description": "Optional avatar URL or data URL."
},
"channel_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Selected channels. Must be non-empty only for `selected` scope."
},
"channel_scope": {
"$ref": "#/components/schemas/AgentChannelScope",
"description": "Whether the agent is global or channel-specific."
},
"default_model": {
"type": "string",
"description": "Model selected specifically for this agent."
},
"description": {
"type": ["string", "null"],
"description": "Optional description."
},
"handle": {
"type": "string",
"description": "Stable `@` handle."
},
"harness": {
"type": "string",
"description": "Harness used to run the agent."
},
"harness_id": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/HarnessId",
"description": "Registered harness to run on. Required when `harness` is `macrod`,\nforbidden otherwise."
}
]
},
"instructions": {
"type": "string",
"description": "Instructions supplied to the agent at the start of a conversation."
},
"is_coding": {
"type": "boolean",
"description": "Whether the agent is a coding agent: a mention is answered with a magic\nchip into its live session (`true`) or a reply in the thread (`false`)."
},
"mcp": {
"$ref": "#/components/schemas/AgentMcpServers",
"description": "Which MCP servers sessions of this agent are handed."
},
"name": {
"type": "string",
"description": "Display name."
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team owner. Omit for a private, user-owned agent."
}
}
},
"CreateBotRequest": {
"type": "object",
"description": "Request to create a bot.",
"required": ["name", "handle"],
"properties": {
"avatar_url": {
"type": ["string", "null"],
"description": "Optional avatar URL."
},
"description": {
"type": ["string", "null"],
"description": "Optional description."
},
"handle": {
"type": "string",
"description": "Stable handle."
},
"has_agent": {
"type": ["boolean", "null"],
"description": "Whether this bot runs as an AI agent: mentions and DMs start an agent session. Defaults to false."
},
"name": {
"type": "string",
"description": "Display name."
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team owner. The caller must be a team administrator or owner. Omit for a user-owned bot."
}
}
},
"CreateBotTokenRequest": {
"type": "object",
"description": "Request to create a bot token.",
"properties": {
"expires_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Optional expiration timestamp."
},
"label": {
"type": ["string", "null"],
"description": "Token label."
}
}
},
"CreateBotTokenResponse": {
"type": "object",
"description": "Response containing a newly minted token.",
"required": ["token", "bearer_token"],
"properties": {
"bearer_token": {
"type": "string",
"description": "Raw bearer token."
},
"token": {
"$ref": "#/components/schemas/BotToken",
"description": "Token metadata."
}
}
},
"CreateBulkDocumentResponse": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateBulkDocumentResponseData"
},
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
},
"CreateBulkDocumentResponseData": {
"type": "object",
"required": ["success"],
"properties": {
"documentMetadata": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentMetadata",
"description": "The created documents metadata\nOnly returned if the document was created successfully"
}
]
},
"presignedUrl": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/PresignedUrl",
"description": "The presigned url used to upload the document\nOnly returned if the document was created successfully"
}
]
},
"success": {
"type": "boolean",
"description": "Indicates if the document was created successfully"
}
}
},
"CreateCanvasDocumentRequest": {
"type": "object",
"description": "Request for a backend-initialized native Canvas.",
"required": ["documentName"],
"properties": {
"documentName": {
"type": "string",
"description": "Canvas name."
},
"projectId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Optional parent project."
}
}
},
"CreateCanvasDocumentResponse": {
"type": "object",
"description": "Response for creating a native Canvas.",
"required": ["documentId", "documentMetadata", "token"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created native Canvas"
},
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Metadata for the created document"
},
"token": {
"type": "string",
"description": "A pre-generated permission token that you can use for SS"
}
}
},
"CreateChannelLabelRequest": {
"type": "object",
"description": "Request body for creating a label.",
"required": ["name"],
"properties": {
"channelIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Channels to move into the new label."
},
"name": {
"type": "string",
"description": "Display name; unique within the scope, case-insensitively."
},
"rule": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ChannelLabelRule",
"description": "Automatic name-matching rule; omitted for manual labels or a name-only rename."
}
]
}
}
},
"CreateChannelRequest": {
"type": "object",
"description": "Request to create a channel.",
"required": ["channel_type", "participants"],
"properties": {
"auto_join_team": {
"type": "boolean",
"description": "Whether team members automatically join this channel. Defaults to false.",
"default": false
},
"channel_type": {
"$ref": "#/components/schemas/ChannelType",
"description": "Channel type."
},
"name": {
"type": ["string", "null"],
"description": "Optional channel name."
},
"participants": {
"type": "array",
"items": {
"type": "string"
},
"description": "Participants to add, excluding the owner.",
"uniqueItems": true
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team id for team channels."
}
}
},
"CreateChannelResponse": {
"type": "object",
"description": "Response returned after creating a channel.",
"required": ["id"],
"properties": {
"id": {
"type": "string",
"description": "Created channel id."
}
}
},
"CreateChannelScopedBotRequest": {
"type": "object",
"description": "Request to create a bot scoped to a channel.",
"required": ["name", "handle"],
"properties": {
"avatar_url": {
"type": ["string", "null"],
"description": "Optional avatar URL."
},
"description": {
"type": ["string", "null"],
"description": "Optional description."
},
"handle": {
"type": "string",
"description": "Stable handle."
},
"has_agent": {
"type": ["boolean", "null"],
"description": "Whether this bot runs as an AI agent: mentions and DMs start an agent session. Defaults to false."
},
"name": {
"type": "string",
"description": "Display name."
},
"team_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team owner. The caller must be a team administrator or owner. Omit for a user-owned bot."
},
"token_expires_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Optional token expiration timestamp."
},
"token_label": {
"type": ["string", "null"],
"description": "Optional token label."
}
}
},
"CreateChannelScopedBotResponse": {
"type": "object",
"description": "Response containing a newly created channel-scoped bot and token.",
"required": ["bot", "token", "bot_token"],
"properties": {
"bot": {
"$ref": "#/components/schemas/Bot",
"description": "Created bot."
},
"bot_token": {
"type": "string",
"description": "Raw bot token."
},
"token": {
"$ref": "#/components/schemas/BotToken",
"description": "Token metadata."
}
}
},
"CreateCrmCompanyRequest": {
"type": "object",
"description": "Request body for `POST /crm/companies`.",
"required": ["name"],
"properties": {
"domain": {
"type": ["string", "null"],
"description": "Optional company domain, e.g. \"acme.com\". Omit for a name-only\ncompany. When supplied, must be a bare\ndomain (no scheme, path, or email) and not a generic email\nprovider domain."
},
"name": {
"type": "string",
"description": "Display name for the company. Team-scoped: overrides the\ndomain-directory name on every read path."
}
}
},
"CreateCrmContactRequest": {
"type": "object",
"description": "Request body for `POST /crm/companies/{company_id}/contacts`.",
"required": ["name"],
"properties": {
"email": {
"type": ["string", "null"],
"description": "The contact's email address, including personal email providers.\nIt need not match a company domain. Optional: omit it to add the\ncontact by name only."
},
"name": {
"type": "string",
"description": "Display name for the contact."
}
}
},
"CreateCrmTeamContactRequest": {
"type": "object",
"description": "Request body for `POST /crm/contacts`.",
"required": ["name"],
"properties": {
"email": {
"type": ["string", "null"],
"description": "The contact's email address, of any domain. Optional: omit it to\nadd the contact by name only."
},
"name": {
"type": "string",
"description": "Display name for the contact."
}
}
},
"CreateDatabaseRequest": {
"type": "object",
"description": "Request body for creating a database.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Display name."
}
}
},
"CreateDatabaseWebhookRequest": {
"type": "object",
"description": "Which table a new webhook inserts rows into.",
"required": ["tableId"],
"properties": {
"tableId": {
"type": "string",
"format": "uuid",
"description": "A table of the database."
}
}
},
"CreateDocumentRequest": {
"type": "object",
"required": ["sha", "documentName"],
"properties": {
"branchedFromId": {
"type": ["string", "null"],
"description": "The document id if the document is being branched."
},
"branchedFromVersionId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The version id if the document is being branched."
},
"createdAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "Optional time to set the document's created_at to. Set when backfilling email attachments."
},
"documentFamilyId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The document family id if the document is being branched."
},
"documentName": {
"type": "string",
"description": "The name of the document without extension."
},
"emailAttachmentId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Internal only field that links the document created to the specified email attachment by\ncreating a row in the document_email table."
},
"fileType": {
"type": ["string", "null"],
"description": "Optional file type of the document."
},
"id": {
"type": ["string", "null"],
"format": "uuid",
"description": "The id of the document in the database"
},
"isTask": {
"type": "boolean",
"description": "Whether the document is a task.\nThis is only applicable for md documents and the request will fail if the file type is not\nmd."
},
"jobId": {
"type": ["string", "null"],
"description": "Optional job id to be used to track an upload job for the newly created document.\nWill need to have a corresponding job initiated for the file beforehand."
},
"mimeType": {
"type": ["string", "null"],
"description": "The content type of the document (currently only used for logging matches against file type)."
},
"projectId": {
"type": ["string", "null"],
"format": "uuid"
},
"sha": {
"type": "string",
"description": "The sha of the document."
},
"skipHistory": {
"type": "boolean",
"description": "Whether to add a viewed_at record for this document upon creation."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team to assign the task number within when creating a task document. If omitted,\nthe service may infer it only when the creator belongs to exactly one team."
}
}
},
"CreateDocumentResponseData": {
"allOf": [
{
"$ref": "#/components/schemas/DocumentResponse"
},
{
"type": "object",
"required": ["contentType"],
"properties": {
"contentType": {
"type": "string",
"description": "Content type of the document converted from file type"
},
"fileType": {
"type": ["string", "null"],
"description": "The file type of the document"
}
}
}
]
},
"CreateEntityMentionRequest": {
"type": "object",
"description": "Request body for `POST /channels/mentions`.",
"required": [
"source_entity_type",
"source_entity_id",
"entity_type",
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"description": "Id of the mentioned entity."
},
"entity_type": {
"type": "string",
"description": "Type of the mentioned entity."
},
"source_entity_id": {
"type": "string",
"description": "Id of the entity that owns the mention."
},
"source_entity_type": {
"type": "string",
"description": "Type of the entity that owns the mention."
}
}
},
"CreateEntityMentionResponse": {
"type": "object",
"description": "Response body for `POST /channels/mentions`.",
"required": [
"id",
"source_entity_type",
"source_entity_id",
"entity_type",
"entity_id",
"created_at"
],
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "Created timestamp."
},
"entity_id": {
"type": "string",
"description": "Id of the mentioned entity."
},
"entity_type": {
"type": "string",
"description": "Type of the mentioned entity."
},
"id": {
"type": "string",
"description": "Mention id."
},
"source_entity_id": {
"type": "string",
"description": "Id of the entity that owns the mention."
},
"source_entity_type": {
"type": "string",
"description": "Type of the entity that owns the mention."
},
"user_id": {
"type": ["string", "null"],
"description": "User who recorded the mention."
}
}
},
"CreateForm": {
"type": "object",
"description": "A request to create a form.",
"required": ["name", "source"],
"properties": {
"name": {
"type": "string",
"description": "Its name; a new database takes it too."
},
"source": {
"$ref": "#/components/schemas/FormSource",
"description": "Where its responses go."
}
}
},
"CreateImport": {
"type": "object",
"description": "Create command. Team identity is deliberately absent.",
"required": [
"idempotencyToken",
"source",
"includeMessageHistory",
"conversations"
],
"properties": {
"conversations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationMetadata"
},
"description": "Full, unique selected conversations (at most the configured bound).",
"maxItems": 2000,
"minItems": 1
},
"idempotencyToken": {
"$ref": "#/components/schemas/CreateToken",
"description": "Replay with the same semantic payload returns the original job; changes conflict."
},
"includeMessageHistory": {
"type": "boolean",
"description": "Default true at the client; false still requires users and zero-part seals."
},
"source": {
"$ref": "#/components/schemas/SourceIdentity",
"description": "Binding or explicit unknown-source confirmation."
}
},
"additionalProperties": false
},
"CreateInitiativeRequest": {
"type": "object",
"description": "Create-initiative HTTP body.",
"required": ["name"],
"properties": {
"description": {
"type": ["string", "null"],
"description": "Initial markdown for the description surface. Not stored on the initiative; later\nedits happen in the collaborative description editor."
},
"memberIds": {
"type": ["array", "null"],
"items": {
"type": "string"
},
"description": "Optional member user ids. Invalid ids fail at the service boundary."
},
"name": {
"type": "string",
"description": "Display name."
},
"propertyValues": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InitialPropertyValue"
},
"description": "Property values set as the owner within the create. A value the properties\nservice rejects fails the whole create; no initiative is left behind."
},
"shareWithTeam": {
"type": ["boolean", "null"],
"description": "Share with the owner's team at create time. Defaults to true; users without\na team create an unshared initiative. Explicit false skips the team grant."
}
}
},
"CreateInstructionsDocumentResponse": {
"type": "object",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string"
}
}
},
"CreateMarkdownDocumentRequest": {
"type": "object",
"description": "Request body for creating a markdown document whose content is initialized\nby the backend.",
"required": ["documentName"],
"properties": {
"documentName": {
"type": "string",
"description": "The document name."
},
"markdown": {
"type": ["string", "null"],
"description": "Markdown source text. Defaults to an empty document."
},
"projectId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Optional project ID to associate the document with."
},
"skipHistory": {
"type": "boolean",
"description": "Whether to add a viewed_at record for this document upon creation."
}
}
},
"CreateMarkdownDocumentResponse": {
"type": "object",
"description": "Response for creating a markdown document.",
"required": ["documentId", "documentMetadata", "token"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created markdown document"
},
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Metadata for the created document"
},
"token": {
"type": "string",
"description": "A pre-generated permission token that you can use for SS"
}
}
},
"CreateMeetingRequest": {
"type": "object",
"description": "Inputs for creating a meeting without starting its RTC room.",
"properties": {
"preparationId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Optional unused room reserved by this actor on the setup screen."
},
"scheduledEnd": {
"type": ["string", "null"],
"format": "date-time",
"description": "Optional scheduled end."
},
"scheduledStart": {
"type": ["string", "null"],
"format": "date-time",
"description": "Optional scheduled start."
},
"title": {
"type": ["string", "null"],
"description": "Optional display title."
}
}
},
"CreatePairingRequest": {
"type": "object",
"description": "Request to open a pairing: the daemon asks for a code the user approves.\n\nThe daemon serializes this, so both derives are used.",
"required": ["name"],
"properties": {
"host": {
"type": ["string", "null"],
"description": "Display-only description of the machine, e.g. `eric@macbook / darwin`."
},
"name": {
"type": "string",
"description": "Requested harness display name (typically the machine's hostname)."
}
}
},
"CreatePipeline": {
"type": "object",
"description": "Request to create an empty pipeline: the standard CRM columns for a tracked\nrecord, or one Name column, like a new database, for a generic pipeline.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Pipeline name."
},
"recordType": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/PipelineRecordType",
"description": "Company or contact entries; omitted, a generic pipeline of free-form rows."
}
]
},
"sharing": {
"$ref": "#/components/schemas/PipelineSharing",
"description": "Defaults to private."
}
},
"additionalProperties": false
},
"CreateProjectRequest": {
"type": "object",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "The name of the project."
},
"projectParentId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The project that the new project will belong to."
}
}
},
"CreateProjectResponse": {
"type": "object",
"required": ["error", "data"],
"properties": {
"data": {
"$ref": "#/components/schemas/Project",
"description": "Data to be returned"
},
"error": {
"type": "boolean",
"description": "Indicates if an error occurred"
}
}
},
"CreateSkillRequest": {
"type": "object",
"description": "Request body for creating a skill — a markdown document containing\ninstructions that AI reads and follows when the skill is referenced in an\nAI input.",
"required": ["skillName", "description"],
"properties": {
"description": {
"type": "string",
"description": "When to use the skill, in one line starting \"Use when\", e.g. \"Use when\ndrafting release notes; not changelog entries\". Agents choose skills\nfor a request by it."
},
"markdown": {
"type": ["string", "null"],
"description": "Markdown source text. Defaults to an empty skill document."
},
"projectId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Optional project ID to associate the skill with."
},
"skillName": {
"type": "string",
"description": "The name of the skill."
}
}
},
"CreateSkillResponse": {
"type": "object",
"description": "Response for creating a skill.",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created skill."
}
}
},
"CreateSnippetRequest": {
"type": "object",
"description": "Request body for creating a snippet — a reusable markdown document that can\nbe inserted into any markdown area.",
"required": ["snippetName"],
"properties": {
"markdown": {
"type": ["string", "null"],
"description": "Markdown source text. Defaults to an empty snippet document."
},
"projectId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Optional project ID to associate the snippet with."
},
"snippetName": {
"type": "string",
"description": "The name of the snippet."
}
}
},
"CreateSnippetResponse": {
"type": "object",
"description": "Response for creating a snippet.",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created snippet."
}
}
},
"CreateTaskRequest": {
"type": "object",
"description": "Request body for creating a task.",
"required": ["taskName"],
"properties": {
"markdown": {
"type": ["string", "null"],
"description": "Markdown source text. Defaults to an empty task document."
},
"projectId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Optional project ID to associate the task with."
},
"propertyValues": {
"type": ["array", "null"],
"items": {
"$ref": "#/components/schemas/PropertyInput"
},
"description": "Optional property values to set on the task."
},
"shareWithTeam": {
"type": "boolean",
"description": "Whether to share the task with your team or not\nDefaults to true"
},
"taskName": {
"type": "string",
"description": "The name of the task."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Team to assign the task number within. If omitted, it is inferred only\nwhen the creator belongs to exactly one team."
}
}
},
"CreateTaskResponse": {
"type": "object",
"description": "Response for creating a task.",
"required": [
"documentId",
"documentMetadata",
"token",
"initialSnapshot"
],
"properties": {
"documentId": {
"type": "string",
"description": "The document ID of the created task."
},
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Metadata for the created document"
},
"initialSnapshot": {
"type": "string",
"description": "Base64-encoded canonical Loro snapshot used to initialize the task."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The team this task number is scoped to."
},
"teamTaskId": {
"type": ["integer", "null"],
"format": "int32",
"description": "The task number assigned within the team."
},
"token": {
"type": "string",
"description": "A pre-generated permission token that you can use for SS"
}
}
},
"CreateToken": {
"type": "string",
"format": "uuid",
"description": "Client-generated create idempotency token, scoped to team and administrator."
},
"CreateUnthreadedAnchorRequest": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/CreateUnthreadedPdfAnchorRequest"
},
{
"type": "object",
"required": ["fileType"],
"properties": {
"fileType": {
"type": "string",
"enum": ["pdf"]
}
}
}
]
}
]
},
"CreateUnthreadedAnchorResponse": {
"allOf": [
{
"$ref": "#/components/schemas/Anchor"
},
{
"type": "object",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string"
}
}
}
]
},
"CreateUnthreadedPdfAnchorRequest": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/PdfHighlightAnchorRequest"
},
{
"type": "object",
"required": ["anchorType"],
"properties": {
"anchorType": {
"type": "string",
"enum": ["highlight"]
}
}
}
]
}
]
},
"CreateUserApiKeyRequest": {
"type": "object",
"description": "Request body for minting a key.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "User-facing name for the key."
}
}
},
"CreateViewRequest": {
"type": "object",
"required": ["name", "config"],
"properties": {
"config": {},
"name": {
"type": "string"
}
}
},
"CreateWebhookRequest": {
"type": "object",
"description": "Request to create a webhook.\n\nClients serialize this, so both derives are used.",
"required": ["scope", "namespace", "name", "endpoint_url", "filters"],
"properties": {
"endpoint_url": {
"type": "string",
"description": "Endpoint URL. HTTPS is required outside local environments."
},
"filters": {
"$ref": "#/components/schemas/Vec",
"description": "Typed filters used to match events and optional entity ids."
},
"headers": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BTreeMap",
"description": "Optional custom delivery headers."
}
]
},
"name": {
"type": "string",
"description": "Display name."
},
"namespace": {
"type": "string",
"description": "Caller-chosen namespace, unique among the owning workspace's webhooks.\nSet at creation time only; it cannot be changed afterwards."
},
"scope": {
"$ref": "#/components/schemas/WebhookScope",
"description": "Scope that owns the webhook."
}
}
},
"CreateWebhookResponse": {
"type": "object",
"description": "Webhook returned after creation, including its signing secret.\n\nClients deserialize this, so both derives are used.",
"required": [
"id",
"workspace_id",
"namespace",
"name",
"endpoint_url",
"signing_secret",
"headers",
"status",
"is_valid",
"created_by_user_id",
"created_at",
"updated_at",
"filters"
],
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"created_by_user_id": {
"type": "string",
"description": "User that created the webhook."
},
"deleted_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Soft-delete timestamp."
},
"endpoint_url": {
"type": "string",
"description": "Endpoint URL. HTTPS is required outside local environments."
},
"filters": {
"$ref": "#/components/schemas/Vec",
"description": "Typed filters used to match events and optional entity ids."
},
"headers": {
"$ref": "#/components/schemas/BTreeMap",
"description": "Custom delivery headers, after decryption by the repository."
},
"id": {
"$ref": "#/components/schemas/String",
"description": "Webhook id."
},
"is_valid": {
"type": "boolean",
"description": "Whether the current endpoint configuration has passed validation."
},
"name": {
"type": "string",
"description": "Display name."
},
"namespace": {
"type": "string",
"description": "Caller-chosen namespace, unique among the owning workspace's webhooks.\nSet at creation time only; it cannot be changed afterwards."
},
"signing_secret": {
"type": "string",
"description": "Signing secret used to verify webhook delivery signatures."
},
"status": {
"$ref": "#/components/schemas/WebhookStatus",
"description": "Webhook lifecycle status."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Update timestamp."
},
"workspace_id": {
"type": "string",
"description": "Owning workspace id."
}
}
},
"CreatedDatabaseWebhookResponse": {
"type": "object",
"description": "A new webhook, with the token its URL carries. The token is shown only\nhere.",
"required": ["webhook", "token"],
"properties": {
"token": {
"type": "string",
"description": "The secret: `POST /databases/webhooks/{token}` inserts rows."
},
"webhook": {
"$ref": "#/components/schemas/DatabaseWebhookResponse",
"description": "The webhook."
}
}
},
"CreatedItem": {
"type": "object",
"description": "A slide or shape an edit created.",
"required": ["slide"],
"properties": {
"section": {
"type": ["string", "null"],
"description": "Section id, for created sections."
},
"shape": {
"type": ["integer", "null"],
"format": "int32",
"description": "Shape id, for created shapes.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
"CreatedPairing": {
"type": "object",
"description": "A pairing the daemon created, including its claim credential.\n\n`device_secret` is returned exactly once and never stored raw; the daemon\nkeeps it to claim the harness credential after approval.",
"required": [
"pairing_id",
"code",
"device_secret",
"expires_at",
"poll_interval_seconds"
],
"properties": {
"code": {
"type": "string",
"description": "Human-readable code the user confirms in the web app, `XXXX-XXXX`."
},
"device_secret": {
"type": "string",
"description": "Claim credential the daemon must present. Shown only here."
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "When the pairing expires."
},
"pairing_id": {
"type": "string",
"format": "uuid",
"description": "Pairing id used to poll for the claim."
},
"poll_interval_seconds": {
"type": "integer",
"format": "int64",
"description": "Suggested delay between claim polls.",
"minimum": 0
}
}
},
"CreatedUserApiKey": {
"type": "object",
"description": "A newly minted key: safe metadata plus the secret, shown only once.",
"required": ["id", "name", "createdAt", "key"],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the key was created."
},
"id": {
"$ref": "#/components/schemas/UserApiKeyId",
"description": "Opaque identifier used to address the key after create."
},
"key": {
"type": "string",
"description": "The newly minted secret. Shown only on create."
},
"name": {
"type": "string",
"description": "User-facing name."
}
}
},
"CrmAssociation": {
"oneOf": [
{
"type": "object",
"description": "Items associated with the company or with any of its contacts.",
"required": ["company"],
"properties": {
"company": {
"type": "string",
"format": "uuid",
"description": "Items associated with the company or with any of its contacts."
}
}
},
{
"type": "object",
"description": "Items associated with the contact.",
"required": ["contact"],
"properties": {
"contact": {
"type": "string",
"format": "uuid",
"description": "Items associated with the contact."
}
}
},
{
"type": "string",
"description": "Activity across visible CRM-enabled teams, excluding hidden records.",
"enum": ["activity"]
}
],
"description": "The CRM record an association filter names."
},
"CrmBlockedDomainResponse": {
"type": "object",
"description": "A domain the team keeps out of email sync.",
"required": ["domain", "created_at"],
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "When it was added."
},
"domain": {
"type": "string",
"description": "The blocked domain, lowercase."
}
}
},
"CrmCompanyFilters": {
"type": "object",
"description": "The crm company filters used to narrow which CRM companies appear in soup.",
"properties": {
"company_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "CRM company ids to filter by. Examples: ['11111111-...']. Empty to\ninclude all of the team's visible CRM companies."
},
"hidden": {
"type": ["boolean", "null"],
"description": "Optional `crm_companies.hidden` filter. `None` = visible only\n(default for back-compat with non-admin callers). `Some(false)` =\nvisible only (explicit). `Some(true)` = hidden only — requires\nadmin/owner team role; enforced by the CRM service from the\ncaller's team receipt."
}
}
},
"CrmCompanyResponse": {
"type": "object",
"description": "A CRM company as returned by `GET /crm/companies/{company_id}`.\nMirrors the soup-listed `crmCompany` shape (`name` / `description`\nresolved from the primary domain's `crm_domain_directory` entry) and\nembeds the company's contacts so the panel can render in a single\nrequest.",
"required": [
"id",
"teamId",
"emailSync",
"hidden",
"createdAt",
"updatedAt",
"domains",
"contacts"
],
"properties": {
"contacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CrmContactResponse"
},
"description": "Contacts attached to this company. Hidden contacts are filtered\nout for non-admin viewers."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Earliest known interaction with this company."
},
"description": {
"type": ["string", "null"],
"description": "Display description from the primary domain's directory entry."
},
"domains": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CrmDomainResponse"
},
"description": "All domains associated with this company, ordered by creation\ntime ascending (primary first)."
},
"emailSync": {
"type": "boolean",
"description": "Whether email sync is enabled for this company."
},
"hidden": {
"type": "boolean",
"description": "Whether the company is hidden from CRM listings for the\nrequesting team. Non-admin viewers never see `hidden = true`\nrows (the endpoint 404s for them); admin/owner callers see\nhidden companies so they can render the right toggle state."
},
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the company."
},
"name": {
"type": ["string", "null"],
"description": "Display name from the primary domain's directory entry, or\n`None` when unresolved."
},
"teamId": {
"type": "string",
"format": "uuid",
"description": "The id of the team that owns this company record."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Most recent known interaction with this company."
}
}
},
"CrmContactResponse": {
"type": "object",
"description": "A CRM contact as returned by `GET /crm/companies/{company_id}/contacts`.",
"required": [
"id",
"hidden",
"firstInteraction",
"lastInteraction",
"createdAt",
"updatedAt"
],
"properties": {
"companyId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The id of the company the contact belongs to; absent for a\ncontact without a company."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the contact record was created."
},
"email": {
"type": ["string", "null"],
"description": "The contact's email address; absent for contacts added by name\nalone."
},
"firstInteraction": {
"type": "string",
"format": "date-time",
"description": "Earliest known interaction with this contact."
},
"hidden": {
"type": "boolean",
"description": "Whether the contact is hidden from CRM listings for the\nrequesting team. Non-admin viewers never see `hidden = true`\nrows (the endpoint filters them out); admin/owner callers see\nhidden contacts so they can render the right toggle state."
},
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the contact record."
},
"lastInteraction": {
"type": "string",
"format": "date-time",
"description": "Most recent known interaction with this contact."
},
"name": {
"type": ["string", "null"],
"description": "Display name observed for the contact, if any."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "When the contact record was last updated."
}
}
},
"CrmDomainResponse": {
"type": "object",
"description": "A CRM domain associated with a company.",
"required": ["id", "companyId", "domain", "createdAt"],
"properties": {
"companyId": {
"type": "string",
"format": "uuid",
"description": "The id of the company the domain belongs to."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the domain record was created."
},
"domain": {
"type": "string",
"description": "The domain (e.g. \"acme.com\")."
},
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the domain record."
}
}
},
"CrmPermissionRole": {
"type": "string",
"description": "Minimum team role required for a CRM governance capability. Members\ncan edit visible CRM records (e.g. company properties), but the\ngovernance capabilities these settings gate stay restricted to\nadmin (default) vs owner. Maps to the `team_role` Postgres enum;\n`member` is deliberately not representable.",
"enum": ["admin", "owner"]
},
"CrmStageInput": {
"type": "object",
"description": "One stage in a `PUT /crm/stages` body.",
"required": ["label"],
"properties": {
"id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Existing stage to keep; omit to add one."
},
"label": {
"type": "string",
"description": "Label after the update; non-blank and unique within the set."
}
}
},
"CrmStageResponse": {
"type": "object",
"description": "One stage of the team's custom pipeline.",
"required": ["id", "label"],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Property option id companies carry as their stage value."
},
"label": {
"type": "string",
"description": "Label."
}
}
},
"CrmStagesResponse": {
"type": "object",
"description": "The team's custom stage set.",
"required": ["definition_id", "stages"],
"properties": {
"definition_id": {
"type": "string",
"format": "uuid",
"description": "Team-scoped stage definition id."
},
"stages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CrmStageResponse"
},
"description": "Stages in pipeline order."
}
}
},
"CrmTeamSettingsResponse": {
"type": "object",
"description": "The team's CRM configuration (everything on `team_crm_settings`\nexcept the `crm_enabled` killswitch, which is managed via\n`PATCH /team/crm` on the auth service).",
"required": [
"edit_stages_role",
"move_closed_deals_role",
"delete_records_role",
"legacy_stage_ids",
"team_views",
"exclude_personal_emails"
],
"properties": {
"closed_stage_ids": {
"type": ["array", "null"],
"items": {
"type": "string",
"format": "uuid"
},
"description": "Stage option ids counting as closed deals; absent = the client\nfalls back to its label heuristic."
},
"default_team_view_id": {
"type": ["string", "null"],
"description": "Team view applied by default when a member opens the CRM view."
},
"delete_records_role": {
"$ref": "#/components/schemas/CrmPermissionRole",
"description": "Who can delete (hide) CRM records."
},
"edit_stages_role": {
"$ref": "#/components/schemas/CrmPermissionRole",
"description": "Who can change the deal stage set in CRM settings."
},
"exclude_personal_emails": {
"type": "boolean",
"description": "Whether email sync keeps personal-provider addresses (gmail.com\netc.) out of the CRM."
},
"legacy_stage_ids": {
"type": "object",
"description": "System stage option id to team stage option id for seeded stages.",
"additionalProperties": {
"type": "string",
"format": "uuid"
},
"propertyNames": {
"type": "string",
"format": "uuid"
}
},
"move_closed_deals_role": {
"$ref": "#/components/schemas/CrmPermissionRole",
"description": "Who can move deals out of a closed stage."
},
"team_views": {
"description": "Team saved views — an opaque JSON array owned by the frontend."
}
}
},
"CropMode": {
"type": "string",
"description": "How `cropPicture` fits a picture's image to its frame.",
"enum": ["fill", "fit"]
},
"CustomSpeakerAssignment": {
"type": "object",
"description": "One per-diarized-speaker override, used in [`EditCallTranscriptRequest`].\n\n`custom_speaker = None` clears any existing override for this\n`diarized_speaker_id`; `Some(macro_user_id)` sets it. The string is\nexpected to parse as a `MacroUserId` (e.g. `macro|[email protected]`);\nthe service layer rejects malformed values with `400 Bad Request`.",
"required": ["diarizedSpeakerId", "customSpeaker"],
"properties": {
"customSpeaker": {
"type": "string",
"description": "Macro user id to attribute matching rows to, or `None` to clear."
},
"diarizedSpeakerId": {
"type": "string",
"description": "The diarization label whose rows this assignment targets."
}
}
},
"DataType": {
"type": "string",
"description": "Data type for property values, determining storage and validation.",
"enum": [
"BOOLEAN",
"DATE",
"DATE_RANGE",
"NUMBER",
"STRING",
"SELECT_NUMBER",
"SELECT_STRING",
"TAG",
"ENTITY",
"LINK"
]
},
"Database": {
"type": "object",
"description": "A database: a named collection of tables, owned and shared as one entity.",
"required": [
"id",
"name",
"owner_id",
"created_at",
"trashed_at",
"project_id"
],
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation time."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Identifier."
},
"name": {
"type": "string",
"description": "Display name."
},
"owner_id": {
"type": "string",
"description": "Owning user."
},
"project_id": {
"type": ["string", "null"],
"description": "The folder it is filed in; `null` at the root."
},
"trashed_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Set when trashed."
}
}
},
"DatabaseDetail": {
"type": "object",
"description": "Everything a client needs to render and edit one database: tables,\ncolumn placements with their definitions, and the SQL names the query\nsurface exposes them under.",
"required": ["database", "grant", "tables"],
"properties": {
"database": {
"$ref": "#/components/schemas/Database",
"description": "The database."
},
"grant": {
"$ref": "#/components/schemas/AccessLevel",
"description": "The viewer's access."
},
"tables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TableDetail"
},
"description": "Tables in tab order."
}
}
},
"DatabaseId": {
"type": "string",
"format": "uuid",
"description": "Identifier of reusable database storage. Its optional Macro entity uses\nthe same identity, so existing routes and grants keep their IDs."
},
"DatabaseOp": {
"oneOf": [
{
"type": "object",
"description": "A change to a table itself: its creation, name, removal, or the\norder of its columns or views.",
"required": ["table", "change", "kind"],
"properties": {
"change": {
"$ref": "#/components/schemas/TableChange",
"description": "What changes."
},
"kind": {
"type": "string",
"enum": ["table"]
},
"table": {
"type": "string",
"format": "uuid",
"description": "The table; for a creation, its new id, minted by the client, which\nlater ops of the request may name."
}
}
},
{
"type": "object",
"description": "A change to one column of a table: its creation, name, type, removal\nor options.",
"required": ["table", "column", "change", "kind"],
"properties": {
"change": {
"$ref": "#/components/schemas/ColumnChange",
"description": "What changes."
},
"column": {
"type": "string",
"format": "uuid",
"description": "The column; for a creation, its new id, minted by the client,\nwhich later ops of the request may name."
},
"kind": {
"type": "string",
"enum": ["column"]
},
"table": {
"type": "string",
"format": "uuid",
"description": "The table."
}
}
},
{
"type": "object",
"description": "A write to a table's rows.",
"required": ["table", "change", "kind"],
"properties": {
"change": {
"$ref": "#/components/schemas/RowsChange",
"description": "What changes."
},
"kind": {
"type": "string",
"enum": ["rows"]
},
"table": {
"type": "string",
"format": "uuid",
"description": "The table the rows belong to."
}
}
},
{
"type": "object",
"description": "A change to one view of a table.",
"required": ["table", "view", "change", "kind"],
"properties": {
"change": {
"$ref": "#/components/schemas/ViewChange",
"description": "What changes."
},
"kind": {
"type": "string",
"enum": ["view"]
},
"table": {
"type": "string",
"format": "uuid",
"description": "The view's table."
},
"view": {
"type": "string",
"format": "uuid",
"description": "The view; for a creation, its new id, minted by the client."
}
}
},
{
"type": "object",
"description": "Set the order of the database's tables: `order` names every one of\nthem once.",
"required": ["order", "kind"],
"properties": {
"kind": {
"type": "string",
"enum": ["reorder_tables"]
},
"order": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Every table, in its new order."
}
}
}
],
"description": "One write to a database: its tables, columns, options, rows or views,\ngrouped by the resource it changes. A request's ops apply in order and\ntogether, or not at all, and every op names a table of the database the\nrequest is for (or, creating one, adds it there)."
},
"DatabaseQueryRequest": {
"type": "object",
"description": "One SQL statement with an optional default database and optimistic write guards.",
"required": ["sql"],
"properties": {
"baseVersions": {
"type": "object",
"description": "Expected version for each table a subsequent statement writes.",
"additionalProperties": {
"$ref": "#/components/schemas/TableVersion"
},
"propertyNames": {
"type": "string",
"format": "uuid",
"description": "Identifier of one table (tab) within a database."
}
},
"databaseId": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DatabaseId",
"description": "Default database for resolving unqualified table names; other visible databases remain joinable."
}
]
},
"sql": {
"type": "string",
"description": "One supported SQL statement. Writes execute once, without automatic retries."
}
}
},
"DatabaseView": {
"type": "object",
"description": "A view of one table, as stored.",
"required": [
"id",
"databaseId",
"tableId",
"name",
"position",
"query",
"layout",
"createdAt",
"updatedAt"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When it was created."
},
"databaseId": {
"type": "string",
"format": "uuid",
"description": "The database the table belongs to."
},
"id": {
"type": "string",
"format": "uuid",
"description": "The view."
},
"layout": {
"$ref": "#/components/schemas/ViewLayout",
"description": "How it draws them."
},
"name": {
"type": "string",
"description": "Its name, unique among the table's views ignoring case."
},
"position": {
"type": "string",
"description": "Where it sorts among the table's views: a fractional key."
},
"query": {
"$ref": "#/components/schemas/ViewQuery",
"description": "Which rows it shows, in what order."
},
"tableId": {
"type": "string",
"format": "uuid",
"description": "The table it shows."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "When it last changed."
}
}
},
"DatabaseWebhookDeliveryResponse": {
"type": "object",
"description": "The rows a webhook call inserted.",
"required": ["databaseId", "tableId", "rows"],
"properties": {
"databaseId": {
"type": "string",
"format": "uuid",
"description": "The database."
},
"rows": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The new rows, in the order the payload sent them."
},
"tableId": {
"type": "string",
"format": "uuid",
"description": "The table."
}
}
},
"DatabaseWebhookPayloadProblem": {
"type": "object",
"description": "One thing wrong with a webhook payload.",
"required": ["row", "field", "message"],
"properties": {
"field": {
"type": ["string", "null"],
"description": "The key at fault, when one is."
},
"message": {
"type": "string",
"description": "What is wrong."
},
"row": {
"type": ["integer", "null"],
"description": "The row's index, when the payload is an array of rows.",
"minimum": 0
}
}
},
"DatabaseWebhookResponse": {
"type": "object",
"description": "A webhook of a database. Its token is never shown again after creation.",
"required": [
"id",
"databaseId",
"tableId",
"createdBy",
"tokenPrefix",
"createdAt"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation time."
},
"createdBy": {
"type": "string",
"description": "Who created it; its calls write with their access."
},
"databaseId": {
"type": "string",
"format": "uuid",
"description": "The database."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Identifier."
},
"tableId": {
"type": "string",
"format": "uuid",
"description": "The table its calls insert rows into."
},
"tokenPrefix": {
"type": "string",
"description": "The token's first characters, to tell webhooks apart."
}
}
},
"DateOperator": {
"type": "string",
"description": "How a date cell compares to a date-time.",
"enum": ["before", "after", "onOrBefore", "onOrAfter"]
},
"DateRange": {
"type": "object",
"description": "A span of time from `start` to `end`, both included. A write whose end\ncomes before its start is refused.",
"required": ["start", "end"],
"properties": {
"end": {
"type": "string",
"format": "date-time",
"description": "Where it ends; never before the start."
},
"start": {
"type": "string",
"format": "date-time",
"description": "Where it starts."
}
}
},
"DateRangeOperator": {
"type": "string",
"description": "How a date-range cell stands to a day: the whole day starting at the\ntest's date-time, so a range from 1 PM to 5 PM contains its day.",
"enum": [
"contains",
"doesNotContain",
"endsBefore",
"endsOnOrAfter",
"startsAfter",
"startsOnOrBefore"
]
},
"DeleteEntityMentionResponse": {
"type": "object",
"description": "Response body for `DELETE /channels/mentions/{mention_id}`.",
"required": ["deleted"],
"properties": {
"deleted": {
"type": "boolean",
"description": "Whether the mention was deleted."
}
}
},
"DeleteUnthreadedAnchorRequest": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/DeleteUnthreadedPdfAnchorRequest"
},
{
"type": "object",
"required": ["fileType"],
"properties": {
"fileType": {
"type": "string",
"enum": ["pdf"]
}
}
}
]
}
]
},
"DeleteUnthreadedAnchorResponse": {
"allOf": [
{
"$ref": "#/components/schemas/AnchorId"
},
{
"type": "object",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string"
},
"rootId": {
"type": ["string", "null"],
"format": "uuid",
"description": "Root of the discussion that was deleted with the anchor, if it had one."
}
}
}
]
},
"DeleteUnthreadedPdfAnchorRequest": {
"oneOf": [
{
"type": "object",
"required": ["uuid", "anchorType"],
"properties": {
"anchorType": {
"type": "string",
"enum": ["highlight"]
},
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
]
},
"DesignFileDescription": {
"type": "object",
"description": "A design file described as text.",
"required": ["content"],
"properties": {
"content": {
"type": "string",
"description": "The description: pages or artboards, the layer tree, and the text of\ntext layers."
}
}
},
"DirectAccess": {
"type": "object",
"description": "A direct user grant; inherited grants are deliberately not editable here.",
"required": ["userId", "accessLevel"],
"properties": {
"accessLevel": {
"$ref": "#/components/schemas/AccessLevel",
"description": "Direct permission level."
},
"userId": {
"type": "string",
"description": "Recipient."
}
}
},
"DocumentAiEditFailed": {
"type": "object",
"description": "The edit failed after it started, so it may have partly applied. Read the\ndocument before retrying.",
"required": ["error", "message"],
"properties": {
"error": {
"$ref": "#/components/schemas/DocumentAiEditFailedCode",
"description": "Always `edit_failed`."
},
"message": {
"type": "string",
"description": "What to do next; the cause is logged, never returned."
}
}
},
"DocumentAiEditFailedCode": {
"type": "string",
"description": "Error code of an edit that failed after it started.",
"enum": ["edit_failed"]
},
"DocumentAiEditRefused": {
"type": "object",
"description": "The editor could not do the edit; nothing changed.",
"required": ["error", "reason"],
"properties": {
"error": {
"$ref": "#/components/schemas/DocumentAiEditRefusedCode",
"description": "Always `edit_refused`."
},
"reason": {
"type": "string",
"description": "Why, in the editor's words: what it needs to know or cannot do."
}
}
},
"DocumentAiEditRefusedCode": {
"type": "string",
"description": "Error code of an edit the editor refused.",
"enum": ["edit_refused"]
},
"DocumentAiEditRequest": {
"type": "object",
"description": "What to change, in words.",
"required": ["instructions"],
"properties": {
"fast": {
"type": "boolean",
"description": "Run the single-model fast pipeline, for one small, contained edit."
},
"instructions": {
"type": "string",
"description": "Natural-language instructions. Name the section or quote the text to\nchange, describe the outcome, and say what must stay as it is.",
"minLength": 1
}
}
},
"DocumentAiEdited": {
"type": "object",
"description": "A completed edit by instructions.",
"required": ["revision"],
"properties": {
"clarification": {
"type": ["string", "null"],
"description": "What the editor needs to know to finish, when it applied part of the\nedit and stopped; the applied part stays."
},
"revision": {
"type": "string",
"description": "The document's version after the edit, as sync-service encodes it."
}
}
},
"DocumentBasic": {
"type": "object",
"description": "Returns basic information of a document used for some db queries",
"required": ["documentId", "documentName", "owner"],
"properties": {
"branchedFromId": {
"type": ["string", "null"]
},
"branchedFromVersionId": {
"type": ["integer", "null"],
"format": "int64"
},
"deletedAt": {
"type": ["string", "null"],
"format": "date-time"
},
"documentFamilyId": {
"type": ["integer", "null"],
"format": "int64"
},
"documentId": {
"type": "string"
},
"documentName": {
"type": "string"
},
"fileType": {
"type": ["string", "null"]
},
"owner": {
"type": "string"
},
"projectId": {
"type": ["string", "null"]
},
"subType": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentSubType"
}
]
}
}
},
"DocumentContent": {
"type": "object",
"description": "API-visible content lifecycle and location metadata.",
"required": ["state"],
"properties": {
"location": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentContentLocation",
"description": "The content location, when known."
}
]
},
"state": {
"$ref": "#/components/schemas/DocumentContentState",
"description": "The current lifecycle state of the content."
}
}
},
"DocumentContentLocation": {
"type": "string",
"description": "Where document content is, or is expected to be, read from.",
"enum": [
"object_storage",
"sync_service",
"docx_bom_parts",
"converted_pdf",
"unknown"
]
},
"DocumentContentState": {
"type": "string",
"description": "API-visible content lifecycle state derived from current document metadata.",
"enum": ["unknown", "pending", "ready"]
},
"DocumentContentUploadedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::ContentUploaded`].",
"required": ["document_id", "owner", "file_type"],
"properties": {
"document_id": {
"type": "string",
"description": "The id of the document whose stored bytes changed."
},
"document_version_id": {
"type": ["string", "null"],
"description": "Version written, or the converted-file marker; `None` for unversioned\nwrites (mirrors `SearchExtractorMessage::document_version_id`)."
},
"file_type": {
"$ref": "#/components/schemas/FileType",
"description": "File type of the uploaded object (may differ from the document's own\ntype, e.g. `pdf` for the converted rendition of a docx)."
},
"owner": {
"type": "string",
"description": "The owner of the document (used by the extractor to resolve S3 keys)."
}
}
},
"DocumentCopiedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::Copied`].",
"required": [
"document_id",
"source_document_id",
"owner",
"document_name"
],
"properties": {
"actor": {
"type": ["string", "null"],
"description": "Who mechanically created the copy."
},
"document_id": {
"type": "string",
"description": "The id of the newly created copy."
},
"document_name": {
"type": "string",
"description": "The name of the new document."
},
"file_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/FileType",
"description": "File type of the document, when known."
}
]
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The user whose feed this copy belongs on, when different from the actor."
}
]
},
"owner": {
"type": "string",
"description": "The principal who owns the new copy."
},
"project_id": {
"type": ["string", "null"],
"description": "Project the copy belongs to, when any."
},
"source_document_id": {
"type": "string",
"description": "The id of the document that was copied."
},
"source_version_id": {
"type": ["integer", "null"],
"format": "int64",
"description": "The specific source version copied, when requested."
},
"sub_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentSubType",
"description": "Sub type (task / snippet), when any."
}
]
}
}
},
"DocumentCreatedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::Created`].",
"required": ["document_id", "owner", "document_name"],
"properties": {
"actor": {
"type": ["string", "null"],
"description": "Who mechanically created the document. Absent on events published\nbefore attribution: ingest derives a user/bot actor from [`Self::owner`].\nTeam owners fall back to [`Self::on_behalf_of`], then the system bot."
},
"created_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "Creation timestamp reported by the repository."
},
"document_id": {
"type": "string",
"description": "The id of the created document."
},
"document_name": {
"type": "string",
"description": "The document name, with any file extension stripped."
},
"file_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/FileType",
"description": "File type of the document, when known."
}
]
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The user whose feed this creation belongs on, when different from\n[`Self::actor`]. Absent means the actor is also the subject."
}
]
},
"owner": {
"type": "string",
"description": "The principal who owns the document."
},
"project_id": {
"type": ["string", "null"],
"description": "Project the document was created in, when any."
},
"sub_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentSubType",
"description": "Sub type (task / snippet), when any."
}
]
}
}
},
"DocumentDeletedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::Deleted`].",
"required": ["document_id"],
"properties": {
"actor": {
"type": ["string", "null"],
"description": "Who mechanically deleted the document. Absent on events published\nbefore attribution, and on user-receipt writes (ingest then uses\n[`Self::actor_user_id`])."
},
"actor_user_id": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The authenticated user who deleted the document; `None` for\nunauthenticated or internal callers."
}
]
},
"document_id": {
"type": "string",
"description": "The id of the deleted document."
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The user whose feed this delete belongs on, when different from\n[`Self::actor`]."
}
]
},
"project_id": {
"type": ["string", "null"],
"description": "Project the document belonged to, when any."
},
"sub_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentSubType",
"description": "Subtype captured before deletion, so consumers can distinguish tasks."
}
]
}
}
},
"DocumentFilters": {
"type": "object",
"description": "The document filters used to filter down what documents you search over.",
"properties": {
"document_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Document ids to search over. Examples: ['doc1'], ['doc1', 'doc2']. Empty to search all accessible documents."
},
"file_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Document file types to search. Examples: ['pdf'], ['md', 'txt']. Empty to search all file types."
},
"importance": {
"type": ["boolean", "null"],
"description": "Filter by document importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing."
},
"is_email_attachment": {
"type": ["boolean", "null"],
"description": "Filter by email attachment status. true = only email attachments, false = only non-email attachments, None = both."
},
"notification_filters": {
"$ref": "#/components/schemas/NotificationFilters",
"description": "Filter by document notification state."
},
"owners": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by document owner principal — a user ('macro|[email protected]'), a bot\n('bot|<uuid>'), or a team (a bare hyphenated uuid). Examples:\n['macro|[email protected]'], ['macro|[email protected]', 'bot|0199...']. Empty to\nsearch all owners."
},
"project_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of project ids to search within. Examples: ['project1'].\nfiltering. Empty to ignore project filtering."
},
"sub_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by document sub type. Examples: ['task']. Empty to search all sub types."
},
"task_filters": {
"$ref": "#/components/schemas/TaskFilters",
"description": "Task-specific filters that only apply to task subtype documents."
}
}
},
"DocumentId": {
"type": "string",
"description": "A validated document identifier. Historical document ids need not be UUIDs."
},
"DocumentInteractionMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::Interaction`].",
"required": ["document_id", "reason"],
"properties": {
"document_id": {
"type": "string",
"description": "The id of the document."
},
"reason": {
"$ref": "#/components/schemas/InteractionReason",
"description": "What triggered this interaction."
}
}
},
"DocumentMetadata": {
"type": "object",
"required": [
"documentId",
"documentVersionId",
"owner",
"documentName"
],
"properties": {
"branchedFromId": {
"type": ["string", "null"],
"description": "The id of the document this document branched from"
},
"branchedFromVersionId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The id of the version this document branched from\nThis could be either DocumentInstance or DocumentBom id depending on\nthe file type"
},
"createdAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document was created"
},
"deletedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document was deleted"
},
"documentBom": {
"type": ["array", "null"],
"items": {
"$ref": "#/components/schemas/BomPart"
},
"description": "If the document is a DOCX document and unzipped, the document_bom will be present"
},
"documentFamilyId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The id of the document family this document belongs to"
},
"documentId": {
"type": "string",
"description": "The document id"
},
"documentName": {
"type": "string",
"description": "The name of the document"
},
"documentVersionId": {
"type": "integer",
"format": "int64",
"description": "The version of the document\nThis could be the document_instance_id or document_bom_id depending on\nthe file type"
},
"fileType": {
"type": ["string", "null"],
"description": "The file type of the document (file extension)"
},
"modificationData": {
"description": "The modification data for the document instance.\nThis is only used for PDF documents."
},
"owner": {
"type": "string",
"description": "The owner of the document"
},
"projectId": {
"type": ["string", "null"],
"description": "The id of the project that this document belongs to"
},
"projectName": {
"type": ["string", "null"],
"description": "The name of the project that this document belongs to"
},
"sha": {
"type": ["string", "null"],
"description": "If the document is a PDF, this is the SHA of the pdf\nIf the document is a DOCX, this will not be present"
},
"subType": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentSubType",
"description": "The sub type of the document if present."
}
]
},
"updatedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document instance / document BOM was updated"
}
}
},
"DocumentMetadataWithContent": {
"allOf": [
{
"$ref": "#/components/schemas/DocumentMetadata",
"description": "Legacy document metadata."
},
{
"type": "object",
"required": ["content"],
"properties": {
"content": {
"$ref": "#/components/schemas/DocumentContent",
"description": "Content lifecycle and location metadata."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The team this task number is scoped to, for task documents."
},
"teamTaskId": {
"type": ["integer", "null"],
"format": "int32",
"description": "The task number assigned within the team, for task documents."
}
}
}
],
"description": "Full document metadata plus content lifecycle metadata."
},
"DocumentPermissionsToken": {
"type": "object",
"required": ["document_id", "access_level", "exp", "iss"],
"properties": {
"access_level": {
"$ref": "#/components/schemas/AccessLevel",
"description": "The access level of the user for the document"
},
"document_id": {
"type": "string",
"description": "The document id"
},
"exp": {
"type": "integer",
"description": "The expiration time of the token",
"minimum": 0
},
"iss": {
"type": "string",
"description": "The issuer of the token"
},
"user_id": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The users id if present"
}
]
}
}
},
"DocumentPermissionsTokenRequest": {
"type": "object",
"required": ["token"],
"properties": {
"token": {
"type": "string",
"description": "The encoded document permissions token"
}
}
},
"DocumentPermissionsTokenResponse": {
"type": "object",
"required": ["token"],
"properties": {
"token": {
"type": "string",
"description": "The encoded document permissions token"
}
}
},
"DocumentPreview": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/DocumentPreviewData"
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["access"]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/WithDocumentId"
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["no_access"]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/WithDocumentId"
},
{
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["does_not_exist"]
}
}
}
]
}
]
},
"DocumentPreviewData": {
"type": "object",
"required": ["document_id", "document_name", "owner"],
"properties": {
"document_id": {
"type": "string",
"description": "The document id"
},
"document_name": {
"type": "string",
"description": "The name of the document"
},
"file_type": {
"type": ["string", "null"],
"description": "The file type of the document (e.g. pdf, docx)"
},
"owner": {
"type": "string",
"description": "The id of the owner of the document"
},
"sub_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentPreviewDataSubType",
"description": "The sub type of the document if present.\nTask-related properties are encoded within the variant."
}
]
},
"updated_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document was last updated"
}
}
},
"DocumentPreviewDataSubType": {
"oneOf": [
{
"type": "object",
"description": "A task document with completion status",
"required": ["is_completed", "type"],
"properties": {
"is_completed": {
"type": "boolean",
"description": "Whether the task is completed.\nTrue if the Status property is set to \"Completed\"."
},
"type": {
"type": "string",
"enum": ["task"]
}
}
},
{
"type": "object",
"description": "A snippet document — reusable markdown",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["snippet"]
}
}
},
{
"type": "object",
"description": "A skill document — markdown instructions for AI",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["skill"]
}
}
},
{
"type": "object",
"description": "The description document of an initiative",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"enum": ["initiative_description"]
}
}
}
],
"description": "The sub type of a document preview with associated properties.\nTask-related properties are encoded within the variant to ensure valid states."
},
"DocumentPurgedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::Purged`].",
"required": ["document_id"],
"properties": {
"document_id": {
"type": "string",
"description": "The id of the hard-deleted document."
}
}
},
"DocumentResponse": {
"type": "object",
"description": "Document response with content lifecycle metadata.",
"required": ["documentMetadata"],
"properties": {
"documentMetadata": {
"$ref": "#/components/schemas/DocumentResponseMetadataWithContent",
"description": "The document metadata."
},
"presignedUrl": {
"type": ["string", "null"],
"description": "Presigned upload URL, when the caller still needs to upload bytes."
}
}
},
"DocumentResponseMetadata": {
"type": "object",
"required": [
"documentId",
"documentVersionId",
"owner",
"documentName"
],
"properties": {
"branchedFromId": {
"type": ["string", "null"],
"description": "The id of the document this document branched from"
},
"branchedFromVersionId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The id of the version this document branched from\nThis could be either DocumentInstance or DocumentBom id depending on\nthe file type"
},
"createdAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document was created"
},
"documentBom": {
"type": ["array", "null"],
"items": {
"$ref": "#/components/schemas/BomPart"
},
"description": "If the document is a DOCX document, the document_bom will be present"
},
"documentFamilyId": {
"type": ["integer", "null"],
"format": "int64",
"description": "The id of the document family this document belongs to"
},
"documentId": {
"type": "string",
"description": "The document id"
},
"documentName": {
"type": "string",
"description": "The name of the document"
},
"documentVersionId": {
"type": "integer",
"format": "int64",
"description": "The version of the document\nThis could be the document_instance_id or document_bom_id depending on\nthe file type"
},
"fileType": {
"type": ["string", "null"],
"description": "The file type of the document"
},
"modificationData": {
"description": "The modification data for the document instance.\nThis is only used for PDF documents."
},
"owner": {
"type": "string",
"description": "The owner of the document"
},
"sha": {
"type": ["string", "null"],
"description": "If the document is a PDF, this is the SHA of the pdf\nIf the document is a DOCX, this will not be present"
},
"subType": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DocumentSubType",
"description": "The sub type of the document if present."
}
]
},
"updatedAt": {
"type": ["string", "null"],
"format": "date-time",
"description": "The time the document instance / document BOM was updated"
}
}
},
"DocumentResponseMetadataWithContent": {
"allOf": [
{
"$ref": "#/components/schemas/DocumentResponseMetadata",
"description": "Legacy create/copy response metadata."
},
{
"type": "object",
"required": ["content"],
"properties": {
"content": {
"$ref": "#/components/schemas/DocumentContent",
"description": "Content lifecycle and location metadata."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The team this task number is scoped to, for task documents."
},
"teamTaskId": {
"type": ["integer", "null"],
"format": "int32",
"description": "The task number assigned within the team, for task documents."
}
}
}
],
"description": "Create/copy response metadata plus content lifecycle metadata."
},
"DocumentStorageServiceApiVersion": {
"type": "string",
"enum": ["v1", "v2"]
},
"DocumentSubType": {
"type": "string",
"description": "The document sub type enum represents all values of document sub types.\nThese values should match the `document_sub_type_value` table in macrodb.\n\nWire, database, and `Display` spellings are all `snake_case` so a\nmulti-word variant serializes identically in every system.",
"enum": ["task", "snippet", "skill", "initiative_description"]
},
"DocumentSyncContentUpdatedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::SyncContentUpdated`].",
"required": ["document_id", "file_type"],
"properties": {
"actor": {
"type": ["string", "null"],
"description": "Legacy single-editor attribution; newer Sync callers send `editors`."
},
"document_id": {
"type": "string",
"description": "The id of the live-collab document whose content changed."
},
"document_version_id": {
"type": ["string", "null"],
"description": "Version marker for the sync snapshot, when the caller supplies one."
},
"editors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentSyncEditor"
},
"description": "Distinct editors since the preceding snapshot notification."
},
"file_type": {
"$ref": "#/components/schemas/FileType",
"description": "File type of the sync document, resolved by the document backend."
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The user whose feed this edit belongs on, when different from\n[`Self::actor`]."
}
]
}
}
},
"DocumentSyncEditor": {
"type": "object",
"description": "An editor reported by Sync from an authenticated session.",
"required": ["actor"],
"properties": {
"actor": {
"type": "string",
"description": "User or bot that performed the edit."
},
"agent_correlation_id": {
"type": ["string", "null"],
"format": "uuid",
"description": "Invocation from the editor's signed document grant."
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "User represented by an agent, if any."
}
]
}
}
},
"DocumentTeamShareResponse": {
"type": "object",
"description": "The team-share state of a document. The team is resolved from the document\nowner's team membership.",
"required": ["sharedWithTeam"],
"properties": {
"sharedWithTeam": {
"type": "boolean",
"description": "Whether explicit team sharing is enabled; inherited team access does not count."
},
"teamId": {
"type": ["string", "null"],
"format": "uuid",
"description": "The owner's team the document is (or would be) shared with. `None` when\nthe owner does not belong to a team."
}
}
},
"DocumentTextContent": {
"type": "object",
"description": "Text representation when the document supports one. Other file formats\nretain their existing download/export behavior.",
"required": ["text"],
"properties": {
"text": {
"type": ["string", "null"],
"description": "Current Markdown, or extracted PDF/Word text. Null means use file export."
}
}
},
"DocumentTopicEvent": {
"oneOf": [
{
"type": "object",
"description": "A document was created.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.created"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentCreatedMetadata",
"description": "A document was created."
}
}
},
{
"type": "object",
"description": "A document's metadata / permissions were updated.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.updated"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentUpdatedMetadata",
"description": "A document's metadata / permissions were updated."
}
}
},
{
"type": "object",
"description": "A document was soft-deleted.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.deleted"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentDeletedMetadata",
"description": "A document was soft-deleted."
}
}
},
{
"type": "object",
"description": "The document's stored bytes were (re)written to S3.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.content_uploaded"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentContentUploadedMetadata",
"description": "The document's stored bytes were (re)written to S3."
}
}
},
{
"type": "object",
"description": "A live-collab (sync) document's content changed and should be re-extracted.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.sync_content_updated"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentSyncContentUpdatedMetadata",
"description": "A live-collab (sync) document's content changed and should be re-extracted."
}
}
},
{
"type": "object",
"description": "The document row was permanently deleted (hard delete).",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.purged"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentPurgedMetadata",
"description": "The document row was permanently deleted (hard delete)."
}
}
},
{
"type": "object",
"description": "A document was copied.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.copied"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentCopiedMetadata",
"description": "A document was copied."
}
}
},
{
"type": "object",
"description": "A peer joined, left, or a periodic save occurred.",
"required": ["metadata", "event_type"],
"properties": {
"event_type": {
"type": "string",
"enum": ["document.interaction"]
},
"metadata": {
"$ref": "#/components/schemas/DocumentInteractionMetadata",
"description": "A peer joined, left, or a periodic save occurred."
}
}
}
],
"description": "Events that can be published to [`MacroDocumentsTopic`]."
},
"DocumentUpdatedMetadata": {
"type": "object",
"description": "Metadata for [`DocumentTopicEvent::Updated`].",
"required": ["document_id", "owner", "share_permission_updated"],
"properties": {
"actor": {
"type": ["string", "null"],
"description": "Who mechanically updated the document. Absent on events published\nbefore attribution, and on user-receipt writes (ingest then uses\n[`Self::actor_user_id`])."
},
"actor_user_id": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The authenticated user who performed the update; `None` for\nunauthenticated or internal callers."
}
]
},
"document_id": {
"type": "string",
"description": "The id of the updated document."
},
"document_name": {
"type": ["string", "null"],
"description": "New (cleaned) document name; `None` when unchanged."
},
"file_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/FileTypeUpdate",
"description": "Requested file type change; `None` when unchanged."
}
]
},
"on_behalf_of": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/MacroUserIdStr",
"description": "The user whose feed this update belongs on, when different from\n[`Self::actor`]."
}
]
},
"owner": {
"type": "string",
"description": "The owner of the document."
},
"previous_project_id": {
"type": ["string", "null"],
"description": "Project id before the update."
},
"project_id": {
"type": ["string", "null"],
"description": "New project id; `None` when unchanged, `Some(\"\")` when removed from\nits project (mirrors the edit repo args semantics)."
},
"share_permission_updated": {
"type": "boolean",
"description": "Whether share permissions were updated."
}
}
},
"DuplicateDatabaseRequest": {
"type": "object",
"description": "Request body for duplicating a database.",
"properties": {
"name": {
"type": ["string", "null"],
"description": "The copy's name; left out, \"<name> copy\"."
}
}
},
"EditAnchorRequest": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/EditPdfAnchorRequest"
},
{
"type": "object",
"required": ["fileType"],
"properties": {
"fileType": {
"type": "string",
"enum": ["pdf"]
}
}
}
]
}
]
},
"EditAnchorResponse": {
"allOf": [
{
"$ref": "#/components/schemas/Anchor"
},
{
"type": "object",
"required": ["documentId"],
"properties": {
"documentId": {
"type": "string"
}
}
}
]
},
"EditCallRecordRequest": {
"type": "object",
"description": "Edit call request, as supplied by inbound callers.",
"properties": {
"customName": {
"type": ["string", "null"],
"description": "Updated user-supplied display name for the call. `None` is a no-op;\n`Some(\"\")` clears `call_records.custom_name`; any other `Some(s)`\noverwrites it with `s`. Only the archived `call_records` row carries\nthis column — patching while the call is still active is a no-op for\nthis field."
},
"sharePermission": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/UpdateSharePermissionRequestV2",
"description": "Updated share permissions. `teamShareAccessLevel` shares the call with\nthe creator's team and only accepts `view` or `null` (revoke). While\nthe call is live it sets the pending share-with-team toggle, which is\napplied when the call is archived; afterwards only the call's creator\nmay change it."
}
]
},
"shareWithTeam": {
"type": ["boolean", "null"],
"description": "Deprecated alias for `sharePermission.teamShareAccessLevel`:\n`Some(true)` behaves like `\"view\"`, `Some(false)` like `null`, and\n`None` is a no-op. Supplying both with disagreeing values is rejected.\nThe team is resolved from the call's `created_by`, not the acting user."
}
}
},
"EditCallTranscriptRequest": {
"type": "object",
"description": "Body of `PATCH /call/record/{call_id}/transcript`.\n\nEach entry in `assignments` sets (or clears, when `custom_speaker` is\n`None`) the `custom_speaker` override for every transcript row in the\ncall whose `diarized_speaker_id` matches. Diarized speakers not listed\nare left untouched. Empty `assignments` is a 204 no-op.",
"required": ["assignments"],
"properties": {
"assignments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomSpeakerAssignment"
},
"description": "The set of per-diarized-speaker overrides to apply."
}
}
},
"EditDocumentResponse": {
"type": "object",
"description": "Edit document response.",
"required": ["error", "data"],
"properties": {
"data": {
"$ref": "#/components/schemas/GenericSuccessResponse",
"description": "The response data."
},
"error": {
"type": "boolean",
"description": "Whether an error occurred."
}
}
},
"EditDocumentServiceArgs": {
"type": "object",
"description": "Arguments for the edit_document service call.",
"properties": {
"documentName": {
"type": ["string", "null"],
"description": "The name of the document."
},
"fileType": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/FileTypeUpdate",
"description": "The new file type for the document (null to clear)."
}
]
},
"projectId": {
"type": ["string", "null"],
"description": "The new project id of the document."
},
"sharePermission": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/UpdateSharePermissionRequestV2",
"description": "Updated share permissions for the document."
}
]
}
}
},
"EditOp": {
"oneOf": [
{
"type": "object",
"description": "Replaces all text of a shape (`\\n` separates paragraphs, `\\u{b}` is a line\nbreak), keeping the formatting of the first run of each paragraph.",
"required": ["slide", "shape", "text", "op"],
"properties": {
"cell": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellRef",
"description": "Table cell whose text to edit (the shape must be a table)."
}
]
},
"op": {
"type": "string",
"enum": ["setText"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"text": {
"type": "string",
"description": "New text."
}
}
},
{
"type": "object",
"description": "Inserts text at a position (`\\n` splits paragraphs).",
"required": ["slide", "shape", "at", "text", "op"],
"properties": {
"at": {
"$ref": "#/components/schemas/TextPos",
"description": "Where to insert."
},
"cell": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellRef",
"description": "Table cell whose text to edit (the shape must be a table)."
}
]
},
"op": {
"type": "string",
"enum": ["insertText"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"text": {
"type": "string",
"description": "Text to insert."
}
}
},
{
"type": "object",
"description": "Deletes text between two positions (may span paragraphs).",
"required": ["slide", "shape", "start", "end", "op"],
"properties": {
"cell": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellRef",
"description": "Table cell whose text to edit (the shape must be a table)."
}
]
},
"end": {
"$ref": "#/components/schemas/TextPos",
"description": "End (exclusive)."
},
"op": {
"type": "string",
"enum": ["deleteText"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"start": {
"$ref": "#/components/schemas/TextPos",
"description": "Start (inclusive)."
}
}
},
{
"type": "object",
"description": "Applies character formatting to a range (whole shape when omitted).",
"required": ["slide", "shape", "props", "op"],
"properties": {
"cell": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellRef",
"description": "Table cell whose text to edit (the shape must be a table)."
}
]
},
"end": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/TextPos",
"description": "End of the range."
}
]
},
"op": {
"type": "string",
"enum": ["formatText"]
},
"props": {
"$ref": "#/components/schemas/RunPatch",
"description": "Changes."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"start": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/TextPos",
"description": "Start of the range."
}
]
}
}
},
{
"type": "object",
"description": "Applies paragraph formatting to paragraphs `from..=to` (all when omitted).",
"required": ["slide", "shape", "props", "op"],
"properties": {
"cell": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellRef",
"description": "Table cell whose text to edit (the shape must be a table)."
}
]
},
"from": {
"type": ["integer", "null"],
"description": "First paragraph.",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["formatParagraphs"]
},
"props": {
"$ref": "#/components/schemas/ParaPatch",
"description": "Changes."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"to": {
"type": ["integer", "null"],
"description": "Last paragraph.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Changes text box properties.",
"required": ["slide", "shape", "props", "op"],
"properties": {
"cell": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellRef",
"description": "Table cell whose text to edit (the shape must be a table)."
}
]
},
"op": {
"type": "string",
"enum": ["formatBody"]
},
"props": {
"$ref": "#/components/schemas/BodyPatch",
"description": "Changes."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Moves, resizes, rotates, or flips a shape (omitted fields stay).\nValues are in slide space, also for group members (as the outline\nreports them); their group grows or shrinks to fit.",
"required": ["slide", "shape", "op"],
"properties": {
"flipH": {
"type": ["boolean", "null"],
"description": "Horizontal flip."
},
"flipV": {
"type": ["boolean", "null"],
"description": "Vertical flip."
},
"h": {
"type": ["number", "null"],
"format": "float",
"description": "Height (points)."
},
"op": {
"type": "string",
"enum": ["setTransform"]
},
"rotation": {
"type": ["number", "null"],
"format": "float",
"description": "Rotation in degrees."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"w": {
"type": ["number", "null"],
"format": "float",
"description": "Width (points)."
},
"x": {
"type": ["number", "null"],
"format": "float",
"description": "Left (points)."
},
"y": {
"type": ["number", "null"],
"format": "float",
"description": "Top (points)."
}
}
},
{
"type": "object",
"description": "Sets a shape's fill.",
"required": ["slide", "shape", "fill", "op"],
"properties": {
"fill": {
"$ref": "#/components/schemas/FillSpec",
"description": "The fill."
},
"op": {
"type": "string",
"enum": ["setFill"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Changes a shape's outline.",
"required": ["slide", "shape", "line", "op"],
"properties": {
"line": {
"$ref": "#/components/schemas/LinePatch",
"description": "Changes."
},
"op": {
"type": "string",
"enum": ["setLine"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Changes a shape's preset geometry.",
"required": ["slide", "shape", "preset", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["setGeometry"]
},
"preset": {
"type": "string",
"description": "Preset name."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Adds a shape (its id is reported in the result).",
"required": ["slide", "shape", "x", "y", "w", "h", "op"],
"properties": {
"h": {
"type": "number",
"format": "float",
"description": "Height (points)."
},
"op": {
"type": "string",
"enum": ["addShape"]
},
"shape": {
"$ref": "#/components/schemas/NewShape",
"description": "What to add."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"w": {
"type": "number",
"format": "float",
"description": "Width (points)."
},
"x": {
"type": "number",
"format": "float",
"description": "Left (points)."
},
"y": {
"type": "number",
"format": "float",
"description": "Top (points)."
}
}
},
{
"type": "object",
"description": "Deletes a shape.",
"required": ["slide", "shape", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["deleteShape"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Duplicates a shape, offset by (dx, dy) points.",
"required": ["slide", "shape", "op"],
"properties": {
"dx": {
"type": "number",
"format": "float",
"description": "Horizontal offset."
},
"dy": {
"type": "number",
"format": "float",
"description": "Vertical offset."
},
"op": {
"type": "string",
"enum": ["duplicateShape"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Changes a shape's z-order.",
"required": ["slide", "shape", "to", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["reorderShape"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"to": {
"$ref": "#/components/schemas/ZOrder",
"description": "Where to move it."
}
}
},
{
"type": "object",
"description": "Replaces a picture's image.",
"required": ["slide", "shape", "data", "op"],
"properties": {
"data": {
"type": "string",
"description": "Base64-encoded PNG, JPEG, or GIF bytes."
},
"op": {
"type": "string",
"enum": ["replaceImage"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Sets the text of a table cell.",
"required": ["slide", "shape", "row", "col", "text", "op"],
"properties": {
"col": {
"type": "integer",
"description": "Column.",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["setCellText"]
},
"row": {
"type": "integer",
"description": "Row.",
"minimum": 0
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"text": {
"type": "string",
"description": "Text."
}
}
},
{
"type": "object",
"description": "Inserts a table row (copying the formatting of an adjacent row).",
"required": ["slide", "shape", "at", "op"],
"properties": {
"at": {
"type": "integer",
"description": "Index of the new row.",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["insertTableRow"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Deletes a table row.",
"required": ["slide", "shape", "row", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["deleteTableRow"]
},
"row": {
"type": "integer",
"description": "Row index.",
"minimum": 0
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Inserts a table column (copying the formatting of an adjacent column).",
"required": ["slide", "shape", "at", "op"],
"properties": {
"at": {
"type": "integer",
"description": "Index of the new column.",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["insertTableColumn"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Deletes a table column.",
"required": ["slide", "shape", "col", "op"],
"properties": {
"col": {
"type": "integer",
"description": "Column index.",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["deleteTableColumn"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Merges the rectangle of table cells between two corners into one cell.\nThe top-left cell keeps its formatting; the text of the other cells is\nappended to it as paragraphs. Merged cells already inside the rectangle\nare absorbed; a rectangle that cuts through a merged cell is rejected.",
"required": ["slide", "shape", "from", "to", "op"],
"properties": {
"from": {
"$ref": "#/components/schemas/CellRef",
"description": "One corner of the rectangle."
},
"op": {
"type": "string",
"enum": ["mergeCells"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"to": {
"$ref": "#/components/schemas/CellRef",
"description": "The opposite corner."
}
}
},
{
"type": "object",
"description": "Splits a merged cell back into the grid cells it covers. The revealed\ncells are empty and take the merged cell's fill and outer borders.",
"required": ["slide", "shape", "cell", "op"],
"properties": {
"cell": {
"$ref": "#/components/schemas/CellRef",
"description": "Any grid cell the merged cell covers."
},
"op": {
"type": "string",
"enum": ["splitCell"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Formats the table cells in the rectangle between two corners (widened\nto whole merged cells). Omitted fields stay unchanged.",
"required": ["slide", "shape", "from", "to", "op"],
"properties": {
"anchor": {
"type": ["string", "null"],
"description": "Vertical text alignment: `top`, `middle`, or `bottom`."
},
"borders": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CellBorders",
"description": "Borders to change."
}
]
},
"fill": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/FillSpec",
"description": "Cell fill (`{\"kind\":\"none\"}` = no fill, so the table background shows)."
}
]
},
"from": {
"$ref": "#/components/schemas/CellRef",
"description": "One corner of the rectangle."
},
"margins": {
"type": ["array", "null"],
"items": {
"type": "number",
"format": "float"
},
"description": "Cell margins `[left, top, right, bottom]` in points."
},
"op": {
"type": "string",
"enum": ["formatCells"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"to": {
"$ref": "#/components/schemas/CellRef",
"description": "The opposite corner."
}
}
},
{
"type": "object",
"description": "Sets a table's style and which of its parts the style emphasizes\n(omitted fields stay unchanged). Applying a different style clears\nfills and borders set directly on cells, as PowerPoint does, so the\ntable shows the new style.",
"required": ["slide", "shape", "op"],
"properties": {
"bandCol": {
"type": ["boolean", "null"],
"description": "Alternate the shading of columns."
},
"bandRow": {
"type": ["boolean", "null"],
"description": "Alternate the shading of rows."
},
"firstCol": {
"type": ["boolean", "null"],
"description": "Emphasize the first column."
},
"firstRow": {
"type": ["boolean", "null"],
"description": "Emphasize the first (header) row."
},
"lastCol": {
"type": ["boolean", "null"],
"description": "Emphasize the last column."
},
"lastRow": {
"type": ["boolean", "null"],
"description": "Emphasize the last (total) row."
},
"op": {
"type": "string",
"enum": ["setTableStyle"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"style": {
"type": ["string", "null"],
"description": "Style id (a GUID from the deck outline's `tableStyles`, e.g.\n`{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` = Medium Style 2 - Accent 1),\nor `\"\"` for no style."
}
}
},
{
"type": "object",
"description": "Sets table column widths and minimum row heights in points (rows still\ngrow to fit their text). The frame is resized to match.",
"required": ["slide", "shape", "op"],
"properties": {
"columnWidths": {
"type": ["array", "null"],
"items": {
"type": "number",
"format": "float"
},
"description": "One width per column."
},
"op": {
"type": "string",
"enum": ["setTableGrid"]
},
"rowHeights": {
"type": ["array", "null"],
"items": {
"type": "number",
"format": "float"
},
"description": "One minimum height per row."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Adds a slide based on a layout (its id is reported in the result).",
"required": ["op"],
"properties": {
"after": {
"type": ["integer", "null"],
"format": "int32",
"description": "Insert after this slide (end of deck when omitted).",
"minimum": 0
},
"body": {
"type": ["string", "null"],
"description": "Body placeholder text (`\\n` separates paragraphs)."
},
"layout": {
"type": ["string", "null"],
"description": "Layout name (e.g. \"Title and Content\"); defaults to the layout of the reference slide."
},
"op": {
"type": "string",
"enum": ["addSlide"]
},
"title": {
"type": ["string", "null"],
"description": "Title placeholder text."
}
}
},
{
"type": "object",
"description": "Duplicates a slide right after itself.",
"required": ["slide", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["duplicateSlide"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Deletes a slide.",
"required": ["slide", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["deleteSlide"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Moves a slide to a 0-based position.",
"required": ["slide", "to", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["moveSlide"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"to": {
"type": "integer",
"description": "New index.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Hides or shows a slide in slideshows.",
"required": ["slide", "hidden", "op"],
"properties": {
"hidden": {
"type": "boolean",
"description": "Hidden."
},
"op": {
"type": "string",
"enum": ["setSlideHidden"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Replaces the speaker notes of a slide.",
"required": ["slide", "text", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["setNotes"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"text": {
"type": "string",
"description": "Notes text (`\\n` separates paragraphs)."
}
}
},
{
"type": "object",
"description": "Sets a slide's background.",
"required": ["slide", "op"],
"properties": {
"fill": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/FillSpec",
"description": "The fill (`None` removes the override, inheriting the layout background)."
}
]
},
"op": {
"type": "string",
"enum": ["setBackground"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Replaces a chart's categories and series (the chart must be `editable`\nin the outline). Existing series keep their formatting; new series\ncopy the last one's with the next theme accent color. The embedded\nworkbook is rewritten to match.",
"required": ["slide", "shape", "categories", "series", "op"],
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Category labels."
},
"op": {
"type": "string",
"enum": ["setChartData"]
},
"series": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChartSeriesData"
},
"description": "Series in plot order (one value per category)."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Changes a chart's type (the chart must be `editable` in the outline).",
"required": ["slide", "shape", "kind", "op"],
"properties": {
"grouping": {
"type": ["string", "null"],
"description": "`clustered`, `stacked`, `percentStacked`, or `standard` (kept or the type's default when omitted)."
},
"kind": {
"type": "string",
"description": "`bar` (horizontal), `column`, `line`, `pie`, `doughnut`, or `area`."
},
"op": {
"type": "string",
"enum": ["setChartType"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Changes a chart's title, legend, data labels, or series colors (omitted fields stay).",
"required": ["slide", "shape", "op"],
"properties": {
"dataLabels": {
"type": ["boolean", "null"],
"description": "Show or hide value data labels on every series."
},
"legend": {
"type": ["string", "null"],
"description": "Legend position: `right`, `left`, `top`, `bottom`, `topRight`, or `none`."
},
"op": {
"type": "string",
"enum": ["formatChart"]
},
"seriesColors": {
"type": ["array", "null"],
"items": {
"$ref": "#/components/schemas/ChartSeriesColor"
},
"description": "Series colors."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Graphic frame id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"title": {
"type": ["string", "null"],
"description": "Title text (`\"\"` removes the title)."
}
}
},
{
"type": "object",
"description": "Groups two or more shapes that share a parent (usually top-level\nshapes) into a new group placed at the z-position of the topmost of\nthem. They keep their order and exactly where they are. The group's id\nis reported in the result. Placeholders cannot be grouped.",
"required": ["slide", "shapes", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["groupShapes"]
},
"shapes": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Ids of the shapes to group (at least two)."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Ungroups a group: its members take its place in the z-order and keep\nexactly where and how they appear (the group's offset, scale,\nrotation, and flips are applied to each). The members' ids are\nreported in the result, back to front.",
"required": ["slide", "shape", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["ungroupShape"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Group id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Pastes shapes copied with `copyShapes` (from this or another\npresentation) on top of a slide, with fresh ids, offset by (dx, dy)\npoints. Pictures, media, charts, and links come along. Theme colors,\ntheme fonts, and style references take this presentation's theme\n(PowerPoint's \"Use Destination Theme\"). The new top-level shape ids are\nreported in the result, back to front.",
"required": ["slide", "payload", "op"],
"properties": {
"dx": {
"type": "number",
"format": "float",
"description": "Horizontal offset in points."
},
"dy": {
"type": "number",
"format": "float",
"description": "Vertical offset in points."
},
"op": {
"type": "string",
"enum": ["pasteShapes"]
},
"payload": {
"type": "string",
"description": "The clipboard payload JSON returned by `copyShapes`."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Pastes slides copied with `copySlides` (from this or another\npresentation), with their speaker notes. Each slide takes this deck's\nlayout of the same name, else the first with the same placeholder\ntypes, else \"Title and Content\", else the first layout; theme colors\nand fonts follow this deck's theme. New slide ids are reported in the\nresult, in order.",
"required": ["payload", "op"],
"properties": {
"after": {
"type": ["integer", "null"],
"format": "int32",
"description": "Insert after this slide (end of deck when omitted).",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["pasteSlides"]
},
"payload": {
"type": "string",
"description": "The clipboard payload JSON returned by `copySlides`."
}
}
},
{
"type": "object",
"description": "Changes a slide's layout. Placeholders are matched to the new layout's\nplaceholders by type and index and take their position; placeholders\nwithout a match stay where they are. Content is kept, and the new\nlayout's other placeholders are added empty.",
"required": ["slide", "layout", "op"],
"properties": {
"layout": {
"type": "string",
"description": "Layout name (e.g. \"Title Only\"), as listed in the deck's layouts."
},
"op": {
"type": "string",
"enum": ["setSlideLayout"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Sets the transition into a slide. Omitted fields keep the slide's\ncurrent value, or take the effect's default for a new transition.",
"required": ["slide", "kind", "op"],
"properties": {
"advanceAfterMs": {
"type": ["integer", "null"],
"format": "int32",
"description": "Advance automatically after this many milliseconds; `0` turns\nautomatic advance off, and an omitted (or null) field keeps the\ncurrent setting.",
"minimum": 0
},
"advanceOnClick": {
"type": ["boolean", "null"],
"description": "Whether a click advances to the next slide."
},
"applyToAll": {
"type": "boolean",
"description": "Give every slide of the deck the resulting transition."
},
"direction": {
"type": ["string", "null"],
"description": "Effect option: `fade`: `smooth` or `black`; `push`, `wipe`: `l`,\n`r`, `u`, `d`; `cover`, `uncover`: those or `lu`, `ru`, `ld`, `rd`;\n`split`: `horzOut`, `horzIn`, `vertOut`, `vertIn`; `reveal`: `l`,\n`r`; `randomBar`: `horz`, `vert`; `shape`: `circle`, `diamond`,\n`plus`; `zoom`: `in`, `out`; `morph`: `byObject`, `byWord`,\n`byChar`. Directions are the OOXML `dir` values."
},
"durationMs": {
"type": ["integer", "null"],
"format": "int32",
"description": "Duration in milliseconds (at most 60000).",
"minimum": 0
},
"kind": {
"type": "string",
"description": "Effect: `none` (removes the transition), `cut`, `fade`, `push`,\n`wipe`, `split`, `reveal`, `randomBar`, `shape`, `uncover`,\n`cover`, `zoom`, `dissolve`, `flash`, or `morph`."
},
"op": {
"type": "string",
"enum": ["setTransition"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Replaces a slide's animations (its main sequence, which plays as the\npresenter clicks through the slide) with these, in playback order;\n`[]` removes them all. An entry matching an animation the slide has\n(same shape, class, effect, and paragraph, and direction when given)\nkeeps it, with its other settings unless the entry gives them, so\nlisting the current animations in a new order reorders them.\nAnimations started by clicking a shape (triggers) are kept.",
"required": ["slide", "animations", "op"],
"properties": {
"animations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AnimationSpec"
},
"description": "Animations in playback order."
},
"op": {
"type": "string",
"enum": ["setAnimations"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Adds a new animation to a slide's sequence.",
"required": ["slide", "animation", "op"],
"properties": {
"animation": {
"$ref": "#/components/schemas/AnimationSpec",
"description": "The animation."
},
"index": {
"type": ["integer", "null"],
"description": "0-based position in playback order (the end when omitted).",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["addAnimation"]
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Removes animations from a slide's sequence: every animation of the\nlisted shapes and the animations at the listed playback positions.\nGive at least one of the lists (`setAnimations` with `[]` removes all).",
"required": ["slide", "op"],
"properties": {
"indexes": {
"type": ["array", "null"],
"items": {
"type": "integer",
"minimum": 0
},
"description": "0-based playback positions to remove."
},
"op": {
"type": "string",
"enum": ["removeAnimations"]
},
"shapeIds": {
"type": ["array", "null"],
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Shapes whose animations to remove."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Replaces text in shapes, group members, and table cells, on one slide\nor on every slide. A match may span differently formatted runs but not\nparagraphs; the replacement takes the formatting of the first matched\ncharacter. The number of replacements is reported in the result.",
"required": ["find", "replace", "op"],
"properties": {
"find": {
"type": "string",
"description": "Text to find (within one paragraph)."
},
"matchCase": {
"type": "boolean",
"description": "Match upper and lower case exactly (default: ignore case)."
},
"op": {
"type": "string",
"enum": ["replaceText"]
},
"replace": {
"type": "string",
"description": "Replacement text (may be empty; no paragraph or line breaks)."
},
"slide": {
"type": ["integer", "null"],
"format": "int32",
"description": "Slide id; omit to replace on every slide.",
"minimum": 0
},
"wholeWord": {
"type": "boolean",
"description": "Only match whole words (no letter, digit, or `_` on either side)."
}
}
},
{
"type": "object",
"description": "Sets a shape's alt text (its description for screen readers); `\"\"` removes it.",
"required": ["slide", "shape", "text", "op"],
"properties": {
"op": {
"type": "string",
"enum": ["setAltText"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"text": {
"type": "string",
"description": "Alt text."
}
}
},
{
"type": "object",
"description": "Renames a shape (the name shown in the selection pane).",
"required": ["slide", "shape", "name", "op"],
"properties": {
"name": {
"type": "string",
"description": "New name."
},
"op": {
"type": "string",
"enum": ["setShapeName"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Links whole shapes: clicking one in a slide show follows the link.\nLinks on text are set with formatText's `link`.",
"required": ["slide", "shapes", "link", "op"],
"properties": {
"link": {
"type": "string",
"description": "An address (`https://…`, `mailto:…`), `#slide=<id>`, a slide show\njump (`#nextslide`, `#previousslide`, `#firstslide`, `#lastslide`,\n`#lastslideviewed`, `#endshow`), or `\"\"` to remove the link."
},
"op": {
"type": "string",
"enum": ["setShapeLink"]
},
"shapes": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Shape ids."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"tip": {
"type": ["string", "null"],
"description": "The ScreenTip shown on hover."
}
}
},
{
"type": "object",
"description": "Hides or shows a shape (hidden shapes are not drawn).",
"required": ["slide", "shape", "hidden", "op"],
"properties": {
"hidden": {
"type": "boolean",
"description": "Hidden."
},
"op": {
"type": "string",
"enum": ["setShapeHidden"]
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Shape id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Format painter: gives shapes the look of another shape — its fill,\noutline, effects, theme style, and text margins and anchoring.\nCharacter and paragraph formatting are not copied (use formatText and\nformatParagraphs). Group targets paint every member.",
"required": ["slide", "shapes", "fromSlide", "fromShape", "op"],
"properties": {
"fromShape": {
"type": "integer",
"format": "int32",
"description": "Shape id to copy from (a shape, line, or picture).",
"minimum": 0
},
"fromSlide": {
"type": "integer",
"format": "int32",
"description": "Slide id of the shape to copy from.",
"minimum": 0
},
"op": {
"type": "string",
"enum": ["pasteFormat"]
},
"shapes": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Shape ids to restyle."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id of the shapes to restyle.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Crops a picture (PowerPoint's Crop). Edges are fractions of the\noriginal image: 0.1 crops 10% of its width (left, right) or height\n(top, bottom) off that edge, 0 shows the edge, and a negative value\nadds empty padding; omitted edges keep their current crop. The image\nkeeps its size and place on the slide, so the picture's frame moves\nand resizes to the part left visible. With `mode` (and no edges), the\nimage is instead cropped (`fill`) or padded (`fit`) to the frame's\naspect ratio, centered, and the frame stays. To crop to a shape, use\n`setGeometry` on the picture.",
"required": ["slide", "shape", "op"],
"properties": {
"bottom": {
"type": ["number", "null"],
"format": "float",
"description": "Fraction of the image's height cropped off its bottom edge."
},
"left": {
"type": ["number", "null"],
"format": "float",
"description": "Fraction of the image's width cropped off its left edge."
},
"mode": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CropMode",
"description": "`fill` or `fit` the frame's aspect ratio (instead of edges)."
}
]
},
"op": {
"type": "string",
"enum": ["cropPicture"]
},
"right": {
"type": ["number", "null"],
"format": "float",
"description": "Fraction of the image's width cropped off its right edge."
},
"shape": {
"type": "integer",
"format": "int32",
"description": "Picture id.",
"minimum": 0
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"top": {
"type": ["number", "null"],
"format": "float",
"description": "Fraction of the image's height cropped off its top edge."
}
}
},
{
"type": "object",
"description": "Adjusts pictures (PowerPoint's Corrections, Color, and Transparency).\nOmitted fields keep their current value.",
"required": ["slide", "shapes", "op"],
"properties": {
"brightness": {
"type": ["number", "null"],
"format": "float",
"description": "Brightness from -1 to 1 (0 = unchanged, 0.2 = +20%)."
},
"contrast": {
"type": ["number", "null"],
"format": "float",
"description": "Contrast from -1 to 1 (0 = unchanged)."
},
"op": {
"type": "string",
"enum": ["formatPicture"]
},
"recolor": {
"type": ["string", "null"],
"description": "Recolor: `none`, `grayscale`, `sepia`, `washout`, `blackWhite`\n(50% threshold), `blackWhite25`, `blackWhite75`,\n`duotone:<color>` (the image in dark shades of the color, on\nwhite), `duotoneLight:<color>` (in light shades of it, on black),\nor `duotone:<dark>,<light>` (black and white become these\ncolors). Colors are `RRGGBB` or theme names (`accent1`...)."
},
"reset": {
"type": "boolean",
"description": "First remove the crop (the frame grows back to the whole image at\nits current scale) and every adjustment; the other fields then\napply."
},
"shapes": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Ids of the pictures."
},
"slide": {
"type": "integer",
"format": "int32",
"description": "Slide id.",
"minimum": 0
},
"transparency": {
"type": ["number", "null"],
"format": "float",
"description": "Transparency from 0 (opaque) to 1."
}
}
File truncated at 1 MB.