{ "openapi": "3.1.0", "info": { "title": "Threads API", "version": "0.0.1", "description": "OpenAPI source of truth for the Threads HTTP API. All registered routes are represented; schemas marked x-schema-status: placeholder need follow-up precision.", "license": { "name": "UNLICENSED", "identifier": "UNLICENSED" } }, "servers": [ { "url": "http://localhost:8788", "description": "Local wrangler dev" }, { "url": "https://threads.example.com/api", "description": "Combined production app (replace with your instance API base)" } ], "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "paths": { "/auth/login": { "post": { "operationId": "postAuthLogin", "tags": [ "auth" ], "summary": "POST /auth/login", "description": "Authenticate with username and password. A normal login returns the user and sets a session cookie. If authenticator MFA is enabled or required, returns the next MFA step and sets a short-lived challenge cookie instead.", "parameters": [], "responses": { "200": { "description": "Authenticated user or the next authenticator MFA step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "x-route-boundary": "core" } }, "/auth/mfa/complete": { "post": { "operationId": "postAuthMfaComplete", "tags": ["auth"], "summary": "Complete authenticator MFA sign-in", "description": "Verify a TOTP code against the short-lived MFA challenge cookie. Forced first-time enrollment is committed only after a valid code. On success, sets the normal session cookie.", "parameters": [], "responses": { "200": { "description": "MFA verified and authenticated session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCompleteResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaCodeRequest" } } } }, "security": [], "x-route-boundary": "core" } }, "/auth/mfa/cancel": { "post": { "operationId": "postAuthMfaCancel", "tags": ["auth"], "summary": "Cancel authenticator MFA sign-in", "description": "Invalidate the current short-lived MFA challenge and clear its cookie.", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/Ok" } }, "security": [], "x-route-boundary": "core" } }, "/auth/logout": { "post": { "operationId": "postAuthLogout", "tags": [ "auth" ], "summary": "POST /auth/logout", "description": "Delete the current session token when present and clear the session cookie.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "x-route-boundary": "core" } }, "/auth/change-password": { "post": { "operationId": "postAuthChangePassword", "tags": [ "auth" ], "summary": "POST /auth/change-password", "description": "Change the authenticated user password after validating the current password.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/auth/email/confirm": { "get": { "operationId": "getAuthEmailConfirm", "tags": [ "auth" ], "summary": "Confirm ownership of an email address", "description": "Consume the single-use verification token sent by email, make the pending address the user's verified recovery email, and redirect to the application settings screen.", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "303": { "description": "Email verified; redirect to the application.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The token is invalid or expired; an informational HTML page is returned." }, "409": { "description": "The pending email is already associated with another account; an informational HTML page is returned." } }, "security": [], "x-route-boundary": "core" } }, "/users": { "post": { "operationId": "postUsers", "tags": [ "users" ], "summary": "POST /users", "description": "Create a human or bot user with an initial password. Human users require a unique recovery email and the API immediately attempts to send its confirmation link; delivery status is returned without making a temporary mail outage block account creation. Bot email is optional. Requires an admin session or an admin bearer token with users:provision.", "parameters": [], "responses": { "201": { "description": "Created user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCreateUserResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCreateUserRequest" } } } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/events": { "get": { "operationId": "getEvents", "tags": [ "ws" ], "summary": "GET /events", "description": "Owner-scoped event WebSocket upgrade endpoint. One socket carries events across all of the authenticated user's channels; payloads are the channel event schemas defined in api/openapi/ws-events.yaml, each enriched with channelId and a room object. HTTP upgrade is represented here.", "parameters": [], "responses": { "101": { "description": "WebSocket upgrade accepted" }, "200": { "description": "Non-upgrade request response; websocket clients should expect 101 on successful upgrade." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }, "x-route-boundary": "core" } }, "/ws/presence": { "get": { "operationId": "getWsPresence", "tags": [ "ws" ], "summary": "GET /ws/presence", "description": "WebSocket upgrade endpoint. HTTP upgrade is represented here; event payloads are defined in api/openapi/ws-events.yaml.", "parameters": [], "responses": { "101": { "description": "WebSocket upgrade accepted" }, "200": { "description": "Non-upgrade request response; websocket clients should expect 101 on successful upgrade." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "x-route-boundary": "core" } }, "/ws/{channelId}": { "get": { "operationId": "getWsChannelId", "tags": [ "ws" ], "summary": "GET /ws/:channelId", "description": "WebSocket upgrade endpoint. HTTP upgrade is represented here; event payloads are defined in api/openapi/ws-events.yaml.", "parameters": [ { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "101": { "description": "WebSocket upgrade accepted" }, "200": { "description": "Non-upgrade request response; websocket clients should expect 101 on successful upgrade." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "x-route-boundary": "core" } }, "/presence": { "get": { "operationId": "getPresence", "tags": [ "presence" ], "summary": "GET /presence", "description": "Return online/offline presence for a comma-separated userIds query parameter via the presence Durable Object.", "parameters": [ { "name": "userIds", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated user ids to query." } ], "responses": { "200": { "$ref": "#/components/responses/PresenceMap" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/uploads/{key}": { "get": { "operationId": "getUploadsKey", "tags": [ "uploads" ], "summary": "GET /uploads/:key{.+}", "description": "Return a previously uploaded R2 object. Dangerous stored content types are served as application/octet-stream.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Uploaded object bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/uploads": { "post": { "operationId": "postUploads", "tags": [ "uploads" ], "summary": "POST /uploads", "description": "Upload one multipart file field named file to R2 and create an unattached attachment record.", "parameters": [], "responses": { "201": { "$ref": "#/components/responses/UploadCreated" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } }, "additionalProperties": false } } } }, "x-route-boundary": "core" } }, "/transcribe": { "post": { "operationId": "postTranscribe", "tags": [ "transcribe" ], "summary": "POST /transcribe", "description": "Transcribe a short audio clip (voice memo) to text with Workers AI Whisper. The request body is raw audio bytes (audio/webm, audio/mp4, audio/ogg); Whisper detects the container. Returns the transcription text, which the client drops into the message composer.", "parameters": [], "responses": { "200": { "description": "Transcription result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The transcribed text; empty when no speech was detected." } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "audio/webm": { "schema": { "type": "string", "format": "binary" } }, "audio/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "x-route-boundary": "extension" } }, "/link-previews": { "get": { "operationId": "getLinkPreviews", "tags": [ "link-previews" ], "summary": "GET /link-previews", "description": "Fetch a safe HTTP(S) URL preview or return a cached preview. Returns preview: null when no usable preview is available.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "HTTP(S) URL to preview." } ], "responses": { "200": { "$ref": "#/components/responses/LinkPreviewResponse" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/users/me": { "get": { "operationId": "getUsersMe", "tags": [ "users" ], "summary": "GET /users/me", "description": "Return the authenticated user profile used by the client session.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUser" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "patch": { "operationId": "patchUsersMe", "tags": [ "users" ], "summary": "PATCH /users/me", "description": "Update mutable authenticated-user profile preferences. At least one recognized field is required.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMeResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMeRequest" } } } }, "x-route-boundary": "core" } }, "/users/me/security": { "get": { "operationId": "getUsersMeSecurity", "tags": ["users", "auth"], "summary": "Get current user's authenticator security state", "description": "Return whether authenticator MFA is enabled and whether workspace policy requires it. Browser session authentication is required.", "parameters": [], "responses": { "200": { "description": "Current user's security state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MySecurityResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" } }, "/users/me/mfa/enrollment": { "post": { "operationId": "postUsersMeMfaEnrollment", "tags": ["users", "auth"], "summary": "Start voluntary authenticator MFA enrollment", "description": "Re-authorize with the current password and create a ten-minute authenticator setup secret. The user must have a verified recovery email. The provisioning URI uses the full tenant hostname as its issuer and the verified email as its account label. Browser session authentication is required.", "parameters": [], "responses": { "200": { "description": "Authenticator setup details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaEnrollmentSetup" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordConfirmationRequest" } } } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" } }, "/users/me/mfa/enrollment/confirm": { "post": { "operationId": "postUsersMeMfaEnrollmentConfirm", "tags": ["users", "auth"], "summary": "Confirm authenticator MFA enrollment", "description": "Verify a TOTP code for the pending setup and enable authenticator MFA. A verified recovery email remains required through confirmation. Browser session authentication is required.", "parameters": [], "responses": { "200": { "description": "Authenticator MFA enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaEnabledResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaCodeRequest" } } } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" } }, "/users/me/mfa": { "delete": { "operationId": "deleteUsersMeMfa", "tags": ["users", "auth"], "summary": "Disable authenticator MFA", "description": "Re-authorize with the current password and a fresh TOTP code, then disable authenticator MFA. Rejected while workspace policy requires MFA.", "parameters": [], "responses": { "200": { "description": "Authenticator MFA disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaDisabledResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaReauthorizationRequest" } } } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" } }, "/users/me/email/change": { "post": { "operationId": "postUsersMeEmailChange", "tags": [ "users" ], "summary": "Set or change the current user's recovery email", "description": "Re-authorize with the current password and send a single-use verification link to the requested address. An existing verified address remains active until the replacement is confirmed. Requesting the already-verified address cancels any pending replacement. Browser session authentication is required; bearer tokens are rejected.", "parameters": [], "responses": { "200": { "description": "Verification sent, or the requested address was already verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChangeRequest" } } } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/users/me/email/verification/resend": { "post": { "operationId": "postUsersMeEmailVerificationResend", "tags": [ "users" ], "summary": "Resend the pending email verification", "description": "Invalidate the prior token and send a fresh verification link for the current pending address. Subject to per-user cooldown and daily limits. Browser session authentication is required; bearer tokens are rejected.", "parameters": [], "responses": { "200": { "description": "A fresh verification message was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/users/me/frequent-emojis": { "get": { "operationId": "getUsersMeFrequentEmojis", "tags": [ "users" ], "summary": "GET /users/me/frequent-emojis", "description": "Return exactly three frequently used reaction emojis, backfilled with defaults when needed.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrequentEmojisResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/users/me/api-tokens": { "post": { "operationId": "postUsersMeApiTokens", "tags": [ "users" ], "summary": "POST /users/me/api-tokens", "description": "Create a scoped API bearer token for the authenticated admin. Requires an interactive session. The token is returned once, stored only as a keyed one-way verifier, and cannot be retrieved later. Scopes default to read/write and expiry defaults to 90 days.", "parameters": [], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCreateApiTokenResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCreateApiTokenRequest" } } } }, "x-route-boundary": "core" }, "get": { "operationId": "getUsersMeApiTokens", "tags": [ "users" ], "summary": "GET /users/me/api-tokens", "description": "List the authenticated admin's API tokens. Requires an interactive session. Returns non-secret metadata including scopes, expiry, and last use — never the token value.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyApiTokenListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/users/me/api-tokens/{id}": { "delete": { "operationId": "deleteUsersMeApiTokensId", "tags": [ "users" ], "summary": "DELETE /users/me/api-tokens/:id", "description": "Revoke one of the authenticated admin's own API tokens by its hashed id (from GET /users/me/api-tokens). Requires an interactive session and immediately closes sockets using that credential.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/users/me/webhooks": { "get": { "operationId": "getUsersMeWebhooks", "tags": [ "webhooks" ], "summary": "GET /users/me/webhooks", "description": "List webhook registrations owned by the authenticated user. Bot agents should call this with the bot's bearer token to inspect the bot's own delivery URLs. Secrets are never returned after creation.", "parameters": [], "responses": { "200": { "description": "Webhook registrations for the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postUsersMeWebhooks", "tags": [ "webhooks" ], "summary": "POST /users/me/webhooks", "description": "Register one webhook URL for the authenticated user. Bot agents should call this with the bot's bearer token. The signing secret is returned once and cannot be retrieved later.", "parameters": [], "responses": { "201": { "description": "Created webhook registration with one-time signing secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "x-route-boundary": "core" } }, "/users/me/webhooks/{id}": { "delete": { "operationId": "deleteUsersMeWebhooksId", "tags": [ "webhooks" ], "summary": "DELETE /users/me/webhooks/:id", "description": "Delete one webhook registration owned by the authenticated user. Deleting and recreating a webhook is the rotation path for the signing secret.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/users/{id}/api-tokens": { "post": { "operationId": "postUsersIdApiTokens", "tags": [ "users" ], "summary": "POST /users/:id/api-tokens", "description": "Create an API bearer token for another user by id. Requires an admin session or an admin bearer token with tokens:manage. The token is returned once, stored only as a keyed one-way verifier, and cannot be retrieved later.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCreateApiTokenResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCreateApiTokenRequest" } } } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/bots/self/capabilities": { "post": { "operationId": "postBotsSelfCapabilities", "tags": [ "bots" ], "summary": "POST /bots/self/capabilities", "description": "Allow bot users to advertise their own model and DM capabilities. Non-bot users receive 403.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSelfCapabilitiesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSelfCapabilitiesRequest" } } } }, "x-route-boundary": "core" } }, "/users/search": { "get": { "operationId": "getUsersSearch", "tags": [ "users" ], "summary": "GET /users/search", "description": "Search users by username or display name. Optional channel filters out existing channel members.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive username/display-name search. Empty or omitted returns users up to the server limit." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When provided, existing members of this channel are excluded from results." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSearchResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/users/bots": { "get": { "operationId": "getUsersBots", "tags": [ "users" ], "summary": "GET /users/bots", "description": "List all bot users (role='bot'). Used to populate the per-user ephemeral-channel bot picker.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSearchResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/dms": { "get": { "operationId": "getDms", "tags": [ "dms" ], "summary": "GET /dms", "description": "List visible direct message channels for the authenticated user, including partner details, unread state, and sendability metadata.", "parameters": [], "responses": { "200": { "description": "DM list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DMListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postDms", "tags": [ "dms" ], "summary": "POST /dms", "description": "Create or reopen a direct message channel with another user. Existing DMs return 200; newly-created DMs return 201.", "parameters": [], "responses": { "200": { "description": "Existing DM channel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DMChannel" } } } }, "201": { "description": "Created DM channel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DMChannel" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDMRequest" } } } }, "x-route-boundary": "core" } }, "/dms/reorder": { "put": { "operationId": "putDmsReorder", "tags": [ "dms" ], "summary": "PUT /dms/reorder", "description": "Persist the authenticated user's custom ordering for visible direct message channels.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderDMsRequest" } } } }, "x-route-boundary": "core" } }, "/dms/{id}/hide": { "patch": { "operationId": "patchDmsIdHide", "tags": [ "dms" ], "summary": "PATCH /dms/:id/hide", "description": "Hide a direct message channel for the authenticated user without deleting the conversation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels": { "get": { "operationId": "getChannels", "tags": [ "channels" ], "summary": "GET /channels", "description": "List non-DM, non-archived channels the authenticated user belongs to, including notification tier and unread metadata.", "parameters": [], "responses": { "200": { "description": "Channel list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postChannels", "tags": [ "channels" ], "summary": "POST /channels", "description": "Create a channel and add the authenticated user as its first member.", "parameters": [], "responses": { "201": { "description": "Created channel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelRequest" } } } }, "x-route-boundary": "core" } }, "/channels/browse": { "get": { "operationId": "getChannelsBrowse", "tags": [ "channels" ], "summary": "GET /channels/browse", "description": "List public non-DM channels, including whether the authenticated user is a current member and each channel member count.", "parameters": [], "responses": { "200": { "description": "Browsable channel list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelBrowseResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels/{id}": { "get": { "operationId": "getChannelsId", "tags": [ "channels" ], "summary": "GET /channels/:id", "description": "Get channel metadata by id. Private channels are only visible to current members.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "patch": { "operationId": "patchChannelsId", "tags": [ "channels" ], "summary": "PATCH /channels/:id", "description": "Update mutable channel metadata and settings for a channel the authenticated user belongs to.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelRequest" } } } }, "x-route-boundary": "core" }, "delete": { "operationId": "deleteChannelsId", "tags": [ "channels" ], "summary": "DELETE /channels/:id", "description": "Delete a channel and its related data. Only the channel creator or an admin may delete it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels/{id}/join": { "post": { "operationId": "postChannelsIdJoin", "tags": [ "channels" ], "summary": "POST /channels/:id/join", "description": "Join a public channel, or rejoin one that the authenticated user previously left.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels/{id}/leave": { "post": { "operationId": "postChannelsIdLeave", "tags": [ "channels" ], "summary": "POST /channels/:id/leave", "description": "Hard-remove the authenticated user from a channel membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels/{id}/members": { "get": { "operationId": "getChannelsIdMembers", "tags": [ "channels" ], "summary": "GET /channels/:id/members", "description": "List current channel members. Private channel member lists are only visible to current members.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channel member list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMemberListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postChannelsIdMembers", "tags": [ "channels" ], "summary": "POST /channels/:id/members", "description": "Add a user to a channel by user id or username. The caller must be a current member.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "201": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChannelMemberRequest" } } } }, "x-route-boundary": "core" } }, "/channels/{id}/members/{targetUserId}": { "delete": { "operationId": "deleteChannelsIdMembersTargetUserId", "tags": [ "channels" ], "summary": "DELETE /channels/:id/members/:targetUserId", "description": "Remove a member from a channel. Non-admin users may only remove themselves.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "targetUserId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels/{id}/membership": { "delete": { "operationId": "deleteChannelsIdMembership", "tags": [ "channels" ], "summary": "DELETE /channels/:id/membership", "description": "Soft-leave a non-DM channel, hiding it from the user while preserving channel history.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/channels/{id}/notifications": { "patch": { "operationId": "patchChannelsIdNotifications", "tags": [ "channels" ], "summary": "PATCH /channels/:id/notifications", "description": "Update the authenticated user's notification tier for a channel membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated notification tier response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelNotificationsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelNotificationsRequest" } } } }, "x-route-boundary": "core" } }, "/folders": { "get": { "operationId": "getFolders", "tags": [ "folders" ], "summary": "GET /folders", "description": "List channel folders for the authenticated user, including ordered channel ids assigned to each folder.", "parameters": [], "responses": { "200": { "description": "Folder list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelFolderListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postFolders", "tags": [ "folders" ], "summary": "POST /folders", "description": "Create a channel folder for the authenticated user at the next folder position.", "parameters": [], "responses": { "201": { "description": "Created folder response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelFolder" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderRequest" } } } }, "x-route-boundary": "core" } }, "/folders/{id}": { "patch": { "operationId": "patchFoldersId", "tags": [ "folders" ], "summary": "PATCH /folders/:id", "description": "Update the authenticated user's folder name, position, and/or collapsed state.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderRequest" } } } }, "x-route-boundary": "core" }, "delete": { "operationId": "deleteFoldersId", "tags": [ "folders" ], "summary": "DELETE /folders/:id", "description": "Delete one of the authenticated user's folders. Channel records are not deleted.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/folders/{id}/channels": { "post": { "operationId": "postFoldersIdChannels", "tags": [ "folders" ], "summary": "POST /folders/:id/channels", "description": "Move a channel into one of the authenticated user's folders, optionally at an explicit position.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChannelToFolderRequest" } } } }, "x-route-boundary": "core" } }, "/folders/{id}/channels/{channelId}": { "delete": { "operationId": "deleteFoldersIdChannelsChannelId", "tags": [ "folders" ], "summary": "DELETE /folders/:id/channels/:channelId", "description": "Remove a channel from one of the authenticated user's folders.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/folders/reorder": { "put": { "operationId": "putFoldersReorder", "tags": [ "folders" ], "summary": "PUT /folders/reorder", "description": "Bulk update folder positions and/or channel-folder item positions for the authenticated user.", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderFoldersRequest" } } } }, "x-route-boundary": "core" } }, "/channels/{id}/messages": { "get": { "operationId": "getChannelsIdMessages", "tags": [ "channels" ], "summary": "GET /channels/:id/messages", "description": "List non-thread messages in a channel. Supports cursor pagination, fetching newer messages, and anchoring around a message id.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return messages older than this message id.", "schema": { "type": "string" } }, { "name": "around", "in": "query", "required": false, "description": "Return a window centered around this message id.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Return messages newer than this message id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "$ref": "#/components/responses/MessagePage" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postChannelsIdMessages", "tags": [ "channels" ], "summary": "POST /channels/:id/messages", "description": "Send a top-level message to a channel.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "$ref": "#/components/responses/Message" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "x-route-boundary": "core" } }, "/channels/{id}/read": { "post": { "operationId": "postChannelsIdRead", "tags": [ "channels" ], "summary": "POST /channels/:id/read", "description": "Mark the latest visible message in a channel as read for the current user.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/inbox": { "get": { "operationId": "getInbox", "tags": [ "messages" ], "summary": "List unread Inbox messages", "description": "List incoming unread human messages and final agent responses across channels and DMs. Thread replies are included. Reading this endpoint does not change read state.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "$ref": "#/components/responses/InboxPage" }, "401": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/messages/{id}": { "get": { "operationId": "getMessagesId", "tags": [ "messages" ], "summary": "GET /messages/:id", "description": "Get a single message by id after verifying channel membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Message" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "patch": { "operationId": "patchMessagesId", "tags": [ "messages" ], "summary": "PATCH /messages/:id", "description": "Edit a message owned by the current user.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageRequest" } } } }, "x-route-boundary": "core" }, "delete": { "operationId": "deleteMessagesId", "tags": [ "messages" ], "summary": "DELETE /messages/:id", "description": "Soft-delete a message owned by the current user.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/messages/{id}/read": { "post": { "operationId": "postMessagesIdRead", "tags": [ "messages" ], "summary": "Mark one message read", "description": "Acknowledge one message for the current user without advancing the containing channel's bulk read cursor.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/messages/{id}/resolve": { "post": { "operationId": "postMessagesIdResolve", "tags": [ "messages" ], "summary": "POST /messages/:id/resolve", "description": "Mark a top-level message as resolved. The thread dims in place rather than being deleted, distinguishing threads the author is finished with from ones still needing work. Any channel member may resolve, which also lets a bot resolve on a user's behalf via an API token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveMessageResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "delete": { "operationId": "deleteMessagesIdResolve", "tags": [ "messages" ], "summary": "DELETE /messages/:id/resolve", "description": "Clear the resolved state of a message so its thread is no longer dimmed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/messages/{id}/thread-title": { "put": { "operationId": "putMessagesIdThreadTitle", "tags": [ "messages" ], "summary": "Set or rename a thread title", "description": "Set a human-readable title on a message thread. The id may identify either the top-level message or one of its replies; the title is stored on the thread root. Titles preserve case and punctuation and do not need to be unique. Any current channel member may rename the thread. Automatic callers can request set-if-empty behavior so they do not overwrite an existing title.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread title updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadTitleResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetThreadTitleRequest" } } } }, "x-route-boundary": "core" } }, "/messages/{id}/replies": { "get": { "operationId": "getMessagesIdReplies", "tags": [ "messages" ], "summary": "GET /messages/:id/replies", "description": "List replies in a message thread.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return replies after this message id.", "schema": { "type": "string" } }, { "name": "around", "in": "query", "required": false, "description": "Return a window centered around this reply id.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Return newer replies after this message id.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Return replies before this message id. Used with latest-first thread views to page older replies.", "schema": { "type": "string" } }, { "name": "latest", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "$ref": "#/components/responses/MessagePage" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" }, "post": { "operationId": "postMessagesIdReplies", "tags": [ "messages" ], "summary": "POST /messages/:id/replies", "description": "Send a reply to a message thread.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "$ref": "#/components/responses/Message" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "x-route-boundary": "core" } }, "/messages/{id}/reactions": { "post": { "operationId": "postMessagesIdReactions", "tags": [ "messages" ], "summary": "POST /messages/:id/reactions", "description": "Add a reaction to a message as the current user. Creating a new reaction returns 201; adding the same emoji again is idempotent and returns 200.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "201": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddReactionRequest" } } } }, "x-route-boundary": "core" } }, "/messages/{id}/reactions/{emoji}": { "delete": { "operationId": "deleteMessagesIdReactionsEmoji", "tags": [ "messages" ], "summary": "DELETE /messages/:id/reactions/:emoji", "description": "Remove the current user's reaction emoji from a message. The emoji path segment is URL-decoded by the API.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "emoji", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/messages/{id}/process": { "post": { "operationId": "postMessagesIdProcess", "tags": [ "messages" ], "summary": "Update message process status", "description": "Attach or update process status and token usage metadata for a message, then broadcast the process_status event to channel subscribers.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMessageProcessStatusRequest" } } } }, "x-route-boundary": "extension" } }, "/messages/{id}/retry": { "post": { "operationId": "postMessagesIdRetry", "tags": [ "messages" ], "summary": "Retry message processing", "description": "Reset a failed, killed, or restarted message process back to queued, clear its process error text, and broadcast process_status and process_retry events.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/mentions": { "get": { "operationId": "getMentions", "tags": [ "mentions" ], "summary": "GET /mentions", "description": "List the latest messages that mention the authenticated user across channels they belong to.", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/MentionsResponse" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/search": { "get": { "operationId": "getSearch", "tags": [ "search" ], "summary": "GET /search", "description": "Search messages visible to the authenticated user. Supports FTS query syntax plus channel, sender, date, and attachment/reaction/link filters.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Full-text search query. Supports quoted phrases, uppercase OR, -term exclusions, and term* prefix matching. Empty query is allowed when at least one filter is provided.", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "Restrict results to a channel id.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Restrict results to messages sent by this user id.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Unix timestamp lower bound for message created_at. Invalid or negative values are ignored.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "until", "in": "query", "required": false, "description": "Unix timestamp upper bound for message created_at. Invalid or negative values are ignored.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "has", "in": "query", "required": false, "description": "Comma-separated content filters. Recognized values: link, reaction, file.", "schema": { "type": "string", "examples": [ "link", "reaction,file" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "$ref": "#/components/responses/SearchResponse" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/w/{id}": { "get": { "operationId": "getWId", "tags": [ "widgets" ], "summary": "Render widget runtime shell", "description": "Return the public sandboxed HTML runtime for a widget iframe. The parentOrigin query parameter must match an allowed Threads client origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." }, { "name": "channelId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Channel id exposed to widget code via ThreadsWidget.getContext()." }, { "name": "parentOrigin", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Embedding Threads client origin; must be allowlisted." } ], "responses": { "200": { "description": "Widget runtime HTML.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "x-route-boundary": "extension" } }, "/channels/ephemeral": { "post": { "operationId": "postChannelsEphemeral", "tags": [ "channels" ], "summary": "Create ephemeral channel", "description": "Create a private ephemeral channel for the authenticated user, optionally adding the Tela bot as the auto-responder when that bot account exists.", "parameters": [], "responses": { "201": { "description": "Ephemeral channel created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralChannelResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/channels/{id}/archive": { "post": { "operationId": "postChannelsIdArchive", "tags": [ "channels" ], "summary": "Archive ephemeral channel", "description": "Soft-archive an ephemeral channel so it disappears from the sidebar while preserving history and searchability. Only the creator or an admin may archive.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "200": { "description": "Archive timestamp response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralArchiveResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "delete": { "operationId": "deleteChannelsIdArchive", "tags": [ "channels" ], "summary": "Unarchive ephemeral channel", "description": "Clear the archive timestamp for an ephemeral channel. The caller must still be a channel member.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "200": { "description": "Archive timestamp cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralUnarchiveResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/channels/{id}/rename": { "post": { "operationId": "postChannelsIdRename", "tags": [ "channels" ], "summary": "Rename ephemeral channel", "description": "Set the inferred slug for an ephemeral channel that has not already been auto-named. The slug is sanitized server-side and collisions are disambiguated.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "200": { "description": "Rename result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralRenameResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameEphemeralChannelRequest" } } } }, "x-route-boundary": "extension" } }, "/channels/{id}/promote": { "post": { "operationId": "postChannelsIdPromote", "tags": [ "channels" ], "summary": "Promote ephemeral channel", "description": "Promote an ephemeral channel into a first-class channel while preserving its id, members, history, and metadata in place.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "200": { "description": "Promotion result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralPromoteResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteEphemeralChannelRequest" } } } }, "x-route-boundary": "extension" } }, "/channels/{id}/regenerate-name": { "post": { "operationId": "postChannelsIdRegenerateName", "tags": [ "channels" ], "summary": "Regenerate ephemeral channel name", "description": "Clear auto_named_at for an ephemeral channel so the next message can trigger the agent-loop name inference again. Only the creator or an admin may regenerate.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "200": { "description": "Regeneration state response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralRegenerateNameResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/channels/{id}/pins": { "get": { "operationId": "getChannelsIdPins", "tags": [ "channels" ], "summary": "GET /channels/:id/pins", "description": "List pinned messages for a channel visible to the authenticated member, newest pin first.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/PinnedMessageList" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "post": { "operationId": "postChannelsIdPins", "tags": [ "channels" ], "summary": "POST /channels/:id/pins", "description": "Pin an existing message in the channel. The message must belong to the channel and not already be pinned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "$ref": "#/components/responses/PinnedMessage" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinMessageRequest" } } } }, "x-route-boundary": "extension" } }, "/channels/{id}/pins/{messageId}": { "delete": { "operationId": "deleteChannelsIdPinsMessageId", "tags": [ "channels" ], "summary": "DELETE /channels/:id/pins/:messageId", "description": "Remove a pin for a message in the channel.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/channels/{id}/board": { "get": { "operationId": "getChannelsIdBoard", "tags": [ "channels" ], "summary": "GET /channels/:id/board", "description": "Return the kanban board for a channel with its cards ordered by position.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/KanbanBoardWithCards" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "post": { "operationId": "postChannelsIdBoard", "tags": [ "channels" ], "summary": "POST /channels/:id/board", "description": "Create a kanban board for the channel using the server default columns. Fails with 409 if one already exists.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "$ref": "#/components/responses/KanbanBoardCreated" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "put": { "operationId": "putChannelsIdBoard", "tags": [ "channels" ], "summary": "PUT /channels/:id/board", "description": "Replace the kanban board column key list for the channel.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/KanbanBoard" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKanbanBoardRequest" } } } }, "x-route-boundary": "extension" } }, "/channels/{id}/board/cards": { "post": { "operationId": "postChannelsIdBoardCards", "tags": [ "channels" ], "summary": "POST /channels/:id/board/cards", "description": "Create a card on the channel board at the next position in the selected column.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "$ref": "#/components/responses/KanbanCardCreated" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKanbanCardRequest" } } } }, "x-route-boundary": "extension" } }, "/boards/cards/{cardId}": { "put": { "operationId": "putBoardsCardsCardId", "tags": [ "boards" ], "summary": "PUT /boards/cards/:cardId", "description": "Update mutable fields for a kanban card. Moving to in-progress may emit a channel message for bot processing.", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/KanbanCard" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKanbanCardRequest" } } } }, "x-route-boundary": "extension" }, "delete": { "operationId": "deleteBoardsCardsCardId", "tags": [ "boards" ], "summary": "DELETE /boards/cards/:cardId", "description": "Delete a kanban card and its activity log.", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/boards/cards/{cardId}/activity": { "get": { "operationId": "getBoardsCardsCardIdActivity", "tags": [ "boards" ], "summary": "GET /boards/cards/:cardId/activity", "description": "List activity entries for a kanban card, newest first.", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/KanbanActivityList" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/widgets": { "get": { "operationId": "getWidgets", "tags": [ "widgets" ], "summary": "List widgets", "description": "Return all registered widgets without their executable code, ordered newest first.", "parameters": [], "responses": { "200": { "description": "Widgets ordered newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetSummary" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "post": { "operationId": "postWidgets", "tags": [ "widgets" ], "summary": "Create widget", "description": "Create a widget owned by the authenticated user. name and code are required; icon defaults to PuzzlePiece.", "parameters": [], "responses": { "201": { "description": "Created widget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWidgetRequest" } } } }, "x-route-boundary": "extension" } }, "/widgets/{id}": { "get": { "operationId": "getWidgetsId", "tags": [ "widgets" ], "summary": "Get widget", "description": "Return one widget, including its executable code.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." } ], "responses": { "200": { "description": "Widget detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "put": { "operationId": "putWidgetsId", "tags": [ "widgets" ], "summary": "Update widget", "description": "Update fields on a widget. Only the widget creator can update it, and at least one field is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." } ], "responses": { "200": { "description": "Updated widget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWidgetRequest" } } } }, "x-route-boundary": "extension" }, "delete": { "operationId": "deleteWidgetsId", "tags": [ "widgets" ], "summary": "Delete widget", "description": "Delete a widget and remove it from all channels. Only the widget creator can delete it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." } ], "responses": { "200": { "description": "Widget deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/channels/{id}/widgets": { "get": { "operationId": "getChannelsIdWidgets", "tags": [ "channels" ], "summary": "List channel widgets", "description": "Return widgets added to a channel. Private channels require membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "200": { "description": "Channel widgets ordered by most recently added.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelWidget" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "post": { "operationId": "postChannelsIdWidgets", "tags": [ "channels" ], "summary": "Add widget to channel", "description": "Add an existing widget to a channel. Private channels require membership; duplicate adds are ignored.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." } ], "responses": { "201": { "description": "Widget added to channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChannelWidgetRequest" } } } }, "x-route-boundary": "extension" } }, "/channels/{id}/widgets/{widgetId}": { "delete": { "operationId": "deleteChannelsIdWidgetsWidgetId", "tags": [ "channels" ], "summary": "Remove widget from channel", "description": "Remove a widget from a channel. Private channels require membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id." }, { "name": "widgetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." } ], "responses": { "200": { "description": "Widget removed from channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/widgets/{id}/data/kv/{key}/all": { "get": { "operationId": "getWidgetsIdDataKvKeyAll", "tags": [ "widgets" ], "summary": "Read all user values for a widget KV key", "description": "Return all per-user values for a widget KV key. This endpoint is restricted to bot users.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget-scoped KV key." } ], "responses": { "200": { "description": "Global widget KV values for the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetKvGlobalResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/widgets/{id}/data/kv/{key}": { "get": { "operationId": "getWidgetsIdDataKvKey", "tags": [ "widgets" ], "summary": "Read widget KV value", "description": "Return the authenticated user's value for a widget-scoped key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget-scoped KV key." } ], "responses": { "200": { "description": "Widget KV entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetKvEntry" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "put": { "operationId": "putWidgetsIdDataKvKey", "tags": [ "widgets" ], "summary": "Store widget KV value", "description": "Create or replace the authenticated user's value for a widget-scoped key. Values are serialized as JSON.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget-scoped KV key." } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetKvPutRequest" } } } }, "x-route-boundary": "extension" }, "delete": { "operationId": "deleteWidgetsIdDataKvKey", "tags": [ "widgets" ], "summary": "Delete widget KV value", "description": "Delete the authenticated user's value for a widget-scoped key. The response is successful even if the key did not exist.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Widget-scoped KV key." } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/push/vapid-key": { "get": { "operationId": "getPushVapidKey", "tags": [ "push" ], "summary": "GET /push/vapid-key", "description": "Return the VAPID public key the client uses to create browser push subscriptions.", "parameters": [], "responses": { "200": { "description": "VAPID public key response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushVapidKeyResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/push/subscribe": { "post": { "operationId": "postPushSubscribe", "tags": [ "push" ], "summary": "POST /push/subscribe", "description": "Register or update the authenticated user's browser push subscription and enable push notifications.", "parameters": [], "responses": { "201": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscriptionRequest" } } } }, "x-route-boundary": "extension" }, "delete": { "operationId": "deletePushSubscribe", "tags": [ "push" ], "summary": "DELETE /push/subscribe", "description": "Remove one browser push subscription for the authenticated user by endpoint.", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushUnsubscribeRequest" } } } } } }, "/push/preferences": { "get": { "operationId": "getPushPreferences", "tags": [ "push" ], "summary": "GET /push/preferences", "description": "Return the authenticated user's push notification preferences, defaulting to enabled and all notifications when no row exists.", "parameters": [], "responses": { "200": { "description": "Push preference response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPreferences" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "put": { "operationId": "putPushPreferences", "tags": [ "push" ], "summary": "PUT /push/preferences", "description": "Upsert the authenticated user's push notification preferences.", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePushPreferencesRequest" } } } }, "x-route-boundary": "extension" } }, "/sync-state": { "get": { "operationId": "getSyncState", "tags": [ "sync-state" ], "summary": "GET /sync-state", "description": "List sync-state rows whose keys start with the required prefix query parameter.", "parameters": [ { "name": "prefix", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Key prefix to match. SQL LIKE wildcards are escaped before querying." } ], "responses": { "200": { "description": "Sync-state entries matching the requested prefix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStateListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/sync-state/{key}": { "get": { "operationId": "getSyncStateKey", "tags": [ "sync-state" ], "summary": "GET /sync-state/:key{.+}", "description": "Return one sync-state row by exact key.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync-state entry response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStateEntry" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "put": { "operationId": "putSyncStateKey", "tags": [ "sync-state" ], "summary": "PUT /sync-state/:key{.+}", "description": "Create or update one sync-state value by key.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated sync-state value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSyncStateResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSyncStateRequest" } } } }, "x-route-boundary": "extension" } }, "/drafts": { "get": { "operationId": "getDrafts", "tags": [ "drafts" ], "summary": "List channels with saved drafts", "description": "Returns channel IDs where the authenticated user has non-empty draft text or draft attachments.", "parameters": [], "responses": { "200": { "description": "Channels that currently have a draft for the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/channels/{id}/draft": { "get": { "operationId": "getChannelsIdDraft", "tags": [ "drafts" ], "summary": "Get a channel draft", "description": "Returns the authenticated user’s draft text and attachments for a channel. Missing drafts return empty content and no attachments.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Draft content and attachments for the channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDraftResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "put": { "operationId": "putChannelsIdDraft", "tags": [ "drafts" ], "summary": "Update a channel draft", "description": "Creates, replaces, or clears the authenticated user’s draft for a channel. Empty content with no attachment IDs clears the draft.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDraftRequest" } } } }, "x-route-boundary": "extension" } }, "/channels/{id}/saved-drafts": { "get": { "operationId": "getChannelsIdSavedDrafts", "tags": [ "saved-drafts" ], "summary": "List saved drafts for a channel", "description": "Returns saved drafts owned by the authenticated user in the requested channel, newest first. Requires channel membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved drafts for the authenticated user in this channel.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SavedDraft" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "post": { "operationId": "postChannelsIdSavedDrafts", "tags": [ "saved-drafts" ], "summary": "Create a saved draft", "description": "Persists non-empty draft content for the authenticated user in the requested channel. Requires channel membership.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created saved draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedDraft" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSavedDraftRequest" } } } }, "x-route-boundary": "extension" } }, "/saved-drafts/{id}": { "delete": { "operationId": "deleteSavedDraftsId", "tags": [ "saved-drafts" ], "summary": "Delete a saved draft", "description": "Deletes a saved draft owned by the authenticated user. Drafts owned by other users are treated as not found.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/saved-drafts/{id}/schedule": { "patch": { "operationId": "patchSavedDraftsIdSchedule", "tags": [ "saved-drafts" ], "summary": "Schedule or unschedule a saved draft", "description": "Sets a saved draft delivery time to a future ISO timestamp, or clears scheduling with null. Only the draft owner can schedule it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated saved draft with the new scheduled_at value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedDraft" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleSavedDraftRequest" } } } }, "x-route-boundary": "extension" } }, "/processes": { "get": { "operationId": "getProcesses", "tags": [ "processes" ], "summary": "List agent processes", "description": "Lists agent process runs visible to the caller (channel members see their channels' runs; admins see all). Optionally filtered by status. Stale running runs are swept to killed on read.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "done", "error", "killed", "restarted" ] } } ], "responses": { "200": { "description": "The visible processes, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "processes" ], "properties": { "processes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "post": { "operationId": "postProcesses", "tags": [ "processes" ], "summary": "Create an agent process", "description": "Called by a bot when it begins a turn, to register a run that the management UI can track and cancel. The run is identified by its own id (there is no OS pid). Bot principals only.", "responses": { "201": { "description": "The created process id and status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "error", "killed" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_id", "message_id" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "message_id": { "type": "string" }, "user_id": { "type": "string" }, "bot_id": { "type": "string", "description": "Owning bot id. Bot callers may only use their own id; admins may create a process on a bot's behalf." }, "status": { "type": "string", "enum": [ "queued", "running", "done", "error", "killed" ] } } } } } }, "x-route-boundary": "extension" } }, "/processes/cleanup-by-bot": { "post": { "operationId": "postProcessesCleanupByBot", "tags": [ "processes" ], "summary": "Reconcile interrupted bot processes", "description": "Called once by a bot at startup, before it consumes new events. Marks all running or queued processes owned by the authenticated bot as restarted, updates their triggering messages, and broadcasts the terminal state. Bot principals only; this operation assumes one active runtime per bot identity.", "parameters": [], "responses": { "200": { "description": "The reconciled process ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessCleanupResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/processes/kill-all": { "post": { "operationId": "postProcessesKillAll", "tags": [ "processes" ], "summary": "Cancel all running processes", "description": "Cancels every running or queued process the caller can see (admins: all). Each cancellation marks the run killed and signals the owning agent over WebSocket and webhook.", "responses": { "200": { "description": "How many runs were cancelled and their ids.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cleaned", "process_ids" ], "properties": { "cleaned": { "type": "integer" }, "process_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/processes/{id}": { "get": { "operationId": "getProcessesId", "tags": [ "processes" ], "summary": "Get one process", "description": "Returns a single process run. Requires channel membership (admins: any).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The process run.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" }, "patch": { "operationId": "patchProcessesId", "tags": [ "processes" ], "summary": "Update a process", "description": "Called by the owning bot to advance status (running/done/error) and report cumulative metrics (tool/reply counts, token usage). Bot principals only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Acknowledged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "running", "done", "error", "killed" ] }, "tool_call_count": { "type": "integer", "minimum": 0 }, "reply_count": { "type": "integer", "minimum": 0 }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cache_creation_input_tokens": { "type": "integer", "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "minimum": 0 } } } } } }, "x-route-boundary": "extension" }, "delete": { "operationId": "deleteProcessesId", "tags": [ "processes" ], "summary": "Cancel a process", "description": "Cooperatively cancels a running or queued process: marks it killed and signals the owning agent over WebSocket and webhook so it can stop. Any channel member (or admin) may cancel.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Acknowledged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "extension" } }, "/processes/{id}/activity": { "post": { "operationId": "postProcessesIdActivity", "tags": [ "processes" ], "summary": "Record process activity", "description": "Called by the owning bot to increment a tool-call/reply counter or add token usage as a turn progresses. Bot principals only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Acknowledged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_call", "reply", "token_usage" ] }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cache_creation_input_tokens": { "type": "integer", "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "minimum": 0 } } } } } }, "x-route-boundary": "extension" } }, "/users/{id}/reset-password": { "post": { "operationId": "postUsersIdResetPassword", "tags": [ "users" ], "summary": "POST /users/:id/reset-password", "description": "Reset another user's password by id. Requires an interactive admin session and revokes all of the target user's sessions.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminResetPasswordRequest" } } } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/users/{id}/api-tokens/{tokenId}": { "delete": { "operationId": "deleteUsersIdApiTokensTokenId", "tags": [ "users" ], "summary": "DELETE /users/:id/api-tokens/:tokenId", "description": "Revoke another user's API token by its hashed id. Requires an admin session or an admin bearer token with tokens:manage and immediately closes sockets using that credential.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "bearerAuth": [] } ], "x-route-boundary": "core" } }, "/users/{id}/mfa": { "delete": { "operationId": "deleteUsersIdMfa", "tags": ["users", "auth"], "summary": "Reset a user's authenticator MFA", "description": "Admin recovery action. Re-authorizes the admin, removes the target human user's authenticator credential, and revokes all target sessions. Admins cannot reset themselves; browser session authentication is required.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authenticator credential removed and sessions revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaResetResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaReauthorizationRequest" } } } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" } }, "/workspace/security": { "get": { "operationId": "getWorkspaceSecurity", "tags": ["users", "auth"], "summary": "Get workspace authenticator MFA policy", "description": "Return workspace enforcement state and per-human-user recovery email and enrollment readiness. Admin browser session authentication is required.", "parameters": [], "responses": { "200": { "description": "Workspace security state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSecurityResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" }, "patch": { "operationId": "patchWorkspaceSecurity", "tags": ["users", "auth"], "summary": "Update workspace authenticator MFA policy", "description": "Re-authorize the admin and enable or disable enforcement for human users. Enabling is blocked until the admin has MFA and every human user has a verified recovery email.", "parameters": [], "responses": { "200": { "description": "Updated workspace security state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSecurityResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSecurityUpdateRequest" } } } }, "security": [{ "sessionCookie": [] }], "x-route-boundary": "core" } }, "/users/{id}": { "delete": { "operationId": "deleteUsersId", "tags": [ "users" ], "summary": "DELETE /users/:id", "description": "Delete a user by id. Requires an interactive admin session.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "core" } }, "/errors": { "get": { "operationId": "getErrors", "tags": [ "operations" ], "summary": "GET /errors", "description": "List the 50 most recent server error-log rows. Requires an interactive admin session.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminErrorLogListResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "extension" } }, "/account": { "delete": { "operationId": "deleteAccount", "tags": [ "operations" ], "summary": "DELETE /account", "description": "Permanently delete this entire workspace (tenant) and all of its Cloudflare infrastructure. Owner-only: the caller must be the workspace owner, and must confirm by typing the exact workspace name and re-entering their password. Irreversible — removes data for every user in the workspace. The teardown itself runs asynchronously in the provisioner.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm", "password" ], "properties": { "confirm": { "type": "string", "description": "Must exactly equal the workspace name (TENANT_NAME)." }, "password": { "type": "string", "description": "The owner's current password, re-entered to authorize the deletion." } } } } } }, "responses": { "200": { "description": "Teardown accepted and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Deprovision workflow status, e.g. \"deleting\"." } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "x-route-boundary": "extension" } } }, "webhooks": { "threadsEventDelivery": { "post": { "operationId": "postThreadsWebhookEventDelivery", "tags": [ "webhooks" ], "summary": "Receive Threads event webhook", "description": "Threads sends this HTTPS POST to each active webhook URL owned by a bot user when that bot would receive the same channel event over WebSocket. Delivery is at-least-once; receivers must verify the signature, handle duplicates by delivery id, and reply with any 2xx status to acknowledge.", "parameters": [ { "name": "X-Threads-Event-Id", "in": "header", "required": true, "description": "Stable event id for this webhook delivery. Use this id for idempotency.", "schema": { "type": "string" } }, { "name": "X-Threads-Timestamp", "in": "header", "required": true, "description": "Unix epoch seconds used when computing the signature.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "X-Threads-Signature", "in": "header", "required": true, "description": "HMAC SHA-256 signature of '.' with the webhook secret, formatted as 'sha256='.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-fA-F]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges delivery. Non-2xx responses and timeouts are retried within the delivery budget." } }, "security": [ { "threadsWebhookSignature": [] } ] } } }, "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-session", "description": "Host-only browser session cookie set by POST /auth/login. The legacy session cookie name is accepted during migration. Generated non-browser clients should prefer bearerAuth when they have a user API token." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "User API token sent as Authorization: Bearer . This is the preferred authentication mode for generated TS/Python clients and Hermes integration." }, "threadsWebhookSignature": { "type": "apiKey", "in": "header", "name": "X-Threads-Signature", "description": "Webhook receiver verification header. The value is HMAC SHA-256 of '.' with the webhook secret, formatted as 'sha256='." } }, "schemas": { "Error": { "type": "object", "description": "Standard JSON error envelope returned by documented 4xx/5xx responses. Generated clients expose this as a normal parsed response for documented error statuses; truly undocumented statuses should be handled via the generator's unexpected-status mechanism.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable error message. Callers should branch on HTTP status codes, not parse this string." } }, "additionalProperties": false }, "PlaceholderObject": { "type": "object", "additionalProperties": true, "x-schema-status": "placeholder" }, "PlaceholderData": { "description": "Placeholder response schema until the operation is modeled precisely.", "x-schema-status": "placeholder" }, "UserRecord": { "type": "object", "description": "Authenticated user record returned by login. password_hash is intentionally excluded.", "required": [ "id", "username", "email", "email_verified_at", "display_name", "name_color", "code_theme", "is_admin", "avatar_url", "role", "bot_capabilities_json", "created_at" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "email_verified_at": { "type": [ "integer", "null" ], "description": "Unix timestamp when ownership of the email was confirmed; null until verified." }, "display_name": { "type": [ "string", "null" ] }, "name_color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "code_theme": { "$ref": "#/components/schemas/CodeThemeNullable" }, "is_admin": { "type": "integer", "enum": [ 0, 1 ] }, "avatar_url": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "bot_capabilities_json": { "type": [ "string", "null" ], "description": "Raw JSON string stored for bot capability metadata." }, "created_at": { "type": "integer" } }, "additionalProperties": true }, "LoginCompleteResponse": { "allOf": [ { "$ref": "#/components/schemas/UserRecord" }, { "type": "object", "required": ["next"], "properties": { "next": { "type": "string", "const": "complete" } } } ] }, "MfaSetup": { "type": "object", "required": ["secret", "otpauthUri"], "properties": { "secret": { "type": "string", "pattern": "^[A-Z2-7]+$", "description": "Base32 TOTP secret for manual authenticator setup. Treat as sensitive and do not persist after enrollment." }, "otpauthUri": { "type": "string", "pattern": "^otpauth://totp/", "description": "Provisioning URI suitable for a locally rendered QR code." } }, "additionalProperties": false }, "MfaEnrollmentSetup": { "type": "object", "required": ["secret", "otpauthUri", "expiresAt"], "properties": { "secret": { "type": "string", "pattern": "^[A-Z2-7]+$" }, "otpauthUri": { "type": "string", "pattern": "^otpauth://totp/" }, "expiresAt": { "type": "integer", "description": "Unix timestamp when this setup expires." } }, "additionalProperties": false }, "LoginResponse": { "oneOf": [ { "$ref": "#/components/schemas/LoginCompleteResponse" }, { "type": "object", "required": ["next"], "properties": { "next": { "type": "string", "const": "verify_mfa" } }, "additionalProperties": false }, { "type": "object", "required": ["next", "setup"], "properties": { "next": { "type": "string", "const": "enroll_mfa" }, "setup": { "$ref": "#/components/schemas/MfaSetup" } }, "additionalProperties": false } ], "discriminator": { "propertyName": "next" } }, "MfaCodeRequest": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$" } }, "additionalProperties": false }, "PasswordConfirmationRequest": { "type": "object", "required": ["currentPassword"], "properties": { "currentPassword": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "MfaReauthorizationRequest": { "type": "object", "required": ["currentPassword"], "properties": { "currentPassword": { "type": "string", "minLength": 1 }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Required when the acting account has authenticator MFA enabled." } }, "additionalProperties": false }, "MfaEnabledResponse": { "type": "object", "required": ["ok", "mfaEnabled"], "properties": { "ok": { "type": "boolean", "const": true }, "mfaEnabled": { "type": "boolean", "const": true } }, "additionalProperties": false }, "MfaDisabledResponse": { "type": "object", "required": ["ok", "mfaEnabled"], "properties": { "ok": { "type": "boolean", "const": true }, "mfaEnabled": { "type": "boolean", "const": false } }, "additionalProperties": false }, "MfaResetResponse": { "type": "object", "required": ["ok", "targetUserId"], "properties": { "ok": { "type": "boolean", "const": true }, "targetUserId": { "type": "string" } }, "additionalProperties": false }, "MySecurityResponse": { "type": "object", "required": ["mfaEnabled", "mfaRequired", "enrollmentExpiresAt", "email", "emailVerified"], "properties": { "mfaEnabled": { "type": "boolean" }, "mfaRequired": { "type": "boolean" }, "enrollmentExpiresAt": { "type": ["integer", "null"] }, "email": { "type": ["string", "null"], "format": "email" }, "emailVerified": { "type": "boolean" } }, "additionalProperties": false }, "WorkspaceSecurityUser": { "type": "object", "required": ["id", "username", "display_name", "email", "email_verified_at", "is_admin", "mfa_enabled"], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": ["string", "null"] }, "email": { "type": ["string", "null"], "format": "email" }, "email_verified_at": { "type": ["integer", "null"] }, "is_admin": { "type": "integer", "enum": [0, 1] }, "mfa_enabled": { "type": "integer", "enum": [0, 1] } }, "additionalProperties": false }, "WorkspaceSecurityResponse": { "type": "object", "required": ["requireMfaForHumans", "users", "enrolledHumans", "totalHumans", "unverifiedHumans"], "properties": { "requireMfaForHumans": { "type": "boolean" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceSecurityUser" } }, "enrolledHumans": { "type": "integer", "minimum": 0 }, "totalHumans": { "type": "integer", "minimum": 0 }, "unverifiedHumans": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "WorkspaceSecurityUpdateRequest": { "type": "object", "required": ["requireMfaForHumans", "currentPassword"], "properties": { "requireMfaForHumans": { "type": "boolean" }, "currentPassword": { "type": "string", "minLength": 1 }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Required when the acting admin has authenticator MFA enabled." } }, "additionalProperties": false }, "CurrentUser": { "type": "object", "required": [ "id", "username", "email", "email_verified_at", "pending_email", "email_verification_expires_at", "display_name", "name_color", "code_theme", "role", "ephemeral_bot_id", "bot_capabilities" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "email_verified_at": { "type": [ "integer", "null" ], "description": "Unix timestamp when ownership of the email was confirmed; null until verified." }, "pending_email": { "type": [ "string", "null" ], "format": "email", "description": "Unverified replacement address awaiting confirmation, when present." }, "email_verification_expires_at": { "type": [ "integer", "null" ], "description": "Unix expiry timestamp for the pending email verification token." }, "display_name": { "type": [ "string", "null" ] }, "name_color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "code_theme": { "$ref": "#/components/schemas/CodeThemeNullable" }, "role": { "type": "string" }, "ephemeral_bot_id": { "type": [ "string", "null" ], "description": "Bot user auto-added to ephemeral channels this user creates (null = none)." }, "bot_capabilities": { "oneOf": [ { "$ref": "#/components/schemas/BotCapabilities" }, { "type": "null" } ] } }, "additionalProperties": false }, "PublicUser": { "type": "object", "required": [ "id", "username", "display_name", "name_color", "avatar_url", "role" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "name_color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "avatar_url": { "type": [ "string", "null" ] }, "role": { "type": "string" } }, "additionalProperties": false }, "BotCapabilities": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "dm_allowed_usernames": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "dm_allowed_user_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": true }, "LoginRequest": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "MetricProcess": { "type": "object", "required": [ "pid", "name", "cpu", "memory", "state" ], "properties": { "pid": { "type": "integer" }, "name": { "type": "string" }, "cpu": { "type": "number" }, "memory": { "type": "number", "description": "Memory usage in megabytes." }, "state": { "type": "string" } }, "additionalProperties": false }, "MetricsCron": { "type": "object", "required": [ "name", "expression", "description", "enabled" ], "properties": { "name": { "type": "string" }, "expression": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": true }, "MetricsScheduledTask": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "executeAt": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true }, "MetricsLaunchdService": { "type": "object", "required": [ "name", "pid", "status" ], "properties": { "name": { "type": "string" }, "pid": { "type": [ "integer", "null" ] }, "status": { "type": "string" } }, "additionalProperties": false }, "OkResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "connections_closed": { "type": "integer", "minimum": 0, "description": "For credential revocation responses, the number of established WebSockets closed immediately. Omitted by other operations." } }, "additionalProperties": false }, "ResolveMessageResponse": { "type": "object", "required": [ "ok", "resolved_at", "resolved_by" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "resolved_at": { "type": "integer", "description": "Unix timestamp when the thread was resolved." }, "resolved_by": { "type": "string", "description": "User id that resolved the thread." } }, "additionalProperties": false }, "ThreadTitleResponse": { "type": "object", "required": [ "ok", "applied", "thread_id", "thread_title", "thread_title_updated_at" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "applied": { "type": "boolean", "description": "Whether this request changed the stored title." }, "thread_id": { "type": "string", "description": "Top-level message id that identifies the thread." }, "thread_title": { "type": "string", "description": "Human-readable thread title." }, "thread_title_updated_at": { "type": "integer", "description": "Unix timestamp when the title was last changed." } }, "additionalProperties": false }, "ChangePasswordRequest": { "type": "object", "required": [ "currentPassword", "newPassword" ], "properties": { "currentPassword": { "type": "string", "minLength": 1 }, "newPassword": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "EmailChangeRequest": { "type": "object", "required": [ "email", "currentPassword" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "currentPassword": { "type": "string", "minLength": 1, "description": "Current account password used for re-authorization." } }, "additionalProperties": false }, "EmailVerificationResponse": { "type": "object", "required": [ "ok", "verified", "pendingEmail", "expiresAt" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "verified": { "type": "boolean", "description": "True only when the requested address was already the verified address." }, "email": { "type": [ "string", "null" ], "format": "email" }, "pendingEmail": { "type": [ "string", "null" ], "format": "email" }, "expiresAt": { "type": [ "integer", "null" ] } }, "additionalProperties": false }, "CodeTheme": { "type": "string", "enum": [ "monokai-sublime", "monokai", "github-dark", "github", "atom-one-dark", "dracula", "solarized-dark", "solarized-light", "nord" ] }, "CodeThemeNullable": { "oneOf": [ { "$ref": "#/components/schemas/CodeTheme" }, { "type": "null" } ] }, "UpdateMeRequest": { "type": "object", "minProperties": 1, "properties": { "displayName": { "type": "string", "maxLength": 100, "description": "Trimmed server-side and truncated to 100 characters." }, "nameColor": { "oneOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ], "description": "Empty string is also accepted by the API to clear the color." }, "codeTheme": { "$ref": "#/components/schemas/CodeThemeNullable" }, "ephemeralBotId": { "type": [ "string", "null" ], "description": "Bot user id auto-added to ephemeral channels this user creates. Must reference an existing bot user; null (or empty string) clears it (no bot auto-added)." } }, "additionalProperties": false }, "UpdateMeResponse": { "type": "object", "required": [ "ok", "displayName", "nameColor", "codeTheme", "ephemeralBotId" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "displayName": { "type": [ "string", "null" ] }, "nameColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "codeTheme": { "$ref": "#/components/schemas/CodeThemeNullable" }, "ephemeralBotId": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "FrequentEmojisResponse": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "string" }, "description": "Exactly three frequently used reaction emojis for the current user, backfilled with defaults." }, "UpdateSelfCapabilitiesRequest": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50 }, "dm_allowed_usernames": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100 }, "dm_allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100 } }, "additionalProperties": true }, "UpdateSelfCapabilitiesResponse": { "type": "object", "required": [ "ok", "capabilities" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "capabilities": { "$ref": "#/components/schemas/BotCapabilities" } }, "additionalProperties": false }, "UserSearchResponse": { "type": "array", "items": { "$ref": "#/components/schemas/PublicUser" } }, "MessageType": { "type": "string", "enum": [ "human", "response", "progress", "tool_output", "thinking" ] }, "ProcessStatus": { "type": "string", "enum": [ "queued", "processing", "running", "done", "error", "killed", "restarted" ] }, "MessageMention": { "type": "object", "required": [ "userId", "username" ], "properties": { "userId": { "type": "string" }, "username": { "type": "string" } }, "additionalProperties": false }, "MessageReaction": { "type": "object", "required": [ "emoji", "userId", "username" ], "properties": { "emoji": { "type": "string", "description": "Reaction emoji or emoji token." }, "userId": { "type": "string", "description": "User id of the reacting user." }, "username": { "type": [ "string", "null" ], "description": "Username of the reacting user, or null if unavailable." } }, "additionalProperties": false, "description": "A reaction attached to a message or thread reply." }, "MessageAttachment": { "type": "object", "required": [ "id", "filename", "contentType", "sizeBytes", "url" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "url": { "type": "string" } }, "additionalProperties": false }, "LinkPreview": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "urlHash": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "siteName": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "Message": { "type": "object", "description": "Message read model. The API preserves legacy snake_case DB fields and exposes camelCase aliases for newer clients.", "required": [ "id", "content" ], "properties": { "type": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "channel_id": { "type": [ "string", "null" ] }, "channelId": { "type": [ "string", "null" ] }, "channel_name": { "type": [ "string", "null" ] }, "is_dm": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ], "description": "SQLite boolean flag included when the message is returned with conversation context." }, "dm_partner_id": { "type": [ "string", "null" ] }, "dm_partner_username": { "type": [ "string", "null" ] }, "dm_partner_display_name": { "type": [ "string", "null" ] }, "user_id": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "name_color": { "type": [ "string", "null" ] }, "nameColor": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "userRole": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "thread_id": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "thread_title": { "type": [ "string", "null" ], "description": "Optional human-readable title stored on a top-level message thread." }, "threadTitle": { "type": [ "string", "null" ] }, "thread_title_updated_at": { "type": [ "integer", "null" ] }, "threadTitleUpdatedAt": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "integer", "null" ] }, "edited_at": { "type": [ "integer", "null" ] }, "editedAt": { "type": [ "integer", "null" ] }, "deleted_at": { "type": [ "integer", "null" ] }, "deletedAt": { "type": [ "integer", "null" ] }, "message_type": { "oneOf": [ { "$ref": "#/components/schemas/MessageType" }, { "type": "null" } ] }, "messageType": { "oneOf": [ { "$ref": "#/components/schemas/MessageType" }, { "type": "null" } ] }, "reply_count": { "type": [ "integer", "null" ] }, "replyCount": { "type": [ "integer", "null" ] }, "pinned": { "type": [ "integer", "boolean", "null" ] }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/MessageMention" } }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/MessageReaction" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" } }, "linkPreviews": { "type": "array", "items": { "$ref": "#/components/schemas/LinkPreview" } }, "metadata": { "description": "Arbitrary JSON metadata.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ] }, "process_id": { "type": [ "string", "null" ] }, "processId": { "type": [ "string", "null" ] }, "process_status": { "oneOf": [ { "$ref": "#/components/schemas/ProcessStatus" }, { "type": "string" }, { "type": "null" } ] }, "processStatus": { "oneOf": [ { "$ref": "#/components/schemas/ProcessStatus" }, { "type": "string" }, { "type": "null" } ] }, "process_error_text": { "type": [ "string", "null" ] }, "processErrorText": { "type": [ "string", "null" ] }, "autoRespondBotId": { "type": [ "string", "null" ] }, "processingMode": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "MessagePage": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "cursor": { "type": [ "string", "null" ] }, "hasNewer": { "type": "boolean" }, "afterCursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "InboxPage": { "type": "object", "required": [ "messages", "total", "cursor" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "total": { "type": "integer", "minimum": 0 }, "cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "SendMessageRequest": { "type": "object", "properties": { "content": { "type": "string", "description": "Required unless attachmentIds is non-empty." }, "threadId": { "type": "string" }, "attachmentIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "description": "Arbitrary JSON metadata.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ] }, "message_type": { "$ref": "#/components/schemas/MessageType" }, "idempotencyKey": { "type": "string", "maxLength": 128, "description": "Optional client-generated key. Re-sending with the same key returns the already-created message (200) instead of creating a duplicate." } }, "additionalProperties": false }, "EditMessageRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "SetThreadTitleRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Human-readable title; case and punctuation are preserved." }, "if_unset": { "type": "boolean", "default": false, "description": "When true, set the title only if the thread is currently untitled." } }, "additionalProperties": false }, "AddReactionRequest": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "type": "string", "minLength": 1, "description": "Reaction emoji or emoji token to add for the current user." } }, "additionalProperties": false }, "ChannelFolder": { "type": "object", "required": [ "id", "name", "position", "collapsed", "channels" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "collapsed": { "type": "integer", "enum": [ 0, 1 ], "description": "SQLite boolean flag; 1 when collapsed, 0 when expanded." }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Channel ids assigned to the folder, ordered by folder item position." } }, "additionalProperties": false }, "ChannelFolderListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelFolder" } }, "CreateFolderRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "UpdateFolderRequest": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string" }, "position": { "type": "integer" }, "collapsed": { "type": "integer", "enum": [ 0, 1 ] } }, "additionalProperties": false }, "AddChannelToFolderRequest": { "type": "object", "required": [ "channelId" ], "properties": { "channelId": { "type": "string", "minLength": 1 }, "position": { "type": "integer" } }, "additionalProperties": false }, "ReorderFolderEntry": { "type": "object", "required": [ "id", "position" ], "properties": { "id": { "type": "string" }, "position": { "type": "integer" } }, "additionalProperties": false }, "ReorderFolderItemEntry": { "type": "object", "required": [ "folderId", "channelId", "position" ], "properties": { "folderId": { "type": "string" }, "channelId": { "type": "string" }, "position": { "type": "integer" } }, "additionalProperties": false }, "ReorderFoldersRequest": { "type": "object", "properties": { "folders": { "type": "array", "items": { "$ref": "#/components/schemas/ReorderFolderEntry" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReorderFolderItemEntry" } } }, "additionalProperties": false }, "NotificationTier": { "type": "string", "enum": [ "all", "mentions", "none" ] }, "DMPartner": { "type": "object", "required": [ "id", "username", "display_name", "name_color", "role", "bot_capabilities" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "name_color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "role": { "type": "string" }, "bot_capabilities": { "oneOf": [ { "$ref": "#/components/schemas/BotCapabilities" }, { "type": "null" } ] } }, "additionalProperties": false }, "DMChannel": { "type": "object", "required": [ "id", "name", "is_dm", "dm_partner_id", "created_at", "partner", "can_send_messages", "disabled_reason" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_dm": { "type": "integer", "enum": [ 1 ], "description": "SQLite boolean flag; DMs always return 1." }, "dm_partner_id": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "position": { "type": [ "integer", "null" ] }, "last_read_message_id": { "type": [ "string", "null" ] }, "notifications": { "$ref": "#/components/schemas/NotificationTier" }, "has_unread": { "type": [ "integer", "boolean", "null" ], "description": "SQLite boolean flag in list responses; omitted or null when creating a DM." }, "unread_count": { "type": [ "integer", "null" ], "minimum": 0 }, "last_message_content": { "type": [ "string", "null" ] }, "last_message_at": { "type": [ "integer", "null" ] }, "partner": { "$ref": "#/components/schemas/DMPartner" }, "can_send_messages": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "DMListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/DMChannel" } }, "CreateDMRequest": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "ReorderDMEntry": { "type": "object", "required": [ "id", "position" ], "properties": { "id": { "type": "string" }, "position": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReorderDMsRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ReorderDMEntry" } } }, "additionalProperties": false }, "ProcessingMode": { "type": "string", "enum": [ "immediate", "serial" ] }, "Channel": { "type": "object", "description": "Channel database read model. The API currently returns legacy snake_case fields.", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "is_private": { "type": "integer", "enum": [ 0, 1 ], "description": "SQLite boolean flag; 1 for true, 0 for false." }, "is_dm": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ], "description": "SQLite boolean flag; 1 for true, 0 for false." }, "is_ephemeral": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ], "description": "SQLite boolean flag; 1 for true, 0 for false." }, "processing_mode": { "$ref": "#/components/schemas/ProcessingMode" }, "board_enabled": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ], "description": "SQLite boolean flag; 1 for true, 0 for false." }, "auto_respond_bot_id": { "type": [ "string", "null" ] }, "auto_named_at": { "type": [ "integer", "null" ] }, "archived_at": { "type": [ "integer", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": [ "integer", "null" ] } }, "additionalProperties": true }, "ChannelListItem": { "allOf": [ { "$ref": "#/components/schemas/Channel" }, { "type": "object", "required": [ "notifications", "has_unread", "unread_count" ], "properties": { "notifications": { "$ref": "#/components/schemas/NotificationTier" }, "last_read_message_id": { "type": [ "string", "null" ] }, "has_unread": { "type": "integer", "enum": [ 0, 1 ], "description": "SQLite boolean flag; 1 for true, 0 for false." }, "unread_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } ] }, "ChannelBrowseItem": { "allOf": [ { "$ref": "#/components/schemas/Channel" }, { "type": "object", "required": [ "is_member", "member_count" ], "properties": { "is_member": { "type": "integer", "enum": [ 0, 1 ], "description": "SQLite boolean flag; 1 for true, 0 for false." }, "member_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } ] }, "ChannelListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelListItem" } }, "ChannelBrowseResponse": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelBrowseItem" } }, "CreateChannelRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "isPrivate": { "type": "boolean" } }, "additionalProperties": false }, "CreateChannelResponse": { "type": "object", "required": [ "id", "name", "description", "isPrivate" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "isPrivate": { "type": "boolean" } }, "additionalProperties": false }, "UpdateChannelRequest": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "processingMode": { "$ref": "#/components/schemas/ProcessingMode" }, "processing_mode": { "$ref": "#/components/schemas/ProcessingMode" }, "board_enabled": { "type": "integer", "enum": [ 0, 1 ], "description": "SQLite boolean flag accepted by the API; use 1 for true and 0 for false." }, "auto_respond_bot_id": { "type": [ "string", "null" ] }, "autoRespondBotId": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ChannelMember": { "type": "object", "required": [ "id", "username" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "ChannelMemberListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMember" } }, "AddChannelMemberRequest": { "type": "object", "minProperties": 1, "properties": { "userId": { "type": "string" }, "username": { "type": "string" } }, "additionalProperties": false, "description": "Provide either userId or username." }, "UpdateChannelNotificationsRequest": { "type": "object", "required": [ "tier" ], "properties": { "tier": { "$ref": "#/components/schemas/NotificationTier" } }, "additionalProperties": false }, "UpdateChannelNotificationsResponse": { "type": "object", "required": [ "ok", "tier" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "tier": { "$ref": "#/components/schemas/NotificationTier" } }, "additionalProperties": false }, "DraftListResponse": { "type": "object", "required": [ "channel_ids" ], "properties": { "channel_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "DraftAttachment": { "type": "object", "required": [ "id", "filename", "contentType", "sizeBytes", "url" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "url": { "type": "string" } }, "additionalProperties": false }, "ChannelDraftResponse": { "type": "object", "required": [ "content", "attachments" ], "properties": { "content": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/DraftAttachment" } } }, "additionalProperties": false }, "UpdateDraftRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "attachment_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "SearchMessage": { "allOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "properties": { "snippet": { "type": [ "string", "null" ], "description": "FTS snippet with sentinel markers around matches, or null for filter-only searches." }, "bm25_score": { "type": [ "number", "integer" ], "description": "FTS bm25 score. Filter-only searches return 0." }, "channel_name": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "description": "Search result row: message columns plus joined user/channel fields and optional FTS ranking/snippet fields." }, "SearchResponse": { "type": "object", "required": [ "results", "total", "hasMore", "offset", "limit" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchMessage" } }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "MentionsResponse": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Message" }, "description": "Mentioned messages ordered newest first." } }, "additionalProperties": false }, "PinMessageRequest": { "type": "object", "required": [ "messageId" ], "properties": { "messageId": { "type": "string", "minLength": 1, "description": "Message ID to pin in the channel." } }, "additionalProperties": false }, "PinnedMessage": { "type": "object", "required": [ "id", "channel_id", "message_id", "pinned_by", "created_at" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "message_id": { "type": "string" }, "pinned_by": { "type": "string" }, "created_at": { "type": "integer", "description": "Unix timestamp when the pin was created." } }, "additionalProperties": false }, "PinnedMessageListItem": { "type": "object", "required": [ "id", "channel_id", "message_id", "pinned_by", "pin_created_at", "content", "message_created_at", "user_id" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "message_id": { "type": "string" }, "pinned_by": { "type": "string" }, "pin_created_at": { "type": "integer", "description": "Unix timestamp when the pin was created." }, "content": { "type": "string" }, "message_created_at": { "type": "integer", "description": "Unix timestamp when the pinned message was created." }, "user_id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "name_color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "avatar_url": { "type": [ "string", "null" ] }, "pinned_by_username": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PinnedMessageListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/PinnedMessageListItem" } }, "KanbanBoard": { "type": "object", "description": "Raw kanban board record. columns is the JSON-encoded column key array stored by the API.", "required": [ "id", "channel_id", "columns", "created_by", "created_at" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "columns": { "type": "string", "description": "JSON-encoded array of column keys, e.g. [\"todo\",\"in-progress\",\"review\",\"done\"]." }, "created_by": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": false }, "KanbanCardPriority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "KanbanCard": { "type": "object", "description": "Raw kanban card record returned by board endpoints. metadata is stored as a JSON string when present.", "required": [ "id", "board_id", "column_key", "title", "position", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "board_id": { "type": "string" }, "column_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ], "description": "Server defaults to normal; existing data may contain custom priority strings." }, "position": { "type": "number" }, "source_message_id": { "type": [ "string", "null" ] }, "metadata": { "type": [ "string", "null" ], "description": "JSON-encoded metadata object, or null." }, "created_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false }, "KanbanBoardWithCardsResponse": { "type": "object", "required": [ "board", "cards" ], "properties": { "board": { "$ref": "#/components/schemas/KanbanBoard" }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanCard" } } }, "additionalProperties": false }, "UpdateKanbanBoardRequest": { "type": "object", "required": [ "columns" ], "properties": { "columns": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "additionalProperties": false }, "CreateKanbanCardRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "assignee": { "type": "string" }, "priority": { "type": "string", "default": "normal" }, "column_key": { "type": "string", "default": "todo" }, "source_message_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "UpdateKanbanCardRequest": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "column_key": { "type": "string" }, "assignee": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "position": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "KanbanActivity": { "type": "object", "required": [ "id", "card_id", "user_id", "action", "created_at" ], "properties": { "id": { "type": "string" }, "card_id": { "type": "string" }, "user_id": { "type": "string" }, "action": { "type": "string" }, "from_value": { "type": [ "string", "null" ] }, "to_value": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "additionalProperties": false }, "KanbanActivityListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanActivity" } }, "PresenceMapResponse": { "type": "object", "description": "Map of requested user ids to online status.", "additionalProperties": { "type": "boolean" } }, "UploadResponse": { "type": "object", "required": [ "id", "filename", "contentType", "sizeBytes", "url" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "url": { "type": "string" } }, "additionalProperties": false }, "LinkPreviewResponse": { "type": "object", "required": [ "preview" ], "properties": { "preview": { "oneOf": [ { "$ref": "#/components/schemas/LinkPreview" }, { "type": "null" } ] } }, "additionalProperties": false }, "PushVapidKeyResponse": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" } }, "additionalProperties": false }, "PushSubscriptionRequest": { "type": "object", "required": [ "endpoint", "p256dh", "auth" ], "properties": { "endpoint": { "type": "string", "format": "uri" }, "p256dh": { "type": "string", "minLength": 1 }, "auth": { "type": "string", "minLength": 1 }, "userAgent": { "type": "string" } }, "additionalProperties": false }, "PushUnsubscribeRequest": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "PushPreferences": { "type": "object", "required": [ "enabled", "notifyMentionsOnly" ], "properties": { "enabled": { "type": "integer", "enum": [ 0, 1 ] }, "notifyMentionsOnly": { "type": "integer", "enum": [ 0, 1 ] } }, "additionalProperties": false }, "UpdatePushPreferencesRequest": { "type": "object", "properties": { "enabled": { "type": "integer", "enum": [ 0, 1 ] }, "notifyMentionsOnly": { "type": "integer", "enum": [ 0, 1 ] } }, "additionalProperties": false }, "SyncStateEntry": { "type": "object", "required": [ "key", "value", "updated_at" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "updated_at": { "type": "integer" } }, "additionalProperties": false }, "SyncStateListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/SyncStateEntry" } }, "PutSyncStateRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" } }, "additionalProperties": false }, "PutSyncStateResponse": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false }, "ProcessRecord": { "type": "object", "description": "Process read model returned by the process monitor APIs. Includes raw DB fields plus joined user/channel/bot display fields when available.", "required": [ "id", "channel_id", "message_id", "user_id", "status", "started_at" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "message_id": { "type": "string" }, "thread_id": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "integer", "null" ], "description": "Unix seconds when the linked top-level thread was marked resolved. For processes attached to thread replies, this is inherited from the thread root." }, "resolved_by": { "type": [ "string", "null" ], "description": "User id that marked the linked top-level thread resolved." }, "user_id": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "channel_name": { "type": [ "string", "null" ] }, "is_dm": { "type": [ "integer", "boolean", "null" ] }, "dm_partner_id": { "type": [ "string", "null" ] }, "dm_partner_display_name": { "type": [ "string", "null" ] }, "dm_partner_username": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ProcessStatus" }, "started_at": { "type": "string", "description": "ISO-8601 timestamp, normalized from SQLite datetime when needed." }, "ended_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "pid": { "type": [ "integer", "null" ] }, "bot_id": { "type": [ "string", "null" ] }, "bot_username": { "type": [ "string", "null" ] }, "bot_display_name": { "type": [ "string", "null" ] }, "tool_call_count": { "type": "integer", "minimum": 0 }, "reply_count": { "type": "integer", "minimum": 0 }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cache_creation_input_tokens": { "type": "integer", "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": true }, "ProcessListResponse": { "type": "object", "required": [ "processes" ], "properties": { "processes": { "type": "array", "items": { "$ref": "#/components/schemas/ProcessRecord" } } }, "additionalProperties": false }, "CreateProcessRequest": { "type": "object", "required": [ "channel_id", "message_id" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "message_id": { "type": "string" }, "user_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ProcessStatus" }, "bot_id": { "type": "string", "description": "Owning bot id. Bot callers may only use their own id; admins may create a process on a bot's behalf." } }, "additionalProperties": false }, "CreateProcessResponse": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ProcessStatus" } }, "additionalProperties": false }, "ProcessCleanupResponse": { "type": "object", "required": [ "cleaned", "process_ids" ], "properties": { "cleaned": { "type": "integer", "minimum": 0 }, "process_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "UpdateProcessRequest": { "type": "object", "minProperties": 1, "properties": { "status": { "$ref": "#/components/schemas/ProcessStatus" }, "tool_call_count": { "type": "integer", "minimum": 0 }, "reply_count": { "type": "integer", "minimum": 0 }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cache_creation_input_tokens": { "type": "integer", "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ProcessActivityRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_call", "reply", "token_usage" ] }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cache_creation_input_tokens": { "type": "integer", "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "SavedDraft": { "type": "object", "required": [ "id", "channel_id", "user_id", "content", "created_at", "updated_at", "scheduled_at" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "user_id": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "CreateSavedDraftRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "ScheduleSavedDraftRequest": { "type": "object", "required": [ "scheduled_at" ], "properties": { "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "DeliverSavedDraftsResponse": { "type": "object", "required": [ "delivered" ], "properties": { "delivered": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "UpdateMessageProcessStatusRequest": { "type": "object", "required": [ "processId", "status" ], "properties": { "processId": { "type": "string", "description": "Process identifier associated with the message." }, "status": { "$ref": "#/components/schemas/ProcessStatus" }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cache_creation_input_tokens": { "type": "integer", "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "minimum": 0 }, "error_text": { "type": [ "string", "null" ], "description": "Optional process error text; server caps stored and broadcast value to 4000 characters." } }, "additionalProperties": false }, "AdminCreateUserRequest": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Required for human users and optional for bots. Must be unique within the workspace after normalization." }, "displayName": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "human", "bot" ] } }, "additionalProperties": false }, "AdminCreateUserResponse": { "type": "object", "required": [ "id", "username", "email", "displayName", "emailVerificationSent", "emailVerificationExpiresAt" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "displayName": { "type": [ "string", "null" ] }, "emailVerificationSent": { "type": "boolean", "description": "Whether the initial confirmation email was accepted by the delivery provider. Always false for bots." }, "emailVerificationExpiresAt": { "type": [ "integer", "null" ], "description": "Unix expiry timestamp for the initial verification link when it was sent." } }, "additionalProperties": false }, "AdminResetPasswordRequest": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "WebhookUrl": { "type": "string", "format": "uri", "minLength": 1, "description": "Webhook receiver URL. Must use https and a public hostname; credentials, localhost, private IPs, and internal hostnames are rejected." }, "WebhookEventType": { "type": "string", "description": "Event type from the embedded payload. Values match the WebSocket ServerEvent `type` values documented in api/openapi/ws-events.yaml." }, "WebhookEventData": { "type": "object", "description": "The event payload exactly as it is sent on channel WebSockets. See `ServerEvent` in api/openapi/ws-events.yaml for the complete per-type schemas.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookEventType" } }, "additionalProperties": true }, "WebhookDelivery": { "type": "object", "description": "Signed event delivery sent by Threads to a registered webhook URL.", "required": [ "event_id", "type", "timestamp", "bot_user_id", "channel_id", "data" ], "properties": { "event_id": { "type": "string", "description": "Stable id across retries. Store this id to make webhook handling idempotent." }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "timestamp": { "type": "integer", "minimum": 0, "description": "Unix epoch seconds when the delivery body was created." }, "bot_user_id": { "type": "string", "description": "Bot user id this delivery targets, so one URL can serve multiple bot identities." }, "channel_id": { "type": "string", "description": "Channel or DM id that produced the event, so one webhook URL can handle all rooms for a bot." }, "data": { "$ref": "#/components/schemas/WebhookEventData" } }, "additionalProperties": false }, "WebhookRegistration": { "type": "object", "required": [ "id", "url", "active", "failure_count", "last_status", "last_delivered_at", "disabled_reason", "token_id", "token_name", "created_at" ], "properties": { "id": { "type": "string" }, "url": { "$ref": "#/components/schemas/WebhookUrl" }, "active": { "type": "boolean" }, "failure_count": { "type": "integer", "minimum": 0 }, "last_status": { "type": [ "integer", "null" ], "minimum": 0 }, "last_delivered_at": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix epoch seconds for the most recent successful delivery, or null when none has succeeded." }, "disabled_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "integer", "minimum": 0 }, "token_id": { "type": "string", "description": "Stable SHA-256 token id for the API token this webhook belongs to." }, "token_name": { "type": "string" } }, "additionalProperties": false }, "WebhookRegistrationWithSecret": { "type": "object", "required": [ "id", "url", "secret" ], "properties": { "id": { "type": "string" }, "url": { "$ref": "#/components/schemas/WebhookUrl" }, "secret": { "type": "string", "description": "Webhook signing secret returned once at creation. Store it securely; later list responses never include it." } }, "additionalProperties": false }, "WebhookListResponse": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookRegistration" } } }, "additionalProperties": false }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "$ref": "#/components/schemas/WebhookUrl" }, "token_id": { "type": "string", "description": "Optional SHA-256 token id to attach the webhook to when authenticated by session. Bearer-authenticated requests infer the current token." } }, "additionalProperties": false }, "CreateWebhookResponse": { "type": "object", "required": [ "id", "url", "secret" ], "properties": { "id": { "type": "string" }, "url": { "$ref": "#/components/schemas/WebhookUrl" }, "secret": { "type": "string" } }, "additionalProperties": false }, "ApiTokenScope": { "type": "string", "enum": [ "threads:read", "threads:write", "users:provision", "tokens:manage" ] }, "AdminCreateApiTokenRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "description": "Token permissions. Omitted defaults to both read and write.", "items": { "$ref": "#/components/schemas/ApiTokenScope" }, "minItems": 1, "uniqueItems": true }, "expires_in_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "description": "Lifetime in days. Omitted defaults to 90; null explicitly disables expiry." }, "webhook_urls": { "type": "array", "description": "Optional webhook URLs to register for the token owner at token creation time. Created webhook secrets are returned once in the token creation response.", "items": { "$ref": "#/components/schemas/WebhookUrl" }, "minItems": 1, "uniqueItems": true } }, "additionalProperties": false }, "AdminCreateApiTokenResponse": { "type": "object", "required": [ "token", "id", "name", "scopes", "expires_at", "webhooks" ], "properties": { "token": { "type": "string" }, "id": { "type": "string", "description": "Stable SHA-256 token id for later token-scoped operations." }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenScope" } }, "expires_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds when the token expires, or null for no expiry." }, "webhooks": { "type": "array", "description": "Webhook registrations created from `webhook_urls`, including one-time signing secrets. Omitted when no webhooks were requested.", "items": { "$ref": "#/components/schemas/WebhookRegistrationWithSecret" } } }, "additionalProperties": false }, "MyApiTokenSummary": { "type": "object", "required": [ "id", "name", "scopes", "expires_at", "created_at", "last_used_at" ], "properties": { "id": { "type": "string", "description": "Stable, non-secret identifier (SHA-256 of the token value). Used to revoke the token." }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenScope" } }, "expires_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds when the token expires, or null for no expiry." }, "created_at": { "type": "integer", "description": "Unix epoch seconds when the token was created." }, "last_used_at": { "type": [ "integer", "null" ], "description": "Unix epoch seconds when authentication last used the token, or null when it has never been used." } }, "additionalProperties": false }, "MyApiTokenListResponse": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/MyApiTokenSummary" } } }, "additionalProperties": false }, "AdminSqlRequest": { "type": "object", "required": [ "sql" ], "properties": { "sql": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "AdminSqlResponse": { "type": "object", "required": [ "ok", "results", "meta" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "AdminSqlWriteResponse": { "type": "object", "required": [ "ok", "meta" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "AdminErrorLog": { "type": "object", "required": [ "id", "method", "path", "error_message", "stack", "timestamp" ], "properties": { "id": { "type": "integer" }, "method": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "stack": { "type": [ "string", "null" ] }, "timestamp": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "AdminErrorLogListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/AdminErrorLog" } }, "EphemeralChannelResponse": { "description": "Ephemeral channel create response. Shape matches the channel read model with ephemeral-specific flag values.", "$ref": "#/components/schemas/Channel" }, "RenameEphemeralChannelRequest": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "minLength": 1, "description": "Free-form slug candidate; sanitized to a short kebab-case channel name server-side." } }, "additionalProperties": false }, "PromoteEphemeralChannelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Optional replacement name before promotion; sanitized server-side." } }, "additionalProperties": false }, "EphemeralArchiveResponse": { "type": "object", "required": [ "ok", "archived_at" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "archived_at": { "type": "integer", "description": "Unix timestamp when the channel was archived." } }, "additionalProperties": false }, "EphemeralUnarchiveResponse": { "type": "object", "required": [ "ok", "archived_at" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "archived_at": { "type": "null" } }, "additionalProperties": false }, "EphemeralRenameResponse": { "type": "object", "required": [ "ok", "name", "auto_named_at" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "name": { "type": "string" }, "auto_named_at": { "type": "integer", "description": "Unix timestamp when the channel was auto-named." } }, "additionalProperties": false }, "EphemeralPromoteResponse": { "type": "object", "required": [ "ok", "id", "channelId", "name" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" }, "channelId": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "EphemeralRegenerateNameResponse": { "type": "object", "required": [ "ok", "auto_named_at" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "auto_named_at": { "type": "null" } }, "additionalProperties": false }, "WidgetSummary": { "type": "object", "required": [ "id", "name", "description", "icon", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "description": "SQLite timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "SQLite timestamp." } }, "additionalProperties": true }, "Widget": { "allOf": [ { "$ref": "#/components/schemas/WidgetSummary" }, { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "User-authored widget HTML/JavaScript payload." } }, "additionalProperties": true } ] }, "ChannelWidget": { "allOf": [ { "$ref": "#/components/schemas/WidgetSummary" }, { "type": "object", "required": [ "added_by", "added_at" ], "properties": { "added_by": { "type": "string" }, "added_at": { "type": "string", "description": "SQLite timestamp." } }, "additionalProperties": true } ] }, "CreateWidgetRequest": { "type": "object", "required": [ "name", "code" ], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "code": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "UpdateWidgetRequest": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "code": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "AddChannelWidgetRequest": { "type": "object", "required": [ "widgetId" ], "properties": { "widgetId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "JsonValue": { "description": "Any JSON value accepted or returned by widget data endpoints. Kept non-recursive for OpenAPI client-generator compatibility.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "WidgetKvEntry": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue" } }, "additionalProperties": false }, "WidgetKvGlobalEntry": { "type": "object", "required": [ "userId", "value" ], "properties": { "userId": { "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue" } }, "additionalProperties": false }, "WidgetKvGlobalResponse": { "type": "object", "required": [ "key", "values" ], "properties": { "key": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetKvGlobalEntry" } } }, "additionalProperties": false }, "WidgetKvPutRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "$ref": "#/components/schemas/JsonValue" } }, "additionalProperties": false } }, "responses": { "PlaceholderSuccess": { "description": "Successful response. Schema is intentionally broad until this operation is modeled precisely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceholderData" } } } }, "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MessagePage": { "description": "Message page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePage" } } } }, "InboxPage": { "description": "Unread Inbox page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxPage" } } } }, "Message": { "description": "Message response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "Ok": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "SearchResponse": { "description": "Search results response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "MentionsResponse": { "description": "Mention list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionsResponse" } } } }, "PinnedMessageList": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedMessageListResponse" } } } }, "PinnedMessage": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedMessage" } } } }, "KanbanBoard": { "description": "Kanban board record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KanbanBoard" } } } }, "KanbanBoardCreated": { "description": "Kanban board created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KanbanBoard" } } } }, "KanbanBoardWithCards": { "description": "Kanban board and ordered cards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KanbanBoardWithCardsResponse" } } } }, "KanbanCard": { "description": "Kanban card record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KanbanCard" } } } }, "KanbanCardCreated": { "description": "Kanban card created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KanbanCard" } } } }, "KanbanActivityList": { "description": "Kanban card activity, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KanbanActivityListResponse" } } } }, "PresenceMap": { "description": "Presence state keyed by user id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceMapResponse" } } } }, "UploadCreated": { "description": "Uploaded attachment metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "LinkPreviewResponse": { "description": "Fetched or cached link preview; preview is null when unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPreviewResponse" } } } } } } }