{ "openapi": "3.1.0", "info": { "title": "Devias API", "version": "0.0.0", "description": "Metadata-driven operations platform: records, metadata, modules, workflows and a change feed." }, "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "Better Auth session cookie" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Workspace api key" } }, "schemas": { "Query": { "type": "object", "properties": { "object": { "type": "string", "minLength": 1 }, "select": { "type": "array", "items": { "type": "string" } }, "filter": { "$ref": "#/components/schemas/Filter" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/Sort" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "cursor": { "type": "string" }, "search": { "type": "string" }, "include": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "boolean", "enum": [true] }, { "type": "object", "properties": { "select": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "exclusiveMinimum": 0 } } } ] } }, "count": { "type": "boolean" } }, "required": ["object"] }, "Filter": { "anyOf": [ { "type": "object", "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": ["and"] }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": ["or"] }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/Filter" } }, "required": ["not"] }, { "$ref": "#/components/schemas/FilterCondition" } ] }, "FilterCondition": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "op": { "$ref": "#/components/schemas/FilterOp" }, "value": {} }, "required": ["field", "op"] }, "FilterOp": { "type": "string", "enum": [ "eq", "neq", "in", "not_in", "lt", "lte", "gt", "gte", "between", "contains", "starts_with", "is_empty", "is_not_empty", "any_of", "all_of" ] }, "Sort": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } }, "required": ["field"] }, "WorkspaceEvent": { "oneOf": [ { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["record.created", "record.updated", "record.deleted"] }, "objectId": { "type": "string" }, "object": { "type": "string" }, "recordId": { "type": "string" }, "changedFields": { "type": "array", "items": { "type": "string" } }, "importId": { "type": "string" } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "objectId", "object", "recordId"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["comment.created", "comment.updated", "comment.deleted"] }, "objectId": { "type": "string" }, "object": { "type": "string" }, "recordId": { "type": "string" }, "commentId": { "type": "string" } }, "required": [ "sequence", "workspaceId", "actor", "occurredAt", "type", "objectId", "object", "recordId", "commentId" ] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["metadata.changed"] }, "entity": { "type": "string", "enum": ["object", "field", "view", "layout", "nav_item", "command_item", "module"] }, "entityId": { "type": "string" }, "metadataVersion": { "type": "integer" } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "entity", "metadataVersion"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["module.applied"] }, "moduleId": { "type": "string" }, "version": { "type": "string" }, "metadataVersion": { "type": "integer" } }, "required": [ "sequence", "workspaceId", "actor", "occurredAt", "type", "moduleId", "version", "metadataVersion" ] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["workflow.changed"] }, "workflowId": { "type": "string" }, "action": { "type": "string", "enum": ["created", "updated", "deleted"] } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "workflowId", "action"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["workflow.run"] }, "workflowId": { "type": "string" }, "runId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "succeeded", "failed"] } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "workflowId", "runId", "status"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["document.changed"] }, "documentId": { "type": "string" }, "action": { "type": "string", "enum": ["created", "updated", "commented", "deleted"] } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "documentId", "action"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["task.changed"] }, "taskId": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "updated", "status_changed", "assigned", "commented", "work_changed", "run_started", "handed_in", "run_failed", "run_stopped", "run_retried", "deleted" ] }, "changes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "assignee": { "type": ["string", "null"] }, "runId": { "type": "string" } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "taskId", "action"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["module.connected", "module.disconnected", "module.connection.failed"] }, "moduleId": { "type": "string" }, "connectionId": { "type": "string" }, "providerId": { "type": "string" } }, "required": [ "sequence", "workspaceId", "actor", "occurredAt", "type", "moduleId", "connectionId", "providerId" ] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["module.event"] }, "moduleId": { "type": "string" }, "eventType": { "type": "string" }, "eventId": { "type": "string" } }, "required": ["sequence", "workspaceId", "actor", "occurredAt", "type", "moduleId", "eventType", "eventId"] }, { "type": "object", "properties": { "sequence": { "type": "integer" }, "workspaceId": { "type": "string" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "type": { "type": "string", "enum": ["notification.changed"] }, "recipientId": { "type": "string" }, "notificationId": { "type": ["string", "null"] }, "action": { "type": "string", "enum": ["created", "read", "deleted"] } }, "required": [ "sequence", "workspaceId", "actor", "occurredAt", "type", "recipientId", "notificationId", "action" ] } ] }, "Actor": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["user", "api_key", "function", "workflow", "system", "agent", "module"] }, "id": { "type": "string" }, "onBehalfOf": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["user"] }, "id": { "type": "string" } }, "required": ["kind", "id"] } }, "required": ["kind", "id"] }, "ChatEvent": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["turn_start"] }, "turnId": { "type": "string" }, "conversationId": { "type": "string" }, "userMessageId": { "type": "string" }, "iteration": { "type": "integer" } }, "required": ["type", "turnId", "conversationId", "iteration"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["message_start"] }, "messageId": { "type": "string" }, "iteration": { "type": "integer" } }, "required": ["type", "messageId", "iteration"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["text_delta"] }, "messageId": { "type": "string" }, "blockIndex": { "type": "integer" }, "text": { "type": "string" } }, "required": ["type", "messageId", "blockIndex", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["thinking_delta"] }, "messageId": { "type": "string" }, "blockIndex": { "type": "integer" }, "text": { "type": "string" } }, "required": ["type", "messageId", "blockIndex", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["thinking_stop"] }, "messageId": { "type": "string" }, "blockIndex": { "type": "integer" } }, "required": ["type", "messageId", "blockIndex"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["tool_call_start"] }, "messageId": { "type": "string" }, "blockIndex": { "type": "integer" }, "toolUseId": { "type": "string" }, "name": { "type": "string" } }, "required": ["type", "messageId", "blockIndex", "toolUseId", "name"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["tool_call_input_delta"] }, "messageId": { "type": "string" }, "blockIndex": { "type": "integer" }, "partialJson": { "type": "string" } }, "required": ["type", "messageId", "blockIndex", "partialJson"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["tool_call"] }, "messageId": { "type": "string" }, "blockIndex": { "type": "integer" }, "toolCall": { "$ref": "#/components/schemas/ToolCall" } }, "required": ["type", "messageId", "blockIndex", "toolCall"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["tool_result"] }, "toolCallId": { "type": "string" }, "status": { "$ref": "#/components/schemas/ToolCallStatus" }, "result": {}, "isError": { "type": "boolean" }, "revealed": { "type": "array", "items": { "$ref": "#/components/schemas/RevealedValue" } } }, "required": ["type", "toolCallId", "status", "isError"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["message_stop"] }, "messageId": { "type": "string" }, "stopReason": { "type": ["string", "null"] }, "usage": { "$ref": "#/components/schemas/AiUsage" }, "model": { "type": "string" } }, "required": ["type", "messageId", "stopReason", "usage", "model"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["navigate"] }, "target": { "$ref": "#/components/schemas/NavigateTarget" } }, "required": ["type", "target"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["paused"] }, "turnId": { "type": "string" }, "pending": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" } } }, "required": ["type", "turnId", "pending"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["done"] }, "turnId": { "type": "string" }, "status": { "type": "string", "enum": ["completed", "cancelled", "failed"] }, "stopReason": { "type": ["string", "null"] }, "truncated": { "type": "boolean" }, "usage": { "$ref": "#/components/schemas/AiUsage" } }, "required": ["type", "turnId", "status", "usage"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["error"] }, "turnId": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": ["type", "code", "message", "retryable"] } ] }, "ToolCall": { "type": "object", "properties": { "id": { "type": "string" }, "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": {}, "status": { "$ref": "#/components/schemas/ToolCallStatus" }, "requiresApproval": { "type": "boolean" }, "result": {}, "isError": { "type": "boolean" }, "reason": { "type": "string" }, "resolvedAt": { "type": "string" }, "executedAt": { "type": "string" }, "inputRequest": { "$ref": "#/components/schemas/InputRequest" }, "revealed": { "type": "array", "items": { "$ref": "#/components/schemas/RevealedValue" } } }, "required": ["id", "toolUseId", "name", "status", "requiresApproval"] }, "ToolCallStatus": { "type": "string", "enum": ["pending", "approved", "rejected", "running", "executed", "failed", "declined"] }, "InputRequest": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SettingField" }, "default": [] }, "question": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": ["value", "label"] } }, "other": { "type": "boolean" } }, "required": ["options", "other"] }, "connect": { "type": "object", "properties": { "module": { "type": "string" }, "provider": { "type": "string" }, "visibility": { "type": "string", "enum": ["user", "workspace"] }, "label": { "type": "string" } }, "required": ["module", "provider", "visibility", "label"] }, "consent": { "type": "object", "properties": { "module": { "type": "string" }, "label": { "type": "string" }, "version": { "type": "string" }, "fromVersion": { "type": ["string", "null"] }, "policies": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "decision": { "type": "string", "enum": ["auto", "review", "deny"] } }, "required": ["description", "decision"] } }, "changes": { "type": "array", "items": { "type": "string" } }, "manifestHash": { "type": "string" } }, "required": ["module", "label", "version", "fromVersion", "policies", "changes", "manifestHash"] } }, "required": ["title"] }, "SettingField": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "label": { "type": "string", "minLength": 1 }, "secret": { "type": "boolean", "default": true }, "required": { "type": "boolean", "default": true }, "placeholder": { "type": "string" }, "help": { "type": "string" } }, "required": ["name", "label"] }, "RevealedValue": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label", "value"] }, "AiUsage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "default": 0 }, "outputTokens": { "type": "integer", "default": 0 }, "cacheReadInputTokens": { "type": "integer", "default": 0 }, "cacheCreationInputTokens": { "type": "integer", "default": 0 } } }, "NavigateTarget": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["record"] }, "object": { "type": "string" }, "id": { "type": "string" } }, "required": ["kind", "object", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["object"] }, "object": { "type": "string" }, "viewId": { "type": "string" } }, "required": ["kind", "object"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["settings"] }, "section": { "type": "string" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["page"] }, "pagePath": { "type": "string" } }, "required": ["kind", "pagePath"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow"] }, "id": { "type": "string" } }, "required": ["kind", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["document"] }, "id": { "type": "string" } }, "required": ["kind", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["task"] }, "id": { "type": "string" } }, "required": ["kind", "id"] } ] }, "Health": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] }, "db": { "type": "string", "enum": ["pg", "pglite"] } }, "required": ["ok", "db"] }, "Me": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": ["string", "null"] } }, "required": ["id", "name", "email"] }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceSummary" } } }, "required": ["user", "workspaces"] }, "WorkspaceSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string" } }, "required": ["id", "name", "slug", "role"] }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION", "NOT_FOUND", "FORBIDDEN", "UNAUTHORIZED", "CONFLICT", "UNIQUE_VIOLATION", "INVALID_CURSOR", "DESTRUCTIVE_CHANGE", "PLAN_MISMATCH", "MISSING_DEPENDENCY", "RATE_LIMITED", "INTERNAL" ] }, "message": { "type": "string" }, "details": {} }, "required": ["code", "message"] } }, "required": ["error"] }, "CreateWorkspace": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 } }, "required": ["name", "slug"] }, "WorkspaceSchema": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "version": { "type": "integer" }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectMetadata" } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldMetadata" } }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/ViewMetadata" } }, "layouts": { "type": "array", "items": { "$ref": "#/components/schemas/Layout" } }, "navItems": { "type": "array", "items": { "$ref": "#/components/schemas/NavItem" } }, "commandItems": { "type": "array", "items": { "$ref": "#/components/schemas/CommandItem" } }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledModule" } } }, "required": [ "workspaceId", "version", "objects", "fields", "views", "layouts", "navItems", "commandItems", "modules" ] }, "ObjectMetadata": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "nameSingular": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "namePlural": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "labelSingular": { "type": "string", "minLength": 1 }, "labelPlural": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "description": { "type": "string" }, "primaryFieldId": { "$ref": "#/components/schemas/Id" }, "isSystem": { "type": "boolean", "default": false }, "readOnly": { "type": "boolean", "default": false }, "deleteWhen": { "$ref": "#/components/schemas/Filter" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "moduleId": { "$ref": "#/components/schemas/ModuleId" } }, "required": [ "workspaceId", "id", "nameSingular", "namePlural", "labelSingular", "labelPlural", "createdAt", "updatedAt", "moduleId" ] }, "Id": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "Stable, opaque identifier shared by module source and workspace metadata" }, "ModuleId": { "type": ["string", "null"], "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "FieldMetadata": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "objectId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "type": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {}, "default": {} }, "isRequired": { "type": "boolean", "default": false }, "isUnique": { "type": "boolean", "default": false }, "defaultValue": {}, "position": { "type": "integer", "default": 0 }, "moduleId": { "$ref": "#/components/schemas/ModuleId" } }, "required": ["workspaceId", "objectId", "id", "name", "type", "label", "moduleId"] }, "ViewMetadata": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "objectId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "isDefault": { "type": "boolean", "default": false }, "position": { "type": "integer", "default": 0 }, "config": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string" }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "visible": { "type": "boolean", "default": true } }, "required": ["fieldId"] }, "default": [] }, "filter": { "$ref": "#/components/schemas/Filter" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } }, "required": ["fieldId"] }, "default": [] }, "groupById": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {}, "default": {} } } }, "moduleId": { "$ref": "#/components/schemas/ModuleId" } }, "required": ["workspaceId", "objectId", "id", "label", "type", "config", "moduleId"] }, "Layout": { "oneOf": [ { "type": "object", "properties": { "workspaceId": { "type": "string" }, "objectId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": ["record"], "default": "record" }, "isDefault": { "type": "boolean", "default": false }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" }, "default": [] }, "moduleId": { "$ref": "#/components/schemas/ModuleId" }, "shell": { "type": "string", "enum": ["tabs"] }, "header": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" }, "column": { "type": "integer", "minimum": 1, "maximum": 12 }, "columnSpan": { "type": "integer", "minimum": 1, "maximum": 12 }, "row": { "type": "integer", "minimum": 1 } }, "required": ["name", "blockId"] }, "default": [] } }, "required": ["name", "label"] } } }, "required": ["workspaceId", "objectId", "id", "label", "moduleId", "shell", "tabs"] }, { "type": "object", "properties": { "workspaceId": { "type": "string" }, "objectId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": ["record"], "default": "record" }, "isDefault": { "type": "boolean", "default": false }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" }, "default": [] }, "moduleId": { "$ref": "#/components/schemas/ModuleId" }, "shell": { "type": "string", "enum": ["column"] }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] } } }, "required": ["workspaceId", "objectId", "id", "label", "moduleId", "shell", "blocks"] }, { "type": "object", "properties": { "workspaceId": { "type": "string" }, "objectId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": ["record"], "default": "record" }, "isDefault": { "type": "boolean", "default": false }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" }, "default": [] }, "moduleId": { "$ref": "#/components/schemas/ModuleId" }, "shell": { "type": "string", "enum": ["split"] }, "main": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] } }, "aside": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "default": [] } }, "required": ["workspaceId", "objectId", "id", "label", "moduleId", "shell", "main"] } ] }, "LayoutAction": { "type": "object", "properties": { "actionId": { "type": "string", "minLength": 1, "description": "The action's id, as list_modules lists it for each installed module's actions." }, "input": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "primary": { "type": "boolean" }, "when": { "$ref": "#/components/schemas/Filter" } }, "required": ["actionId"] }, "NavItem": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "target": { "$ref": "#/components/schemas/NavTarget" }, "position": { "type": "integer", "default": 0 }, "parentId": { "type": ["string", "null"], "default": null }, "pinned": { "type": "boolean", "default": false }, "overrides": { "$ref": "#/components/schemas/NavOverrides" }, "moduleId": { "$ref": "#/components/schemas/ModuleId" } }, "required": ["workspaceId", "id", "label", "target", "moduleId"] }, "NavTarget": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["object"] }, "objectId": { "type": "string" }, "viewId": { "type": "string" } }, "required": ["kind", "objectId"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["page"] }, "pageId": { "type": "string" } }, "required": ["kind", "pageId"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["url"] }, "url": { "type": "string" }, "external": { "type": "boolean" } }, "required": ["kind", "url"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["group"] } }, "required": ["kind"] } ] }, "NavOverrides": { "type": ["object", "null"], "properties": { "label": { "type": "string", "minLength": 1 }, "icon": { "type": ["string", "null"] }, "position": { "type": "integer" }, "parentId": { "type": ["string", "null"] }, "hidden": { "type": "boolean" } }, "default": null }, "CommandItem": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "group": { "type": "string" }, "shortcut": { "type": "string" }, "action": { "$ref": "#/components/schemas/CommandAction" }, "moduleId": { "$ref": "#/components/schemas/ModuleId" } }, "required": ["workspaceId", "id", "label", "action", "moduleId"] }, "CommandAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["navigate"] }, "target": { "$ref": "#/components/schemas/NavTarget" } }, "required": ["kind", "target"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["create_record"] }, "objectId": { "type": "string" } }, "required": ["kind", "objectId"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["open_block"] }, "blockId": { "$ref": "#/components/schemas/Id" } }, "required": ["kind", "blockId"] } ] }, "InstalledModule": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ModuleId" }, "version": { "type": "string" }, "manifestHash": { "type": "string" }, "installedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "logo": { "type": "string" }, "website": { "type": "string" }, "engines": { "$ref": "#/components/schemas/ModuleEngines" }, "core": { "type": "boolean", "default": false }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDeclaration" }, "default": [] }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDefinition" }, "default": [] }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillDefinition" }, "default": [] }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionProvider" }, "default": [] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableDefinition" }, "default": [] }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionDefinition" }, "default": [] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventDefinition" }, "default": [] }, "webhookHelp": { "type": "string" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyDefinition" } } }, "required": ["id", "version", "manifestHash", "installedAt", "updatedAt", "label"] }, "ModuleEngines": { "type": "object", "properties": { "devias": { "type": "string", "minLength": 1 } }, "required": ["devias"] }, "BlockDeclaration": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "surfaces": { "type": "array", "items": { "type": "string", "enum": ["record", "home", "dialog", "panel", "approval"] }, "minItems": 1 } }, "required": ["id", "label", "surfaces"] }, "AgentDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "maxLength": 64 }, "description": { "type": "string", "maxLength": 500 }, "instructions": { "type": "string", "maxLength": 20000 }, "actionIds": { "type": "array", "items": { "$ref": "#/components/schemas/Id" }, "minItems": 1, "maxItems": 500 }, "starterPrompts": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 5, "default": [] }, "skillIds": { "type": "array", "items": { "$ref": "#/components/schemas/Id" }, "maxItems": 20, "default": [] } }, "required": ["id", "label", "actionIds"] }, "SkillDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": ["id", "label", "description", "body"] }, "ConnectionProvider": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "kind": { "type": "string", "enum": ["api_key"] }, "visibility": { "type": "string", "enum": ["user", "workspace", "both"], "default": "workspace" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SettingField" }, "minItems": 1 } }, "required": ["id", "label", "kind", "fields"] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "kind": { "type": "string", "enum": ["oauth2"] }, "visibility": { "type": "string", "enum": ["user", "workspace", "both"], "default": "user" }, "oauth": { "$ref": "#/components/schemas/OAuthConfig" } }, "required": ["id", "label", "kind", "oauth"] } ] }, "OAuthConfig": { "type": "object", "properties": { "authorizeUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [] }, "pkce": { "type": "boolean", "default": true }, "extraAuthorizeParams": { "type": "object", "additionalProperties": { "type": "string" } }, "clientId": { "type": "object", "properties": { "variable": { "$ref": "#/components/schemas/Id" } }, "required": ["variable"] }, "clientSecret": { "type": "object", "properties": { "variable": { "$ref": "#/components/schemas/Id" } }, "required": ["variable"] } }, "required": ["authorizeUrl", "tokenUrl", "clientId"] }, "VariableDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "secret": { "type": "boolean", "default": false }, "required": { "type": "boolean", "default": false }, "defaultValue": { "type": "string" } }, "required": ["id", "label"] }, "ActionDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "input": { "type": "array", "items": { "$ref": "#/components/schemas/ActionField" }, "default": [] }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/ActionOutputField" }, "default": [] }, "approval": { "type": "string", "enum": ["auto", "approve"], "default": "approve" }, "external": { "type": "boolean", "default": true } }, "required": ["id", "name", "label"] }, "ActionField": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": ["text", "long_text", "email", "number", "boolean", "json", "record"], "default": "text" }, "objectId": { "type": "string", "minLength": 1 }, "required": { "type": "boolean", "default": false }, "placeholder": { "type": "string" }, "help": { "type": "string" } }, "required": ["name", "label"] }, "ActionOutputField": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": ["text", "number", "boolean", "json", "record"], "default": "text" }, "objectId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": ["name"] }, "EventDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "name": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+)*$" }, "description": { "type": "string" } }, "required": ["id", "name"] }, "PolicyDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "description": { "type": "string", "minLength": 1 }, "match": { "type": "object", "properties": { "actionId": { "type": "string", "minLength": 1 }, "objectId": { "$ref": "#/components/schemas/Id" }, "fieldId": { "type": "string", "minLength": 1 } } }, "when": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "above": { "type": "number" } }, "required": ["fieldId", "above"] }, "decision": { "type": "string", "enum": ["auto", "review", "deny"] } }, "required": ["id", "description", "match", "decision"] }, "BlockList": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "module": { "type": "string", "description": "The id of the module that declares the block; `core` for the platform's own" }, "description": { "type": "string" } }, "required": ["id", "label", "module"] } } }, "required": ["blocks"] }, "ObjectDescription": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ObjectMetadata" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldMetadata" } }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/ViewMetadata" } } }, "required": ["object", "fields", "views"] }, "ObjectCreateInput": { "type": "object", "properties": { "nameSingular": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "namePlural": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "labelSingular": { "type": "string", "minLength": 1 }, "labelPlural": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "description": { "type": "string" }, "primaryFieldId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The id of the field that names a record, one of the object's fields (create the field first); the first text field when left out." }, "readOnly": { "type": "boolean" }, "deleteWhen": { "anyOf": [ { "type": "object", "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": ["and"] }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": ["or"] }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/Filter" } }, "required": ["not"] }, { "$ref": "#/components/schemas/FilterCondition" } ], "description": "A record can be deleted only while it matches this filter, e.g. status is draft. null removes the rule." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectFieldInput" }, "maxItems": 100, "description": "Its fields, in display order" }, "addToNavigation": { "type": "boolean", "description": "Put it in the sidebar (default true)" } }, "required": ["nameSingular", "namePlural", "labelSingular", "labelPlural"] }, "ObjectFieldInput": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "type": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {} }, "isRequired": { "type": "boolean" }, "isUnique": { "type": "boolean" }, "defaultValue": {}, "position": { "type": "integer" } }, "required": ["name", "type", "label"] }, "FieldInput": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "The object: its id, or its API name (e.g. 'person'), plural name or id" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "type": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {} }, "isRequired": { "type": "boolean" }, "isUnique": { "type": "boolean" }, "defaultValue": {}, "position": { "type": "integer" } }, "required": ["objectId", "name", "type", "label"] }, "ViewInput": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "The object: its id, or its API name (e.g. 'person'), plural name or id" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "isDefault": { "type": "boolean" }, "position": { "type": "integer" }, "config": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string" }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "visible": { "type": "boolean", "default": true } }, "required": ["fieldId"] } }, "filter": { "$ref": "#/components/schemas/Filter" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } }, "required": ["fieldId"] } }, "groupById": { "type": ["string", "null"] }, "settings": { "type": "object", "additionalProperties": {} } } } }, "required": ["objectId", "label"] }, "LayoutInput": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "The object: its id, or its API name (e.g. 'person'), plural name or id" }, "label": { "type": "string", "minLength": 1 }, "isDefault": { "type": "boolean" }, "shell": { "type": "string", "enum": ["tabs", "column", "split"], "description": "The shape of the page. `tabs`: a header block, a tab bar and a 12-column grid of blocks per tab (give `header` and `tabs`). `column`: one centered column under a slim toolbar, for things people write in (give `blocks`). `split`: a main column and an aside on the right, like an issue (give `main` and `aside`). A shape takes only its own keys." }, "header": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"], "description": "`tabs` only: the block that draws the page header (the object's icon and name when left out)." }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" }, "column": { "type": "integer", "minimum": 1, "maximum": 12 }, "columnSpan": { "type": "integer", "minimum": 1, "maximum": 12 }, "row": { "type": "integer", "minimum": 1 } }, "required": ["name", "blockId"] }, "default": [] } }, "required": ["name", "label"] }, "description": "`tabs` only: the tabs, each a grid of blocks." }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "description": "`column` only: the blocks, top to bottom." }, "main": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "description": "`split` only: the blocks of the main column, top to bottom." }, "aside": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "description": "`split` only: the blocks of the aside, top to bottom." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" } } }, "required": ["objectId", "label", "shell"] }, "NavItemInput": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "target": { "$ref": "#/components/schemas/NavTarget" }, "position": { "type": "integer" }, "parentId": { "type": ["string", "null"] }, "hidden": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "required": ["label", "target"] }, "NavArrange": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "parentId": { "type": ["string", "null"] }, "position": { "type": "integer", "minimum": 0 } }, "required": ["id", "parentId", "position"] }, "minItems": 1, "maxItems": 500 } }, "required": ["items"] }, "CommandItemInput": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "group": { "type": "string" }, "shortcut": { "type": "string" }, "action": { "$ref": "#/components/schemas/CommandAction" } }, "required": ["label", "action"] }, "Page": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecordData" } }, "nextCursor": { "type": ["string", "null"] }, "totalCount": { "type": "integer" }, "included": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/RecordData" } } } }, "required": ["items", "nextCursor"] }, "RecordData": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" } }, "required": ["id", "created_at", "updated_at"], "additionalProperties": {} }, "QueryBody": { "type": "object", "properties": { "object": { "type": "string" }, "select": { "type": "array", "items": { "type": "string" } }, "filter": { "$ref": "#/components/schemas/Filter" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/Sort" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "cursor": { "type": "string" }, "search": { "type": "string" }, "include": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "boolean", "enum": [true] }, { "type": "object", "properties": { "select": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "exclusiveMinimum": 0 } } } ] } }, "count": { "type": "boolean" } } }, "AggregateResult": { "type": "object", "properties": { "object": { "type": "string" }, "groupBy": { "type": ["string", "null"] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "label": { "type": "string" }, "count": { "type": "integer" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] } } }, "required": ["key", "count", "values"] } }, "total": { "type": "object", "properties": { "count": { "type": "integer" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] } } }, "required": ["count", "values"] }, "truncated": { "type": "boolean" } }, "required": ["object", "groupBy", "groups", "total", "truncated"] }, "AggregateBody": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/Filter" }, "search": { "type": "string" }, "groupBy": { "type": "string" }, "measures": { "type": "array", "items": { "$ref": "#/components/schemas/AggregateMeasure" }, "minItems": 1, "maxItems": 10, "default": [ { "fn": "count" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 } } }, "AggregateMeasure": { "type": "object", "properties": { "fn": { "type": "string", "enum": ["count", "sum", "avg", "min", "max"] }, "field": { "type": "string" } }, "required": ["fn"] }, "RecordWithLabels": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/RecordData" }, "included": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/RecordData" } } } }, "required": ["record"] }, "RecordWrite": { "type": "object", "additionalProperties": {} }, "DeleteRecords": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 500 } }, "required": ["ids"] }, "UpsertResult": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/RecordData" }, "created": { "type": "boolean" } }, "required": ["record", "created"] }, "UpsertBody": { "type": "object", "properties": { "match": { "type": "object", "additionalProperties": {} }, "values": { "$ref": "#/components/schemas/RecordWrite" } }, "required": ["match", "values"] }, "BatchResult": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/RecordData" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/RecordData" } }, "deleted": { "type": "array", "items": { "type": "string" } } }, "required": ["created", "updated", "deleted"] }, "BatchInput": { "type": "object", "properties": { "create": { "type": "array", "items": { "$ref": "#/components/schemas/RecordWrite" }, "maxItems": 500 }, "update": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "patch": { "$ref": "#/components/schemas/RecordWrite" } }, "required": ["id", "patch"] }, "maxItems": 500 }, "delete": { "type": "array", "items": { "type": "string" }, "maxItems": 500 } } }, "ImportReport": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" }, "errorCount": { "type": "integer" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ImportError" }, "maxItems": 1000 }, "dryRun": { "type": "boolean" }, "importId": { "type": "string" } }, "required": ["created", "updated", "skipped", "errorCount", "errors", "dryRun"] }, "ImportError": { "type": "object", "properties": { "row": { "type": "integer", "description": "The row's number in the spreadsheet (the header is row 1)" }, "field": { "type": "string", "description": "The field's label, when the problem is in one cell" }, "message": { "type": "string" } }, "required": ["row", "message"] }, "ImportBody": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": ["string", "null"] }, "minItems": 1, "maxItems": 200, "description": "The field each column fills, by API name or id; null leaves the column out" }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "maxItems": 500, "description": "The rows without the header, as text, at most 500 per call" }, "matchOn": { "type": "string", "description": "A unique field that is among the columns: a row whose value exists updates that record, not creates one" }, "dateOrder": { "type": "string", "enum": ["dmy", "mdy"], "description": "How the file writes 13/11/2026: day first or month first" }, "timeZone": { "type": "string", "description": "The time zone (Europe/Bucharest) of date-times that have no offset; UTC when left out" }, "firstRow": { "type": "integer", "minimum": 1, "description": "The number the first row has in the person's spreadsheet, for the errors (2 when left out: row 1 is the header)" }, "dryRun": { "type": "boolean", "description": "Check everything and write nothing" } }, "required": ["columns", "rows"] }, "LookupHit": { "type": "object", "properties": { "object": { "type": "string" }, "objectId": { "type": "string" }, "recordId": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" } }, "required": ["object", "objectId", "recordId", "title"] }, "LookupInput": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "objects": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": ["text"] }, "ActivityPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEntry" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"] }, "ActivityEntry": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "kind": { "type": "string", "enum": ["created"] } }, "required": ["id", "sequence", "actor", "occurredAt", "kind"] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "kind": { "type": "string", "enum": ["updated"] }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityChange" } } }, "required": ["id", "sequence", "actor", "occurredAt", "kind", "changes"] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "actor": { "$ref": "#/components/schemas/Actor" }, "occurredAt": { "type": "string" }, "kind": { "type": "string", "enum": ["deleted"] } }, "required": ["id", "sequence", "actor", "occurredAt", "kind"] } ] }, "ActivityChange": { "type": "object", "properties": { "field": { "type": "string" }, "before": {}, "after": {} }, "required": ["field"] }, "RecordCommentPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecordComment" } }, "nextCursor": { "type": ["string", "null"] }, "total": { "type": "integer" } }, "required": ["items", "nextCursor", "total"] }, "RecordComment": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "recordId": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "author": { "$ref": "#/components/schemas/Actor" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["id", "object", "recordId", "title", "body", "author", "createdAt", "updatedAt"] }, "RecordCommentInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "maxLength": 10000 } }, "required": ["title"] }, "RecordCommentPatch": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "maxLength": 10000 } } }, "DocumentPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } }, "nextCursor": { "type": ["string", "null"] }, "total": { "type": "integer" } }, "required": ["items", "nextCursor", "total"] }, "DocumentSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "preview": { "type": "string" }, "version": { "type": "integer" }, "createdBy": { "$ref": "#/components/schemas/Actor" }, "updatedBy": { "$ref": "#/components/schemas/Actor" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["id", "title", "preview", "version", "createdBy", "updatedBy", "createdAt", "updatedAt"] }, "Document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "preview": { "type": "string" }, "version": { "type": "integer" }, "createdBy": { "$ref": "#/components/schemas/Actor" }, "updatedBy": { "$ref": "#/components/schemas/Actor" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "body": { "$ref": "#/components/schemas/RichTextDoc" }, "markdown": { "type": "string" } }, "required": [ "id", "title", "preview", "version", "createdBy", "updatedBy", "createdAt", "updatedAt", "body", "markdown" ] }, "RichTextDoc": { "type": "object", "properties": { "type": { "type": "string", "enum": ["doc"] }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "required": ["type"], "additionalProperties": {} } } }, "required": ["type"], "additionalProperties": {} }, "DocumentInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "$ref": "#/components/schemas/RichTextDoc" }, "markdown": { "type": "string", "maxLength": 200000 } }, "required": ["title"] }, "DocumentPatch": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "$ref": "#/components/schemas/RichTextDoc" }, "markdown": { "type": "string", "maxLength": 200000 }, "expectedVersion": { "type": "integer", "minimum": 1 } } }, "DocumentAppend": { "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 200000 }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": ["markdown"] }, "DocumentActivityPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentActivityEntry" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"] }, "DocumentActivityEntry": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "kind": { "type": "string", "enum": ["created", "edited", "comment"] }, "actor": { "$ref": "#/components/schemas/Actor" }, "body": { "type": ["string", "null"] }, "data": { "type": ["object", "null"], "additionalProperties": {} }, "cause": { "type": ["object", "null"], "additionalProperties": {} }, "createdAt": { "type": "string" } }, "required": ["id", "documentId", "kind", "actor", "body", "data", "cause", "createdAt"] }, "DocumentComment": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "parentId": { "type": ["string", "null"] }, "actor": { "$ref": "#/components/schemas/Actor" }, "body": { "type": "string" }, "anchor": { "$ref": "#/components/schemas/DocumentCommentAnchor" }, "resolvedAt": { "type": ["string", "null"] }, "resolvedBy": { "allOf": [ { "$ref": "#/components/schemas/Actor" }, { "type": ["object", "null"] } ] }, "cause": { "type": ["object", "null"], "additionalProperties": {} }, "createdAt": { "type": "string" }, "editedAt": { "type": ["string", "null"] } }, "required": [ "id", "documentId", "parentId", "actor", "body", "anchor", "resolvedAt", "resolvedBy", "cause", "createdAt", "editedAt" ] }, "DocumentCommentAnchor": { "type": ["object", "null"], "properties": { "quote": { "type": "string" }, "prefix": { "type": "string" }, "suffix": { "type": "string" }, "hint": { "type": "integer" } }, "required": ["quote", "prefix", "suffix", "hint"] }, "DocumentCommentInput": { "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 20000 }, "anchor": { "type": "object", "properties": { "quote": { "type": "string", "minLength": 1, "maxLength": 1000 }, "prefix": { "type": "string", "maxLength": 80 }, "suffix": { "type": "string", "maxLength": 80 }, "hint": { "type": "integer", "minimum": 0 } }, "required": ["quote"] }, "parent": { "type": "string", "minLength": 1 } }, "required": ["markdown"] }, "DocumentThreadPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentThread" } } }, "required": ["items"] }, "DocumentThread": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/DocumentComment" }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentComment" } } }, "required": ["comment", "replies"] }, "DocumentCommentPatch": { "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 20000 }, "resolved": { "type": "boolean" } } }, "TaskPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSummary" } }, "nextCursor": { "type": ["string", "null"] }, "total": { "type": "integer" } }, "required": ["items", "nextCursor", "total"] }, "TaskSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "assignee": { "type": ["string", "null"] }, "dueDate": { "type": ["string", "null"] }, "parentId": { "type": ["string", "null"] }, "subtasks": { "type": "object", "properties": { "total": { "type": "integer" }, "open": { "type": "integer" } }, "required": ["total", "open"] }, "work": { "$ref": "#/components/schemas/TaskWorkState" }, "runId": { "type": ["string", "null"] }, "version": { "type": "integer" }, "createdBy": { "$ref": "#/components/schemas/Actor" }, "updatedBy": { "$ref": "#/components/schemas/Actor" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "statusChangedAt": { "type": "string" }, "closedAt": { "type": ["string", "null"] } }, "required": [ "id", "title", "status", "priority", "assignee", "dueDate", "parentId", "subtasks", "work", "runId", "version", "createdBy", "updatedBy", "createdAt", "updatedAt", "statusChangedAt", "closedAt" ] }, "TaskStatus": { "type": "string", "enum": ["backlog", "todo", "in_progress", "in_review", "done", "canceled"] }, "TaskPriority": { "type": "string", "enum": ["urgent", "high", "medium", "low", "none"] }, "TaskWorkState": { "type": ["string", "null"], "enum": ["working", "waiting_on_you", "waiting_on_subtasks", "failed", null] }, "Task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "assignee": { "type": ["string", "null"] }, "dueDate": { "type": ["string", "null"] }, "parentId": { "type": ["string", "null"] }, "subtasks": { "type": "object", "properties": { "total": { "type": "integer" }, "open": { "type": "integer" } }, "required": ["total", "open"] }, "work": { "$ref": "#/components/schemas/TaskWorkState" }, "runId": { "type": ["string", "null"] }, "version": { "type": "integer" }, "createdBy": { "$ref": "#/components/schemas/Actor" }, "updatedBy": { "$ref": "#/components/schemas/Actor" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "statusChangedAt": { "type": "string" }, "closedAt": { "type": ["string", "null"] }, "body": { "$ref": "#/components/schemas/RichTextDoc" }, "markdown": { "type": "string" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/TaskLink" } } }, "required": [ "id", "title", "status", "priority", "assignee", "dueDate", "parentId", "subtasks", "work", "runId", "version", "createdBy", "updatedBy", "createdAt", "updatedAt", "statusChangedAt", "closedAt", "body", "markdown", "links" ] }, "TaskLink": { "type": "object", "properties": { "link": { "type": "string" }, "role": { "type": "string", "enum": ["mention", "about"] } }, "required": ["link", "role"] }, "TaskInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "$ref": "#/components/schemas/RichTextDoc" }, "markdown": { "type": "string", "maxLength": 200000 }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "dueDate": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "parent": { "type": ["string", "null"], "minLength": 1 }, "about": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 }, "maxItems": 20 }, "key": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["title"] }, "TaskCounts": { "type": "object", "properties": { "open": { "type": "integer" }, "overdue": { "type": "integer" }, "dueToday": { "type": "integer" }, "dueThisWeek": { "type": "integer" }, "inReview": { "type": "integer" }, "mine": { "type": "integer" }, "agentsWorking": { "type": "integer" }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": ["open", "overdue", "dueToday", "dueThisWeek", "inReview", "mine", "agentsWorking", "byStatus"] }, "TaskPatch": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "$ref": "#/components/schemas/RichTextDoc" }, "markdown": { "type": "string", "maxLength": 200000 }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "dueDate": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "parent": { "type": ["string", "null"], "minLength": 1 }, "about": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 }, "maxItems": 20 }, "expectedVersion": { "type": "integer", "minimum": 1 } } }, "TaskActivityPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaskActivityEntry" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"] }, "TaskActivityEntry": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "kind": { "type": "string", "enum": ["created", "changed", "comment", "run", "review"] }, "actor": { "$ref": "#/components/schemas/Actor" }, "body": { "type": ["string", "null"] }, "data": { "type": ["object", "null"], "additionalProperties": {} }, "cause": { "type": ["object", "null"], "additionalProperties": {} }, "createdAt": { "type": "string" } }, "required": ["id", "taskId", "kind", "actor", "body", "data", "cause", "createdAt"] }, "Comment": { "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": ["markdown"] }, "Workflow": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "$ref": "#/components/schemas/WorkflowTrigger" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" } }, "lastRunAt": { "type": ["string", "null"] }, "nextRunAt": { "type": ["string", "null"] }, "moduleId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "workspaceId", "title", "enabled", "trigger", "steps", "lastRunAt", "nextRunAt", "createdAt", "updatedAt" ] }, "WorkflowTrigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["record_event"] }, "objectId": { "type": "string", "minLength": 1 }, "types": { "type": "array", "items": { "type": "string", "enum": ["record.created", "record.updated", "record.deleted"] }, "minItems": 1 }, "fieldIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "condition": { "$ref": "#/components/schemas/Filter" }, "onImport": { "type": "boolean" } }, "required": ["kind", "objectId", "types"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["manual"] }, "objectId": { "type": "string", "minLength": 1 } }, "required": ["kind", "objectId"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schedule"] }, "cron": { "type": "string", "description": "Five fields, minute hour day-of-month month day-of-week, read in UTC: \"*/15 * * * *\" is every 15 minutes, \"0 9 * * 1-5\" weekdays at 09:00, \"0 0 1 * *\" the first of each month." }, "objectId": { "type": "string", "minLength": 1 }, "condition": { "$ref": "#/components/schemas/Filter" } }, "required": ["kind", "cron"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["module_event"] }, "moduleId": { "type": "string", "minLength": 1 }, "types": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "required": ["kind", "moduleId", "types"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["task_event"] }, "types": { "type": "array", "items": { "type": "string", "enum": ["created", "updated", "status_changed", "assigned", "commented", "run_failed"] }, "minItems": 1 }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/TaskStatus" }, "minItems": 1 }, "condition": { "$ref": "#/components/schemas/Filter" } }, "required": ["kind", "types"] } ] }, "WorkflowStep": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "maxLength": 120 }, "kind": { "type": "string", "enum": ["action"] }, "actionId": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} } }, "required": ["id", "kind", "actionId", "input"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "maxLength": 120 }, "kind": { "type": "string", "enum": ["branch"] }, "condition": { "$ref": "#/components/schemas/Filter" }, "yes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" } }, "no": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" } } }, "required": ["id", "kind", "condition", "yes", "no"] } ] }, "WorkflowInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "enabled": { "type": "boolean" }, "trigger": { "$ref": "#/components/schemas/WorkflowTrigger" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStepInput" }, "minItems": 1 } }, "required": ["title", "trigger", "steps"] }, "WorkflowStepInput": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "maxLength": 120 }, "kind": { "type": "string", "enum": ["action"] }, "actionId": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} } }, "required": ["kind", "actionId", "input"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "maxLength": 120 }, "kind": { "type": "string", "enum": ["branch"] }, "condition": { "$ref": "#/components/schemas/Filter" }, "yes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStepInput" } }, "no": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStepInput" } } }, "required": ["kind", "condition", "yes", "no"] } ] }, "WorkflowRunPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"] }, "WorkflowRun": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "succeeded", "failed"] }, "trigger": { "$ref": "#/components/schemas/WorkflowRunTrigger" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunStep" } }, "error": { "type": "string" }, "createdAt": { "type": "string" }, "startedAt": { "type": ["string", "null"] }, "finishedAt": { "type": ["string", "null"] } }, "required": ["id", "workflowId", "status", "trigger", "steps", "createdAt", "startedAt", "finishedAt"] }, "WorkflowRunTrigger": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["record_event", "manual", "schedule", "module_event", "task_event"] }, "objectId": { "type": "string" }, "recordId": { "type": "string" }, "eventType": { "type": "string" }, "sequence": { "type": "integer" }, "actor": { "$ref": "#/components/schemas/Actor" }, "moduleId": { "type": "string" }, "eventId": { "type": "string" }, "taskId": { "type": "string" }, "retryOf": { "type": "string" } }, "required": ["kind"] }, "WorkflowRunStep": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": ["action", "branch"] }, "actionId": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": ["succeeded", "failed", "skipped", "retrying"] }, "output": {}, "error": { "type": "string" }, "attempt": { "type": "integer", "exclusiveMinimum": 0 }, "retryAt": { "type": "string" } }, "required": ["id", "kind", "status"] }, "WorkflowRunList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" } } }, "required": ["items"] }, "WorkflowActivity": { "type": "object", "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowActivityDay" } }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowHealth" } } }, "required": ["days", "workflows"] }, "WorkflowActivityDay": { "type": "object", "properties": { "date": { "type": "string" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } }, "required": ["date", "succeeded", "failed"] }, "WorkflowHealth": { "type": "object", "properties": { "workflowId": { "type": "string" }, "runs": { "type": "integer" }, "failed": { "type": "integer" }, "lastRunId": { "type": "string" }, "lastStatus": { "type": "string", "enum": ["succeeded", "failed"] }, "lastError": { "type": "string" } }, "required": ["workflowId", "runs", "failed", "lastRunId", "lastStatus"] }, "RunWorkflowInput": { "type": "object", "properties": { "recordId": { "type": "string" }, "wait": { "type": "boolean" } } }, "TaskRunPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRun" } } }, "required": ["items"] }, "TaskRun": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "agentId": { "type": "string" }, "conversationId": { "type": "string" }, "status": { "type": "string", "enum": ["running", "awaiting_review", "completed", "failed", "cancelled"] }, "attempt": { "type": "integer" }, "requestedBy": { "type": "string" }, "summary": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string" }, "finishedAt": { "type": ["string", "null"] } }, "required": [ "id", "taskId", "agentId", "conversationId", "status", "attempt", "requestedBy", "summary", "error", "startedAt", "finishedAt" ] }, "NotificationPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"] }, "Notification": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "recipientId": { "type": "string" }, "kind": { "type": "string" }, "level": { "type": "string", "enum": ["info", "success", "warning", "error"] }, "title": { "type": "string" }, "body": { "type": ["string", "null"] }, "target": { "$ref": "#/components/schemas/NotificationTarget" }, "key": { "type": ["string", "null"] }, "data": { "type": ["object", "null"], "additionalProperties": {} }, "actor": { "$ref": "#/components/schemas/Actor" }, "readAt": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "workspaceId", "recipientId", "kind", "level", "title", "body", "target", "key", "data", "actor", "readAt", "createdAt", "updatedAt" ] }, "NotificationTarget": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["record"] }, "object": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": ["kind", "object", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["object"] }, "object": { "type": "string", "minLength": 1 }, "view": { "type": "string" } }, "required": ["kind", "object"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["page"] }, "pagePath": { "type": "string", "minLength": 1 } }, "required": ["kind", "pagePath"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["settings"] }, "section": { "type": "string" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow"] }, "id": { "type": "string", "minLength": 1 } }, "required": ["kind", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["document"] }, "id": { "type": "string", "minLength": 1 } }, "required": ["kind", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["task"] }, "id": { "type": "string", "minLength": 1 } }, "required": ["kind", "id"] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["url"] }, "url": { "type": "string", "minLength": 1 }, "external": { "type": "boolean" } }, "required": ["kind", "url"] }, { "type": "null" } ] }, "UnreadCount": { "type": "object", "properties": { "count": { "type": "integer" } }, "required": ["count"] }, "NotificationSendResult": { "type": "object", "properties": { "recipients": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" } }, "required": ["recipients", "created", "updated"] }, "NotificationInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "maxLength": 4000 }, "level": { "type": "string", "enum": ["info", "success", "warning", "error"], "default": "info" }, "kind": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "default": "general" }, "key": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "$ref": "#/components/schemas/NotificationTarget" }, "data": { "type": "object", "additionalProperties": {} }, "to": { "$ref": "#/components/schemas/NotificationAudience" } }, "required": ["title", "to"] }, "NotificationAudience": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500 }, "roles": { "type": "array", "items": { "type": "string", "enum": ["owner", "admin", "member"] } }, "all": { "type": "boolean" }, "me": { "type": "boolean" } } }, "MarkAllReadResult": { "type": "object", "properties": { "updated": { "type": "integer" } }, "required": ["updated"] }, "PlanResult": { "type": "object", "properties": { "moduleId": { "type": "string" }, "fromVersion": { "type": ["string", "null"] }, "toVersion": { "type": "string" }, "manifestHash": { "type": "string" }, "planHash": { "type": "string" }, "hasDestructive": { "type": "boolean" }, "hasConflicts": { "type": "boolean" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PlanChange" } } }, "required": [ "moduleId", "fromVersion", "toVersion", "manifestHash", "planHash", "hasDestructive", "hasConflicts", "changes" ] }, "PlanChange": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["object", "field", "view", "layout", "nav_item", "command_item", "workflow"] }, "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string" }, "action": { "type": "string", "enum": ["create", "update", "delete", "noop", "conflict"] }, "destructive": { "type": "boolean" }, "reason": { "type": "string" }, "diff": { "type": "object", "additionalProperties": { "type": "object", "properties": { "from": {}, "to": {} } } } }, "required": ["kind", "id", "label", "action", "destructive"] }, "PlanRequest": { "type": "object", "properties": { "manifest": { "$ref": "#/components/schemas/ModuleManifest" } }, "required": ["manifest"] }, "ModuleManifest": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ModuleId" }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+([-+].+)?$" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "logo": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "engines": { "$ref": "#/components/schemas/ModuleEngines" }, "core": { "type": "boolean", "default": false }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectDefinition" }, "default": [] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldDefinition" }, "default": [] }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/ViewDefinition" }, "default": [] }, "layouts": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutDefinition" }, "default": [] }, "navItems": { "type": "array", "items": { "$ref": "#/components/schemas/NavItemDefinition" }, "default": [] }, "commandItems": { "type": "array", "items": { "$ref": "#/components/schemas/CommandItemDefinition" }, "default": [] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDeclaration" }, "default": [] }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/PageDeclaration" }, "default": [] }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDefinition" }, "default": [] }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillDefinition" }, "maxItems": 20, "default": [] }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowDefinition" }, "default": [] }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionProvider" }, "default": [] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableDefinition" }, "default": [] }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionDefinition" }, "default": [] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventDefinition" }, "default": [] }, "webhookHelp": { "type": "string" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyDefinition" } } }, "required": ["id", "version", "label"] }, "ObjectDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "nameSingular": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "namePlural": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "labelSingular": { "type": "string", "minLength": 1 }, "labelPlural": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "description": { "type": "string" }, "primaryFieldId": { "$ref": "#/components/schemas/Id" }, "deleteWhen": { "$ref": "#/components/schemas/Filter" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldDefinition" }, "default": [] } }, "required": ["id", "nameSingular", "namePlural", "labelSingular", "labelPlural"] }, "FieldDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "objectId": { "$ref": "#/components/schemas/Id" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "settings": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "icon": { "type": "string" }, "isRequired": { "type": "boolean" }, "isUnique": { "type": "boolean" }, "defaultValue": {}, "position": { "type": "integer" } }, "required": ["id", "name", "label", "type"] }, "ViewDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "objectId": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "default": "table" }, "icon": { "type": "string" }, "isDefault": { "type": "boolean" }, "position": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "visible": { "type": "boolean" } }, "required": ["fieldId"] } }, "filter": { "$ref": "#/components/schemas/Filter" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } }, "required": ["fieldId"] } }, "groupById": { "type": "string", "minLength": 1 }, "settings": { "type": "object", "additionalProperties": {} } }, "required": ["id", "objectId", "label"] }, "LayoutDefinition": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "objectId": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "isDefault": { "type": "boolean" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" } }, "shell": { "type": "string", "enum": ["tabs"] }, "header": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" }, "column": { "type": "integer", "minimum": 1, "maximum": 12 }, "columnSpan": { "type": "integer", "minimum": 1, "maximum": 12 }, "row": { "type": "integer", "minimum": 1 } }, "required": ["name", "blockId"] }, "default": [] } }, "required": ["name", "label"] } } }, "required": ["id", "objectId", "label", "shell", "tabs"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "objectId": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "isDefault": { "type": "boolean" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" } }, "shell": { "type": "string", "enum": ["column"] }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] } } }, "required": ["id", "objectId", "label", "shell", "blocks"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "objectId": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "isDefault": { "type": "boolean" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" } }, "shell": { "type": "string", "enum": ["split"] }, "main": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] } }, "aside": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "default": [] } }, "required": ["id", "objectId", "label", "shell", "main"], "additionalProperties": false } ] }, "NavItemDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "target": { "$ref": "#/components/schemas/NavTarget" }, "position": { "type": "integer" }, "parentId": { "$ref": "#/components/schemas/Id" }, "pinned": { "type": "boolean" } }, "required": ["id", "label", "target"] }, "CommandItemDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "group": { "type": "string" }, "shortcut": { "type": "string" }, "action": { "$ref": "#/components/schemas/CommandAction" } }, "required": ["id", "label", "action"] }, "PageDeclaration": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" } }, "required": ["id", "label"] }, "WorkflowDefinition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "enabled": { "type": "boolean" }, "trigger": { "$ref": "#/components/schemas/WorkflowTrigger" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" }, "minItems": 1 } }, "required": ["id", "title", "trigger", "steps"] }, "ApplyResult": { "type": "object", "properties": { "moduleId": { "type": "string" }, "version": { "type": "string" }, "manifestHash": { "type": "string" }, "metadataVersion": { "type": "integer" }, "applied": { "type": "array", "items": { "$ref": "#/components/schemas/PlanChange" } } }, "required": ["moduleId", "version", "manifestHash", "metadataVersion", "applied"] }, "ApplyRequest": { "type": "object", "properties": { "manifest": { "$ref": "#/components/schemas/ModuleManifest" }, "expectedPlanHash": { "type": "string" }, "allowDestructive": { "type": "boolean" } }, "required": ["manifest"] }, "ConnectionList": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionProviderStatus" } }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } }, "required": ["providers", "connections"] }, "ConnectionProviderStatus": { "type": "object", "properties": { "moduleId": { "type": "string" }, "providerId": { "type": "string" }, "kind": { "type": "string", "enum": ["api_key", "oauth2"] }, "label": { "type": "string" }, "visibility": { "type": "string", "enum": ["user", "workspace", "both"] }, "available": { "type": "boolean" }, "problem": { "type": "string" }, "redirectUrl": { "type": "string" } }, "required": ["moduleId", "providerId", "kind", "label", "visibility", "available"] }, "Connection": { "type": "object", "properties": { "id": { "type": "string" }, "moduleId": { "type": "string" }, "providerId": { "type": "string" }, "kind": { "type": "string", "enum": ["api_key", "oauth2"] }, "visibility": { "type": "string", "enum": ["user", "workspace"] }, "ownerUserId": { "type": ["string", "null"] }, "label": { "type": ["string", "null"] }, "account": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["connected", "auth_failed"] }, "hints": { "type": "object", "additionalProperties": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": ["string", "null"] }, "lastError": { "type": ["string", "null"] }, "authFailedAt": { "type": ["string", "null"] }, "lastTestedAt": { "type": ["string", "null"] }, "lastUsedAt": { "type": ["string", "null"] }, "webhookPath": { "type": ["string", "null"] }, "webhookUrl": { "type": ["string", "null"] }, "createdBy": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "moduleId", "providerId", "kind", "visibility", "ownerUserId", "label", "account", "status", "hints", "scopes", "expiresAt", "lastError", "authFailedAt", "lastTestedAt", "lastUsedAt", "webhookPath", "createdBy", "createdAt", "updatedAt" ] }, "ConnectionCreate": { "type": "object", "properties": { "module": { "type": "string", "minLength": 1 }, "provider": { "type": "string" }, "visibility": { "type": "string", "enum": ["user", "workspace"] }, "label": { "type": "string", "maxLength": 120 }, "values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 4096 } } }, "required": ["module", "values"] }, "ConnectionPatch": { "type": "object", "properties": { "label": { "type": ["string", "null"], "maxLength": 120 }, "values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 4096 } } } }, "ConnectionAuthorizeResult": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }, "ConnectionAuthorize": { "type": "object", "properties": { "module": { "type": "string", "minLength": 1 }, "provider": { "type": "string" }, "visibility": { "type": "string", "enum": ["user", "workspace"] }, "returnTo": { "type": "string", "maxLength": 2000 } }, "required": ["module"] }, "ConnectionTestResult": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "account": { "type": "string" }, "testedAt": { "type": "string" } }, "required": ["ok", "testedAt"] }, "ModuleVariable": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "secret": { "type": "boolean" }, "required": { "type": "boolean" }, "value": { "type": ["string", "null"] }, "source": { "type": "string", "enum": ["workspace", "default", "unset"] } }, "required": ["id", "label", "secret", "required", "value", "source"] }, "ModuleVariablesPatch": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 4096 } } }, "required": ["values"] }, "WebhookEventPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string" }, "moduleId": { "type": "string" }, "type": { "type": "string" }, "externalId": { "type": ["string", "null"] }, "payload": {}, "receivedAt": { "type": "string" } }, "required": ["id", "moduleId", "type", "externalId", "receivedAt"] }, "ApiKeySummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": ["string", "null"] }, "start": { "type": ["string", "null"] }, "prefix": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "expiresAt": { "type": ["string", "null"] }, "lastRequest": { "type": ["string", "null"] }, "permissions": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["id", "name", "createdAt"] }, "CreatedApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": ["string", "null"] }, "start": { "type": ["string", "null"] }, "prefix": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "expiresAt": { "type": ["string", "null"] }, "lastRequest": { "type": ["string", "null"] }, "permissions": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "key": { "type": "string" } }, "required": ["id", "name", "createdAt", "key"] }, "CreateApiKey": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "permissions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["name"] }, "WorkspaceMember": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": ["string", "null"] } }, "required": ["id", "name", "email", "image"] } }, "required": ["id", "userId", "role", "createdAt", "user"] }, "UpdateMemberRole": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/WorkspaceRole" } }, "required": ["role"] }, "WorkspaceRole": { "type": "string", "enum": ["owner", "admin", "member"] }, "WorkspaceInvitation": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "accepted", "rejected", "canceled"] }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "inviterId": { "type": "string" } }, "required": ["id", "email", "role", "status", "expiresAt", "createdAt", "inviterId"] }, "CreateInvitation": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/WorkspaceRole" } }, "required": ["email"] }, "AiSettings": { "type": "object", "properties": { "defaultAgentId": { "type": ["string", "null"] }, "updatedAt": { "type": ["string", "null"] } }, "required": ["defaultAgentId", "updatedAt"] }, "AiSettingsPatch": { "type": "object", "properties": { "defaultAgentId": { "type": ["string", "null"] } } }, "AiAgent": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "instructions": { "type": ["string", "null"] }, "tools": { "type": ["array", "null"], "items": { "type": "string" } }, "starterPrompts": { "type": "array", "items": { "type": "string" } }, "approvalOverrides": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ApprovalMode" } }, "skills": { "type": ["array", "null"], "items": { "type": "string" } }, "takesTasks": { "type": "boolean" }, "moduleId": { "type": ["string", "null"] }, "archivedAt": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "workspaceId", "id", "label", "icon", "description", "instructions", "tools", "starterPrompts", "approvalOverrides", "skills", "takesTasks", "moduleId", "archivedAt", "createdAt", "updatedAt" ] }, "ApprovalMode": { "type": "string", "enum": ["auto", "approve"] }, "AiAgentActivity": { "type": "object", "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/AiAgentActivityDay" } } }, "required": ["days"] }, "AiAgentActivityDay": { "type": "object", "properties": { "date": { "type": "string" }, "conversations": { "type": "integer" }, "messages": { "type": "integer" }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } }, "required": ["date", "conversations", "messages", "inputTokens", "outputTokens"] }, "AiAgentUsage": { "type": "object", "properties": { "agentId": { "type": "string" }, "conversations": { "type": "integer" }, "usage": { "$ref": "#/components/schemas/AiUsage" }, "lastMessageAt": { "type": ["string", "null"] } }, "required": ["agentId", "conversations", "usage", "lastMessageAt"] }, "AiAgentInput": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": ["string", "null"], "maxLength": 64 }, "description": { "type": ["string", "null"], "maxLength": 500 }, "instructions": { "type": ["string", "null"], "maxLength": 20000 }, "tools": { "type": ["array", "null"], "items": { "type": "string" }, "minItems": 1, "maxItems": 500 }, "starterPrompts": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 5 }, "approvalOverrides": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ApprovalMode" } }, "skills": { "type": ["array", "null"], "items": { "type": "string" }, "maxItems": 50 }, "takesTasks": { "type": "boolean" } }, "required": ["label"] }, "AiAgentPatch": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": ["string", "null"], "maxLength": 64 }, "description": { "type": ["string", "null"], "maxLength": 500 }, "instructions": { "type": ["string", "null"], "maxLength": 20000 }, "tools": { "type": ["array", "null"], "items": { "type": "string" }, "minItems": 1, "maxItems": 500 }, "starterPrompts": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 5 }, "approvalOverrides": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ApprovalMode" } }, "skills": { "type": ["array", "null"], "items": { "type": "string" }, "maxItems": 50 }, "takesTasks": { "type": "boolean" }, "archived": { "type": "boolean" } } }, "AiSkillSummary": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "moduleId": { "type": ["string", "null"] }, "archivedAt": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["workspaceId", "id", "label", "description", "moduleId", "archivedAt", "createdAt", "updatedAt"] }, "AiSkill": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "moduleId": { "type": ["string", "null"] }, "archivedAt": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "body": { "type": "string" } }, "required": [ "workspaceId", "id", "label", "description", "moduleId", "archivedAt", "createdAt", "updatedAt", "body" ] }, "AiSkillInput": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "One line saying when to use the skill" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The procedure to follow, as Markdown" } }, "required": ["label", "description", "body"] }, "AiSkillPatch": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "One line saying when to use the skill" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The procedure to follow, as Markdown" }, "archived": { "type": "boolean" } } }, "WebhookResult": { "type": "object", "properties": { "received": { "type": "integer" }, "duplicates": { "type": "integer" } }, "required": ["received", "duplicates"] }, "AiStatus": { "type": "object", "properties": { "configured": { "type": "boolean" }, "model": { "type": "string" }, "effort": { "type": "string" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/AiToolInfo" } }, "canManage": { "type": "boolean" } }, "required": ["configured", "model", "effort", "tools", "canManage"] }, "AiToolInfo": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "area": { "type": "string", "enum": [ "records", "model", "workflows", "documents", "tasks", "modules", "actions", "people", "notifications", "agents", "skills", "interface", "conversation" ] }, "readOnly": { "type": "boolean" }, "escalates": { "type": "boolean" }, "approval": { "$ref": "#/components/schemas/ApprovalMode" }, "locked": { "type": "boolean" }, "moduleId": { "type": ["string", "null"] } }, "required": ["name", "description", "area", "readOnly", "escalates", "approval", "locked", "moduleId"] }, "Conversation": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "title": { "type": ["string", "null"] }, "activeTurnId": { "type": ["string", "null"] }, "usage": { "$ref": "#/components/schemas/AiUsage" }, "lastMessageAt": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "workspaceId", "userId", "agentId", "title", "activeTurnId", "usage", "lastMessageAt", "createdAt", "updatedAt" ] }, "CreateConversationInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "agentId": { "type": "string" } } }, "ConversationThread": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "activeTurn": { "$ref": "#/components/schemas/AiTurn" } }, "required": ["conversation", "messages", "activeTurn"] }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "turnId": { "type": "string" }, "seq": { "type": "integer" }, "role": { "type": "string", "enum": ["user", "assistant"] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/DisplayBlock" } }, "text": { "type": "string" }, "context": { "$ref": "#/components/schemas/ChatContext" }, "model": { "type": "string" }, "usage": { "$ref": "#/components/schemas/AiUsage" }, "stopReason": { "type": ["string", "null"] }, "partial": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": ["id", "conversationId", "turnId", "seq", "role", "blocks", "createdAt"] }, "DisplayBlock": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["text"] }, "text": { "type": "string" } }, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["thinking"] }, "text": { "type": "string" } }, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["tool_use"] }, "toolCall": { "$ref": "#/components/schemas/ToolCall" } }, "required": ["type", "toolCall"] } ] }, "ChatContext": { "type": "object", "properties": { "page": { "type": "object", "properties": { "object": { "type": "string" }, "recordId": { "type": "string" }, "viewId": { "type": "string" }, "path": { "type": "string" }, "workflowId": { "type": "string" } } } } }, "AiTurn": { "type": ["object", "null"], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "status": { "$ref": "#/components/schemas/TurnStatus" }, "iteration": { "type": "integer" }, "usage": { "$ref": "#/components/schemas/AiUsage" }, "error": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] }, "startedAt": { "type": "string" }, "finishedAt": { "type": ["string", "null"] } }, "required": ["id", "conversationId", "status", "iteration", "usage", "error", "startedAt", "finishedAt"] }, "TurnStatus": { "type": "string", "enum": ["running", "awaiting_approval", "completed", "failed", "cancelled"] }, "SendMessageInput": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 20000 }, "context": { "$ref": "#/components/schemas/ChatContext" } }, "required": ["content"] }, "ResolveToolCallInput": { "type": "object", "properties": { "approved": { "type": "boolean" }, "reason": { "type": "string", "maxLength": 2000 }, "values": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 10000 } } }, "required": ["approved"] } }, "parameters": {} }, "paths": { "/api/health": { "get": { "summary": "Health check", "tags": ["system"], "responses": { "200": { "description": "Server is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/api/me": { "get": { "summary": "Get the current user", "tags": ["auth"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The signed-in user and their workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces": { "get": { "summary": "List workspaces", "tags": ["workspaces"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Workspaces the user belongs to", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceSummary" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a workspace", "tags": ["workspaces"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspace" } } } }, "responses": { "201": { "description": "Created workspace (the caller is its owner)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSummary" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata": { "get": { "summary": "Get the workspace schema", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "The whole workspace schema; ETag is the metadata version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSchema" } } } }, "304": { "description": "Not modified" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/blocks": { "get": { "summary": "List the blocks a layout can place", "description": "The blocks of the studio and of the installed modules that render on a surface: record pages (what a layout cell names) by default, or Home, dialogs, the panel or approvals.", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "enum": ["record", "home", "dialog", "panel", "approval"], "description": "Where the blocks render; record pages (layouts) by default" }, "required": false, "description": "Where the blocks render; record pages (layouts) by default", "name": "surface", "in": "query" } ], "responses": { "200": { "description": "The blocks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockList" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/objects/{object}/describe": { "get": { "summary": "Describe an object", "description": "The object with its fields and its views, in one read: what a script needs to write records or change the data model.", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular) or id" }, "required": true, "description": "Object API name (nameSingular) or id", "name": "object", "in": "path" } ], "responses": { "200": { "description": "The object, its fields and its views", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectDescription" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/objects": { "get": { "summary": "List objects", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "All objects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectMetadata" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create an object", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectCreateInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectMetadata" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/objects/{id}": { "get": { "summary": "Get an object", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectMetadata" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update an object", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nameSingular": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "namePlural": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "labelSingular": { "type": "string", "minLength": 1 }, "labelPlural": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "description": { "type": "string" }, "primaryFieldId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The id of the field that names a record, one of the object's fields (create the field first); the first text field when left out." }, "readOnly": { "type": "boolean" }, "deleteWhen": { "anyOf": [ { "type": "object", "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": ["and"] }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": ["or"] }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/Filter" } }, "required": ["not"] }, { "$ref": "#/components/schemas/FilterCondition" } ], "description": "A record can be deleted only while it matches this filter, e.g. status is draft. null removes the rule." } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectMetadata" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete an object", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/fields": { "get": { "summary": "List fields", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "All fields", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FieldMetadata" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a field", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldMetadata" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/fields/{id}": { "get": { "summary": "Get a field", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldMetadata" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a field", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "The object: its id, or its API name (e.g. 'person'), plural name or id" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "type": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {} }, "isRequired": { "type": "boolean" }, "isUnique": { "type": "boolean" }, "defaultValue": {}, "position": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldMetadata" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a field", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/views": { "get": { "summary": "List views", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "All views", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ViewMetadata" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a view", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewMetadata" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/views/{id}": { "get": { "summary": "Get a view", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewMetadata" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a view", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "The object: its id, or its API name (e.g. 'person'), plural name or id" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "isDefault": { "type": "boolean" }, "position": { "type": "integer" }, "config": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string" }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "visible": { "type": "boolean", "default": true } }, "required": ["fieldId"] } }, "filter": { "$ref": "#/components/schemas/Filter" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } }, "required": ["fieldId"] } }, "groupById": { "type": ["string", "null"] }, "settings": { "type": "object", "additionalProperties": {} } } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewMetadata" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a view", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/layouts": { "get": { "summary": "List layouts", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "All layouts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Layout" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a layout", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayoutInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layout" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/layouts/{id}": { "get": { "summary": "Get a layout", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layout" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a layout", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "minLength": 1, "description": "The object: its id, or its API name (e.g. 'person'), plural name or id" }, "label": { "type": "string", "minLength": 1 }, "isDefault": { "type": "boolean" }, "shell": { "type": "string", "enum": ["tabs", "column", "split"], "description": "The shape of the page. `tabs`: a header block, a tab bar and a 12-column grid of blocks per tab (give `header` and `tabs`). `column`: one centered column under a slim toolbar, for things people write in (give `blocks`). `split`: a main column and an aside on the right, like an issue (give `main` and `aside`). A shape takes only its own keys." }, "header": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"], "description": "`tabs` only: the block that draws the page header (the object's icon and name when left out)." }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" }, "column": { "type": "integer", "minimum": 1, "maximum": 12 }, "columnSpan": { "type": "integer", "minimum": 1, "maximum": 12 }, "row": { "type": "integer", "minimum": 1 } }, "required": ["name", "blockId"] }, "default": [] } }, "required": ["name", "label"] }, "description": "`tabs` only: the tabs, each a grid of blocks." }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "description": "`column` only: the blocks, top to bottom." }, "main": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "description": "`split` only: the blocks of the main column, top to bottom." }, "aside": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Names the cell, unique in the layout (a short identifier like `comments`)" }, "label": { "type": "string" }, "blockId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "The block's id, from list_blocks: the record's fields (config.fieldIds lists fields by id or API name, default all), the records whose relation points at this one (config.objectId, config.fieldId (its relation field), optional config.limit), the activity (history), or a record block an installed module declares. list_blocks lists them all with their config." }, "config": { "type": "object", "additionalProperties": {} }, "optional": { "type": "boolean" } }, "required": ["name", "blockId"] }, "description": "`split` only: the blocks of the aside, top to bottom." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutAction" } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layout" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a layout", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/nav-items": { "get": { "summary": "List nav items", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "All nav-items", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NavItem" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a nav item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavItemInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavItem" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/nav-items/{id}": { "get": { "summary": "Get a nav item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavItem" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a nav item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "target": { "$ref": "#/components/schemas/NavTarget" }, "position": { "type": "integer" }, "parentId": { "type": ["string", "null"] }, "hidden": { "type": "boolean" }, "pinned": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavItem" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a nav item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/nav-items/arrange": { "post": { "summary": "Arrange nav items", "description": "Moves several nav items at once, so a reorder is one change. A module’s items are moved as the workspace’s choice and survive module updates.", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The new parent and position of each item moved", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavArrange" } } } }, "responses": { "200": { "description": "Every nav item, as arranged", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NavItem" } } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/nav-items/{id}/reset": { "post": { "summary": "Reset a nav item", "description": "Drops the workspace’s overrides of a module’s nav item, so it shows as the module defines it.", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The nav item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavItem" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/nav-items/reset": { "post": { "summary": "Reset the navigation", "description": "Clears the workspace’s overrides of every nav item, so the sidebar is as the modules and the studio define it. Items the workspace created are kept.", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Every nav item that remains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NavItem" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/command-items": { "get": { "summary": "List command items", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "All command-items", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommandItem" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a command item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandItemInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandItem" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/metadata/command-items/{id}": { "get": { "summary": "Get a command item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandItem" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a command item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "icon": { "type": "string" }, "group": { "type": "string" }, "shortcut": { "type": "string" }, "action": { "$ref": "#/components/schemas/CommandAction" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandItem" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a command item", "tags": ["metadata"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/list": { "post": { "summary": "List records", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "Query IR; the path object wins over the body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryBody" } } } }, "responses": { "200": { "description": "A page of records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/aggregate": { "post": { "summary": "Aggregate records", "description": "Counts and measures (sum, average, min, max) over the records that match, per group of one field or in total. Select fields list every option, in order.", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "What to group by and measure; the filter is the query filter", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregateBody" } } } }, "responses": { "200": { "description": "Groups with their count and measures, and the totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregateResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/{id}": { "get": { "summary": "Get a record", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordData" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a record", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Partial field values", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordWrite" } } } }, "responses": { "200": { "description": "Updated record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordData" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a record", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/{id}/labels": { "get": { "summary": "Get a record with the labels of its relations", "description": "The record, and for each relation field the record it points at, so a reader can say who it is.", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The record and the records its relations point at", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordWithLabels" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}": { "post": { "summary": "Create a record", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "Field values by API name", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordWrite" } } } }, "responses": { "201": { "description": "Created record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordData" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete records", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRecords" } } } }, "responses": { "204": { "description": "Deleted" }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/upsert": { "post": { "summary": "Create or update a record by a unique field", "description": "Finds the record whose unique field has the given value: updates it with `values`, or creates one with `values` and the match. The field must be unique.", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "The unique field to match on, and the values", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertBody" } } } }, "responses": { "200": { "description": "The record, and whether it was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/batch": { "post": { "summary": "Batch write records", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "Up to 500 operations in one transaction", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInput" } } } }, "responses": { "200": { "description": "What was created, updated and deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/import": { "post": { "summary": "Import records from the rows of a file", "description": "Reads the cells as text by the rules of the import (numbers, dates, options, related records by name), validates every row, writes the valid ones and reports the rest by row. `dryRun` writes nothing. At most 500 rows per call: send a bigger file in several.", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" } ], "requestBody": { "description": "The columns, the rows as text and how to read them", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportBody" } } } }, "responses": { "200": { "description": "How many were created, updated and skipped, and the problems by row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportReport" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/lookup": { "post": { "summary": "Look up records", "tags": ["records"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Free-text search across objects", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupInput" } } } }, "responses": { "200": { "description": "Search hits", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LookupHit" } } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/{id}/activity": { "get": { "summary": "List a record's activity", "description": "Changes, newest first. Page with `nextCursor`.", "tags": ["activity"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of activity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/{id}/comments": { "get": { "summary": "List a record's comments", "description": "Newest first. Page with `nextCursor`; `total` is how many the record has.", "tags": ["comments"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommentPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Add a comment to a record", "tags": ["comments"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "The comment: a title and an optional body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommentInput" } } } }, "responses": { "201": { "description": "The comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordComment" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/records/{object}/{id}/comments/{commentId}": { "patch": { "summary": "Edit a comment", "description": "Authors can edit their own comments; owners and admins any.", "tags": ["comments"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "commentId", "in": "path" } ], "requestBody": { "description": "The title and/or the body to change", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommentPatch" } } } }, "responses": { "200": { "description": "The comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordComment" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Remove a comment", "description": "Authors can remove their own comments; owners and admins any.", "tags": ["comments"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Object API name (nameSingular)" }, "required": true, "description": "Object API name (nameSingular)", "name": "object", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "commentId", "in": "path" } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/documents": { "get": { "summary": "List documents", "description": "Newest change first, without their text; page with `nextCursor`. `search` matches the title and the text, `mentions` keeps the documents that mention a record or another document (`record:/`, `document:`), `ids` picks some by id.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "mentions", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "ids", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "updatedAfter", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a document", "description": "A title and, optionally, the text as `markdown` (or as an editor document in `body`). Mention a record or a document with a link, `[Label](record:/)` or `[Label](document:)`.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The document: a title and, optionally, its text", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/documents/{id}": { "get": { "summary": "Get a document", "description": "The whole document: its text as an editor document (`body`) and as Markdown, and its `version`.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a document", "description": "Sends only what changes. A new `body` or `markdown` replaces the whole text. With `expectedVersion`, a document that changed since is a `CONFLICT`; without it the change overwrites.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPatch" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a document", "description": "The document stops being listed, readable and linked.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/documents/{id}/append": { "post": { "summary": "Add to a document", "description": "Adds Markdown after the last block, atomically: nothing needs reading first, and a person typing meanwhile loses nothing.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "The Markdown to add", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAppend" } } } }, "responses": { "200": { "description": "The document with the text added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/documents/{id}/activity": { "get": { "summary": "List a document’s timeline", "description": "When it was made, who edited it and the comments written on it, newest first; page with `nextCursor`.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of the timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentActivityPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/documents/{id}/comments": { "post": { "summary": "Comment on a document", "description": "Adds a comment as Markdown; mention with `[Label](record:/)` or `[Name](member:)`. Give `anchor.quote`, text of the document, to put it on that text (the studio underlines it and shows the comment beside it); give `parent`, the id of a top-level comment, to reply to its thread. A comment does not change the document or its version.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "The comment: its text, and optionally the text it is on or the comment it replies to", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCommentInput" } } } }, "responses": { "201": { "description": "The comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentComment" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "summary": "List the comments of a document", "description": "Threads: each a top-level comment (with the text it is on, if any, and whether it is resolved) and its replies, oldest first. `status` is `open` (default), `resolved` or `all`.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": ["open", "resolved", "all"] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "The threads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentThreadPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/documents/{id}/comments/{commentId}": { "patch": { "summary": "Change or resolve a comment", "description": "Send `resolved: true` to resolve a top-level comment (and so its thread) or `false` to reopen it; send `markdown` to change the text, which only its author or an admin may do.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "commentId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCommentPatch" } } } }, "responses": { "200": { "description": "The comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentComment" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a comment", "description": "Only its author or an admin may. Deleting a top-level comment deletes its replies.", "tags": ["documents"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "commentId", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks": { "get": { "summary": "List tasks", "description": "Most recently changed first, without their text; page with `nextCursor`. `assignee` is `me`, `unassigned`, `agents`, `people`, `user:` or `agent:`; `scope` is `open` or `closed`; `due` is `overdue`, `today`, `week` or `none`; `parent` keeps the subtasks of a task (or `none` for top-level tasks); `mentions` keeps the tasks that mention or are about a record, a document or a task (`record:/`, `document:`, `task:`); `search` matches the title and the description.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": ["open", "closed"] }, "required": false, "name": "scope", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "assignee", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "priority", "in": "query" }, { "schema": { "type": "string", "enum": ["overdue", "today", "week", "none"] }, "required": false, "name": "due", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "today", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "parent", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "mentions", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "work", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "ids", "in": "query" }, { "schema": { "type": "string", "enum": ["updated", "created", "due", "priority", "closed", "title"] }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"] }, "required": false, "name": "order", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a task", "description": "A title and, optionally, the description as `markdown` (or as an editor document in `body`), `priority`, `dueDate` (`YYYY-MM-DD`), an `assignee` (`user:`, `agent:`), a `parent` task and what it is `about` (`record:/`, `document:`). Mention a record, a document, a task or a member with a link: `[Label](record:/)`, `[Label](document:)`, `[Label](task:)`, `[Name](member:)`. The same `key` twice returns the first task instead of making another.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The task: a title and, optionally, its description, assignee and links", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/counts": { "get": { "summary": "Count tasks", "description": "Open, overdue, due today and this week, in review, the caller’s own and by status.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "today", "in": "query" } ], "responses": { "200": { "description": "Counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCounts" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/{id}": { "get": { "summary": "Get a task", "description": "The whole task: its description as an editor document (`body`) and as Markdown, what it mentions and is about, its subtask counts and its `version`.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a task", "description": "Sends only what changes. A new `body` or `markdown` replaces the whole description. With `expectedVersion`, a task that changed since is a `CONFLICT`; without it the change overwrites. Moving a task to `done` or `canceled` closes it; any other status reopens it.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPatch" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a task", "description": "The task and its subtasks stop being listed, readable and linked.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/{id}/activity": { "get": { "summary": "List a task’s timeline", "description": "Comments, changes and agent runs of one task, newest first; page with `nextCursor`.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of the timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskActivityPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/{id}/stop": { "post": { "summary": "Stop an agent working on a task", "description": "Cancels the run in progress, declines what it proposed and marks the task as failed until someone retries it.", "tags": ["tasks"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/{id}/retry": { "post": { "summary": "Retry a task", "description": "Puts a failed or stopped task back in the agent’s queue.", "tags": ["tasks"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/{id}/comments": { "post": { "summary": "Comment on a task", "description": "Adds a comment to the task’s timeline as Markdown; mention with `[Label](record:/)` or `[Name](member:)`. A comment does not change the task’s version.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "The comment, as Markdown", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "responses": { "201": { "description": "The comment, as a timeline entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskActivityEntry" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflows": { "get": { "summary": "List workflows", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Every workflow of the workspace, oldest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a workflow", "description": "Owners and admins only. The trigger and steps are checked against the workspace metadata: objects, fields, filters and functions must exist.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflows/{id}": { "get": { "summary": "Get a workflow", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The workflow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a workflow", "description": "Sends only what changes. A new trigger, or enabling the workflow, starts it from now: events that happened in between are not replayed.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "enabled": { "type": "boolean" }, "trigger": { "$ref": "#/components/schemas/WorkflowTrigger" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStepInput" }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a workflow", "description": "Its runs go with it.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflows/{id}/runs": { "get": { "summary": "List a workflow's runs", "description": "Newest first. Page with `nextCursor`.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflow-runs": { "get": { "summary": "List the workflow runs about a record", "description": "The runs, newest first, that were about one record or, with `objectId`, about any record of an object (started by hand on it, by a change to it, or by a schedule that ran per record), whichever workflow they belong to. `state=open` keeps only those that wait for a runner, are being worked on or wait to try a step again: it is how a page tells a record is being worked on.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "recordId", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "objectId", "in": "query" }, { "schema": { "type": "string", "enum": ["open", "all"] }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "The runs about the record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunList" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflow-activity": { "get": { "summary": "Get workflow activity", "description": "How the workspace’s workflows have run: runs per day (succeeded and failed) over the last `days` days counted in `tz`, and for every workflow that has run, its runs and failures in that period and how its latest run ended.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 366 }, "required": false, "name": "days", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tz", "in": "query" } ], "responses": { "200": { "description": "Runs per day and per workflow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowActivity" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflows/{id}/run": { "post": { "summary": "Run a workflow now", "description": "Runs the steps right away and returns the finished run. With `wait: false` it queues the run instead and returns it at once, pending, for a runner to take. When the trigger names an object, `recordId` picks the record; the caller must be able to read it. The steps run as the workflow actor.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "What to run on", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowInput" } } } }, "responses": { "201": { "description": "The finished run, or the queued one when `wait` is false", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRun" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/workflows/{id}/runs/{runId}/retry": { "post": { "summary": "Retry a workflow run", "description": "Runs the workflow again with the trigger of an earlier run (its record or module event), and returns the new run, which names the one it retries in `trigger.retryOf`.", "tags": ["workflows"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "runId", "in": "path" } ], "responses": { "201": { "description": "The new run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRun" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/tasks/{id}/runs": { "get": { "summary": "List the runs of a task", "description": "The attempts an agent made at the task, newest first: status, summary and error.", "tags": ["tasks"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunPage" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/notifications": { "get": { "summary": "List my notifications", "description": "The caller’s notifications, newest first. `unread=true` keeps the unread ones; page with `nextCursor`.", "tags": ["notifications"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ] }, "required": false, "name": "unread", "in": "query" } ], "responses": { "200": { "description": "A page of notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Send a notification", "description": "Notify members: everyone (`to.all`), roles (`to.roles`), people by user id (`to.users`) or the caller (`to.me`). `target` says where it leads; a repeated `key` replaces the unread notification instead of adding one.", "tags": ["notifications"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The notification and who receives it", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationInput" } } } }, "responses": { "201": { "description": "How many people it reached, and how many notifications were created or replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSendResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/notifications/unread-count": { "get": { "summary": "Count my unread notifications", "tags": ["notifications"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "How many are unread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnreadCount" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/notifications/{id}/read": { "post": { "summary": "Mark a notification read", "tags": ["notifications"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/notifications/{id}/unread": { "post": { "summary": "Mark a notification unread", "tags": ["notifications"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/notifications/read-all": { "post": { "summary": "Mark all my notifications read", "tags": ["notifications"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "How many were unread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAllReadResult" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/notifications/{id}": { "delete": { "summary": "Delete a notification", "tags": ["notifications"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules": { "get": { "summary": "List installed modules", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Installed modules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledModule" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/plan": { "post": { "summary": "Plan a module install", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The manifest to reconcile", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRequest" } } } }, "responses": { "200": { "description": "The plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Missing dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/apply": { "post": { "summary": "Apply a module manifest", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The manifest to apply, optionally pinned to a reviewed plan", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyRequest" } } } }, "responses": { "200": { "description": "What was applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Missing dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/{moduleId}": { "delete": { "summary": "Uninstall a module", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "moduleId", "in": "path" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "allowDestructive", "in": "query" } ], "responses": { "200": { "description": "What was removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Missing dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/catalog": { "get": { "summary": "List installable modules", "description": "The manifest of every module registered on this server, installed in the workspace or not.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Every registered module", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModuleManifest" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/connections": { "get": { "summary": "List connections", "description": "The workspace's connections and the caller's own, and the providers installed modules offer. Credentials never come back; `hints` carries masked previews.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "description": "Only this module" }, "required": false, "description": "Only this module", "name": "module", "in": "query" } ], "responses": { "200": { "description": "Providers and connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionList" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Connect with an API key", "description": "Store an API key connection, encrypted, and test it against the outside service: the returned `status` is `connected` or `auth_failed` (see `lastError`). A person's own connection needs `module.connect`; a workspace one, owners and admins. OAuth providers connect through `connections.authorize`.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The module, its provider and the values", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCreate" } } } }, "responses": { "201": { "description": "The connection, tested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/connections/{id}": { "get": { "summary": "Get a connection", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Change a connection", "description": "Replace some of its values, or its label; the connection is tested again.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPatch" } } } }, "responses": { "200": { "description": "The connection, tested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Disconnect", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Disconnected" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/connections/authorize": { "post": { "summary": "Start connecting an account", "description": "The OAuth provider's consent page for the caller to open. Once they agree, the provider sends them to the server's callback, which stores the connection and sends them back to `returnTo`.", "tags": ["modules"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The module and its OAuth provider", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionAuthorize" } } } }, "responses": { "200": { "description": "The consent page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionAuthorizeResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/connections/{id}/test": { "post": { "summary": "Test a connection", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTestResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/{moduleId}/variables": { "get": { "summary": "List a module's variables", "description": "What is in effect for each variable the module declares, and where it comes from: this workspace, the default, or nowhere. Each has an id; set values by it. A secret never comes back, only whether it is set.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "moduleId", "in": "path" } ], "responses": { "200": { "description": "The variables", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModuleVariable" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Set a module's variables", "description": "Owners and admins only. Sets this workspace's values of the module's variables, by the ids list_module_variables gives (an empty string goes back to the default). A secret variable is typed in Settings → Modules, never through the agent: this refuses it.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "moduleId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModuleVariablesPatch" } } } }, "responses": { "200": { "description": "The variables", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModuleVariable" } } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/{moduleId}/events": { "get": { "summary": "List a module's events", "description": "Events the module delivered through its webhook, newest first. Page with `nextCursor`.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "moduleId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "type", "in": "query" } ], "responses": { "200": { "description": "A page of events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventPage" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/api-keys": { "get": { "summary": "List API keys", "tags": ["api-keys"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Keys of this workspace", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeySummary" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create an API key", "tags": ["api-keys"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKey" } } } }, "responses": { "201": { "description": "The new key; `key` is shown only once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/api-keys/{id}": { "delete": { "summary": "Delete an API key", "tags": ["api-keys"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Archived" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/members": { "get": { "summary": "List members", "tags": ["members"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Members with their role, oldest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMember" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/members/{memberId}": { "patch": { "summary": "Change a member's role", "tags": ["members"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "memberId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRole" } } } }, "responses": { "200": { "description": "The member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceMember" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Remove a member", "description": "They lose access to the workspace at once. Records they created stay.", "tags": ["members"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "memberId", "in": "path" } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/invitations": { "get": { "summary": "List pending invitations", "tags": ["members"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Pending invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInvitation" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Invite someone", "description": "They join with the given role when they accept, after signing up with this email if they have no account. Invitations expire after 48 hours.", "tags": ["members"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitation" } } } }, "responses": { "201": { "description": "The invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceInvitation" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/invitations/{invitationId}": { "delete": { "summary": "Cancel an invitation", "tags": ["members"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "invitationId", "in": "path" } ], "responses": { "204": { "description": "Canceled" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/settings": { "get": { "summary": "Get AI settings", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "The default agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettings" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update AI settings", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettingsPatch" } } } }, "responses": { "200": { "description": "Updated settings (owners and admins only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettings" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/agents": { "get": { "summary": "List agents", "description": "The agents of this workspace with their tools; archived ones only when asked for.", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "includeArchived", "in": "query" } ], "responses": { "200": { "description": "The agents of this workspace", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AiAgent" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create an agent", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentInput" } } } }, "responses": { "201": { "description": "The new agent (owners and admins only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgent" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/agents/{id}/activity": { "get": { "summary": "Get agent activity", "description": "One agent's conversations started, replies given and tokens used (input and output) per day over the last `days` days counted in `tz`.", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 366 }, "required": false, "name": "days", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tz", "in": "query" } ], "responses": { "200": { "description": "The agent's activity per day (owners and admins only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentActivity" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/agents/usage": { "get": { "summary": "Get agent usage", "description": "How many conversations each agent has had (everyone's) and the tokens they used, for every agent including archived ones.", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Usage per agent (owners and admins only)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AiAgentUsage" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/agents/{id}": { "patch": { "summary": "Update an agent", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentPatch" } } } }, "responses": { "200": { "description": "The updated agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgent" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Archive an agent", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/skills": { "get": { "summary": "List skills", "tags": ["skills"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "enum": ["true", "false"] }, "required": false, "name": "includeArchived", "in": "query" } ], "responses": { "200": { "description": "The skills of this workspace (owners and admins only)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AiSkillSummary" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a skill", "tags": ["skills"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillInput" } } } }, "responses": { "201": { "description": "The new skill (owners and admins only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkill" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/skills/{id}": { "get": { "summary": "Get a skill", "tags": ["skills"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The skill, with its text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkill" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update a skill", "tags": ["skills"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillPatch" } } } }, "responses": { "200": { "description": "The updated skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkill" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Archive a skill", "tags": ["skills"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Archived" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-4234df6192ae/actions/recalculate_quote": { "post": { "summary": "Recalculate a quote", "description": "Add the quote's items up and store the total on the quote.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Recalculate a quote", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_id": { "type": "string", "minLength": 1 } }, "required": ["quote_id"] } } } }, "responses": { "200": { "description": "What it returns: id (the id of a record of 01a17356-5c6d-765a-82b2-067efe9f82a4): The quote.; total (number): The quote's fresh total.; items (number): How many items it has.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-47af0d9faa3a/actions/recalculate_invoice": { "post": { "summary": "Recalculate an invoice", "description": "Total the lines and store subtotal, discount, tax and total on the invoice.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Recalculate an invoice", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "minLength": 1 } }, "required": ["invoice_id"] } } } }, "responses": { "200": { "description": "What it returns: id (the id of a record of 01a17356-5c6c-76d4-aa86-978b865606c1): The invoice.; subtotal (number): The lines added up.; discount_amount (number): What the discount takes off.; tax (number): The tax on what is left.; total (number): What the customer owes.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-47af0d9faa3a/actions/add_payment": { "post": { "summary": "Add a payment", "description": "Add a payment to a sent invoice; a settled invoice becomes paid.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Add a payment", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "minLength": 1 }, "amount": { "type": ["number", "null"], "exclusiveMinimum": 0 }, "paid_on": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "method": { "type": ["string", "null"], "enum": ["bank_transfer", "card", "cash", "other", null] }, "reference": { "type": ["string", "null"] } }, "required": ["invoice_id"] } } } }, "responses": { "200": { "description": "What it returns: payment_id (the id of a record of 01a17356-5c6c-76d4-aa86-9ed6e20902ff): The payment recorded.; invoice_id (the id of a record of 01a17356-5c6c-76d4-aa86-978b865606c1): The invoice it was recorded on.; paid (number): What has been paid so far, this payment included.; balance (number): What is still owed.; status (text): The invoice's status after this payment.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-4c5e734c8e86/actions/stock_on_hand": { "post": { "summary": "Stock on hand", "description": "Stock on hand by product and location, and what is low. Filter by product or location.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Stock on hand", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": ["string", "null"] }, "location": { "type": ["string", "null"] } } } } } }, "responses": { "200": { "description": "What it returns: products (json): Products with any move: stock on hand, reorder point, low flag, and by location.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-4c5e734c8e86/actions/transfer_stock": { "post": { "summary": "Move stock between locations", "description": "Move a quantity of a product from one location to another.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Move stock between locations", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "moved_on": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "reference": { "type": ["string", "null"] } }, "required": ["product", "from", "to", "quantity"] } } } }, "responses": { "200": { "description": "What it returns: out (the id of a record of 01a17356-5c6c-76d4-aa86-1d0e8d9f8e06): The move out of the first location.; in (the id of a record of 01a17356-5c6c-76d4-aa86-1d0e8d9f8e06): The move into the second.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-4c5e734c8e86/actions/count_stock": { "post": { "summary": "Record a stock count", "description": "Record the counted quantity of a product at a location; any difference is recorded as a count move.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Record a stock count", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "counted": { "type": ["number", "null"], "minimum": 0 }, "counted_on": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": ["product", "location", "counted"] } } } }, "responses": { "200": { "description": "What it returns: before (number): What the moves added up to before the count.; counted (number): What was counted.; difference (number): Counted minus before.; move_id (the id of a record of 01a17356-5c6c-76d4-aa86-1d0e8d9f8e06): The count move that recorded the difference; null when it matched.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-5201430b1059/actions/create_invoice_payment_link": { "post": { "summary": "Create a payment link for an invoice", "description": "Create a payment link for what is left to pay on a sent invoice; the payment is recorded when the customer pays. Needs Invoicing and the checkout.session webhook events.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Create a payment link for an invoice", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "description": "The connection to use, from list_connections" } }, "required": ["invoice_id"] } } } }, "responses": { "200": { "description": "What it returns: invoice_id (the id of a record of 01a17356-5c6c-76d4-aa86-978b865606c1): The invoice.; url (text): The payment link, also stored on the invoice.; amount (number): What the link asks for: what is left to pay.; currency (text): The currency of the amount.; reused (boolean): True when the invoice already had a link for that amount.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-5201430b1059/actions/handle_checkout_event": { "post": { "summary": "Handle a Stripe checkout event", "description": "Add the payment of a paid Checkout session, from an invoice's payment link, to its invoice. Anything else is left alone, and a payment already recorded is not added twice. The workflow that comes with the module runs it for each event.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Handle a Stripe checkout event", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "additionalProperties": {} }, "connectionId": { "type": "string", "description": "The connection to use, from list_connections" } }, "required": ["event"] } } } }, "responses": { "200": { "description": "What it returns: recorded (boolean): True when a payment was added to the invoice.; reason (text): Why nothing was added, when nothing was.; invoice_id (the id of a record of 01a17356-5c6c-76d4-aa86-978b865606c1): The invoice.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a173cd-7d37-7041-9060-55d4bb9b036b/actions/send_email": { "post": { "summary": "Send an email", "description": "Send a transactional email from a verified domain.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Send an email", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] }, "subject": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "text": { "type": "string" }, "reply_to": { "type": "string" }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "connectionId": { "type": "string", "description": "The connection to use, from list_connections" } }, "required": ["from", "to", "subject"] } } } }, "responses": { "200": { "description": "What it returns: id (text): The email id, which the webhook events refer to as email_id.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/modules/01a17ead-51f8-77e3-a0d1-7b99efb1b867/actions/enrich_person": { "post": { "summary": "Enrich a person with Context.dev", "description": "Look a CRM person up on Context.dev by their email (or their first and last name and a company or city) and fill in what is empty: job title, city, country, LinkedIn, X, GitHub and website, and the company when it is already in the CRM. Never overwrites what is there. A match costs 20 Context.dev credits, so a person looked up in the last 30 days is not looked up again unless `force` is set.", "tags": ["modules"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "The input of Enrich a person with Context.dev", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "person_id": { "type": "string", "minLength": 1 }, "force": { "type": "boolean" }, "connectionId": { "type": "string", "description": "The connection to use, from list_connections" } }, "required": ["person_id"] } } } }, "responses": { "200": { "description": "What it returns: enriched (boolean): True when the person was updated.; reason (text): Why nothing was filled in, when nothing was.; score (number): Context.dev's confidence in the match, from 0 to 100.; fields (json): The names of the fields that were filled in.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/events": { "get": { "summary": "Subscribe to the change feed", "tags": ["events"], "security": [ { "cookieAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "text/event-stream. First `event: ready` with `{\"sequence\"}`, then events after `after` (or `Last-Event-ID`), then live events; each has `id: ` and `event: `." } } } }, "/api/webhooks/{token}": { "post": { "summary": "Receive a webhook", "description": "The URL a module's connection shows as `webhookUrl`. The signature is checked with that connection's webhook secret; the body is stored as the event payload. Unknown tokens answer 404, failed checks 400. Not for clients.", "tags": ["modules"], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResult" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/oauth/callback": { "get": { "summary": "Finish connecting an account", "description": "The redirect URI to register with an OAuth provider. It checks the state, exchanges the code, stores the connection and sends the person back to the studio. Not for clients.", "tags": ["modules"], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "200": { "description": "How it went, for a window that closes itself", "content": { "text/html": { "schema": { "type": "string" } } } }, "302": { "description": "Back to the studio page the consent started from" } } } }, "/api/modules/{moduleId}/logo": { "get": { "summary": "A module's logo", "description": "The image the module declares as its `logo`, served from its package. Public. 404 when the module is unknown or declares none. Not for clients to build: the studio shows it where a module is listed.", "tags": ["modules"], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "moduleId", "in": "path" } ], "responses": { "200": { "description": "The image", "content": { "image/svg+xml": { "schema": { "type": "string" } }, "image/png": { "schema": { "type": "string" } }, "image/webp": { "schema": { "type": "string" } } } }, "304": { "description": "Unchanged since the ETag the request sent" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/status": { "get": { "summary": "Get AI status", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Whether the agent is configured, its model and the tools this user can use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiStatus" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/conversations": { "get": { "summary": "List conversations", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "This user's conversations, most recent first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a conversation", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationInput" } } } }, "responses": { "201": { "description": "The new conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/conversations/{id}": { "get": { "summary": "Get a conversation", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The conversation with its messages and the active turn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThread" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a conversation", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/conversations/{id}/messages": { "post": { "summary": "Send a message", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageInput" } } } }, "responses": { "200": { "description": "Send a message and stream the turn. text/event-stream of ChatEvent frames: `event: `, `data: `; heartbeats are comment lines. The stream ends with `paused` (approval needed) or `done`." }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "AI is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/conversations/{id}/tool-calls/{toolCallId}/resolve": { "post": { "summary": "Resolve a tool call", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "toolCallId", "in": "path" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveToolCallInput" } } } }, "responses": { "200": { "description": "Approve or reject a pending tool call and stream the rest of the turn. text/event-stream of ChatEvent frames: `event: `, `data: `; heartbeats are comment lines. The stream ends with `paused` (approval needed) or `done`." }, "400": { "description": "Validation error or invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "AI is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/workspaces/{workspaceId}/ai/conversations/{id}/cancel": { "post": { "summary": "Cancel the active turn", "tags": ["ai"], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Workspace (organization) id" }, "required": true, "description": "Workspace (organization) id", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The cancelled turn, or null when nothing was running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiTurn" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "webhooks": {} }