{ "openapi": "3.0.3", "info": { "title": "Threa Public API", "version": "1.0.0", "description": "The Threa Public API lets you programmatically read and write messages, list streams, search, and more.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer thr_your_api_key_here\n```\n\nAPI keys are created by **workspace admins** in the Threa app under **Settings > API Keys**.\nEach key is scoped to a workspace and granted specific permissions (scopes).\n\n## Scopes\n\nAPI keys are granted specific scopes that control access:\n\n- `messages:search` — Grants access to search messages in public streams in a workspace. Application level stream grants can extend permissions to private streams.\n- `streams:read` — Grants access to list and search accessible streams in a workspace.\n- `messages:read` — Grants access to read messages in accessible streams.\n- `messages:write` — Grants access to send, update, and delete messages in accessible streams.\n- `users:read` — Grants access to list and search workspace users.\n- `memos:read` — Grants access to search preserved workspace memos and inspect their provenance.\n- `attachments:read` — Grants access to search accessible attachments, inspect extracted content, and fetch download URLs.\n- `attachments:write` — Grants access to upload and replace attachments in accessible streams.\n- `bot-runtime:read` — Grants access to read bot runtime presence and invocation state.\n- `bot-runtime:write` — Grants access to heartbeat bot runtime presence and link runtime sessions.\n- `bot-invocations:read` — Grants access to read bot invocation state.\n- `bot-invocations:write` — Grants access to claim, complete, or fail bot invocations.\n\n## Rate Limits\n\nRequests are rate-limited per workspace and per API key. Rate limit headers are included in responses.\n\n## Pagination\n\nList endpoints return paginated results with `hasMore` and `cursor` fields.\nPass the `cursor` value as the `after` query parameter to fetch the next page." }, "servers": [{ "url": "https://app.threa.io", "description": "Production" }], "security": [{ "apiKey": [] }], "paths": { "/api/v1/workspaces/{workspaceId}/messages/search": { "post": { "operationId": "searchMessages", "summary": "Search messages", "tags": ["Messages"], "description": "Full-text and optional semantic search across accessible streams.", "security": [{ "apiKey": ["messages:search"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "semantic": { "default": false, "type": "boolean" }, "exact": { "default": false, "type": "boolean" }, "streams": { "type": "array", "items": { "type": "string" } }, "from": { "type": "string" }, "type": { "type": "array", "items": { "type": "string", "enum": ["scratchpad", "channel", "dm", "thread", "system"] } }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, "required": ["query", "semantic", "exact", "limit"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "sequence": { "type": "string", "description": "Numeric sequence as string" }, "content": { "type": "string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorDisplayName": { "type": "string" }, "replyCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "External references attached by the sender. Always present; empty when unset." }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "rank": { "type": "number" } }, "required": [ "id", "streamId", "sequence", "content", "authorId", "authorType", "replyCount", "metadata", "createdAt", "rank" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/memos/search": { "post": { "operationId": "searchMemos", "summary": "Search memos", "tags": ["Memos"], "description": "Search preserved workspace memos with semantic, exact, or recent-first retrieval.", "security": [{ "apiKey": ["memos:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "default": "", "type": "string" }, "exact": { "type": "boolean" }, "streams": { "type": "array", "items": { "type": "string" } }, "memoType": { "type": "array", "items": { "type": "string", "enum": ["message", "conversation"] } }, "knowledgeType": { "type": "array", "items": { "type": "string", "enum": ["decision", "learning", "procedure", "context", "reference"] } }, "tags": { "type": "array", "items": { "type": "string" } }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": ["query", "limit"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "memo": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "memoType": { "type": "string", "enum": ["message", "conversation"] }, "sourceMessageId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "sourceConversationId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "title": { "type": "string" }, "abstract": { "type": "string" }, "keyPoints": { "type": "array", "items": { "type": "string" } }, "sourceMessageIds": { "type": "array", "items": { "type": "string" } }, "participantIds": { "type": "array", "items": { "type": "string" } }, "knowledgeType": { "type": "string", "enum": ["decision", "learning", "procedure", "context", "reference"] }, "tags": { "type": "array", "items": { "type": "string" } }, "parentMemoId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "status": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "revisionReason": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "archivedAt": { "anyOf": [{ "type": "string", "format": "date-time" }, { "type": "null" }] } }, "required": [ "id", "workspaceId", "memoType", "sourceMessageId", "sourceConversationId", "title", "abstract", "keyPoints", "sourceMessageIds", "participantIds", "knowledgeType", "tags", "parentMemoId", "status", "version", "revisionReason", "createdAt", "updatedAt", "archivedAt" ], "additionalProperties": false }, "distance": { "type": "number" }, "sourceStream": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["id", "type", "name"], "additionalProperties": false }, { "type": "null" } ] }, "rootStream": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["id", "type", "name"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["memo", "distance", "sourceStream", "rootStream"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/memos/{memoId}": { "get": { "operationId": "getMemo", "summary": "Get a memo", "tags": ["Memos"], "description": "Retrieve a memo together with source stream and source message provenance.", "security": [{ "apiKey": ["memos:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "memoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Memo ID (prefixed ULID)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "memo": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "memoType": { "type": "string", "enum": ["message", "conversation"] }, "sourceMessageId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "sourceConversationId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "title": { "type": "string" }, "abstract": { "type": "string" }, "keyPoints": { "type": "array", "items": { "type": "string" } }, "sourceMessageIds": { "type": "array", "items": { "type": "string" } }, "participantIds": { "type": "array", "items": { "type": "string" } }, "knowledgeType": { "type": "string", "enum": ["decision", "learning", "procedure", "context", "reference"] }, "tags": { "type": "array", "items": { "type": "string" } }, "parentMemoId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "status": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "revisionReason": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "archivedAt": { "anyOf": [{ "type": "string", "format": "date-time" }, { "type": "null" }] } }, "required": [ "id", "workspaceId", "memoType", "sourceMessageId", "sourceConversationId", "title", "abstract", "keyPoints", "sourceMessageIds", "participantIds", "knowledgeType", "tags", "parentMemoId", "status", "version", "revisionReason", "createdAt", "updatedAt", "archivedAt" ], "additionalProperties": false }, "distance": { "type": "number" }, "sourceStream": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["id", "type", "name"], "additionalProperties": false }, { "type": "null" } ] }, "rootStream": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["id", "type", "name"], "additionalProperties": false }, { "type": "null" } ] }, "sourceMessages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "streamName": { "type": "string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorName": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "streamId", "streamName", "authorId", "authorType", "authorName", "content", "createdAt" ], "additionalProperties": false } } }, "required": ["memo", "distance", "sourceStream", "rootStream", "sourceMessages"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/attachments": { "post": { "operationId": "uploadAttachment", "summary": "Upload an attachment", "tags": ["Attachments"], "description": "Upload a file as multipart/form-data using field `file`. Include the returned attachment id in message markdown as `attachment:` to attach it to a message.", "security": [{ "apiKey": ["attachments:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "filename", "mimeType", "sizeBytes", "processingStatus", "createdAt"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/attachments/search": { "post": { "operationId": "searchAttachments", "summary": "Search attachments", "tags": ["Attachments"], "description": "Search accessible attachments by filename or extracted content.", "security": [{ "apiKey": ["attachments:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "streams": { "type": "array", "items": { "type": "string" } }, "contentTypes": { "type": "array", "items": { "type": "string", "enum": ["chart", "table", "diagram", "screenshot", "photo", "document", "other"] } }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, "required": ["query", "limit"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "contentType": { "anyOf": [ { "type": "string", "enum": ["chart", "table", "diagram", "screenshot", "photo", "document", "other"] }, { "type": "null" } ] }, "summary": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "streamId": { "type": "string" }, "messageId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "filename", "mimeType", "contentType", "summary", "createdAt"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/attachments/{attachmentId}": { "get": { "operationId": "getAttachment", "summary": "Get an attachment", "tags": ["Attachments"], "description": "Retrieve attachment metadata and extracted content for an accessible attachment.", "security": [{ "apiKey": ["attachments:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Attachment ID (prefixed ULID)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "createdAt": { "type": "string", "format": "date-time" }, "extraction": { "anyOf": [ { "type": "object", "properties": { "contentType": { "type": "string", "enum": ["chart", "table", "diagram", "screenshot", "photo", "document", "other"] }, "summary": { "type": "string" }, "fullText": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "structuredData": { "anyOf": [{}, { "type": "null" }] }, "pdfMetadata": { "anyOf": [{}, { "type": "null" }] }, "textMetadata": { "anyOf": [{}, { "type": "null" }] }, "wordMetadata": { "anyOf": [{}, { "type": "null" }] }, "excelMetadata": { "anyOf": [{}, { "type": "null" }] } }, "required": ["contentType", "summary", "fullText", "structuredData"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "processingStatus", "createdAt", "extraction" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/attachments/{attachmentId}/url": { "get": { "operationId": "getAttachmentDownloadUrl", "summary": "Get an attachment download URL", "tags": ["Attachments"], "description": "Create a short-lived signed URL for an accessible attachment.", "security": [{ "apiKey": ["attachments:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Attachment ID (prefixed ULID)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresIn": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["url", "expiresIn"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/bot-runtime/presence": { "post": { "operationId": "upsertBotRuntimePresence", "summary": "Heartbeat bot runtime presence", "tags": ["Bot runtimes"], "security": [{ "apiKey": ["bot-runtime:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runtimeKind": { "type": "string", "enum": ["pi-local", "hermes", "openclaw", "claude-code-channel", "custom"] }, "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "runtimeSessionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "maxLength": 100 }, "status": { "type": "string", "enum": ["available", "busy", "offline", "error"] }, "acceptingInvocations": { "type": "boolean" }, "capabilities": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "statusText": { "type": "string", "maxLength": 200 }, "publicKey": { "type": "string", "minLength": 44, "maxLength": 44, "pattern": "^[A-Za-z0-9+/]{43}=$" }, "publicKeyId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["runtimeKind", "instanceId", "status", "acceptingInvocations", "capabilities"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "botId": { "type": "string" }, "runtimeKind": { "type": "string", "enum": ["pi-local", "hermes", "openclaw", "claude-code-channel", "custom"] }, "instanceId": { "type": "string" }, "displayName": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "status": { "type": "string", "enum": ["available", "busy", "offline", "error"] }, "acceptingInvocations": { "type": "boolean" }, "capabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "statusText": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "lastSeenAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "botId", "runtimeKind", "instanceId", "displayName", "status", "acceptingInvocations", "capabilities", "statusText", "lastSeenAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/bot-runtime/sessions": { "post": { "operationId": "createBotRuntimeSession", "summary": "Create or link a bot runtime session", "tags": ["Bot runtimes"], "security": [{ "apiKey": ["bot-runtime:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runtimeKind": { "type": "string", "const": "pi-local" }, "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "runtimeSessionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 100 }, "localCwd": { "type": "string", "maxLength": 1000 } }, "required": ["runtimeKind", "instanceId", "runtimeSessionId", "displayName"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "linkId": { "type": "string" }, "rootStreamId": { "type": "string" }, "activeStreamId": { "type": "string" }, "runtimeSessionId": { "type": "string" }, "streamUrlPath": { "type": "string" } }, "required": ["linkId", "rootStreamId", "activeStreamId", "runtimeSessionId", "streamUrlPath"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/bot-runtime/sessions/rename": { "post": { "operationId": "renameBotRuntimeSession", "summary": "Rename the scratchpad linked to a bot runtime session", "tags": ["Bot runtimes"], "security": [{ "apiKey": ["bot-runtime:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "runtimeSessionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["instanceId", "runtimeSessionId", "displayName"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "linkId": { "type": "string" }, "rootStreamId": { "type": "string" }, "activeStreamId": { "type": "string" }, "runtimeSessionId": { "type": "string" }, "streamUrlPath": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "linkId", "rootStreamId", "activeStreamId", "runtimeSessionId", "streamUrlPath", "displayName" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/bot-invocations/claim": { "post": { "operationId": "claimBotInvocation", "summary": "Claim one pending bot invocation", "tags": ["Bot invocations"], "security": [{ "apiKey": ["bot-invocations:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runtimeKind": { "type": "string", "enum": ["pi-local", "hermes", "openclaw", "claude-code-channel", "custom"] }, "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "runtimeSessionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "supportedCapabilities": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": ["mentionable", "active-scratchpad", "session-control"] } }, "claimTtlSeconds": { "default": 60, "type": "integer", "minimum": 15, "maximum": 300 } }, "required": ["runtimeKind", "instanceId", "supportedCapabilities", "claimTtlSeconds"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "rootStreamId": { "type": "string" }, "activeStreamId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "responseStreamId": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "type": "string", "const": "bot" }, "id": { "type": "string" }, "slug": { "type": "string" } }, "required": ["type", "id", "slug"], "additionalProperties": false }, "trigger": { "type": "string", "enum": ["mention", "active-scratchpad", "session-control"] }, "requiredCapability": { "type": "string", "enum": ["mentionable", "active-scratchpad", "session-control"] }, "promptMarkdown": { "type": "string" }, "authorUserId": { "type": "string" }, "mentionedActorSlugs": { "type": "array", "items": { "type": "string" } }, "claimToken": { "type": "string" }, "claimExpiresAt": { "type": "string", "format": "date-time" }, "runtimeSessionId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "workspaceId", "rootStreamId", "activeStreamId", "sourceMessageId", "responseStreamId", "actor", "trigger", "requiredCapability", "promptMarkdown", "authorUserId", "mentionedActorSlugs", "claimToken", "claimExpiresAt", "runtimeSessionId", "metadata" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/bot-invocations/{invocationId}/renew": { "post": { "operationId": "renewBotInvocationClaim", "summary": "Renew a claimed bot invocation", "tags": ["Bot invocations"], "security": [{ "apiKey": ["bot-invocations:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invocation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "claimToken": { "type": "string", "minLength": 1, "maxLength": 256 }, "claimTtlSeconds": { "default": 60, "type": "integer", "minimum": 15, "maximum": 300 } }, "required": ["instanceId", "claimToken", "claimTtlSeconds"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "invocationId": { "type": "string" }, "status": { "type": "string" }, "claimExpiresAt": { "anyOf": [{ "type": "string", "format": "date-time" }, { "type": "null" }] } }, "required": ["invocationId", "status", "claimExpiresAt"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/bot-invocations/{invocationId}/steps": { "post": { "operationId": "recordBotInvocationStep", "summary": "Record a bot invocation trace step", "tags": ["Bot invocations"], "security": [{ "apiKey": ["bot-invocations:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invocation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "claimToken": { "type": "string", "minLength": 1, "maxLength": 256 }, "stepType": { "type": "string", "enum": [ "context_received", "thinking", "reconsidering", "web_search", "visit_page", "workspace_search", "research", "github_access", "linear_access", "message_sent", "message_edited", "response", "tool_call", "tool_error", "rate_limited", "rate_limit_retry" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "statusText": { "type": "string", "maxLength": 200 } }, "required": ["instanceId", "claimToken", "stepType", "content"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "invocationId": { "type": "string" }, "sessionId": { "type": "string" }, "stepId": { "type": "string" } }, "required": ["invocationId", "sessionId", "stepId"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/bot-invocations/{invocationId}/complete": { "post": { "operationId": "completeBotInvocation", "summary": "Complete a claimed bot invocation", "tags": ["Bot invocations"], "security": [{ "apiKey": ["bot-invocations:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invocation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "claimToken": { "type": "string", "minLength": 1, "maxLength": 256 }, "finalMessageMarkdown": { "type": "string", "minLength": 1, "maxLength": 50000 }, "noResponse": { "type": "boolean" }, "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_.\\-:]+$" }, "additionalProperties": { "type": "string", "maxLength": 256 } } }, "required": ["instanceId", "claimToken"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "invocationId": { "type": "string" }, "message": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "sequence": { "type": "string", "description": "Numeric sequence as string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorDisplayName": { "type": "string" }, "content": { "type": "string" }, "replyCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "threadStreamId": { "type": "string" }, "clientMessageId": { "type": "string" }, "sentVia": { "description": "Present when message was sent via API on behalf of a user", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "External references attached by the sender. Always present; empty when unset." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "filename", "mimeType", "sizeBytes"], "additionalProperties": false } }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "streamId", "sequence", "authorId", "authorType", "content", "replyCount", "metadata", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["invocationId", "message"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/bot-invocations/{invocationId}/fail": { "post": { "operationId": "failBotInvocation", "summary": "Fail a claimed bot invocation", "tags": ["Bot invocations"], "security": [{ "apiKey": ["bot-invocations:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invocation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "claimToken": { "type": "string", "minLength": 1, "maxLength": 256 }, "errorMessage": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["instanceId", "claimToken", "errorMessage"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "invocationId": { "type": "string" }, "status": { "type": "string" } }, "required": ["invocationId", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/streams": { "get": { "operationId": "listStreams", "summary": "List streams", "tags": ["Streams"], "description": "List streams accessible to this API key, with optional type and text filters.", "security": [{ "apiKey": ["streams:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "type", "in": "query", "required": true, "schema": {} }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["scratchpad", "channel", "dm", "thread", "system"] }, "displayName": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string" }, "parentStreamId": { "type": "string" }, "rootStreamId": { "type": "string" }, "parentMessageId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "format": "date-time" } }, "required": ["id", "type", "displayName", "visibility", "createdAt"], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "cursor": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "cursor"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/streams/{streamId}": { "get": { "operationId": "getStream", "summary": "Get a stream", "tags": ["Streams"], "security": [{ "apiKey": ["streams:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "streamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stream ID (prefixed ULID)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["scratchpad", "channel", "dm", "thread", "system"] }, "displayName": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string" }, "parentStreamId": { "type": "string" }, "rootStreamId": { "type": "string" }, "parentMessageId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "format": "date-time" } }, "required": ["id", "type", "displayName", "visibility", "createdAt"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/streams/{streamId}/members": { "get": { "operationId": "listMembers", "summary": "List stream members", "tags": ["Streams"], "security": [{ "apiKey": ["streams:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "streamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stream ID (prefixed ULID)" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "avatarUrl": { "type": "string" }, "joinedAt": { "type": "string", "format": "date-time" } }, "required": ["userId", "name", "slug", "joinedAt"], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "cursor": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "cursor"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/streams/{streamId}/messages": { "get": { "operationId": "listMessages", "summary": "List messages in a stream", "tags": ["Messages"], "description": "Cursor-paginated message list. Use `before` or `after` sequence numbers.", "security": [{ "apiKey": ["messages:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "streamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stream ID (prefixed ULID)" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "sequence": { "type": "string", "description": "Numeric sequence as string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorDisplayName": { "type": "string" }, "content": { "type": "string" }, "replyCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "threadStreamId": { "type": "string" }, "clientMessageId": { "type": "string" }, "sentVia": { "description": "Present when message was sent via API on behalf of a user", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "External references attached by the sender. Always present; empty when unset." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "filename", "mimeType", "sizeBytes"], "additionalProperties": false } }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "streamId", "sequence", "authorId", "authorType", "content", "replyCount", "metadata", "createdAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": ["data", "hasMore"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } }, "post": { "operationId": "sendMessage", "summary": "Send a message", "tags": ["Messages"], "description": "Send a message. Workspace-scoped keys send as a bot; user-scoped keys send on behalf of the key owner.", "security": [{ "apiKey": ["messages:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "streamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stream ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "clientMessageId": { "type": "string", "maxLength": 128 }, "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_.\\-:]+$" }, "additionalProperties": { "type": "string", "maxLength": 256 } } }, "required": ["content"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "sequence": { "type": "string", "description": "Numeric sequence as string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorDisplayName": { "type": "string" }, "content": { "type": "string" }, "replyCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "threadStreamId": { "type": "string" }, "clientMessageId": { "type": "string" }, "sentVia": { "description": "Present when message was sent via API on behalf of a user", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "External references attached by the sender. Always present; empty when unset." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "filename", "mimeType", "sizeBytes"], "additionalProperties": false } }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "streamId", "sequence", "authorId", "authorType", "content", "replyCount", "metadata", "createdAt" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/messages/find-by-metadata": { "post": { "operationId": "findMessagesByMetadata", "summary": "Find messages by metadata", "tags": ["Messages"], "description": "Find non-deleted messages whose `metadata` contains all the given key/value pairs (AND-containment). Useful for dedup flows — e.g. 'has a message already been posted for this GitHub PR event?'.", "security": [{ "apiKey": ["messages:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_.\\-:]+$" }, "additionalProperties": { "type": "string", "maxLength": 256 } }, "streamId": { "type": "string", "minLength": 1 }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": ["metadata", "limit"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "sequence": { "type": "string", "description": "Numeric sequence as string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorDisplayName": { "type": "string" }, "content": { "type": "string" }, "replyCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "threadStreamId": { "type": "string" }, "clientMessageId": { "type": "string" }, "sentVia": { "description": "Present when message was sent via API on behalf of a user", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "External references attached by the sender. Always present; empty when unset." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "filename", "mimeType", "sizeBytes"], "additionalProperties": false } }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "streamId", "sequence", "authorId", "authorType", "content", "replyCount", "metadata", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/messages/{messageId}": { "patch": { "operationId": "updateMessage", "summary": "Update a message", "tags": ["Messages"], "description": "Update a message you previously sent via API.", "security": [{ "apiKey": ["messages:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID (prefixed ULID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "required": ["content"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "streamId": { "type": "string" }, "sequence": { "type": "string", "description": "Numeric sequence as string" }, "authorId": { "type": "string" }, "authorType": { "type": "string", "enum": ["user", "persona", "system", "bot"] }, "authorDisplayName": { "type": "string" }, "content": { "type": "string" }, "replyCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "threadStreamId": { "type": "string" }, "clientMessageId": { "type": "string" }, "sentVia": { "description": "Present when message was sent via API on behalf of a user", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "External references attached by the sender. Always present; empty when unset." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processingStatus": { "type": "string", "enum": ["pending", "processing", "completed", "failed", "skipped"] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "filename", "mimeType", "sizeBytes"], "additionalProperties": false } }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "streamId", "sequence", "authorId", "authorType", "content", "replyCount", "metadata", "createdAt" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } }, "delete": { "operationId": "deleteMessage", "summary": "Delete a message", "tags": ["Messages"], "description": "Delete a message you previously sent via API.", "security": [{ "apiKey": ["messages:write"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID (prefixed ULID)" } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" }, "404": { "description": "Resource not found" } } } }, "/api/v1/workspaces/{workspaceId}/users": { "get": { "operationId": "listUsers", "summary": "List workspace users", "tags": ["Users"], "description": "List users in the workspace with optional text search and cursor pagination.", "security": [{ "apiKey": ["users:read"] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "email": { "type": "string" }, "avatarUrl": { "type": "string" }, "role": { "type": "string" } }, "required": ["id", "name", "slug", "email", "role"], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "cursor": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "cursor"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/me": { "get": { "operationId": "getMe", "summary": "Get the authenticated principal", "tags": ["Identity"], "description": "Returns a discriminated union describing the authenticated principal — either the API-key owner (`kind: \"user\"`) or the bot whose key is in use (`kind: \"bot\"`). Used by clients (e.g. the OpenClaw channel plugin) to verify their key and discover their identity after pairing.", "security": [{ "apiKey": [] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "user" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" } }, "required": ["kind", "workspaceId", "userId"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bot" }, "workspaceId": { "type": "string" }, "botId": { "type": "string" }, "botType": { "type": "string", "const": "shared" }, "traits": { "type": "array", "items": { "type": "string", "enum": ["mentionable", "active-scratchpad"] } }, "ownerUserId": { "type": "null" } }, "required": ["kind", "workspaceId", "botId", "botType", "traits", "ownerUserId"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bot" }, "workspaceId": { "type": "string" }, "botId": { "type": "string" }, "botType": { "type": "string", "const": "personal" }, "traits": { "type": "array", "items": { "type": "string", "enum": ["mentionable", "active-scratchpad"] } }, "ownerUserId": { "type": "string" } }, "required": ["kind", "workspaceId", "botId", "botType", "traits", "ownerUserId"], "additionalProperties": false } ] } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } }, "/api/v1/workspaces/{workspaceId}/me/bots": { "get": { "operationId": "listMyBots", "summary": "List my personal bots", "tags": ["Identity"], "description": "For user-scoped keys: lists the authenticated user's personal bots, optionally filtered by trait. Used by the frontend to enumerate quick-switcher commands. Bot-scoped keys receive 403.", "security": [{ "apiKey": [] }], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID (prefixed ULID)" }, { "name": "traits", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mentionable", "active-scratchpad"] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "traits": { "type": "array", "items": { "type": "string", "enum": ["mentionable", "active-scratchpad"] } }, "slug": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "name": { "type": "string" }, "description": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "avatarEmoji": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "avatarUrl": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "archivedAt": { "anyOf": [{ "type": "string", "format": "date-time" }, { "type": "null" }] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "type": { "type": "string", "const": "personal" }, "ownerUserId": { "type": "string" } }, "required": [ "id", "workspaceId", "traits", "slug", "name", "description", "avatarEmoji", "avatarUrl", "archivedAt", "createdAt", "updatedAt", "type", "ownerUserId" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["error"], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient permissions or inaccessible resource" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key created by a workspace admin in Settings > API Keys. Prefix: `thr_`." } } }, "tags": [ { "name": "Streams", "description": "List and inspect streams (channels, scratchpads, threads)" }, { "name": "Messages", "description": "Read, send, update, and delete messages" }, { "name": "Memos", "description": "Search preserved workspace knowledge and inspect memo provenance" }, { "name": "Attachments", "description": "Search attachments, inspect extracted content, and fetch download URLs" }, { "name": "Users", "description": "List workspace users" } ] }