{ "openapi": "3.1.0", "info": { "title": "Strata API", "description": "AI-powered collaborative document editing API", "license": { "name": "MIT OR Apache-2.0", "identifier": "MIT OR Apache-2.0" }, "version": "0.1.0" }, "paths": { "/api/admin/users/{userId}": { "delete": { "tags": [ "Admin" ], "summary": "Cascade-delete a Cognito user. See `specs/072-scope-model-remediation/contracts/cognito-delete-cascade.md`", "operationId": "admin_delete_user", "parameters": [ { "name": "userId", "in": "path", "description": "Target Cognito user ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cascade completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminDeleteUserResponse" } } } }, "207": { "description": "Cascade halted mid-flight (same schema with `failedStep` populated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminDeleteUserResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Target user not in caller Company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/anon/documents/{docId}/yjs": { "post": { "tags": [ "anonymous" ], "summary": "Persist a Yjs update from an anonymous workspace client", "description": "Returns 204 on success. Returns 429 with a [`GatedActionError`] body\nwhen the edit-rate or document-size cap is exceeded.\n\n[`GatedActionError`]: st_api_types::anon::GatedActionError", "operationId": "persist_anonymous_yjs_update", "parameters": [ { "name": "docId", "in": "path", "description": "Document id (must match the session's sample doc id)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Raw Yjs binary update bytes", "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "required": true }, "responses": { "204": { "description": "Yjs update persisted" }, "401": { "description": "Missing or invalid session cookie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Feature disabled or doc not in session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Edit-rate or document-size cap exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatedActionError" } } } } } } }, "/api/anon/session": { "post": { "tags": [ "anonymous" ], "summary": "Bootstrap or retrieve an anonymous workspace session", "description": "Idempotent: callers with a valid `st_anon_session` cookie receive the\nexisting session. Cookie-less callers receive a new session with a\n`Set-Cookie` header in the response.", "operationId": "init_anonymous_session", "responses": { "200": { "description": "Existing or newly created anonymous session. Set-Cookie is only present on new sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousSessionResponse" } } } }, "404": { "description": "Anonymous workspace feature is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/anon/workspace": { "get": { "tags": [ "anonymous" ], "summary": "Retrieve the anonymous workspace metadata for a live session", "operationId": "get_anonymous_workspace", "responses": { "200": { "description": "Anonymous workspace metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousWorkspaceResponse" } } } }, "401": { "description": "Missing or invalid session cookie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Anonymous workspace feature is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/me/import-anon-workspace": { "post": { "tags": [ "AccountLifecycle" ], "summary": "Migrate the caller's anonymous workspace into their newly-authenticated tier.", "description": "Reads the `st_anon_session` cookie. When absent, returns 200 with\n`outcome: \"noAnonSession\"` and no `Set-Cookie` (steady-state\nauthenticated request, nothing to clear). When present, runs the\nmigration transaction and clears the cookie on EVERY outcome — a spent\ncookie after a successful migrate, and a dead cookie (expired or\nalready-consumed session, lost migration race, or malformed value) that\nwould otherwise keep tripping the anonymous-gating 401 reshape on the\nnow-authenticated caller's future mutating requests.\n\nIdempotent: a repeat call after a successful migration returns\n`outcome: \"alreadyMigrated\"` with the same `docId`.", "operationId": "import_anon_workspace", "responses": { "200": { "description": "Migration outcome. A cookie-clearing Set-Cookie header is present whenever the request carried an st_anon_session cookie, regardless of outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportAnonWorkspaceResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/account": { "delete": { "tags": [ "AccountLifecycle" ], "summary": "Self-service account deletion", "operationId": "delete_own_account", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Idempotency-Key (16-128 chars)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOwnAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "Account deletion completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOwnAccountResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Self-service deletion not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } }, "409": { "description": "Stale summary or pending operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/account/deletion-summary": { "get": { "tags": [ "AccountLifecycle" ], "summary": "Self-service account deletion summary", "operationId": "get_account_deletion_summary", "responses": { "200": { "description": "Eligibility summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionSummaryResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/activate/{token}": { "get": { "tags": [ "Enterprise" ], "summary": "Get activation token details", "operationId": "get_activation", "parameters": [ { "name": "token", "in": "path", "description": "Activation token ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationDetailResponse" } } } }, "404": { "description": "Token not found or consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "410": { "description": "Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "post": { "tags": [ "Enterprise" ], "summary": "Complete enterprise account activation", "operationId": "complete_activation", "parameters": [ { "name": "token", "in": "path", "description": "Activation token ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRequest" } } }, "required": true }, "responses": { "200": { "description": "Account activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateResponse" } } } }, "400": { "description": "Passwords don't match or fail policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Token not found or consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "410": { "description": "Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/admin/free-providers": { "get": { "tags": [ "PlatformAdmin" ], "summary": "List every entry on the free-email-provider allowlist", "operationId": "list_free_providers", "responses": { "200": { "description": "Allowlist entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFreeProvidersResponse" } } } }, "403": { "description": "Caller is not a platform operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "PlatformAdmin" ], "summary": "Add a domain to the free-email-provider allowlist", "operationId": "add_free_provider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFreeProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Entry added or already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeProviderEntry" } } } }, "400": { "description": "Invalid domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller is not a platform operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Domain is already a verified claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/admin/free-providers/{domain}": { "delete": { "tags": [ "PlatformAdmin" ], "summary": "Remove a domain from the free-email-provider allowlist", "operationId": "remove_free_provider", "parameters": [ { "name": "domain", "in": "path", "description": "Canonical registrable domain", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed (or was already absent)" }, "400": { "description": "Invalid domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller is not a platform operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents in the current tenant", "description": "Merges built-in platform agents (`@summarizer`, `@formatter`,\n`@translator`, etc.) with the caller's user-authored agent\ndefinitions from the per-user `Agents/` folder. Both surfaces are\nreturned as `AgentResponse`; user-agent system prompts are not\nloaded in this listing path — they're only fetched at invocation\ntime via the resolver.", "operationId": "list_agents", "responses": { "200": { "description": "Agent list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/agents/settings": { "get": { "tags": [ "Agents" ], "summary": "Get the caller's agents settings", "operationId": "get_agents_settings", "responses": { "200": { "description": "Agents settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsSettingsResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Agents" ], "summary": "Update the caller's agents settings", "operationId": "update_agents_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentsSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Agents settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsSettingsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/agents/tools": { "get": { "tags": [ "Agents" ], "summary": "List the platform tools an agent's frontmatter `tools:` array may grant", "operationId": "list_agent_tools", "responses": { "200": { "description": "Tool catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentToolsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/agents/user-agents": { "get": { "tags": [ "Agents" ], "summary": "List the caller's user-authored agent definitions", "operationId": "list_user_agents", "responses": { "200": { "description": "User-authored agent list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserAgentsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/agents/{agentId}": { "get": { "tags": [ "Agents" ], "summary": "Get an agent by ID. Falls back to the user-authored agents-folder\nresolver when the id matches the deterministic\n`agent_` shape", "operationId": "get_agent", "parameters": [ { "name": "agentId", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/agents/{agentId}/invoke": { "post": { "tags": [ "Agents" ], "summary": "Invoke an agent", "operationId": "invoke_agent", "parameters": [ { "name": "agentId", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeAgentRequest" } } }, "required": true }, "responses": { "202": { "description": "Agent invoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/attachments/{attachmentId}/content": { "get": { "tags": [ "Attachments" ], "summary": "Fetch live content for an attachment", "operationId": "get_attachment_live_content", "parameters": [ { "name": "attachmentId", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Live content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentContentResponse" } } } }, "403": { "description": "Cannot resolve credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Attachment or source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/auth/browser-session/establish": { "post": { "tags": [ "Auth" ], "summary": "Establish same-origin browser session cookies from a refresh token", "operationId": "auth_browser_session_establish", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEstablishRequest" } } }, "required": true }, "responses": { "204": { "description": "Browser session cookies issued" }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Trusted browser origin or Origin check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/browser-session/renew": { "post": { "tags": [ "Auth" ], "summary": "Renew same-origin browser session cookies from the renewal cookie", "description": "Origin allowlist, trusted-browser-origin extraction, and double-submit\nCSRF verification all happen inside the\n[`st_api_core::auth::browser_session::BrowserRenewalSession`] extractor.\nReaching the handler body is itself proof that all three checks passed.", "operationId": "auth_browser_session_renew", "responses": { "204": { "description": "Browser session cookies renewed" }, "401": { "description": "Renewal credential missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Trusted browser origin or CSRF check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] }, { "cookie_csrf": [] } ] } }, "/api/v1/auth/current-user": { "get": { "tags": [ "auth" ], "summary": "Return the current authenticated user", "operationId": "auth_current_user", "responses": { "200": { "description": "Current authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAuthUserResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/auth/establish": { "post": { "tags": [ "Auth" ], "summary": "Persist an Amplify-issued refresh token into the `HttpOnly` cookie.", "description": "Hybrid-flow bridge: when the SPA signs in via the existing Amplify\nclient (password, MFA, federated, etc.), the refresh token lands in\nJS memory. This endpoint moves it into the `HttpOnly` cookie so the\nSPA can drop its in-memory copy. Validation is deferred — the next\n`/refresh` request consumes the cookie and lets the upstream `IdP`\nreject it if it's malformed or revoked.", "operationId": "auth_establish", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEstablishRequest" } } }, "required": true }, "responses": { "204": { "description": "Refresh credential stored in cookie" }, "400": { "description": "Empty or oversized refresh token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Origin not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/exchange": { "post": { "tags": [ "Auth" ], "summary": "Exchange an OAuth authorization code for an access token + refresh cookie.", "description": "Public endpoint (no JWT required — this endpoint is the *source* of\naccess tokens). The calling page must have generated a fresh PKCE\npair and OAuth `state` value; `state` validation is the SPA's\nresponsibility before posting here. PKCE verification happens at\nthe upstream `IdP`.", "operationId": "auth_exchange", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthExchangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Code exchanged; refresh cookie issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Authorization code rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Auth provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Revoke the refresh credential and clear the cookie.", "description": "Best-effort: even if the upstream revoke call fails, the cookie is\ncleared in the response so the page returns to a logged-out state.", "operationId": "auth_logout", "responses": { "204": { "description": "Logged out" }, "403": { "description": "Origin not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Mint a fresh access token using the long-lived refresh cookie.", "description": "Bodyless POST; the refresh credential rides the `Cookie` header.\nOn success returns a new access token in JSON and a (rotated) refresh\ncookie via `Set-Cookie`.", "operationId": "auth_refresh", "responses": { "200": { "description": "Access token minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "401": { "description": "Refresh credential missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Origin not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/signup-domain-check": { "get": { "tags": [ "auth" ], "summary": "Probe the user's email domain before signup so the webapp can route\nclaimed-domain users away from personal-plan signup", "operationId": "signup_domain_check", "parameters": [ { "name": "email", "in": "query", "description": "User-entered email; the server canonicalizes the domain portion.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Routing decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupDomainCheckResponse" } } } }, "400": { "description": "Email could not be canonicalized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/sso-config": { "get": { "tags": [ "SSO" ], "summary": "Lookup SSO configuration by domain (public, no auth)", "operationId": "lookup_sso_config", "parameters": [ { "name": "domain", "in": "query", "description": "Email domain to look up (e.g., \"acme.com\")", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSO config for domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConfigLookupResponse" } } } }, "404": { "description": "Domain not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/auth/switch-tenant": { "post": { "tags": [ "auth" ], "summary": "Switch the active tenant for the authenticated user", "operationId": "switch_tenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "Tenant switched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchTenantResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/billing/plans": { "get": { "tags": [ "Billing" ], "summary": "Public — list active plan prices read straight from the upstream\nbilling provider so the storefront never hand-mirrors numbers", "operationId": "get_billing_plans", "responses": { "200": { "description": "Active plan prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlansResponse" } } } }, "500": { "description": "Stripe not configured or upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/chat-messages/{messageId}/attachments": { "get": { "tags": [ "Attachments" ], "summary": "List attachments on a chat message", "operationId": "list_chat_message_attachments", "parameters": [ { "name": "messageId", "in": "path", "description": "Chat message ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAttachmentsResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Attachments" ], "summary": "Attach an external resource to a chat message", "operationId": "attach_resource_to_chat_message", "parameters": [ { "name": "messageId", "in": "path", "description": "Chat message ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttachmentRequest" } } }, "required": true }, "responses": { "201": { "description": "Attachment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat-messages/{messageId}/attachments/{attachmentId}": { "delete": { "tags": [ "Attachments" ], "summary": "Remove an attachment from a chat message", "operationId": "remove_chat_message_attachment", "parameters": [ { "name": "messageId", "in": "path", "description": "Chat message ID", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed (or was absent)" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/health": { "get": { "tags": [ "Chat" ], "summary": "Check AI service health", "operationId": "check_chat_health", "responses": { "200": { "description": "Chat health status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatHealthResponse" } } } } } } }, "/api/v1/chat/rate-limit": { "get": { "tags": [ "Chat" ], "summary": "Get the current user's chat rate limit status", "operationId": "get_chat_rate_limit", "responses": { "200": { "description": "Rate limit status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions": { "get": { "tags": [ "Chat" ], "summary": "List chat sessions for the authenticated user", "operationId": "list_chat_sessions", "parameters": [ { "name": "scope", "in": "query", "description": "Filter by scope", "required": false, "schema": { "$ref": "#/components/schemas/AssistantScope" } }, { "name": "scopeEntityId", "in": "query", "description": "Filter by scope entity ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by session status", "required": false, "schema": { "$ref": "#/components/schemas/SessionStatus" } }, { "name": "limit", "in": "query", "description": "Maximum number of results (1-50)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of chat sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Chat" ], "summary": "Create a new chat session", "operationId": "create_chat_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}": { "get": { "tags": [ "Chat" ], "summary": "Get a chat session by ID with its messages", "operationId": "get_chat_session", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chat session with messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}/archive": { "post": { "tags": [ "Chat" ], "summary": "Archive a chat session and create a new one", "operationId": "archive_chat_session", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveSessionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}/memory": { "patch": { "tags": [ "Chat" ], "summary": "Toggle memory injection for a single chat session", "description": "Flips `memoryDisabled` on the session. When `true`, memory blocks\n(profile.md / MEMORY.md) are stripped from the next turn's system\nprompt and `record_memory` is dropped from the tool list — without\ntouching the user's global memory preference.", "operationId": "update_chat_session_memory", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionMemoryRequest" } } }, "required": true }, "responses": { "200": { "description": "Session memory toggled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}/messages/cancel": { "post": { "tags": [ "chat" ], "summary": "Cancel an in-flight assistant streaming response", "operationId": "cancel_chat_message", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cancellation acknowledged" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}/messages/{messageId}/remember": { "post": { "tags": [ "memory" ], "summary": "\"Remember this\" one-shot capture from a chat message", "operationId": "remember_chat_message", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "description": "Message sequence number — the server fetches the message by (sessionId, sequence) and uses its content", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RememberMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "Captured entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntry" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Session or message not found / not owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}/tool-overrides": { "patch": { "tags": [ "Chat" ], "summary": "Set or clear a per-conversation tool override", "description": "Backs the chat composer's per-tool toggle. Today only `web_search`\nreads this map; other tools are unaffected. `overrideValue=null`\nremoves the entry.", "operationId": "update_chat_session_tool_override", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionToolOverrideRequest" } } }, "required": true }, "responses": { "200": { "description": "Tool override updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/chat/sessions/{sessionId}/tools/respond": { "post": { "tags": [ "chat" ], "summary": "Submit the user's approve/deny response to a paused tool call", "operationId": "respond_to_tool_approval", "parameters": [ { "name": "sessionId", "in": "path", "description": "Chat session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolApprovalBatchRequest" } } }, "required": true }, "responses": { "204": { "description": "Tool approval recorded; streaming resumes" }, "400": { "description": "Invalid approval payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/claims": { "get": { "tags": [ "DomainClaims" ], "summary": "List the authenticated caller's claim attempts", "operationId": "list_domain_claims", "responses": { "200": { "description": "Caller's claim attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainClaimsResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "DomainClaims" ], "summary": "Issue a new domain-claim attempt with a DNS TXT verification token", "operationId": "create_domain_claim", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainClaimRequest" } } }, "required": true }, "responses": { "201": { "description": "Claim attempt created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainClaimAttempt" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Refused — domain on free-provider allowlist or already claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/claims/{claimId}/verify": { "post": { "tags": [ "DomainClaims" ], "summary": "Verify a pending claim by reading the DNS TXT record, then create the\ncompany tenant and run the migration backfill", "operationId": "verify_domain_claim", "parameters": [ { "name": "claimId", "in": "path", "description": "Claim attempt ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainClaimVerifyResponse" } } } }, "404": { "description": "Claim not found or not owned by caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Refused — domain claimed by another company between create and verify", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "DNS TXT token not present at the registrable domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies": { "get": { "tags": [ "Companies" ], "summary": "List companies the user belongs to", "operationId": "list_companies", "responses": { "200": { "description": "List of companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompaniesResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Create a new company", "operationId": "create_company", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompanyRequest" } } }, "required": true }, "responses": { "201": { "description": "Company created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetailResponse" } } } }, "409": { "description": "Slug already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}": { "get": { "tags": [ "Companies" ], "summary": "Get company details", "operationId": "get_company", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetailResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Companies" ], "summary": "Update a company", "operationId": "update_company", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyRequest" } } }, "required": true }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetailResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "WorkspaceLifecycle" ], "summary": "Self-service workspace deletion", "operationId": "delete_workspace", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Idempotency-Key (16-128 chars)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Workspace deletion completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkspaceResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Workspace lifecycle action not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Stale summary or pending operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/agent-settings": { "get": { "tags": [ "Agent Settings" ], "summary": "Get company agent settings with platform agent catalog and model info", "operationId": "get_agent_settings", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent settings with catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettingsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Agent Settings" ], "summary": "Update company agent settings", "operationId": "update_agent_settings", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated agent settings with catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettingsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/ai-usage": { "get": { "tags": [ "Billing" ], "summary": "Get AI token usage for a company", "operationId": "get_ai_usage", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "AI usage metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiUsageResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/ai-usage/daily": { "get": { "tags": [ "Billing" ], "summary": "Get daily per-model AI credit usage for a company", "operationId": "get_ai_daily_usage", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily per-model AI usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiDailyUsageResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/ai-usage/events": { "get": { "tags": [ "Billing" ], "summary": "List AI usage ledger events for a company", "operationId": "list_ai_usage_events", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } }, { "name": "userId", "in": "query", "description": "Filter by user ID", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by AI usage source", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 50, max 200)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Opaque pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "AI usage ledger events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiUsageEventsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/ai-usage/history": { "get": { "tags": [ "Billing" ], "summary": "Get AI token usage history for a company", "operationId": "get_ai_usage_history", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "months", "in": "query", "description": "Number of months of history (default 6, max 12)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "AI usage history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiUsageHistoryResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/ai-usage/users": { "get": { "tags": [ "Billing" ], "summary": "List user-attributed AI usage for a company", "operationId": "list_ai_usage_users", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 50, max 200)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Opaque pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-user AI usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiUsageUsersResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/ai-usage/users/{userId}/daily": { "get": { "tags": [ "Billing" ], "summary": "Get daily per-model AI usage for a company user", "operationId": "get_ai_user_daily_usage", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID", "required": true, "schema": { "type": "string" } }, { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User daily AI usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiUserDailyUsageResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/change-interval": { "post": { "tags": [ "Billing" ], "summary": "Change billing cadence (Monthly ↔ Annual) on the active subscription", "operationId": "change_billing_interval", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeBillingIntervalRequest" } } }, "required": true }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSubscriptionResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/checkout": { "post": { "tags": [ "Billing" ], "summary": "Create a checkout session for plan upgrade", "operationId": "create_checkout_session", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/invoices": { "get": { "tags": [ "Billing" ], "summary": "List invoices for a company", "operationId": "list_invoices", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInvoicesResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/portal-session": { "post": { "tags": [ "Billing" ], "summary": "Create a billing portal session", "operationId": "create_portal_session", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional return URL", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreatePortalSessionRequest" } ] } } } }, "responses": { "200": { "description": "Portal session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalSessionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/reconcile": { "post": { "tags": [ "Billing" ], "summary": "Reconcile billing member count with Stripe", "operationId": "reconcile_billing", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reconciliation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/subscription": { "get": { "tags": [ "Billing" ], "summary": "Get billing subscription for a company", "operationId": "get_billing_subscription", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSubscriptionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/billing/usage": { "get": { "tags": [ "Billing" ], "summary": "Get billing usage for a company", "operationId": "get_billing_usage", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/branches": { "get": { "tags": [ "Branches" ], "summary": "List all branches (depth-0 tier nodes) the user has access to", "operationId": "list_branches", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of branches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBranchesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/branches/switch": { "post": { "tags": [ "Branches" ], "summary": "Switch the user's active branch", "operationId": "switch_branch", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchBranchRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch switched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchBranchResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connections": { "get": { "tags": [ "Repo Connections" ], "summary": "List repository connections", "operationId": "list_repo_connections", "parameters": [ { "name": "companyId", "in": "path", "description": "Company identifier", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by lifecycle status", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRepoConnectionsResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connections/{connectionId}/approve": { "post": { "tags": [ "Repo Connections" ], "summary": "Approve a repository connection", "operationId": "approve_connection", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "description": "Connection ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoConnectionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connections/{connectionId}/repos": { "get": { "tags": [ "Repo Connections" ], "summary": "List repositories available through a connection", "operationId": "list_connection_repos", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "description": "Connection ID", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Filter repos by name", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "perPage", "in": "query", "description": "Results per page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Repository list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryList" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connections/{connectionId}/revoke": { "post": { "tags": [ "Repo Connections" ], "summary": "Revoke a repository connection", "operationId": "revoke_connection", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "description": "Connection ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoConnectionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connector-policy": { "get": { "tags": [ "Connector Policy" ], "summary": "Fetch the company's connector governance policy", "operationId": "get_connector_policy", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current connector governance policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyConnectorPolicy" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connector-policy/disable-all": { "put": { "tags": [ "Connector Policy" ], "summary": "Toggle the global connector kill switch", "operationId": "set_connector_disable_all", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDisableAllRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyConnectorPolicy" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connector-policy/force-revoke/{kind}": { "post": { "tags": [ "Connector Policy" ], "summary": "Force-revoke all user grants for a connector kind", "operationId": "force_revoke_connector_grants", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grants revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForceRevokeResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connector-policy/governance/{kind}": { "put": { "tags": [ "Connector Policy" ], "summary": "Set the governance override for a specific connector kind", "operationId": "set_connector_governance", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetGovernanceRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyConnectorPolicy" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Connector Policy" ], "summary": "Remove the governance override for a connector kind", "operationId": "remove_connector_governance_override", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyConnectorPolicy" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors": { "get": { "tags": [ "Connectors" ], "summary": "List connector connections for a company", "operationId": "list_connectors", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "description": "Opaque cursor from a prior response's `nextToken`", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1–100, default 50)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectorsResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Connectors" ], "summary": "Register a new custom MCP connector. First-party declarative\nconnectors are lazy-created on first authorize and do NOT use\nthis endpoint", "operationId": "register_mcp_connector", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterMcpConnectorRequest" } } }, "required": true }, "responses": { "201": { "description": "Connection created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorConnectionResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/catalog": { "get": { "tags": [ "Connectors" ], "summary": "Get the catalog of available connector types", "operationId": "connector_catalog", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connector catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}": { "get": { "tags": [ "Connectors" ], "summary": "Get a single connector connection", "operationId": "get_connector", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorConnectionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Connectors" ], "summary": "Delete a connector connection. Primarily for custom MCP\nde-registration — first-party connectors should be governance-\ndisabled via the connector policy instead", "operationId": "delete_connector", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connection deleted" }, "403": { "description": "Caller lacks CompanyManage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}/grants": { "get": { "tags": [ "Connector Grants" ], "summary": "Admin: list all user grants for a connector", "operationId": "list_grants_admin", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grant list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserGrantsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}/grants/authorize": { "post": { "tags": [ "Connector Grants" ], "summary": "Start OAuth flow for user-delegated connector", "operationId": "authorize_grant", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } }, { "name": "workspaceSlug", "in": "query", "description": "Workspace slug to deep-link back to after OAuth completes", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth redirect URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeGrantResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}/grants/me": { "get": { "tags": [ "Connector Grants" ], "summary": "Get the current user grant status for a connector", "operationId": "get_my_grant", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grant status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserGrantResponse" } } } }, "404": { "description": "No grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Connector Grants" ], "summary": "Revoke the current user grant", "operationId": "revoke_my_grant", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Grant revoked" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}/manifest/review": { "post": { "tags": [ "Connectors" ], "summary": "Mark a custom `MCP` connector's discovered manifest as reviewed.\nAdmin flips this bool after inspecting the list of tools/resources\nthe server exposes. Unreviewed `MCP` connectors cannot issue grants", "operationId": "mark_manifest_reviewed", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Manifest marked reviewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorConnectionResponse" } } } }, "400": { "description": "Not an MCP connector", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller lacks CompanyManage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}/oauth/authorize-admin": { "post": { "tags": [ "Connector Grants" ], "summary": "Start admin-initiated `OAuth` flow for `ServiceAccount` connector", "operationId": "authorize_admin_connector", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } }, { "name": "workspaceSlug", "in": "query", "description": "Workspace slug to deep-link back to after OAuth completes", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth redirect URL for admin consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeGrantResponse" } } } }, "400": { "description": "Connector is not Pending, is UserDelegated, or has no OAuth spec", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller lacks CompanyManage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/connectors/{kind}/refresh": { "post": { "tags": [ "Connectors" ], "summary": "Re-run `MCP` discovery against a custom connector", "operationId": "refresh_connector", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorConnectionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "502": { "description": "Upstream unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/domains": { "get": { "tags": [ "Domain Verification" ], "summary": "List all domain verification records for a company", "operationId": "list_domains", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of domain verifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/domains/{domain}/check": { "post": { "tags": [ "Domain Verification" ], "summary": "Check domain DNS verification status", "operationId": "check_domain", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain verification with DNS check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerificationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/domains/{domain}/verify": { "post": { "tags": [ "Domain Verification" ], "summary": "Initiate domain verification — generates a DNS TXT challenge token", "operationId": "verify_domain", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain name (e.g. acme.com)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification initiated; DNS TXT record returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainVerificationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Domain already verified or pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/finalize-team-upgrade": { "post": { "tags": [ "Billing" ], "summary": "Finalize the personal-to-team upgrade after Stripe Checkout success", "operationId": "finalize_team_upgrade", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeTeamUpgradeRequest" } } }, "required": true }, "responses": { "200": { "description": "Upgrade finalized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeTeamUpgradeResponse" } } } }, "400": { "description": "Invalid slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/hierarchy": { "get": { "tags": [ "Hierarchy" ], "summary": "Get the company's hierarchy definition", "operationId": "get_hierarchy", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hierarchy definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HierarchyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Hierarchy" ], "summary": "Define / replace the company's hierarchy", "operationId": "set_hierarchy", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetHierarchyRequest" } } }, "required": true }, "responses": { "201": { "description": "Hierarchy definition saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HierarchyResponse" } } } }, "400": { "description": "Invalid hierarchy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/hierarchy/tiers/{tierId}": { "patch": { "tags": [ "Hierarchy" ], "summary": "Update a single tier in the company's hierarchy", "operationId": "update_hierarchy_tier", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "tierId", "in": "path", "description": "Tier ID within the hierarchy", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTierRequest" } } }, "required": true }, "responses": { "200": { "description": "Tier updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HierarchyTier" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations": { "get": { "tags": [ "Integrations" ], "summary": "List every connector kind with admin governance detail", "operationId": "list_company_integrations", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Governance catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationsListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/custom-mcp": { "post": { "tags": [ "Integrations" ], "summary": "Register a custom MCP server URL for this company", "operationId": "register_custom_mcp", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCustomMcpRequest" } } }, "required": true }, "responses": { "200": { "description": "Custom MCP registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDetail" } } } }, "400": { "description": "Invalid URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/access-requests": { "get": { "tags": [ "Integrations" ], "summary": "List pending access requests for a connector kind (admin view)", "operationId": "list_access_requests_for_kind", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessRequestsForKindResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/approve-manifest": { "post": { "tags": [ "Integrations" ], "summary": "Approve the manifest for a registered custom MCP server", "operationId": "approve_custom_mcp_manifest", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Custom MCP connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Manifest approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDetail" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/byo-oauth-app": { "put": { "tags": [ "Integrations" ], "summary": "Swap in a company-owned OAuth application", "operationId": "set_byo_oauth_app", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetByoOauthAppRequest" } } }, "required": true }, "responses": { "200": { "description": "Saved" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Integrations" ], "summary": "Revert to the platform default OAuth app", "operationId": "clear_byo_oauth_app", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/grants": { "get": { "tags": [ "Integrations" ], "summary": "List user grants for a connector kind (admin view)", "operationId": "list_user_grants_for_kind", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grants list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserGrantsForKindResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/grants/{userId}": { "delete": { "tags": [ "Integrations" ], "summary": "Admin force-revoke a specific user's grant", "operationId": "force_revoke_user_grant", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID to revoke", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked (or was absent)" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/kill-switch": { "put": { "tags": [ "Integrations" ], "summary": "Engage or disengage the per-kind kill switch", "operationId": "set_integration_kill_switch", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetKillSwitchRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/policy": { "put": { "tags": [ "Integrations" ], "summary": "Set the policy state for a connector kind", "operationId": "set_integration_policy", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIntegrationPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDetail" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/refresh-manifest": { "post": { "tags": [ "Integrations" ], "summary": "Re-run discovery and refresh the manifest for a custom MCP server", "operationId": "refresh_custom_mcp_manifest", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Custom MCP connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Manifest refreshed" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/integrations/{kind}/service-account": { "post": { "tags": [ "Integrations" ], "summary": "Begin OAuth for the company-wide service account", "operationId": "start_service_account_connect", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorization URL issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartServiceAccountResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Integrations" ], "summary": "Remove the company-wide service-account credential", "operationId": "disconnect_service_account", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed (or was absent)" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/invites": { "get": { "tags": [ "Companies" ], "summary": "List pending company invitations", "operationId": "list_company_invitations", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompanyInvitationsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Invite a member to a company by email", "operationId": "invite_company_member", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCompanyMemberRequest" } } }, "required": true }, "responses": { "201": { "description": "Invitation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInvitationResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Already a member or already invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/invites/batch": { "post": { "tags": [ "Companies" ], "summary": "Batch invite members to a company", "operationId": "batch_invite_company_members", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch invitation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInviteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/invites/{email}": { "delete": { "tags": [ "Companies" ], "summary": "Revoke a pending company invitation", "operationId": "revoke_company_invitation", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "email", "in": "path", "description": "Invitee email", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Invitation revoked" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "No invitation found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/leave": { "post": { "tags": [ "WorkspaceLifecycle" ], "summary": "Self-service workspace leave", "operationId": "leave_workspace", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Idempotency-Key (16-128 chars)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Workspace leave completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveWorkspaceResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Workspace lifecycle action not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Stale summary or pending operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/lifecycle": { "get": { "tags": [ "WorkspaceLifecycle" ], "summary": "Workspace lifecycle summary", "operationId": "get_workspace_lifecycle_summary", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace lifecycle summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLifecycleSummaryResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Workspace access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/members": { "get": { "tags": [ "Companies" ], "summary": "List company members", "operationId": "list_company_members", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompanyMembersResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Add a member to a company", "operationId": "add_company_member", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCompanyMemberRequest" } } }, "required": true }, "responses": { "201": { "description": "Member added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "User is already a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/members/{userId}": { "put": { "tags": [ "Companies" ], "summary": "Update a company member's role", "operationId": "update_company_member_role", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyMemberRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Companies" ], "summary": "Remove a member from a company", "operationId": "remove_company_member", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Member removed" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/oauth-overrides": { "get": { "tags": [ "OAuth Overrides" ], "summary": "List per-provider OAuth credential status for a company", "operationId": "list_provider_credential_status", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One entry per provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProviderCredentialStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/oauth-overrides/{provider}": { "put": { "tags": [ "OAuth Overrides" ], "summary": "Create or update a customer-supplied OAuth override for a provider", "operationId": "put_oauth_override", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "description": "OAuth provider group", "required": true, "schema": { "$ref": "#/components/schemas/OAuthProvider" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutOAuthOverrideRequest" } } }, "required": true }, "responses": { "200": { "description": "Saved (upsert)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthOverrideResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "OAuth Overrides" ], "summary": "Delete a customer-supplied OAuth override for a provider", "operationId": "delete_oauth_override", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "description": "OAuth provider group", "required": true, "schema": { "$ref": "#/components/schemas/OAuthProvider" } } ], "responses": { "204": { "description": "Deleted (or was already absent)" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/oauth-overrides/{provider}/revoke-user-grants": { "post": { "tags": [ "OAuth Overrides" ], "summary": "Force-revoke every end-user grant for a provider in this company", "operationId": "force_revoke_user_grants", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "description": "OAuth provider group", "required": true, "schema": { "$ref": "#/components/schemas/OAuthProvider" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeUserGrantsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/orgs": { "get": { "tags": [ "Companies" ], "summary": "List organizations within a company", "operationId": "list_company_orgs", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompanyOrgsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Create an organization within a company", "operationId": "add_org_to_company", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgInCompanyRequest" } } }, "required": true }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalEntityResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Slug already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/orgs/{orgId}": { "delete": { "tags": [ "Companies" ], "summary": "Remove an organization from a company", "operationId": "remove_org_from_company", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Organization removed from company" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/orgs/{orgId}/members": { "get": { "tags": [ "Companies" ], "summary": "List members of an org as company admin", "operationId": "list_org_members_as_company_admin", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Org member list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgMembersResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/orgs/{orgId}/owner": { "put": { "tags": [ "Companies" ], "summary": "Transfer org ownership to another company member", "operationId": "transfer_org_ownership", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrgOwnerRequest" } } }, "required": true }, "responses": { "200": { "description": "Ownership transferred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgDetailResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/policies/sharing": { "get": { "tags": [ "Company Sharing Policy" ], "summary": "Get the company-level sharing policy", "operationId": "get_company_sharing_policy", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company sharing policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySharingPolicy" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Company Sharing Policy" ], "summary": "Replace the company-level sharing policy", "operationId": "update_company_sharing_policy", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySharingPolicy" } } }, "required": true }, "responses": { "200": { "description": "Sharing policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySharingPolicy" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/scim-tier-mappings": { "get": { "tags": [ "SCIM" ], "summary": "List SCIM tier mappings for a company", "operationId": "list_scim_tier_mappings", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of SCIM tier mappings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScimTierMappingsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "SCIM" ], "summary": "Create a SCIM tier mapping", "operationId": "create_scim_tier_mapping", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimTierMappingRequest" } } }, "required": true }, "responses": { "201": { "description": "SCIM tier mapping created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimTierMappingResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/scim-tier-mappings/{mappingId}": { "delete": { "tags": [ "SCIM" ], "summary": "Delete a SCIM tier mapping", "operationId": "delete_scim_tier_mapping", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "mappingId", "in": "path", "description": "SCIM tier mapping ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "SCIM tier mapping deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/scim/idp-mappings": { "get": { "tags": [ "IdP Mappings" ], "summary": "List `IdP` group-to-Organization mappings for a company", "operationId": "list_idp_mappings", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of IdP mappings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIdpMappingsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "IdP Mappings" ], "summary": "Create a new `IdP` group-to-Organization mapping", "operationId": "create_idp_mapping", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdpMappingRequest" } } }, "required": true }, "responses": { "201": { "description": "Mapping created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdpMappingResponse" } } } }, "400": { "description": "Validation error or org not in company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "SCIM group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Mapping already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/scim/idp-mappings/{mappingId}": { "put": { "tags": [ "IdP Mappings" ], "summary": "Update an `IdP` group mapping's org role", "operationId": "update_idp_mapping", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "mappingId", "in": "path", "description": "Mapping ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdpMappingRequest" } } }, "required": true }, "responses": { "200": { "description": "Mapping updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdpMappingResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "IdP Mappings" ], "summary": "Delete an `IdP` group mapping", "operationId": "delete_idp_mapping", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "mappingId", "in": "path", "description": "Mapping ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Mapping deleted" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/scim/tokens": { "get": { "tags": [ "SCIM Tokens" ], "summary": "List SCIM tokens (redacted — prefix only)", "operationId": "list_scim_tokens", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of SCIM tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScimTokensResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "SCIM Tokens" ], "summary": "Generate a new SCIM bearer token (full token shown once only)", "operationId": "create_scim_token", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "Token created; full token shown once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimTokenResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Maximum active tokens reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/scim/tokens/{tokenId}": { "delete": { "tags": [ "SCIM Tokens" ], "summary": "Revoke a SCIM token", "operationId": "revoke_scim_token", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "tokenId", "in": "path", "description": "SCIM token ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Token revoked" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/settings": { "get": { "tags": [ "Companies" ], "summary": "Get company settings", "operationId": "get_company_settings", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySettings" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Companies" ], "summary": "Update company settings", "operationId": "update_company_settings", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySettingsUpdate" } } }, "required": true }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySettings" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/signup/team": { "post": { "tags": [ "Signup" ], "summary": "Upgrade a Personal-plan company to Team plan", "operationId": "team_signup", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSignupRequest" } } }, "required": true }, "responses": { "200": { "description": "Company upgraded to Team plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSignupResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Slug taken or not on Personal plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/spaces/{spaceId}/pins": { "get": { "tags": [ "Pinned Resources" ], "summary": "List pinned resources in a Space", "operationId": "list_pinned_resources", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max results (default 50)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } }, { "name": "connectorKind", "in": "query", "description": "Filter by connector kind", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pinned resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPinnedResourcesResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Pinned Resources" ], "summary": "Pin an external resource to a Space", "operationId": "pin_resource", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinResourceRequest" } } }, "required": true }, "responses": { "200": { "description": "Re-pin (snapshot refreshed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedResourceResponse" } } } }, "201": { "description": "Resource pinned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedResourceResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Space or connector source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "502": { "description": "Downstream fetch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/spaces/{spaceId}/pins/{pinId}": { "get": { "tags": [ "Pinned Resources" ], "summary": "Get a pinned resource metadata", "operationId": "get_pinned_resource", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "pinId", "in": "path", "description": "Pin ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pin metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedResourceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Pinned Resources" ], "summary": "Delete a pinned resource", "operationId": "delete_pinned_resource", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "pinId", "in": "path", "description": "Pin ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Pin deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/spaces/{spaceId}/pins/{pinId}/content": { "get": { "tags": [ "Pinned Resources" ], "summary": "Get content snapshot of a pinned resource", "operationId": "get_pinned_resource_content", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "pinId", "in": "path", "description": "Pin ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Content snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedResourceContentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/spaces/{spaceId}/pins/{pinId}/refresh": { "post": { "tags": [ "Pinned Resources" ], "summary": "Refresh a pinned resource content", "operationId": "refresh_pinned_resource", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "pinId", "in": "path", "description": "Pin ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pin refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinnedResourceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Source paused or connection revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "502": { "description": "Downstream fetch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/sso/config": { "get": { "tags": [ "SSO" ], "summary": "Get SSO enforcement config for a company", "operationId": "get_sso_config", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSO config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConfigResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "SSO" ], "summary": "Update SSO enforcement config", "operationId": "update_sso_config", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "SSO config updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConfigResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/sso/connections": { "get": { "tags": [ "SSO" ], "summary": "List SSO connections for a company", "operationId": "list_sso_connections", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of SSO connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSsoConnectionsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "SSO" ], "summary": "Create a new SSO connection", "operationId": "create_sso_connection", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSsoConnectionRequest" } } }, "required": true }, "responses": { "201": { "description": "Connection created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/sso/connections/{connectionId}": { "get": { "tags": [ "SSO" ], "summary": "Get a specific SSO connection", "operationId": "get_sso_connection", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "description": "SSO connection ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSO connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "SSO" ], "summary": "Update an SSO connection", "operationId": "update_sso_connection", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "description": "SSO connection ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoConnectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Connection updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "SSO" ], "summary": "Delete an SSO connection", "operationId": "delete_sso_connection", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "description": "SSO connection ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connection deleted" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/tiers": { "get": { "tags": [ "Tiers" ], "summary": "List all tier nodes in a company", "operationId": "list_company_tier_nodes", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tier nodes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTierNodesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/companies/{companyId}/transfer-ownership": { "post": { "tags": [ "WorkspaceLifecycle" ], "summary": "Self-service workspace ownership transfer", "operationId": "transfer_workspace_ownership", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Idempotency-Key (16-128 chars)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferWorkspaceOwnershipRequest" } } }, "required": true }, "responses": { "200": { "description": "Ownership transfer completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferWorkspaceOwnershipResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Workspace lifecycle action not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } }, "404": { "description": "Workspace or recipient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Stale summary or invalid recipient", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/company-invites/accept": { "post": { "tags": [ "Companies" ], "summary": "Accept a pending company invitation", "operationId": "accept_company_invitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptCompanyInvitationRequest" } } }, "required": true }, "responses": { "200": { "description": "Invitation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberResponse" } } } }, "404": { "description": "No pending invitation found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/company-invites/preview/{token}": { "get": { "tags": [ "Companies" ], "summary": "Preview a company invitation by token (public — token signature is the auth)", "operationId": "preview_company_invitation", "parameters": [ { "name": "token", "in": "path", "description": "HMAC-signed invitation token from the email link", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Decoded invitation preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInvitationPreviewResponse" } } } }, "400": { "description": "Malformed or invalid signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Company referenced by the token no longer exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "410": { "description": "Invitation expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/connections/{connId}": { "delete": { "tags": [ "Document Connections" ], "summary": "Delete a document connection", "operationId": "delete_document_connection", "parameters": [ { "name": "connId", "in": "path", "description": "Connection ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connection deleted" }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/connectors": { "get": { "tags": [ "Connector Grants" ], "summary": "List connectors visible to the current user (Connections panel)", "operationId": "list_my_connectors", "responses": { "200": { "description": "Catalog for this user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyConnectorsResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/connectors/browse": { "get": { "tags": [ "Connectors" ], "summary": "Browse a connector's resources via the caller's personal grant", "description": "Returns the same shape as the space-scoped browse endpoint, but does not\nrequire a `Space` context — used by document-level surfaces such as the\nresource-attachment dialog where the natural authz scope is \"the user\nhas a grant for this connector kind\".", "operationId": "browse_connector_resources_for_user", "parameters": [ { "name": "kind", "in": "query", "description": "Connector kind slug (e.g. notion, slack)", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Optional search query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full list of browsable resources (no pagination)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResourcesResponse" } } } }, "403": { "description": "Connector disabled by policy or no grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Unknown connector kind", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/connectors/{kind}/access-requests": { "post": { "tags": [ "Connector Grants" ], "summary": "Request admin access to a disallowed connector kind", "operationId": "request_connector_access", "parameters": [ { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestConnectorAccessBody" } } }, "required": true }, "responses": { "200": { "description": "Request recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorAccessRequestResponse" } } } }, "400": { "description": "Kind already allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/connectors/{kind}/grants/me": { "delete": { "tags": [ "Connector Grants" ], "summary": "Disconnect (force-revoke) the current user's personal grant — idempotent", "operationId": "disconnect_my_grant", "parameters": [ { "name": "kind", "in": "path", "description": "Connector kind", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed (or was already absent)" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents": { "get": { "tags": [ "documents" ], "summary": "List documents for the authenticated user", "operationId": "list_documents", "parameters": [ { "name": "folderId", "in": "query", "description": "Filter by folder ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by document status (active, trashed, archived)", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filter by publishing lifecycle state: `draft` or `published`", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } }, { "name": "ownerId", "in": "query", "description": "Filter by document owner (for 'mine' facet)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "documents" ], "summary": "Create a new document", "operationId": "create_document", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" } } }, "required": true }, "responses": { "201": { "description": "Document created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/bulk": { "post": { "tags": [ "documents" ], "summary": "Bulk document action (trash, restore, archive)", "operationId": "bulk_document_action", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDocumentActionRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk action results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDocumentActionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/search": { "get": { "tags": [ "search" ], "summary": "Full-text search across documents", "operationId": "search_documents", "parameters": [ { "name": "q", "in": "query", "description": "Search query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "status", "in": "query", "description": "Filter by document status (active, trashed, archived)", "required": false, "schema": { "type": "string" } }, { "name": "ownerId", "in": "query", "description": "Filter by document owner user ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "in": "query", "description": "Narrow results to documents in this org", "required": false, "schema": { "type": "string" } }, { "name": "spaceId", "in": "query", "description": "Narrow results to documents in this Space", "required": false, "schema": { "type": "string" } }, { "name": "folderId", "in": "query", "description": "Narrow results to documents in this folder", "required": false, "schema": { "type": "string" } }, { "name": "excludeDocIds", "in": "query", "description": "Document IDs to exclude from results", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "updatedAfter", "in": "query", "description": "Only documents updated on or after this timestamp (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "updatedBefore", "in": "query", "description": "Only documents updated on or before this timestamp (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "createdAfter", "in": "query", "description": "Only documents created on or after this timestamp (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "createdBefore", "in": "query", "description": "Only documents created on or before this timestamp (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "isPublic", "in": "query", "description": "Filter by public link visibility", "required": false, "schema": { "type": "boolean" } }, { "name": "minScope", "in": "query", "description": "Minimum document audience to include: 'personal' (everything) or 'tier' (exclude owner-only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/shared": { "get": { "tags": [ "documents" ], "summary": "List documents shared with the current user", "operationId": "list_shared_documents", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of shared documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSharedDocumentsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}": { "get": { "tags": [ "documents" ], "summary": "Get a document by ID", "operationId": "get_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "documents" ], "summary": "Update document metadata", "operationId": "update_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "Document updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "documents" ], "summary": "Delete a document", "operationId": "delete_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Document deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/access": { "get": { "tags": [ "access" ], "summary": "List access grants for a document", "operationId": "list_access", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Access entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessEntriesResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "access" ], "summary": "Grant access to a document, or create a pending invitation for an\nexternal email", "operationId": "grant_access", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantAccessRequest" } } }, "required": true }, "responses": { "201": { "description": "Access granted to an existing tenant user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantAccessResponse" } } } }, "202": { "description": "Pending invitation created for an external email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantAccessResponse" } } } }, "403": { "description": "Sharing policy denied the invitation target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/access/self": { "delete": { "tags": [ "access" ], "summary": "Revoke the authenticated user's own access to a document", "operationId": "revoke_self_access", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Access self-revoked" }, "403": { "description": "Forbidden — user is the document owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/access/{userId}": { "delete": { "tags": [ "access" ], "summary": "Revoke access from a document", "operationId": "revoke_access", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID to revoke access for", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Access revoked" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/archive": { "post": { "tags": [ "documents" ], "summary": "Archive a document", "operationId": "archive_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/attachments": { "get": { "tags": [ "Attachments" ], "summary": "List attachments on a document", "operationId": "list_document_attachments", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAttachmentsResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Attachments" ], "summary": "Attach an external resource to a document", "operationId": "attach_resource_to_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttachmentRequest" } } }, "required": true }, "responses": { "201": { "description": "Attachment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/attachments/{attachmentId}": { "delete": { "tags": [ "Attachments" ], "summary": "Remove an attachment from a document", "operationId": "remove_document_attachment", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed (or was absent)" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/attribution": { "get": { "tags": [ "history" ], "summary": "Get character-level attribution for a document", "description": "Returns a run-length encoded map of text positions to the actors\n(humans or agents) that last edited them.", "operationId": "get_attribution", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attribution map", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionMap" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/check-staleness": { "post": { "tags": [ "documents" ], "summary": "Cheap staleness probe against a document's upstream source", "operationId": "check_document_staleness", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Staleness evaluated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckStalenessResponse" } } } }, "400": { "description": "Document is not an imported document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/comments": { "get": { "tags": [ "comments" ], "summary": "List comments on a document", "operationId": "list_comments", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommentsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "comments" ], "summary": "Create a comment on a document", "operationId": "create_comment", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommentRequest" } } }, "required": true }, "responses": { "201": { "description": "Comment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/comments/mark-read": { "post": { "tags": [ "comments" ], "summary": "Mark all comments on a document as read", "operationId": "mark_comments_read", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comments marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkReadResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/comments/{commentId}": { "put": { "tags": [ "comments" ], "summary": "Update a comment", "operationId": "update_comment", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentRequest" } } }, "required": true }, "responses": { "200": { "description": "Comment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "comments" ], "summary": "Delete a comment", "operationId": "delete_comment", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCommentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/comments/{commentId}/reactions": { "post": { "tags": [ "comments" ], "summary": "Toggle a reaction on a comment", "operationId": "toggle_reaction", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleReactionRequest" } } }, "required": true }, "responses": { "200": { "description": "Reaction toggled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/comments/{commentId}/reopen": { "post": { "tags": [ "comments" ], "summary": "Reopen a resolved comment thread", "operationId": "reopen_comment", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread reopened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReopenCommentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/comments/{commentId}/resolve": { "post": { "tags": [ "comments" ], "summary": "Resolve a comment thread", "operationId": "resolve_comment", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveCommentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/connections": { "get": { "tags": [ "Document Connections" ], "summary": "List connections for a document", "operationId": "list_document_connections", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Filter by direction: source, target, or both (default)", "required": false, "schema": { "$ref": "#/components/schemas/ConnectionDirection" } } ], "responses": { "200": { "description": "List of connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentConnectionsResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Document Connections" ], "summary": "Create a connection between two documents", "operationId": "create_document_connection", "parameters": [ { "name": "docId", "in": "path", "description": "Source document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentConnectionRequest" } } }, "required": true }, "responses": { "201": { "description": "Connection created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentConnectionResponse" } } } }, "400": { "description": "Validation error or cycle detected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Duplicate connection or cycle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/content": { "get": { "tags": [ "documents" ], "summary": "Get document content (`ProseMirror` JSON, markdown, or HTML)", "operationId": "get_document_content", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Output format: markdown, html, or omit for JSON", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } } }, "304": { "description": "Not modified — If-None-Match matched the current content ETag" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/edit": { "post": { "tags": [ "documents" ], "summary": "Edit document content (append, replace section, etc.)", "operationId": "edit_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "Document edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/graph": { "get": { "tags": [ "Document Connections" ], "summary": "Get the connection graph around a document", "operationId": "get_document_graph", "parameters": [ { "name": "docId", "in": "path", "description": "Starting document ID", "required": true, "schema": { "type": "string" } }, { "name": "depth", "in": "query", "description": "BFS traversal depth (default 2, max 5)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "maxNodes", "in": "query", "description": "Maximum nodes to return (default 50, max 200)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Connection graph", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionGraphResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/history": { "get": { "tags": [ "history" ], "summary": "List grouped edit history for a document", "operationId": "list_history", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "description": "Pagination token (sequence ID of oldest entry from previous page)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of raw WAL records to fetch (default 200, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Grouped history entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListHistoryResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/history/undo": { "post": { "tags": [ "history" ], "summary": "Apply a selective undo, replacing the targeted edit's content", "operationId": "selective_undo", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectiveUndoRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated document content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectiveUndoResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Undo conflicts with later edits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/history/undo-preview": { "get": { "tags": [ "history" ], "summary": "Preview the effect of selectively undoing a specific edit group", "operationId": "selective_undo_preview", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "query", "description": "Sequence ID of the newest WAL record in the target group.", "required": true, "schema": { "type": "string" } }, { "name": "beforeSequenceId", "in": "query", "description": "Sequence ID of the record before the target group (the \"before\" state).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Selective-undo preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectiveUndoResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/history/{sequenceId}/diff": { "get": { "tags": [ "history" ], "summary": "Compute section-level diff between two history points", "operationId": "history_diff", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "description": "WAL sequence ID of the 'after' state", "required": true, "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "WAL sequence ID of the 'before' state (omit for diff against empty document)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Block-level diff with word-level chunks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryDiffResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/history/{sequenceId}/preview": { "get": { "tags": [ "history" ], "summary": "Preview document at a specific point in history", "operationId": "preview_history", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "description": "WAL sequence ID to reconstruct to", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Historical document preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPreviewResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/holds": { "get": { "tags": [ "Legal Holds" ], "summary": "List all legal holds on a document", "operationId": "list_document_holds", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Legal holds on the document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLegalHoldsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Legal Holds" ], "summary": "Place a legal hold on a document", "operationId": "place_document_hold", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceLegalHoldRequest" } } }, "required": true }, "responses": { "201": { "description": "Legal hold placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/holds/{holdId}": { "delete": { "tags": [ "Legal Holds" ], "summary": "Release a legal hold from a document", "operationId": "release_document_hold", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "holdId", "in": "path", "description": "Hold ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Legal hold released" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Hold not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/invites": { "get": { "tags": [ "access" ], "summary": "List pending document invitations", "operationId": "list_document_invites", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentInvitesResponse" } } } }, "403": { "description": "Forbidden — caller lacks DocumentShare", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/invites/{email}": { "delete": { "tags": [ "access" ], "summary": "Revoke a pending document invitation", "operationId": "revoke_document_invite", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "email", "in": "path", "description": "Email whose pending invitation to revoke", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Invitation revoked (idempotent — also returns 204 if the invitation does not exist)" }, "403": { "description": "Forbidden — caller lacks DocumentShare", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/public-link": { "post": { "tags": [ "access" ], "summary": "Create a public share link for a document", "operationId": "create_public_link", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicLinkResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "access" ], "summary": "Delete a public share link for a document", "operationId": "delete_public_link", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Public link deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/publish": { "post": { "tags": [ "publish" ], "summary": "Publish a document, creating a versioned snapshot and assigning a public URL", "operationId": "publish_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional publish options", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublishDocumentRequest" } ] } } } }, "responses": { "200": { "description": "Document published (new version or idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishDocumentResponse" } } } }, "400": { "description": "Invalid slug format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller lacks DocumentPublish permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Slug supplied on republish (slug is immutable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/publish-status": { "get": { "tags": [ "publish" ], "summary": "Read the publish status of a document (drives the publish-status pill)", "operationId": "get_publish_status", "parameters": [ { "name": "docId", "in": "path", "description": "Document identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Publish status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller lacks DocumentRead permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/purge": { "post": { "tags": [ "documents" ], "summary": "Permanently purge a trashed document", "operationId": "purge_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Document purged" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/refresh-from-source": { "post": { "tags": [ "documents" ], "summary": "Refresh an imported document from its upstream source", "operationId": "refresh_document_from_source", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refresh attempted; see refreshOutcome for outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshFromSourceResponse" } } } }, "400": { "description": "Document is not an imported document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/restore": { "post": { "tags": [ "documents" ], "summary": "Restore a trashed document", "operationId": "restore_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/revert": { "post": { "tags": [ "history" ], "summary": "Revert document to a prior point in history", "operationId": "revert_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "Document reverted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/review-console/cards/{commentId}/draft": { "post": { "tags": [ "review-console" ], "summary": "Generate or regenerate a draft reply for a Review Console card", "operationId": "regenerate_review_console_draft", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateDraftRequest" } } }, "required": true }, "responses": { "200": { "description": "Draft generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateDraftResponse" } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Feature flag off, document missing, or caller is not an author", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "410": { "description": "Parent comment was deleted between draft and post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "AI quota exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/review-console/cards/{commentId}/mark-addressed": { "post": { "tags": [ "review-console" ], "summary": "Mark a Review Console card addressed without posting a reply", "operationId": "mark_review_console_card_addressed", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAddressedRequest" } } }, "required": true }, "responses": { "200": { "description": "Card marked addressed (or replay returned)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAddressedResponse" } } } }, "404": { "description": "Feature flag off, document missing, or caller is not an author", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Scratchpad CAS conflict — supplied sequenceNumber is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/review-console/cards/{commentId}/post": { "post": { "tags": [ "review-console" ], "summary": "Post the active draft as a reply on the shared comment thread", "operationId": "post_review_console_reply", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "description": "Parent comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostReplyRequest" } } }, "required": true }, "responses": { "200": { "description": "Reply posted (or replay returned)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostReplyResponse" } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Feature flag off, document missing, or caller is not an author", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Scratchpad CAS conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "410": { "description": "Parent comment was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/review-console/meta": { "put": { "tags": [ "review-console" ], "summary": "Replace the per-author Review Console META slot for a document", "description": "Body MUST carry a full `ReviewConsoleMeta`. `sequenceNumber` is the\n**expected** value (compare-and-swap); the server writes\n`expected + 1` on success and returns the freshly written meta.", "operationId": "review_console_put_meta", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewConsoleMeta" } } }, "required": true }, "responses": { "200": { "description": "Updated meta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewConsoleMeta" } } } }, "400": { "description": "Body identifiers don't match caller / URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Feature flag off, document missing, or caller is not an author", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "CAS conflict — supplied sequenceNumber is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/review-console/session": { "get": { "tags": [ "review-console" ], "summary": "Hydrate the per-author Review Console session for a document", "operationId": "review_console_get_session", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-author session bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewConsoleSessionResponse" } } } }, "404": { "description": "Feature flag off, document missing, or caller is not an author", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/scan-references": { "post": { "tags": [ "Document Connections" ], "summary": "Resolve candidate document references into a connection-ready shape", "operationId": "scan_document_references", "parameters": [ { "name": "docId", "in": "path", "description": "Source document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanReferencesRequest" } } }, "required": true }, "responses": { "200": { "description": "Resolved references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanReferencesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller cannot read source document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Source document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/similar": { "get": { "tags": [ "Discovery" ], "summary": "Find documents similar to a given document", "operationId": "get_similar_documents", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Similar documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarDocumentsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions": { "get": { "tags": [ "Suggestions" ], "summary": "List pending suggestions for a document", "operationId": "list_suggestions", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of suggestions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSuggestionsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Suggestions" ], "summary": "Create a human-authored suggestion on a document", "operationId": "create_suggestion", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Suggestion details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuggestionRequest" } } }, "required": true }, "responses": { "201": { "description": "Suggestion created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSuggestionResponse" } } } }, "404": { "description": "Not found or text not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/accept-all": { "post": { "tags": [ "Suggestions" ], "summary": "Accept all suggestions on a document", "operationId": "accept_all_suggestions", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionActionRequest" } ] } } } }, "responses": { "200": { "description": "All suggestions accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSuggestionActionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/batch/{batchId}/accept": { "post": { "tags": [ "Suggestions" ], "summary": "Accept every pending suggestion in a single batch (agent task)", "operationId": "accept_batch_suggestions", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "batchId", "in": "path", "description": "Suggestion batch ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionActionRequest" } ] } } } }, "responses": { "200": { "description": "Batch accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSuggestionActionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/batch/{batchId}/reject": { "post": { "tags": [ "Suggestions" ], "summary": "Reject every pending suggestion in a single batch (agent task)", "operationId": "reject_batch_suggestions", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "batchId", "in": "path", "description": "Suggestion batch ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSuggestionActionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/reject-all": { "post": { "tags": [ "Suggestions" ], "summary": "Reject all suggestions on a document", "operationId": "reject_all_suggestions", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All suggestions rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSuggestionActionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/{suggestionId}/accept": { "post": { "tags": [ "Suggestions" ], "summary": "Accept a suggestion", "operationId": "accept_suggestion", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "suggestionId", "in": "path", "description": "Suggestion ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional force flag", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionActionRequest" } ] } } } }, "responses": { "200": { "description": "Suggestion accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionActionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Overlapping suggestions conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/{suggestionId}/reject": { "post": { "tags": [ "Suggestions" ], "summary": "Reject a suggestion", "operationId": "reject_suggestion", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "suggestionId", "in": "path", "description": "Suggestion ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional force flag", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionActionRequest" } ] } } } }, "responses": { "200": { "description": "Suggestion rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionActionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Overlapping suggestions conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/{suggestionId}/revise": { "post": { "tags": [ "Suggestions" ], "summary": "Request a revision of an agent-authored suggestion with feedback", "operationId": "request_suggestion_revision", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "suggestionId", "in": "path", "description": "Suggestion ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestSuggestionRevisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Revision requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestSuggestionRevisionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Not in revisable state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/suggestions/{suggestionId}/withdraw": { "post": { "tags": [ "Suggestions" ], "summary": "Withdraw a suggestion authored by the current user", "operationId": "withdraw_suggestion", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } }, { "name": "suggestionId", "in": "path", "description": "Suggestion ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Suggestion withdrawn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawSuggestionResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Not pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/unarchive": { "post": { "tags": [ "documents" ], "summary": "Unarchive a document", "operationId": "unarchive_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document unarchived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{docId}/unpublish": { "post": { "tags": [ "publish" ], "summary": "Unpublish a document, retiring its public URL and clearing version records", "operationId": "unpublish_document", "parameters": [ { "name": "docId", "in": "path", "description": "Document identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document unpublished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnpublishDocumentResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller lacks DocumentPublish permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Document is not currently published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{documentId}/docx": { "post": { "tags": [ "documents" ], "summary": "Export a `.docx` of the document at its current state", "operationId": "export_document_docx", "parameters": [ { "name": "documentId", "in": "path", "description": "Document ULID", "required": true, "schema": { "type": "string" } }, { "name": "includeComments", "in": "query", "description": "Include comment threads as Word-native comments. Default false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "DOCX bytes inline", "content": { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {} } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden — caller lacks DocumentRead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Document is in Trash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate-limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Render failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/documents/{documentId}/pdf": { "post": { "tags": [ "documents" ], "summary": "Export a PDF of the document at its current state", "description": "Returns `200 OK` with the PDF bytes inline when small, or `303 See Other`\npointing at a single-use, time-limited download URL for large PDFs.", "operationId": "export_document_pdf", "parameters": [ { "name": "documentId", "in": "path", "description": "Document ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF bytes inline", "content": { "application/pdf": {} } }, "303": { "description": "Large PDF redirect to a single-use download URL" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden — caller lacks DocumentRead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Document is in Trash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate-limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Render failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "PDF renderer not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/feature-flags": { "get": { "tags": [ "feature-flags" ], "summary": "Get the runtime feature flags evaluated for the requesting user", "operationId": "get_feature_flags", "responses": { "200": { "description": "Evaluated feature flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFlagsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/folders": { "get": { "tags": [ "folders" ], "summary": "List folders for the authenticated user", "operationId": "list_folders", "parameters": [ { "name": "parentFolderId", "in": "query", "description": "Filter by parent folder ID", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFoldersResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "folders" ], "summary": "Create a new folder", "operationId": "create_folder", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderRequest" } } }, "required": true }, "responses": { "201": { "description": "Folder created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/folders/{folderId}": { "delete": { "tags": [ "folders" ], "summary": "Delete a folder", "operationId": "delete_folder", "parameters": [ { "name": "folderId", "in": "path", "description": "Folder ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Folder deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "folders" ], "summary": "Rename a folder", "operationId": "update_folder", "parameters": [ { "name": "folderId", "in": "path", "description": "Folder ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderRequest" } } }, "required": true }, "responses": { "200": { "description": "Folder updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResponse" } } } }, "400": { "description": "Invalid name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Personal root cannot be renamed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/folders/{folderId}/access": { "get": { "tags": [ "Folder Access" ], "summary": "List access grants for a folder", "operationId": "list_folder_access", "parameters": [ { "name": "folderId", "in": "path", "description": "Folder ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Folder access grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFolderAccessResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Folder Access" ], "summary": "Grant access to a folder", "operationId": "grant_folder_access", "parameters": [ { "name": "folderId", "in": "path", "description": "Folder ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantFolderAccessRequest" } } }, "required": true }, "responses": { "201": { "description": "Access granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderAccessGrantResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/folders/{folderId}/access/{userId}": { "delete": { "tags": [ "Folder Access" ], "summary": "Revoke access from a folder", "operationId": "revoke_folder_access", "parameters": [ { "name": "folderId", "in": "path", "description": "Folder ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Access revoked" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/folders/{folderId}/move": { "post": { "tags": [ "folders" ], "summary": "Move a folder to a different parent or to root", "operationId": "move_folder", "parameters": [ { "name": "folderId", "in": "path", "description": "Folder ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveFolderRequest" } } }, "required": true }, "responses": { "200": { "description": "Folder moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResponse" } } } }, "400": { "description": "Bad request (cycle detected)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/gate/consume": { "post": { "tags": [ "Gate" ], "summary": "Retrieve and clear the conversion-gate cookie after sign-in.\nReturns 200 with the stashed payload when the cookie is valid,\n404 when the cookie is missing, malformed, or expired (the SPA\ntreats 404 as \"no gate active, fall through to default landing\")", "operationId": "gate_consume", "responses": { "200": { "description": "Gate payload consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateConsumeResponse" } } } }, "404": { "description": "No valid gate cookie present", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/gate/issue": { "post": { "tags": [ "Gate" ], "summary": "Plant a signed conversion-gate cookie for an unauthenticated\nvisitor. Anonymous endpoint — anyone can call it; the destination\naction enforces its own permissions on consume", "operationId": "gate_issue", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateIssueRequest" } } }, "required": true }, "responses": { "200": { "description": "Gate cookie issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateIssueResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/handles/{handle}/available": { "get": { "tags": [ "publishing-profile" ], "summary": "Check whether a candidate handle is available", "operationId": "check_handle_available", "parameters": [ { "name": "handle", "in": "path", "description": "Candidate handle string", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Availability result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandleAvailabilityResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/hierarchy-templates": { "get": { "tags": [ "Hierarchy" ], "summary": "List the built-in hierarchy templates an admin can pick from when\ninitializing a company's hierarchy", "operationId": "list_hierarchy_templates", "responses": { "200": { "description": "Available hierarchy templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/images": { "post": { "tags": [ "Images" ], "summary": "Upload an image", "operationId": "upload_image", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "201": { "description": "Image uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUploadResponse" } } } }, "400": { "description": "Invalid image or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/images/urls": { "post": { "tags": [ "Images" ], "summary": "Batch-resolve presigned URLs for image IDs", "operationId": "resolve_image_urls", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveImageUrlsRequest" } } }, "required": true }, "responses": { "200": { "description": "Resolved URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveImageUrlsResponse" } } } }, "400": { "description": "Too many IDs or invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden — caller lacks DocumentRead on the stated document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/images/{imageId}": { "get": { "tags": [ "Images" ], "summary": "Get raw image bytes by ID", "operationId": "get_image_binary", "parameters": [ { "name": "imageId", "in": "path", "description": "Image content-hash ID (SHA256 hex)", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "query", "description": "Document the image belongs to; caller must have DocumentRead on this document", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Image bytes", "content": { "application/octet-stream": {} } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden — caller lacks DocumentRead on the stated document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Image or document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/internal/companies": { "post": { "tags": [ "Enterprise" ], "summary": "Provision a new enterprise company (internal API)", "operationId": "provision_enterprise", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionEnterpriseRequest" } } }, "required": true }, "responses": { "201": { "description": "Enterprise company provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionEnterpriseResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Slug taken or email exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/internal/companies/{companyId}/domains/{domain}/verify": { "post": { "tags": [ "Enterprise" ], "summary": "Initiate domain verification for a company (internal API)", "operationId": "internal_domain_verification", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Email domain to verify", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Domain verification initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalDomainVerificationResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Domain already verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/internal/companies/{companyId}/orgs": { "post": { "tags": [ "Enterprise" ], "summary": "Create an organization under a company (internal API)", "operationId": "internal_create_org", "parameters": [ { "name": "companyId", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgInCompanyRequest" } } }, "required": true }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalEntityResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/models": { "get": { "tags": [ "Models" ], "summary": "List all platform-supported models with credit multipliers", "operationId": "list_models", "responses": { "200": { "description": "Model catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notifications for the authenticated user", "operationId": "list_notifications", "parameters": [ { "name": "unread_only", "in": "query", "description": "Only return unread notifications", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "sinceId", "in": "query", "description": "Only return notifications created after this notification ID", "required": false, "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "description": "Opaque pagination token from a previous response", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notification list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNotificationsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/notifications/{notificationId}/read": { "post": { "tags": [ "Notifications" ], "summary": "Mark a notification as read", "operationId": "mark_notification_read", "parameters": [ { "name": "notificationId", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Notification marked as read" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/oauth/clients": { "get": { "tags": [ "oauth" ], "summary": "List `OAuth` clients for the authenticated user", "operationId": "list_oauth_clients", "responses": { "200": { "description": "List of OAuth clients", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthClientInfo" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "oauth" ], "summary": "Create a new `OAuth` client", "operationId": "create_oauth_client", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthClientRequest" } } }, "required": true }, "responses": { "201": { "description": "OAuth client created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthClientResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/oauth/clients/{clientId}": { "delete": { "tags": [ "oauth" ], "summary": "Delete an `OAuth` client", "operationId": "delete_oauth_client", "parameters": [ { "name": "clientId", "in": "path", "description": "OAuth client ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "OAuth client deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/audit-logs": { "get": { "tags": [ "Audit Logs" ], "summary": "List audit events for an organization", "operationId": "list_audit_logs", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Inclusive start of the time range (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Inclusive end of the time range (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "actor", "in": "query", "description": "Filter by actor ID", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Filter by action or action category prefix", "required": false, "schema": { "type": "string" } }, { "name": "resource", "in": "query", "description": "Filter by resource ID", "required": false, "schema": { "type": "string" } }, { "name": "resourceType", "in": "query", "description": "Filter by resource type", "required": false, "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "description": "Filter by outcome (success, failure, denied)", "required": false, "schema": { "type": "string" } }, { "name": "ipAddress", "in": "query", "description": "Filter by IP address (client-side post-filter)", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1–200, default 50)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of audit events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditLogsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/audit-logs/export": { "post": { "tags": [ "Audit Logs" ], "summary": "Request an async audit log export", "operationId": "request_audit_export", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportRequest" } } }, "required": true }, "responses": { "202": { "description": "Export job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportCreateResponse" } } } }, "400": { "description": "Invalid request or date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/audit-logs/export/{exportId}": { "get": { "tags": [ "Audit Logs" ], "summary": "Poll the status of an audit log export", "operationId": "get_audit_export", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "exportId", "in": "path", "description": "Export job ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export status and optional download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditExportStatusResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Export not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/audit-logs/exports": { "get": { "tags": [ "Audit Logs" ], "summary": "List the 30 most recent audit log exports for an organization", "operationId": "list_audit_exports", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent exports ordered by createdAt descending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditExportsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/audit-logs/{eventId}": { "get": { "tags": [ "Audit Logs" ], "summary": "Get a single audit event by ID", "operationId": "get_audit_log", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "description": "Audit event ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit event detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditLogsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Event not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/guests": { "get": { "tags": [ "Guest Access" ], "summary": "List guests for an organization", "operationId": "list_guests", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of guests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGuestsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Guest Access" ], "summary": "Invite a guest to an organization", "operationId": "invite_guest", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestRequest" } } }, "required": true }, "responses": { "201": { "description": "Guest invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAccessResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Guest already has access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/guests/{email}": { "delete": { "tags": [ "Guest Access" ], "summary": "Revoke guest access from an organization", "operationId": "revoke_guest", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "email", "in": "path", "description": "Guest email address", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Guest access revoked" }, "404": { "description": "Guest not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/holds": { "get": { "tags": [ "Legal Holds" ], "summary": "List all active legal holds for an organization", "operationId": "list_org_holds", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All active document holds for the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgLegalHoldsResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/policies/agents": { "get": { "tags": [ "Agent Policy" ], "summary": "Get agent policy for an organization", "operationId": "get_agent_policy", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current agent policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPolicyResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Agent Policy" ], "summary": "Update agent policy for an organization", "operationId": "update_agent_policy", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated agent policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPolicyResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/policies/retention": { "get": { "tags": [ "Retention Policy" ], "summary": "Get the retention policy for an organization", "operationId": "get_retention_policy", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current retention policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Retention Policy" ], "summary": "Update the retention policy for an organization", "operationId": "update_retention_policy", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated retention policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyResponse" } } } }, "400": { "description": "Invalid retention values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/policies/sharing": { "get": { "tags": [ "Sharing Policy" ], "summary": "Get sharing policy for an organization", "operationId": "get_sharing_policy", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current sharing policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharingPolicyResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Sharing Policy" ], "summary": "Update sharing policy for an organization", "operationId": "update_sharing_policy", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSharingPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated sharing policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharingPolicyResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/s3-export": { "get": { "tags": [ "S3 Export" ], "summary": "Get the current S3 audit export configuration", "operationId": "get_s3_export_config", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current S3 export configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/S3ExportConfigResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "No S3 export configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "S3 Export" ], "summary": "Create or update the S3 audit export configuration", "operationId": "create_or_update_s3_export", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateS3ExportConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "S3 export configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/S3ExportConfigResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "S3 Export" ], "summary": "Delete the S3 audit export configuration", "operationId": "delete_s3_export_config", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "S3 export configuration deleted" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/webhook": { "get": { "tags": [ "SIEM Webhook" ], "summary": "Get the current SIEM webhook configuration", "operationId": "get_webhook_config", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current webhook configuration (secret masked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "No webhook configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "SIEM Webhook" ], "summary": "Create or update the SIEM webhook configuration", "operationId": "create_or_update_webhook", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "SIEM Webhook" ], "summary": "Delete the SIEM webhook configuration", "operationId": "delete_webhook_config", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook configuration deleted" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/webhook/dlq": { "get": { "tags": [ "SIEM Webhook" ], "summary": "List dead-letter queue entries for a webhook", "operationId": "list_webhook_dlq", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum entries to return", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DLQ entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDlqListResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/webhook/dlq/replay": { "post": { "tags": [ "SIEM Webhook" ], "summary": "Replay all dead-letter queue entries", "operationId": "replay_webhook_dlq", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Replay results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDlqReplayResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "No webhook configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/webhook/status": { "get": { "tags": [ "SIEM Webhook" ], "summary": "Get 24-hour delivery statistics for the configured webhook", "operationId": "get_webhook_delivery_status", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery statistics for the past 24 hours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatus" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/orgs/{orgId}/webhook/test": { "post": { "tags": [ "SIEM Webhook" ], "summary": "Test the configured SIEM webhook endpoint", "operationId": "test_webhook", "parameters": [ { "name": "orgId", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test delivery result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "No webhook configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/profile": { "get": { "tags": [ "profile" ], "summary": "Get the authenticated user's profile", "operationId": "get_profile", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "profile" ], "summary": "Update the authenticated user's profile", "operationId": "update_profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/profiles/me": { "get": { "tags": [ "publishing-profile" ], "summary": "Get the authenticated user's publishing profile", "operationId": "get_publishing_profile", "responses": { "200": { "description": "Publishing profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishingProfileResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Publishing profile not yet created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "publishing-profile" ], "summary": "Update the authenticated user's publishing profile (bio, pinned items)", "operationId": "update_publishing_profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublishingProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishingProfileResponse" } } } }, "400": { "description": "Bio too long or pinned cap exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/profiles/me/handle": { "put": { "tags": [ "publishing-profile" ], "summary": "Change the authenticated user's handle (creates a 90-day redirect)", "operationId": "change_handle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeHandleRequest" } } }, "required": true }, "responses": { "200": { "description": "Handle changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeHandleResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Handle taken or in redirect window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Handle failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/profiles/me/visibility": { "put": { "tags": [ "publishing-profile" ], "summary": "Set the authenticated user's public-presence visibility.", "description": "Switching to `private` is a full retreat: the profile page is hidden and\nevery published document the caller owns is unpublished.", "operationId": "set_profile_visibility", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfileVisibilityRequest" } } }, "required": true }, "responses": { "200": { "description": "Visibility updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfileVisibilityResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Publishing profile not yet created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/prompts": { "get": { "tags": [ "prompts" ], "summary": "List every well-formed prompt the caller owns. Powers the slash\npicker, settings page, and MCP `prompts/list`", "operationId": "list_prompts", "responses": { "200": { "description": "Prompt list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPromptsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/prompts/settings": { "get": { "tags": [ "prompts" ], "summary": "Get the user's prompts master toggle and aggregate counts", "operationId": "get_prompts_settings", "responses": { "200": { "description": "Prompts settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptsSettingsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "prompts" ], "summary": "Toggle the prompts library on/off; lazy-provisions the folder when\nenabling for the first time", "operationId": "update_prompts_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePromptsSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptsSettingsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/prompts/{promptId}/render": { "post": { "tags": [ "prompts" ], "summary": "Render a prompt body against the caller-supplied argument map. The\nrendered body is what the slash picker auto-sends as the user's next\nchat message after argument collection", "operationId": "render_prompt", "parameters": [ { "name": "promptId", "in": "path", "description": "Prompt document ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderPromptRequest" } } }, "required": true }, "responses": { "200": { "description": "Rendered prompt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderedPrompt" } } } }, "400": { "description": "Invalid frontmatter or missing arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Caller is not the prompt owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Prompt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/public/by-token/{token}/clone": { "post": { "tags": [ "public-share" ], "summary": "Clone a public-share-token document into the authenticated requester's\npersonal workspace", "description": "JWT-required (the token gates WHAT, the JWT gates WHO). Lives in the\nJWT-only subtree (no company context — the requester might be a\nmember of an unrelated company at click time, but the clone always\ntargets their personal tenant via `UserProfile.tenant_id`, never\nthe active JWT tier or the source's tenant).", "operationId": "clone_public_share_token_document", "parameters": [ { "name": "token", "in": "path", "description": "Opaque public share token from the share URL", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Reserved for future options; callers may send `{}` or omit the body entirely.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicShareCloneRequest" } ] } } } }, "responses": { "201": { "description": "Clone succeeded; new document is ready to load", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShareCloneResponse" } } } }, "401": { "description": "Missing or invalid JWT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Token does not resolve, expired, or the source document was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal failure during clone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/public/by-token/{token}/docx": { "post": { "tags": [ "public-share" ], "summary": "Render and download the DOCX for a public-share-token document", "description": "Mirror of [`download_public_share_token_pdf_handler`]: token alone\nauthorizes the download; comments are deliberately stripped because\nthe public surface is the \"share with someone outside\" channel.", "operationId": "download_public_share_token_docx", "parameters": [ { "name": "token", "in": "path", "description": "Opaque public share token from the share URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DOCX bytes inline", "content": { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {} } }, "404": { "description": "Token does not resolve, expired, or the source document was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate-limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Render failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/public/by-token/{token}/pdf": { "post": { "tags": [ "public-share" ], "summary": "Render and download the PDF for a public-share-token document", "description": "Authorized by the share token alone — no JWT required. Anyone holding\na valid token can render the document as PDF (the read-content\nendpoint for the same token already exposes every byte of the doc,\nso PDF rendering adds zero new disclosure). The signup gate that\nfunnels visitors to this endpoint is a UX nudge, not a security\nboundary.", "operationId": "download_public_share_token_pdf", "parameters": [ { "name": "token", "in": "path", "description": "Opaque public share token from the share URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF bytes inline", "content": { "application/pdf": {} } }, "303": { "description": "Large PDF redirect to a single-use download URL" }, "404": { "description": "Token does not resolve, expired, or the source document was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "410": { "description": "Token explicitly revoked (reserved — currently unreachable; see research.md Decision 7)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate-limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Render failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "PDF renderer not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/public/documents/{documentId}/clone": { "post": { "tags": [ "public-share" ], "summary": "Clone a Published document by id into the authenticated requester's\npersonal workspace", "description": "JWT-required and gated on the doc being in `Published` state — same\nauth model as the SSR public-document page (`/d/{docId}` and\n`/@{handle}/{slug}`). Lives in the JWT-only subtree because the\nclone always targets the requester's personal tenant via\n`UserProfile.tenant_id`, never the active JWT tier.", "operationId": "clone_public_document_by_doc_id", "parameters": [ { "name": "documentId", "in": "path", "description": "ULID-format document id (`doc_…`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Reserved for future options; callers may send `{}` or omit the body entirely.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicShareCloneRequest" } ] } } } }, "responses": { "201": { "description": "Clone succeeded; new document is ready to load", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShareCloneResponse" } } } }, "401": { "description": "Missing or invalid JWT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document does not exist or is not Published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal failure during clone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/public/documents/{documentId}/docx": { "post": { "tags": [ "public" ], "summary": "Export a DOCX of a published document. Public surface — never\nincludes comments regardless of any client-supplied flag", "operationId": "export_public_document_docx", "parameters": [ { "name": "documentId", "in": "path", "description": "Document ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DOCX bytes inline", "content": { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {} } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found or not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate-limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Render failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/public/documents/{documentId}/pdf": { "post": { "tags": [ "public" ], "summary": "Export a PDF of a published document", "description": "JWT-only — anonymous viewers can read the public document page but\na download requires the gate (sign in or sign up). The route lives\nin the JWT-only subtree (no tenant context: callers may not be a\nmember of the doc's tenant). Drafts and unpublished documents\nreturn `404` with the same opaque error as a missing doc to prevent\nexistence-leakage.", "operationId": "export_public_document_pdf", "parameters": [ { "name": "documentId", "in": "path", "description": "Document ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF bytes inline", "content": { "application/pdf": {} } }, "303": { "description": "Large PDF redirect to a single-use download URL" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found or not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate-limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Render failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "PDF renderer not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/public/documents/{token}": { "get": { "tags": [ "public" ], "summary": "Get a public document by share token", "operationId": "get_public_document", "parameters": [ { "name": "token", "in": "path", "description": "Public share token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDocumentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/public/documents/{token}/content": { "get": { "tags": [ "public" ], "summary": "Get public document content by share token", "operationId": "get_public_document_content", "parameters": [ { "name": "token", "in": "path", "description": "Public share token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public document content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/signup/check-slug": { "get": { "tags": [ "Signup" ], "summary": "Check if a slug is available for use", "operationId": "check_slug", "parameters": [ { "name": "slug", "in": "query", "description": "Slug to check availability for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug availability result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlugCheckResponse" } } } }, "400": { "description": "Invalid slug format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/sources/search": { "get": { "tags": [ "Sources" ], "summary": "Search for sources (documents, spaces, folders, and connectors)", "operationId": "search_sources", "parameters": [ { "name": "q", "in": "query", "description": "Free-text query. When empty, returns contextual suggestions, favorites,\nand top accessible spaces.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum total results (default 15, capped at 50).", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "contextDocumentId", "in": "query", "description": "Current document ID for contextual suggestions.", "required": false, "schema": { "type": "string" } }, { "name": "contextSpaceId", "in": "query", "description": "Current space ID for contextual suggestions.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceSearchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces": { "get": { "tags": [ "Spaces" ], "summary": "List Spaces accessible to the authenticated user", "operationId": "list_spaces", "parameters": [ { "name": "scopeType", "in": "query", "description": "Filter by scope type (company, org, team, folder)", "required": false, "schema": { "type": "string" } }, { "name": "scopeId", "in": "query", "description": "Filter by scope ID", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum results (default 50)", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of accessible Spaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSpacesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Spaces" ], "summary": "Create a new Space", "operationId": "create_space", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpaceRequest" } } }, "required": true }, "responses": { "201": { "description": "Space created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/shared": { "get": { "tags": [ "Spaces" ], "summary": "List Spaces shared with the authenticated user", "operationId": "list_shared_spaces", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (default 50, max 200)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of shared Spaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSharedSpacesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}": { "get": { "tags": [ "Spaces" ], "summary": "Get a Space by ID", "operationId": "get_space", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Space details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Spaces" ], "summary": "Update a Space", "operationId": "update_space", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSpaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Space updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Spaces" ], "summary": "Delete a Space", "operationId": "delete_space", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Space deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/access-preview": { "get": { "tags": [ "Spaces" ], "summary": "Preview a user's document access within a Space", "operationId": "access_preview", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "query", "description": "Target user ID to preview access for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Access preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPreviewResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/documents": { "get": { "tags": [ "Spaces" ], "summary": "List documents in a Space", "operationId": "list_space_documents", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "folderId", "in": "query", "description": "When provided, return only documents in this folder (direct children, not recursive)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum results (default 50)", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "nextToken", "in": "query", "description": "Pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of Space documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSpaceDocumentsResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Spaces" ], "summary": "Add documents to a Space", "operationId": "add_space_documents", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSpaceDocumentsRequest" } } }, "required": true }, "responses": { "200": { "description": "Documents added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSpaceDocumentsResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/documents/import-from-connector": { "post": { "tags": [ "Spaces" ], "summary": "Import an external connector resource as a Space document", "operationId": "import_from_connector", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportFromConnectorRequest" } } }, "required": true }, "responses": { "200": { "description": "Import result (created, refreshed, or noChange)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportFromConnectorResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "No credentials, kill switch, or policy denial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Space or connector kind not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/documents/import-from-connector/browse": { "get": { "tags": [ "Spaces" ], "summary": "Browse importable resources for a connector kind within a Space", "operationId": "browse_connector_resources", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Connector kind slug (e.g. notion, slack)", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Optional search query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full list of browsable resources (no pagination)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResourcesResponse" } } } }, "403": { "description": "No credentials or forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Space or kind not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/documents/{docId}": { "delete": { "tags": [ "Spaces" ], "summary": "Remove a document from a Space", "operationId": "remove_space_document", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "docId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Document removed from Space" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/filters": { "get": { "tags": [ "Spaces" ], "summary": "List source filters for a Space", "operationId": "list_space_filters", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of source filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSpaceFiltersResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Spaces" ], "summary": "Create a source filter for a Space", "operationId": "create_space_filter", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpaceFilterRequest" } } }, "required": true }, "responses": { "201": { "description": "Filter created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceFilterResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/filters/{filterId}": { "put": { "tags": [ "Spaces" ], "summary": "Update a source filter", "operationId": "update_space_filter", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "filterId", "in": "path", "description": "Filter ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSpaceFilterRequest" } } }, "required": true }, "responses": { "200": { "description": "Filter updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceFilterResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Spaces" ], "summary": "Delete a source filter", "operationId": "delete_space_filter", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "filterId", "in": "path", "description": "Filter ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Filter deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/folders": { "get": { "tags": [ "Spaces" ], "summary": "List folders visible within a Space", "description": "When `parentFolderId` is omitted, returns top-level linked folders (filter roots).\nWhen provided, returns direct child subfolders of that parent.", "operationId": "list_space_folders", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "parentFolderId", "in": "query", "description": "When provided, return children of this folder. When omitted, return top-level linked folders.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of folders in Space", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSpaceFoldersResponse" } } } }, "400": { "description": "Parent folder not in Space scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Space or folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/grants": { "get": { "tags": [ "Spaces" ], "summary": "List access grants for a Space", "operationId": "list_space_grants", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSpaceGrantsResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Spaces" ], "summary": "Grant access to a Space", "operationId": "grant_space_access", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantSpaceAccessRequest" } } }, "required": true }, "responses": { "201": { "description": "Access granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceGrantResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/grants/{principalKey}": { "delete": { "tags": [ "Spaces" ], "summary": "Revoke a Space access grant", "operationId": "revoke_space_access", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "principalKey", "in": "path", "description": "Principal key (user:{id} or team:{id})", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Grant revoked" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/repo-sources": { "get": { "tags": [ "Repo Sources" ], "summary": "List repository sources for a Space", "operationId": "list_repo_sources", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRepoSourcesResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Repo Sources" ], "summary": "Create a repository source", "operationId": "create_repo_source", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRepoSourceRequest" } } }, "required": true }, "responses": { "201": { "description": "Source created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSourceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/repo-sources/{repoSourceId}": { "get": { "tags": [ "Repo Sources" ], "summary": "Get a repository source", "operationId": "get_repo_source", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "repoSourceId", "in": "path", "description": "Repo source ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSourceResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Repo Sources" ], "summary": "Delete a repository source", "operationId": "delete_repo_source", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "repoSourceId", "in": "path", "description": "Repo source ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Source deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Repo Sources" ], "summary": "Update a repository source", "operationId": "update_repo_source", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "repoSourceId", "in": "path", "description": "Repo source ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRepoSourceRequest" } } }, "required": true }, "responses": { "200": { "description": "Source updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSourceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/repo-sources/{repoSourceId}/pause": { "post": { "tags": [ "Repo Sources" ], "summary": "Pause a repository source", "operationId": "pause_repo_source", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "repoSourceId", "in": "path", "description": "Repo source ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSourceResponse" } } } }, "400": { "description": "Source not Active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/repo-sources/{repoSourceId}/resume": { "post": { "tags": [ "Repo Sources" ], "summary": "Resume a paused repository source", "operationId": "resume_repo_source", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "repoSourceId", "in": "path", "description": "Repo source ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSourceResponse" } } } }, "400": { "description": "Source not Paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/spaces/{spaceId}/search": { "get": { "tags": [ "Spaces" ], "summary": "Search within a Space using hybrid keyword + semantic search (in-app REST)", "operationId": "search_space", "parameters": [ { "name": "spaceId", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Search query (1-1000 characters)", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of chunks to return (default 10, max 50)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceSearchResponse" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Space not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tasks/{taskId}": { "get": { "tags": [ "Agents" ], "summary": "Get task status", "operationId": "get_task", "parameters": [ { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tasks/{taskId}/cancel": { "post": { "tags": [ "Agents" ], "summary": "Cancel a running agent task", "operationId": "cancel_task", "parameters": [ { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/telemetry/pdf-gate-redirect": { "post": { "tags": [ "telemetry" ], "summary": "Record one PDF-export gate redirect", "description": "`POST /api/v1/telemetry/pdf-gate-redirect` — webapp pings this when\nan unauthenticated visitor clicks **Download PDF** on a public\ndocument page, just before redirecting to `/login`. No\nauthentication required; per-IP rate limiting is inherited from the\npublic-route middleware.", "operationId": "record_pdf_gate_redirect", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfGateRedirectRequest" } } }, "required": true }, "responses": { "204": { "description": "Event recorded" } } } }, "/api/v1/tenant/resolve/{slug}": { "get": { "tags": [ "tenant" ], "summary": "Resolve a tenant by subdomain slug", "operationId": "resolve_tenant_by_slug", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug from the subdomain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResolveResponse" } } } }, "404": { "description": "No organization found for this slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/tiers": { "post": { "tags": [ "Tiers" ], "summary": "Create a new tier node", "operationId": "create_tier_node", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTierNodeRequest" } } }, "required": true }, "responses": { "201": { "description": "Tier node created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierNodeResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tiers/{nodeId}": { "get": { "tags": [ "Tiers" ], "summary": "Get a tier node by ID", "operationId": "get_tier_node", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tier node", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierNodeResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Tiers" ], "summary": "Delete a tier node", "operationId": "delete_tier_node", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tier node deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Tiers" ], "summary": "Update a tier node", "operationId": "update_tier_node", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTierNodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Tier node updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierNodeResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tiers/{nodeId}/children": { "get": { "tags": [ "Tiers" ], "summary": "List all children of a tier node", "operationId": "list_tier_children", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of child tier nodes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTierNodesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tiers/{nodeId}/members": { "get": { "tags": [ "Tiers" ], "summary": "List all members of a tier node", "operationId": "list_tier_members", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tier members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTierMembersResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Tiers" ], "summary": "Add a member to a tier node", "operationId": "add_tier_member", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTierMemberRequest" } } }, "required": true }, "responses": { "201": { "description": "Member added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierMembershipResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tiers/{nodeId}/members/{userId}": { "delete": { "tags": [ "Tiers" ], "summary": "Remove a member from a tier node", "operationId": "remove_tier_member", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Member removed" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tiers/{nodeId}/members/{userId}/role": { "put": { "tags": [ "Tiers" ], "summary": "Update a tier node member's role", "operationId": "update_tier_member_role", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "User ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTierMemberRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Member role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierMembershipResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/tiers/{nodeId}/tree": { "get": { "tags": [ "Tiers" ], "summary": "Get a tier node and its full subtree", "operationId": "get_tier_tree", "parameters": [ { "name": "nodeId", "in": "path", "description": "Tier node ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tier node with tree", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierNodeTreeResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/ai-usage": { "get": { "tags": [ "Billing" ], "summary": "Get the authenticated user's AI usage", "operationId": "get_my_ai_usage", "parameters": [ { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "My AI usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyAiUsageResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/ai-usage/daily": { "get": { "tags": [ "Billing" ], "summary": "Get the authenticated user's daily AI usage", "operationId": "get_my_ai_daily_usage", "parameters": [ { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "My daily AI usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiUserDailyUsageResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/ai-usage/events": { "get": { "tags": [ "Billing" ], "summary": "List the authenticated user's AI usage ledger events", "operationId": "list_my_ai_usage_events", "parameters": [ { "name": "cycleStart", "in": "query", "description": "Cycle start date (YYYY-MM-DD) or legacy month (YYYY-MM). Defaults to current billing cycle.", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by AI usage source", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 50, max 200)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextToken", "in": "query", "description": "Opaque pagination token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "My AI usage ledger events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiUsageEventsResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/memory/entries": { "get": { "tags": [ "memory" ], "summary": "List all active memory entries", "operationId": "list_memory_entries", "responses": { "200": { "description": "Memory entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMemoryEntriesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "memory" ], "summary": "Create a new memory entry (explicit user-initiated capture)", "operationId": "create_memory_entry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoryEntryRequest" } } }, "required": true }, "responses": { "200": { "description": "Created entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntry" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/memory/entries/{docId}": { "delete": { "tags": [ "memory" ], "summary": "Delete a memory entry (soft-delete via trash; index rebuilds)", "operationId": "delete_memory_entry", "parameters": [ { "name": "docId", "in": "path", "description": "Memory entry document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Not owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/memory/profile": { "get": { "tags": [ "memory" ], "summary": "Read `profile.md` content", "operationId": "get_memory_profile", "responses": { "200": { "description": "Profile content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProfileResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Memory not provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "memory" ], "summary": "Overwrite `profile.md` content. 422 when over cap", "operationId": "update_memory_profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryProfileResponse" } } } }, "400": { "description": "Content exceeds cap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Memory not provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/memory/settings": { "get": { "tags": [ "memory" ], "summary": "Get the user's memory settings + provisioning state", "operationId": "get_memory_settings", "responses": { "200": { "description": "Memory settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySettingsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "memory" ], "summary": "Toggle memory on/off; lazily provisions folder + Space when enabling", "operationId": "update_memory_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemorySettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySettingsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/notifications/mark-all-read": { "post": { "tags": [ "Notifications" ], "summary": "Mark all notifications as read", "operationId": "mark_all_notifications_read", "responses": { "204": { "description": "All notifications marked as read" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/notifications/unread-count": { "get": { "tags": [ "Notifications" ], "summary": "Get unread notification count", "operationId": "get_unread_notification_count", "responses": { "200": { "description": "Unread count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnreadCountResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/notifications/{notificationId}": { "delete": { "tags": [ "Notifications" ], "summary": "Dismiss a notification", "operationId": "dismiss_notification", "parameters": [ { "name": "notificationId", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Notification dismissed" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/onboarding/{wizardKey}/{version}": { "get": { "tags": [ "onboarding" ], "summary": "Get the user's state for an onboarding wizard", "operationId": "get_onboarding_state", "parameters": [ { "name": "wizardKey", "in": "path", "description": "Wizard identifier (e.g., `first-time-user`)", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "description": "Wizard version (`1` for the first-time-user wizard)", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Current onboarding state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingState" } } } }, "204": { "description": "No state recorded yet for this wizard" }, "400": { "description": "Unknown wizard or version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "onboarding" ], "summary": "Patch the user's onboarding state. Upserts; missing fields leave\nexisting state untouched", "operationId": "update_onboarding_state", "parameters": [ { "name": "wizardKey", "in": "path", "description": "Wizard identifier (e.g., `first-time-user`)", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "description": "Wizard version", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnboardingRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingState" } } } }, "400": { "description": "Unknown wizard or version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/preferences/favorites": { "get": { "tags": [ "preferences" ], "summary": "Get the user's favorite folder IDs", "operationId": "get_favorite_folders", "responses": { "200": { "description": "Favorite folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoritesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "preferences" ], "summary": "Replace the user's favorite folder IDs", "operationId": "update_favorite_folders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFavoritesRequest" } } }, "required": true }, "responses": { "200": { "description": "Favorites updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoritesResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/users/me/tier-memberships": { "get": { "tags": [ "Tiers" ], "summary": "List the authenticated user's tier node memberships across all hierarchy levels", "operationId": "list_user_tier_memberships", "responses": { "200": { "description": "User tier memberships", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserTierMembershipsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/waitlist": { "post": { "tags": [ "public" ], "summary": "Add an email to the waitlist (public, no auth)", "operationId": "waitlist_signup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistSignupRequest" } } }, "required": true }, "responses": { "200": { "description": "Added to waitlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistSignupResponse" } } } }, "400": { "description": "Invalid email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/workspaces/{slug}/sso-config": { "get": { "tags": [ "SSO" ], "summary": "Lookup SSO configuration by workspace slug (public, no auth)", "description": "Drives the SPA's login flow under `app.{base}/w/{slug}/...` — the SPA\nreads the slug from the URL path and asks whether to render password\nsign-in or redirect to a configured `IdP`.", "operationId": "lookup_workspace_sso_config", "parameters": [ { "name": "slug", "in": "path", "description": "Workspace slug from the URL path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSO config for workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSsoConfigResponse" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/ws-tickets": { "post": { "tags": [ "WebSocket" ], "summary": "Mint a short-lived document-scoped WebSocket ticket", "operationId": "create_web_socket_ticket", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebSocketTicketRequest" } } }, "required": true }, "responses": { "200": { "description": "WebSocket ticket minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebSocketTicketResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Ticket signing not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/health": { "get": { "tags": [ "health" ], "summary": "Health check handler - returns 200 with version info.", "operationId": "health", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v": { "post": { "tags": [ "marketing" ], "summary": "Record a marketing visit", "operationId": "record_marketing_visit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitEvent" } } }, "required": true }, "responses": { "200": { "description": "Attribution-tier visit recorded; body carries the visitor identifier so the client can submit it with the signup form", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitResponse" } } } }, "204": { "description": "Audience-tier visit recorded, or any error path (validation / storage failure). Set-Cookie refreshed regardless." } } } }, "/v/geo": { "get": { "tags": [ "marketing" ], "summary": "Geo lookup for banner targeting", "operationId": "marketing_geo", "responses": { "200": { "description": "Country code from the CDN, when known", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoResponse" } } } } } } } }, "components": { "schemas": { "AcceptCompanyInvitationRequest": { "type": "object", "description": "Request to accept a company invitation.", "required": [ "companyId" ], "properties": { "companyId": { "type": "string", "description": "Company ID from the invitation" } } }, "AccessEntryResponse": { "type": "object", "required": [ "userId", "email", "role", "grantedAt" ], "properties": { "email": { "type": "string" }, "grantedAt": { "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/ResourceRole" }, "userId": { "type": "string" } } }, "AccessPreviewResponse": { "type": "object", "description": "Response previewing a user's document access within a Space.", "required": [ "totalDocuments", "accessibleDocuments", "isScopeMember" ], "properties": { "accessibleDocuments": { "type": "integer", "format": "int32", "description": "Documents the target user can independently read.", "minimum": 0 }, "isScopeMember": { "type": "boolean", "description": "Whether the target user is a member of the Space's scope." }, "totalDocuments": { "type": "integer", "format": "int32", "description": "Total documents in the Space.", "minimum": 0 } } }, "AccessRequestEntry": { "type": "object", "description": "A single pending access request entry in the admin view.", "required": [ "requestedBy", "requestedAt" ], "properties": { "reason": { "type": [ "string", "null" ], "description": "Optional justification." }, "requestedAt": { "type": "string", "format": "date-time", "description": "When the request was created or last updated." }, "requestedBy": { "type": "string", "description": "User who submitted the request." } } }, "AccessResolution": { "type": "object", "description": "Result of evaluating all applicable grants for a user on a resource.\n\nMulti-source resolution that unions permissions from all contributing sources.", "required": [ "permissions", "effectiveRole", "sources", "adminOverride" ], "properties": { "adminOverride": { "type": "boolean", "description": "Whether org admin implicit access was used" }, "effectiveRole": { "$ref": "#/components/schemas/ResourceRole", "description": "Highest role that the permission set fully satisfies" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" }, "description": "Union of all permission atoms from all contributing sources", "uniqueItems": true }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AccessSource" }, "description": "All sources that contributed grants" } } }, "AccessSource": { "type": "string", "description": "Source of effective access (for audit/debugging)", "enum": [ "own", "directShare", "folderInheritance", "publicLink", "teamGrant", "scopeMembership", "adminOverride", "spaceMembership" ] }, "AccountDeletionBlocker": { "type": "object", "description": "Concrete blocker entry attached to an [`AccountDeletionSummaryResponse`].", "required": [ "kind", "messageKey" ], "properties": { "companyId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Optional company identifier (same as `workspace_id` today; kept\ndistinct to mirror the wire contract)." } ] }, "kind": { "$ref": "#/components/schemas/AccountDeletionBlockerKind", "description": "Discriminator for the blocker class." }, "messageKey": { "type": "string", "description": "Stable i18n key the client uses to translate a human-readable\nblocker description." }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Optional workspace identifier the blocker refers to." } ] } } }, "AccountDeletionBlockerKind": { "type": "string", "description": "Discriminator for [`AccountDeletionBlocker`].", "enum": [ "enterpriseMembership", "ownedWorkspace", "soloOwnedWorkspace", "pendingLifecycleOperation", "staleSummary" ] }, "AccountDeletionConfirmation": { "type": "string", "description": "Explicit confirmation token for account deletion. Single variant so a\nmissing or differing value fails validation rather than silently\nproceeding.", "enum": [ "deleteAccount" ] }, "AccountDeletionEligibility": { "type": "string", "description": "Overall self-service account-deletion eligibility.", "enum": [ "eligible", "blockedEnterpriseMembership", "blockedOwnedWorkspaces", "blockedPendingLifecycleOperation" ] }, "AccountDeletionSummaryResponse": { "type": "object", "description": "Result of evaluating self-service account deletion eligibility for the\nsigned-in user. Computed fresh on every request and identified by a\nstable `summaryVersion` so confirmation requests can detect a stale\nreview.", "required": [ "userId", "eligibility", "summaryVersion", "ownedWorkspaces", "membershipsToLeave", "cleanupTotals", "blockers" ], "properties": { "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/AccountDeletionBlocker" }, "description": "Typed blocker entries the UI can translate and present." }, "cleanupTotals": { "$ref": "#/components/schemas/DocumentCleanupCounts", "description": "Aggregate document counts across all workspaces the user is about\nto leave or have re-homed." }, "eligibility": { "$ref": "#/components/schemas/AccountDeletionEligibility", "description": "Overall eligibility — drives whether the destructive endpoint is\navailable at all." }, "enterpriseMemberships": { "type": "array", "items": { "$ref": "#/components/schemas/EnterpriseMembershipBlocker" }, "description": "Active Enterprise-plan memberships blocking deletion, if any." }, "membershipsToLeave": { "type": "array", "items": { "$ref": "#/components/schemas/AccountWorkspaceSummary" }, "description": "Free or Pro workspaces the user holds non-owner active membership\nin; deletion will leave these." }, "ownedWorkspaces": { "type": "array", "items": { "$ref": "#/components/schemas/AccountWorkspaceSummary" }, "description": "Free or Pro workspaces the user owns that require resolution\n(delete or transfer) before account deletion can complete." }, "summaryVersion": { "type": "string", "description": "Server-computed digest of the eligibility inputs. Required on the\ndestructive request body; a mismatch returns conflict and prompts\nthe caller to re-review the summary." }, "userId": { "$ref": "#/components/schemas/TypedId", "description": "Subject user identifier." } } }, "AccountWorkspaceSummary": { "type": "object", "description": "Per-workspace entry inside [`AccountDeletionSummaryResponse`].", "required": [ "workspaceId", "workspaceName", "plan", "ownerState", "resolution", "activeMemberCount", "cleanupPreview" ], "properties": { "activeMemberCount": { "type": "integer", "format": "int32", "description": "Active members in the workspace at evaluation time.", "minimum": 0 }, "cleanupPreview": { "$ref": "#/components/schemas/DocumentCleanupCounts", "description": "Document cleanup that would run for this workspace if the leave\nstep ran now." }, "ownerState": { "$ref": "#/components/schemas/WorkspaceOwnerState", "description": "The user's owner-state relative to this workspace." }, "plan": { "$ref": "#/components/schemas/BillingPlan", "description": "Billing plan of the workspace." }, "resolution": { "$ref": "#/components/schemas/WorkspaceResolution", "description": "What the user must do to clear this workspace before account\ndeletion can complete." }, "workspaceId": { "$ref": "#/components/schemas/TypedId", "description": "Workspace identifier (the root tier node / company identifier)." }, "workspaceName": { "type": "string", "description": "Display name of the workspace at evaluation time." } } }, "ActionTaxonomyResponse": { "type": "object", "description": "Summary of available action types for a catalog connector.", "required": [ "readCount", "writeCount", "searchCount" ], "properties": { "readCount": { "type": "integer", "format": "int32", "description": "Number of read-only actions.", "minimum": 0 }, "searchCount": { "type": "integer", "format": "int32", "description": "Number of search actions.", "minimum": 0 }, "writeCount": { "type": "integer", "format": "int32", "description": "Number of write (mutating) actions.", "minimum": 0 } } }, "ActivateRequest": { "type": "object", "description": "Request to complete activation (set password).", "required": [ "password", "confirmPassword" ], "properties": { "confirmPassword": { "type": "string", "description": "Password confirmation (must match `password`)" }, "password": { "type": "string", "description": "New password (must meet Cognito policy)" } } }, "ActivateResponse": { "type": "object", "description": "Response after successful activation.", "required": [ "companyId", "tenantId", "email", "message" ], "properties": { "companyId": { "type": "string", "description": "Company ID" }, "email": { "type": "string", "description": "Admin email" }, "message": { "type": "string", "description": "Confirmation message" }, "tenantId": { "type": "string", "description": "Organization (tenant) ID" } } }, "ActivationDetailResponse": { "type": "object", "description": "Public response showing activation token details.", "required": [ "email", "companyName", "billingPlan", "ssoConfigured" ], "properties": { "billingPlan": { "type": "string", "description": "Company billing plan" }, "companyName": { "type": "string", "description": "Company name" }, "email": { "type": "string", "description": "Admin email address" }, "ssoConfigured": { "type": "boolean", "description": "Whether SSO is configured for the company" } } }, "AddCompanyMemberRequest": { "type": "object", "description": "Request to add a member to a company.", "required": [ "userId", "role" ], "properties": { "role": { "$ref": "#/components/schemas/TierRole", "description": "Role to assign" }, "userId": { "type": "string", "description": "User ID to add" } } }, "AddFreeProviderRequest": { "type": "object", "description": "Request body for `POST /admin/free-providers`.", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "User-entered domain (any form); canonicalized server-side." }, "note": { "type": [ "string", "null" ], "description": "Optional free-form rationale." } } }, "AddSpaceDocumentResult": { "type": "object", "description": "Per-item result in a batch add-to-Space operation.", "required": [ "documentId", "status" ], "properties": { "documentId": { "type": "string", "description": "The document ID this result pertains to." }, "error": { "type": [ "string", "null" ], "description": "Error detail when `status` is `Failed`." }, "status": { "$ref": "#/components/schemas/AddSpaceDocumentStatus", "description": "Outcome for this document." } } }, "AddSpaceDocumentStatus": { "type": "string", "description": "Per-item status for a document in a batch add-to-Space operation.", "enum": [ "added", "alreadyExists", "notFound", "forbidden", "failed" ] }, "AddSpaceDocumentsRequest": { "type": "object", "description": "Request to add documents to a Space.", "required": [ "documentIds" ], "properties": { "documentIds": { "type": "array", "items": { "type": "string" }, "description": "Document IDs to add (1-100)." } } }, "AddSpaceDocumentsResponse": { "type": "object", "description": "Response after adding documents to a Space.", "required": [ "results", "totalAdded", "totalFailed" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/AddSpaceDocumentResult" }, "description": "Per-item results for each document ID in the request." }, "totalAdded": { "type": "integer", "description": "Number of documents successfully added or already present (idempotent successes).", "minimum": 0 }, "totalFailed": { "type": "integer", "description": "Number of documents that failed (`NotFound` or `Failed`).", "minimum": 0 } } }, "AddTierMemberRequest": { "type": "object", "description": "Request body for adding a member to a tier node.", "required": [ "userId", "role" ], "properties": { "role": { "$ref": "#/components/schemas/TierRole", "description": "Role to assign (must be valid for the tier's role template)." }, "userId": { "type": "string", "description": "User to add." } } }, "AdminDeleteUserResponse": { "type": "object", "description": "Unified cascade response. A single shape covers both the `200 OK`\nsuccess case and the `207 Multi-Status` partial-failure case; fields\nthat only apply to one of those outcomes are `Option`-wrapped and\nomitted from success bodies.\n\nThe binary handler reads [`Self::partial`] to decide whether to\nrespond with 200 or 207.", "required": [ "userId", "cognitoDeleted", "ddbCleanup" ], "properties": { "cognitoDeleted": { "type": "boolean", "description": "`true` when `Cognito` reported the user existed before the delete.\n`false` indicates `UserNotFoundException` was swallowed as success." }, "completedSteps": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CognitoCleanupStep" }, "description": "Present only on `207 Multi-Status` — steps that completed before the\nfailure (in order)." }, "ddbCleanup": { "$ref": "#/components/schemas/CognitoCleanupStats", "description": "Per-step cleanup counters." }, "failedStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CognitoCleanupStep", "description": "Present only on `207 Multi-Status` — the step that halted the cascade." } ] }, "message": { "type": [ "string", "null" ], "description": "Present only on `207 Multi-Status` — operator-facing replay hint." }, "userId": { "type": "string", "description": "Cognito sub / user ID whose cascade was attempted." } } }, "AdminPolicyState": { "type": "string", "description": "Policy state visible to the admin integrations panel.", "enum": [ "allowed", "allowedPendingApproval", "disallowed" ] }, "AgentFrontmatter": { "type": "object", "description": "The agent definition's leading YAML frontmatter, parsed and validated.\n\nAuthors edit this directly in the agent document; the server extracts\nit on every save and stores a derived [`AgentMetadata`] alongside the\ndocument row.", "required": [ "name", "description" ], "properties": { "autoInvokable": { "type": "boolean", "description": "When true, the orchestrating chat model may autonomously invoke\nthis agent via its `invoke_agent` tool catalog. When false\n(default), the agent is still invocable explicitly: `@agent-name`\nin chat, MCP `invoke_agent { agentName }`, or any direct caller\npath." }, "description": { "type": "string", "description": "Sentence describing when to use this agent. Surfaces in tool\ncatalogs and pickers, so be specific about the agent's job." }, "enabled": { "type": "boolean", "description": "Master enable. False keeps the document and its frontmatter\nintact but suppresses every invocation surface for this agent\n(`@mention`, MCP `invoke_agent`, orchestrator catalog)." }, "model": { "type": [ "string", "null" ], "description": "Optional model identifier override. Falls back to the platform\ndefault when omitted. Validated against the model registry at\nsave time.\n\nSkipped from serialization when `None` so the starter YAML\nstays minimal — the field still deserializes from a present\n`null` for backwards compatibility with existing rows." }, "name": { "type": "string", "description": "Kebab-case identifier, unique within the owner's agent library.\nBecomes the `@mention` label and the resolution key for MCP\n`invoke_agent { agentName }`. Must not collide with a platform\nagent name." }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted tool names this agent may invoke. Omit or pass an\nempty list to disable tool use entirely. Tool names are\nvalidated against the platform tool registry at save time." } } }, "AgentFrontmatterError": { "oneOf": [ { "type": "object", "description": "The leading YAML block was not present, was malformed, or the\nfields did not match the expected schema. `message` is the parser\nerror string, intended for display in the editor banner.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "The leading YAML block was not present, was malformed, or the\nfields did not match the expected schema. `message` is the parser\nerror string, intended for display in the editor banner.", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable description of what went wrong." } } }, "kind": { "type": "string", "enum": [ "invalidFrontmatter" ] } } }, { "type": "object", "description": "The `name` collides with a platform-vended built-in agent. The\neditor banner asks the author to rename so the platform agent\nkeeps the canonical surface.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "The `name` collides with a platform-vended built-in agent. The\neditor banner asks the author to rename so the platform agent\nkeeps the canonical surface.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name that was rejected." } } }, "kind": { "type": "string", "enum": [ "reservedName" ] } } }, { "type": "object", "description": "The `name` collides with another of the user's existing agents.\nBoth agents render the same `@mention` and the same\n`invoke_agent` resolution key — surfaced as a banner so the\nauthor can rename one of them.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "The `name` collides with another of the user's existing agents.\nBoth agents render the same `@mention` and the same\n`invoke_agent` resolution key — surfaced as a banner so the\nauthor can rename one of them.", "required": [ "name", "conflictId" ], "properties": { "conflictId": { "$ref": "#/components/schemas/TypedId", "description": "ID of the other agent document holding the same name." }, "name": { "type": "string", "description": "The colliding name." } } }, "kind": { "type": "string", "enum": [ "nameCollision" ] } } }, { "type": "object", "description": "One or more entries in `tools:` are not registered platform tool\nnames. Names are reported so the author can fix the typo.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "One or more entries in `tools:` are not registered platform tool\nnames. Names are reported so the author can fix the typo.", "required": [ "names" ], "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Tool names that were rejected." } } }, "kind": { "type": "string", "enum": [ "unknownTools" ] } } }, { "type": "object", "description": "The `model:` value did not resolve via the platform model\nregistry. The editor banner suggests known model identifiers.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "The `model:` value did not resolve via the platform model\nregistry. The editor banner suggests known model identifiers.", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "The model identifier that was rejected." } } }, "kind": { "type": "string", "enum": [ "unknownModel" ] } } } ], "description": "Reasons an agent document's frontmatter cannot be used as-is. Each\nvariant is reported alongside the agent in [`AgentMetadata`] so the\neditor can render a banner and the `@mention` / MCP / orchestrator\nsurfaces can drop the agent from their listings.\n\nAliased on the wire as `AgentFrontmatterError` to keep it distinct\nfrom the prompt-side `FrontmatterError` enum — both enums share\nthe bare Rust name within their module but expose different\nvariants, so the `OpenAPI` schema name has to disambiguate." }, "AgentInvokeFailReason": { "type": "string", "description": "Reason an agent invocation failed before a task could be created.", "enum": [ "quotaExceeded", "notFound", "unauthorized", "internalError" ] }, "AgentListItem": { "type": "object", "description": "One entry in the agent listing / settings list / `@mention` picker\nresponse — the agent's identity plus the cached metadata needed to\nrender its label without fetching the body.", "required": [ "id", "title", "metadata", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/TypedId", "description": "Document identifier of the underlying agent definition." }, "metadata": { "$ref": "#/components/schemas/AgentMetadata", "description": "Cached agent metadata. Always present; the listing endpoint\nfilters out documents whose `agent_metadata` is `None` (e.g.\ndocuments under a non-agent folder)." }, "title": { "type": "string", "description": "Document title (separate from frontmatter `name`; the user may\nrename the document independently of the agent's resolution\nname)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp, surfaced so the listing can sort\nrecently-edited agents to the top." } } }, "AgentMetadata": { "allOf": [ { "$ref": "#/components/schemas/AgentFrontmatter", "description": "Inlined canonical frontmatter. `#[serde(flatten)]` keeps the\nstored DDB JSON wire-flat so existing rows deserialize cleanly\n(same key set as before this refactor — no migration needed)." }, { "type": "object", "properties": { "frontmatterError": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentFrontmatterError", "description": "Set when the extractor refused to accept the frontmatter as-is —\neither because the YAML failed to parse, because the name\ncollided with a platform or another user agent, because a tool\nor model name did not resolve, or because the body was empty.\nCleared on the next clean save." } ] } } } ], "description": "Cached, derived metadata persisted alongside every agent document.\nPopulated by the server-side frontmatter extractor on save and read\nby every agent-aware surface (sidebar listing, `@mention` picker,\nMCP `invoke_agent`, orchestrator catalog, settings page) so the body\nnever has to be reparsed at request time.\n\nComposed of the canonical [`AgentFrontmatter`] (flattened, so the\nwire shape stays a flat camelCase JSON object) plus a derived\n`frontmatter_error` slot that captures extraction-time problems\n(collisions, malformed YAML, unknown tools, etc.). Adding a field\nto `AgentFrontmatter` automatically extends `AgentMetadata` —\ncallers reach into `metadata.frontmatter.` for canonical\nfields and `metadata.frontmatter_error` for the derived slot." }, "AgentPolicyResponse": { "type": "object", "description": "Agent policy API response.", "required": [ "maxAgentsPerUser", "allowedPermissions", "allowAgentOnExternalDocs", "emergencyStop", "restrictedFolders", "allowedAgentTypes", "rateLimitPerHour" ], "properties": { "allowAgentOnExternalDocs": { "type": "boolean", "description": "Whether agents can operate on documents shared from external organizations" }, "allowedAgentTypes": { "type": "array", "items": { "type": "string" }, "description": "Agent types allowed to run (empty = all types allowed)" }, "allowedPermissions": { "type": "array", "items": { "type": "string" }, "description": "Set of permissions that agents are allowed to use" }, "emergencyStop": { "type": "boolean", "description": "Emergency stop: if true, all agent executions are blocked org-wide" }, "maxAgentsPerUser": { "type": "integer", "format": "int32", "description": "Maximum number of agents each user can create", "minimum": 0 }, "rateLimitPerHour": { "type": "integer", "format": "int32", "description": "Max invocations per agent per hour (0 = unlimited)", "minimum": 0 }, "restrictedFolders": { "type": "array", "items": { "type": "string" }, "description": "Folder IDs that agents are not allowed to access" } } }, "AgentResponse": { "type": "object", "description": "Agent API response.", "required": [ "id", "name", "description", "agentType", "ownerId", "status", "enabledTools", "permissions", "scope", "defaultAutonomy", "createdAt", "updatedAt" ], "properties": { "agentType": { "$ref": "#/components/schemas/AgentType" }, "createdAt": { "type": "string" }, "defaultAutonomy": { "$ref": "#/components/schemas/AutonomyLevel" }, "description": { "type": "string" }, "enabledTools": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "status": { "$ref": "#/components/schemas/AgentStatus" }, "updatedAt": { "type": "string" } } }, "AgentSettingsResponse": { "type": "object", "description": "Response for the `GET /api/v1/companies/{companyId}/agent-settings` endpoint.", "required": [ "settings", "platformAgents", "models" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInfoEntry" }, "description": "All platform-supported models with credit multipliers." }, "platformAgents": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformAgentMeta" }, "description": "Catalog of all built-in platform agents." }, "settings": { "$ref": "#/components/schemas/CompanyAgentSettings", "description": "Current company agent settings." } } }, "AgentStatus": { "type": "string", "description": "Lifecycle status of an agent with permitted state transitions.", "enum": [ "pendingApproval", "active", "paused", "revoked" ] }, "AgentToolListItem": { "type": "object", "description": "One entry in the response of `GET /api/v1/agents/tools` — the tools an\nagent definition's `tools:` frontmatter array may grant.\n\nThe catalog is essentially static: the underlying tool registry is\ncompiled into the server binary and only changes when a new tool ships.\nClients should cache the response (a long `staleTime` on the React\nQuery hook is appropriate). The handler intentionally omits sandbox-\ninternal aliases (e.g. `edit_target_document`) so authors only see\nnames that are valid to declare.", "required": [ "name", "description", "requiredPermission" ], "properties": { "description": { "type": "string", "description": "Human-readable description of what the tool does. Surfaced to the\nLLM as the tool's schema description and to the document author\nin the agent banner's tool catalog." }, "name": { "type": "string", "description": "Tool name as it must appear in the agent frontmatter `tools:`\narray (e.g. `read_document`, `search_space`). Stable identifier;\nrenaming a tool is a breaking change to all existing agent docs." }, "requiredPermission": { "$ref": "#/components/schemas/Permission", "description": "Permission an agent's owner must hold for the tool to be usable\nat runtime. The frontmatter accepts the tool name regardless of\nthe owner's current permissions — the runtime gate is enforced\nat invocation time, not at save." } } }, "AgentType": { "type": "string", "description": "Classification of an agent.", "enum": [ "builtIn", "custom" ] }, "AgentsCreatorMode": { "type": "string", "description": "Mode controlling whether the orchestrating chat model may author\nagent definitions on behalf of the user.\n\nBoth authoring tools (`create_agent_definition` /\n`update_agent_definition`) require the user to attach an\nAgents-folder source to the current chat turn before they appear in\nthe model's tool catalog — this enum is the second gate the user can\nset on the settings page.", "enum": [ "both", "createOnly", "disabled" ] }, "AgentsSettingsResponse": { "type": "object", "description": "Response body for `GET /api/v1/agents/settings` and the body of\n`PATCH /api/v1/agents/settings` (re-used so the client can read the\nnew state back without an extra round-trip).", "required": [ "enabled", "totalAgentCount", "autoInvokableCount", "creatorMode" ], "properties": { "autoInvokableCount": { "type": "integer", "format": "int32", "description": "Number of agent documents with `autoInvokable: true` and a\nvalid frontmatter (i.e. visible to the orchestrator catalog).", "minimum": 0 }, "creatorMode": { "$ref": "#/components/schemas/AgentsCreatorMode", "description": "Mode controlling whether the orchestrating chat model may\ncreate new agent definitions, edit existing ones, both, or\nneither when the user attaches an Agents-folder source to the\nchat session." }, "enabled": { "type": "boolean", "description": "Master toggle. When false, the `@mention` picker, MCP\n`invoke_agent` resolution, the orchestrator's `invoke_agent`\ncatalog entries for user agents, and the agent-authoring chat\ntools are all suppressed for this user." }, "folderId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "ID of the auto-provisioned `Agents/` folder, when present.\n`None` only if provisioning has not yet completed (effectively\nalways populated for a logged-in user)." } ] }, "totalAgentCount": { "type": "integer", "format": "int32", "description": "Total number of agent documents owned by this user (including\ndrafts with frontmatter errors).", "minimum": 0 } } }, "AiDailyEntry": { "type": "object", "description": "A single day's AI usage with per-model breakdown.", "required": [ "date", "totalCredits", "models" ], "properties": { "date": { "type": "string", "description": "Date (`YYYY-MM-DD`)." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AiModelDailyUsage" }, "description": "Per-model breakdown." }, "totalCredits": { "type": "number", "format": "double", "description": "Total credits consumed across all models on this day (fractional)." } } }, "AiDailyUsageResponse": { "type": "object", "description": "Daily AI usage response with per-model credit breakdown.", "required": [ "cycleStart", "creditLimit", "totalCredits", "totalOperations", "utilization", "days" ], "properties": { "creditLimit": { "type": "number", "format": "double", "description": "Credit limit for the cycle (fractional credits)." }, "cycleEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive end of the cycle (`cycle_start + 1 month`, clamped at\nmonth-end overflow). `None` for legacy calendar-month bucket\nlookups that predate the cycle-anchor migration." }, "cycleStart": { "type": "string", "format": "date-time", "description": "Start of the billing cycle being reported (RFC3339). For legacy\ncalendar-month buckets this is the first instant of the month;\nfor anchored cycles it is the anchor's anniversary in the current\nperiod." }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/AiDailyEntry" }, "description": "Daily entries sorted by date ascending." }, "totalCredits": { "type": "number", "format": "double", "description": "Total credits consumed in the cycle (fractional; from the\nauthoritative aggregate row)." }, "totalOperations": { "type": "integer", "format": "int64", "description": "Total operations in the cycle.", "minimum": 0 }, "utilization": { "type": "number", "format": "double", "description": "Percentage of credit quota consumed (0.0 to 1.0+)." } } }, "AiModelDailyUsage": { "type": "object", "description": "Credits and operations for a single model on a single day.", "required": [ "model", "credits", "operations" ], "properties": { "credits": { "type": "number", "format": "double", "description": "Credits consumed by this model on this day (fractional)." }, "model": { "type": "string", "description": "Model identifier (e.g. `claude-sonnet-4-6`)." }, "operations": { "type": "integer", "format": "int64", "description": "Operations performed with this model on this day.", "minimum": 0 } } }, "AiUsageContext": { "oneOf": [ { "type": "object", "description": "Chat turn or title-generation context.", "required": [ "type" ], "properties": { "sessionId": { "type": [ "string", "null" ], "description": "Chat session identifier, when available." }, "type": { "type": "string", "enum": [ "chat" ] } } }, { "type": "object", "description": "Agent task execution context.", "required": [ "taskId", "agentId", "type" ], "properties": { "agentId": { "type": "string", "description": "Agent identifier." }, "documentId": { "type": [ "string", "null" ], "description": "Target document identifier, when the task was document-scoped." }, "taskId": { "type": "string", "description": "Agent task identifier." }, "type": { "type": "string", "enum": [ "agentTask" ] } } }, { "type": "object", "description": "Review-console draft or synthesis context.", "required": [ "documentId", "commentId", "type" ], "properties": { "commentId": { "type": "string", "description": "Comment identifier." }, "documentId": { "type": "string", "description": "Document identifier." }, "type": { "type": "string", "enum": [ "reviewConsole" ] } } }, { "type": "object", "description": "Embedding context.", "required": [ "documentId", "type" ], "properties": { "documentId": { "type": "string", "description": "Document identifier." }, "type": { "type": "string", "enum": [ "embedding" ] } } } ], "description": "Source-specific identifiers for an AI usage operation." }, "AiUsageEventResponse": { "type": "object", "description": "A single AI usage ledger event.", "required": [ "eventId", "source", "context", "model", "inputTokenCount", "cacheReadTokenCount", "cacheWriteTokenCount", "outputTokenCount", "creditCount", "cycleKey", "occurredAt" ], "properties": { "cacheReadTokenCount": { "type": "integer", "format": "int64", "description": "Cache-read tokens consumed.", "minimum": 0 }, "cacheWriteTokenCount": { "type": "integer", "format": "int64", "description": "Cache-write tokens consumed.", "minimum": 0 }, "context": { "$ref": "#/components/schemas/AiUsageContext", "description": "Source-specific identifiers." }, "creditCount": { "type": "number", "format": "double", "description": "Credits consumed, in user-facing fractional credits." }, "cycleKey": { "type": "string", "description": "Billing cycle key." }, "eventId": { "type": "string", "description": "Ledger event identifier." }, "inputTokenCount": { "type": "integer", "format": "int64", "description": "Input tokens consumed.", "minimum": 0 }, "model": { "type": "string", "description": "Provider model identifier." }, "occurredAt": { "type": "string", "format": "date-time", "description": "Operation timestamp." }, "outputTokenCount": { "type": "integer", "format": "int64", "description": "Output tokens consumed.", "minimum": 0 }, "source": { "$ref": "#/components/schemas/AiUsageSource", "description": "Product surface that consumed the usage." }, "userId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "User identifier when the source path had one." } ] } } }, "AiUsageHistoryEntry": { "type": "object", "description": "A single month's AI usage with computed utilization.", "required": [ "month", "usage", "creditLimit", "utilization" ], "properties": { "creditLimit": { "type": "number", "format": "double", "description": "Credit limit that applied (fractional credits)." }, "month": { "type": "string", "description": "The month (YYYY-MM)." }, "usage": { "$ref": "#/components/schemas/MonthlyAiUsage", "description": "Usage record for the month." }, "utilization": { "type": "number", "format": "double", "description": "Percentage of credit quota consumed (0.0 to 1.0+)." } } }, "AiUsageHistoryResponse": { "type": "object", "description": "AI usage history response for a company.", "required": [ "history", "creditLimit" ], "properties": { "creditLimit": { "type": "number", "format": "double", "description": "Current monthly credit limit for the company (fractional credits)." }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/AiUsageHistoryEntry" }, "description": "Monthly usage entries, most recent first." } } }, "AiUsageResponse": { "type": "object", "description": "AI usage response for a company.", "required": [ "usage", "creditLimit", "cycleStart", "utilization" ], "properties": { "creditLimit": { "type": "number", "format": "double", "description": "Credit limit for the cycle (fractional credits)." }, "cycleEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive end of the cycle (`cycle_start + 1 month`, clamped at\nmonth-end overflow). `None` for legacy calendar-month bucket\nlookups that predate the cycle-anchor migration." }, "cycleStart": { "type": "string", "format": "date-time", "description": "Start of the billing cycle being reported (RFC3339). For legacy\ncalendar-month buckets this is the first instant of the month;\nfor anchored cycles it is the anchor's anniversary in the current\nperiod." }, "usage": { "$ref": "#/components/schemas/MonthlyAiUsage", "description": "Usage record for the bucket identified by [`Self::cycle_start`]." }, "utilization": { "type": "number", "format": "double", "description": "Percentage of credit quota consumed (0.0 to 1.0+)." } } }, "AiUsageSource": { "type": "string", "description": "Product surface that consumed AI usage.", "enum": [ "chatTurn", "chatTitle", "agentTask", "reviewConsoleDraft", "reviewConsoleSynthesis", "embedding" ] }, "AiUsageUserSummary": { "type": "object", "description": "Per-user AI usage summary for a billing cycle.", "required": [ "usage" ], "properties": { "displayName": { "type": [ "string", "null" ], "description": "Display name when the user profile is still available." }, "email": { "type": [ "string", "null" ], "description": "Email address when the user profile is still available." }, "usage": { "$ref": "#/components/schemas/MonthlyAiUsage", "description": "Aggregated usage for this user in the requested cycle. Attribution\nonly — credits pool at the workspace level, so there is no per-member\ncap. Read the company-level usage view for the shared pool ceiling." }, "userId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "User identifier. `None` represents unattributed historical or\ntransitional usage." } ] } } }, "AiUserDailyUsageResponse": { "type": "object", "description": "Daily AI usage response for one user.", "required": [ "userId", "cycleStart", "totalCredits", "totalOperations", "days" ], "properties": { "cycleEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive end of the cycle when known." }, "cycleStart": { "type": "string", "format": "date-time", "description": "Start of the billing cycle being reported." }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/AiDailyEntry" }, "description": "Daily entries sorted by date ascending." }, "totalCredits": { "type": "number", "format": "double", "description": "Total credits consumed by the user in the cycle." }, "totalOperations": { "type": "integer", "format": "int64", "description": "Total operations performed by the user in the cycle.", "minimum": 0 }, "userId": { "$ref": "#/components/schemas/TypedId", "description": "User identifier." } } }, "AnonymousDocument": { "type": "object", "description": "Sample document metadata in an anonymous workspace.\n\nSchema is intentionally narrower than the authenticated `DocumentResponse`:\nanonymous documents have no sharing, no comments, no version metadata.", "required": [ "docId", "title", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "integer", "format": "int64", "description": "Epoch milliseconds when the document was created." }, "docId": { "type": "string", "description": "ULID-formatted document id (e.g. `doc_01J...`)." }, "title": { "type": "string", "description": "Document title; defaults to a product-curated welcome title." }, "updatedAt": { "type": "integer", "format": "int64", "description": "Epoch milliseconds of the last persisted edit." } } }, "AnonymousSessionResponse": { "type": "object", "description": "Bootstrap response for an anonymous workspace session.\n\nReturned by the session-init endpoint. Idempotent: a request that\nalready carries a valid session cookie receives the existing session.", "required": [ "sessionId", "sampleDocId", "expiresAt" ], "properties": { "expiresAt": { "type": "integer", "format": "int64", "description": "Epoch seconds when the session expires. Rolls forward on activity." }, "sampleDocId": { "type": "string", "description": "ULID of the workspace's single sample document." }, "sessionId": { "type": "string", "description": "Opaque session id, also present as the `st_anon_session` cookie value." } } }, "AnonymousWorkspaceResponse": { "type": "object", "description": "Full workspace bootstrap returned to an anonymous caller whose\nsession cookie resolved to a live workspace row.", "required": [ "sessionId", "document" ], "properties": { "document": { "$ref": "#/components/schemas/AnonymousDocument", "description": "The workspace's single sample document." }, "sessionId": { "type": "string", "description": "Opaque session id (same value as the cookie)." } } }, "ApiErrorBase": { "type": "object", "description": "Common fields present on every error response variant.", "required": [ "error", "code" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "HTTP status code mirrored in the body for clients that lose access to\nthe transport status (e.g. some streaming wrappers).", "minimum": 0 }, "error": { "type": "string", "description": "Human-readable summary." }, "requestId": { "type": [ "string", "null" ], "description": "Per-request identifier for correlating with server-side logs." }, "traceId": { "type": [ "string", "null" ], "description": "OTEL trace identifier, included in non-production environments." } } }, "ApiErrorResponse": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "400 — malformed or invalid request parameters.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "badRequest" ] } } } ], "description": "400 — malformed or invalid request parameters." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "401 — missing or invalid credentials.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "unauthorized" ] } } } ], "description": "401 — missing or invalid credentials." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "401 — refresh blocked because the configured maximum session\nduration elapsed since initial sign-in.\n\nDistinguished from `unauthorized` so the client can render an\nidle-timeout UX (countdown banner, \"your session timed out\"\ncopy) rather than the generic credential-failed sign-out.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "sessionTimeoutExpired" ] } } } ], "description": "401 — refresh blocked because the configured maximum session\nduration elapsed since initial sign-in.\n\nDistinguished from `unauthorized` so the client can render an\nidle-timeout UX (countdown banner, \"your session timed out\"\ncopy) rather than the generic credential-failed sign-out." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "403 — authenticated but insufficient permissions.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "forbidden" ] } } } ], "description": "403 — authenticated but insufficient permissions." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "403 — MFA enrollment required before this action.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "mfaSetupRequired" ] } } } ], "description": "403 — MFA enrollment required before this action." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "404 — requested resource does not exist.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "notFound" ] } } } ], "description": "404 — requested resource does not exist." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "409 — duplicate or conflicting resource.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "conflict" ] } } } ], "description": "409 — duplicate or conflicting resource." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "410 — resource existed but has been permanently removed.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "gone" ] } } } ], "description": "410 — resource existed but has been permanently removed." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "413 — request body exceeds the configured size limit.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "payloadTooLarge" ] } } } ], "description": "413 — request body exceeds the configured size limit." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "422 — syntactically valid but semantically rejected.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "unprocessableEntity" ] } } } ], "description": "422 — syntactically valid but semantically rejected." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "429 — generic rate limit exceeded.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "tooManyRequests" ] } } } ], "description": "429 — generic rate limit exceeded." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "503 — service temporarily unavailable.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "serviceUnavailable" ] } } } ], "description": "503 — service temporarily unavailable." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "description": "500 — unexpected internal error.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "internal" ] } } } ], "description": "500 — unexpected internal error." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "$ref": "#/components/schemas/PlanLimitDetails" }, { "type": "object", "description": "403 — resource creation blocked by billing plan limit.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "planLimitExceeded" ] } } } ], "description": "403 — resource creation blocked by billing plan limit." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "$ref": "#/components/schemas/FeatureGateErrorDetails" }, { "type": "object", "description": "403 — feature blocked by billing plan tier.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "featureGated" ] } } } ], "description": "403 — feature blocked by billing plan tier." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "$ref": "#/components/schemas/QuotaDetails" }, { "type": "object", "description": "429 — usage quota exceeded.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "quotaExceeded" ] } } } ], "description": "429 — usage quota exceeded." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "type": "object", "required": [ "inaccessibleSources" ], "properties": { "inaccessibleSources": { "type": "array", "items": { "$ref": "#/components/schemas/InaccessibleSource" }, "description": "Sources the user lacks read access to." } } }, { "type": "object", "description": "403 — one or more research sources are inaccessible.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "sourceAccessDenied" ] } } } ], "description": "403 — one or more research sources are inaccessible." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "$ref": "#/components/schemas/ConnectorDisabledByPolicyDetails" }, { "type": "object", "description": "403 — connector authorize denied by company policy.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "connectorDisabledByPolicy" ] } } } ], "description": "403 — connector authorize denied by company policy." }, { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBase" }, { "$ref": "#/components/schemas/ModelNotAllowedDetails" }, { "type": "object", "description": "403 — requested LLM model not permitted on the caller's billing plan.", "required": [ "errorType" ], "properties": { "errorType": { "type": "string", "enum": [ "modelNotAllowedForPlan" ] } } } ], "description": "403 — requested LLM model not permitted on the caller's billing plan." } ], "description": "Wire-side discriminated error envelope.\n\nThe `errorType` field is the discriminator. Per-variant payloads (e.g.\n`resource` / `current` / `limit` for `planLimitExceeded`) are flattened\nalongside `error`, `code`, and `requestId` so consumers can read common\nfields without switching on the discriminator first." }, "ArchiveSessionResponse": { "type": "object", "description": "Response for archiving a session.", "required": [ "archivedSessionId", "newSession" ], "properties": { "archivedSessionId": { "type": "string", "description": "ID of the archived session." }, "newSession": { "$ref": "#/components/schemas/SessionResponse", "description": "The new active session for the same scope+entity." } } }, "AssistantAction": { "oneOf": [ { "type": "object", "description": "Navigate the user to a URL.", "required": [ "url", "label", "type" ], "properties": { "label": { "type": "string", "description": "Human-readable label for the link." }, "type": { "type": "string", "enum": [ "navigate" ] }, "url": { "type": "string", "description": "Target URL (relative or absolute)." } } }, { "type": "object", "description": "Request confirmation for a batch operation.", "required": [ "description", "count", "operationId", "type" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Number of items affected.", "minimum": 0 }, "description": { "type": "string", "description": "Description of the operation to confirm." }, "operationId": { "type": "string", "description": "Opaque identifier for the pending operation." }, "type": { "type": "string", "enum": [ "batchConfirm" ] } } } ], "description": "An action the assistant instructs the frontend to perform." }, "AssistantContext": { "oneOf": [ { "type": "object", "description": "Document scope: document editor page.", "required": [ "documentId", "documentTitle", "sectionCount", "spaceIds", "scope" ], "properties": { "documentId": { "type": "string", "description": "The document being viewed." }, "documentTitle": { "type": "string", "description": "Document title." }, "scope": { "type": "string", "enum": [ "document" ] }, "sectionCount": { "type": "integer", "format": "int32", "description": "Number of sections in the document.", "minimum": 0 }, "spaceIds": { "type": "array", "items": { "type": "string" }, "description": "Spaces this document belongs to." } } }, { "type": "object", "description": "Space scope: space detail page.", "required": [ "spaceId", "spaceName", "documentCount", "scope" ], "properties": { "documentCount": { "type": "integer", "format": "int32", "description": "Number of documents in the space.", "minimum": 0 }, "scope": { "type": "string", "enum": [ "space" ] }, "spaceId": { "type": "string", "description": "The space being viewed." }, "spaceName": { "type": "string", "description": "Space name." } } } ], "description": "Page-specific context sent with each user message.\n\nThe `scope` field acts as the discriminator tag. The frontend constructs\nthis from the current route and page state, and the backend uses it for\nprompt assembly and tool filtering." }, "AssistantScope": { "type": "string", "description": "Which page context the assistant is operating in.", "enum": [ "home", "document", "space" ] }, "AssistantToolCallRecord": { "type": "object", "description": "Record of a tool invocation during an assistant response.\n\nNamed `AssistantToolCallRecord` in the `OpenAPI` spec to avoid a\nschema-name clash with [`crate::agent::ToolCallRecord`], which is a\nseparate, coarser-grained trace type emitted by the agent-runtime\nexecutor. The Rust type keeps the shorter `ToolCallRecord` name so\nexisting `use st_api_types::assistant::ToolCallRecord;` call sites don't\nneed to change.", "required": [ "toolName", "description", "status" ], "properties": { "arguments": { "description": "The `input` argument object the LLM passed to the tool. Captured so\nthe UI can surface arguments on reload (and on active turns) rather\nthan leaving the user guessing what the assistant asked for. Stored\nverbatim as `serde_json::Value` — safely truncated at the display\nlayer if excessive." }, "description": { "type": "string", "description": "Human-readable description of what the tool is doing." }, "durationMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Execution duration in milliseconds.", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error message (present when failed)." }, "resultCount": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of results found (for search tools) or 1 for read tools.", "minimum": 0 }, "resultSummary": { "type": [ "string", "null" ], "description": "One-line summary of the result (present when completed)." }, "sourceName": { "type": [ "string", "null" ], "description": "Source entity name (space name, document title, folder path) for\nstructured rendering in the `SourcesConsulted` widget. Avoids\nregex-parsing `result_summary` for display purposes." }, "status": { "$ref": "#/components/schemas/ToolCallStatus", "description": "Current execution status." }, "toolName": { "type": "string", "description": "Name of the tool that was invoked." }, "toolResultContent": { "type": [ "string", "null" ], "description": "Content returned to the LLM as the `tool_result` (for history\nreconstruction). Absent in records created before this field was added." }, "toolResultIsError": { "type": [ "boolean", "null" ], "description": "Whether the `tool_result` was an error (for history reconstruction).\nAbsent in records created before this field was added." }, "toolUseId": { "type": [ "string", "null" ], "description": "LLM `tool_use` block ID (for conversation history reconstruction).\nAbsent in records created before this field was added." } } }, "AttachmentContentResponse": { "type": "object", "description": "Live content fetched from the upstream connector for an attachment.", "required": [ "connectorKind", "resourceUri" ], "properties": { "connectorKind": { "type": "string", "description": "Connector kind that served this content." }, "externalUrl": { "type": [ "string", "null" ], "description": "Human-openable URL for the resource, if available." }, "mimeType": { "type": [ "string", "null" ], "description": "MIME type of the resource content." }, "resourceUri": { "type": "string", "description": "Canonical resource identifier." }, "text": { "type": [ "string", "null" ], "description": "Text content of the resource, if text-based." } } }, "AttachmentDisplaySnapshotRequest": { "type": "object", "description": "Display metadata for a resource attachment, provided by the client.", "required": [ "title" ], "properties": { "excerpt": { "type": [ "string", "null" ], "description": "Short excerpt or description." }, "icon": { "type": [ "string", "null" ], "description": "URL to a small icon." }, "title": { "type": "string", "description": "Human-readable title of the resource." } } }, "AttachmentResponse": { "type": "object", "description": "A persisted transient reference from a document or chat message to an external resource.", "required": [ "attachmentId", "connectorKind", "resourceUri", "displaySnapshot", "createdBy", "createdAt" ], "properties": { "attachmentId": { "type": "string", "description": "Unique identifier for this attachment." }, "connectorKind": { "type": "string", "description": "Connector kind that exposes this resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Wall-clock time this attachment was created." }, "createdBy": { "type": "string", "description": "User who created this attachment." }, "displaySnapshot": { "$ref": "#/components/schemas/DisplaySnapshotResponse", "description": "Rendered snapshot for display without a fresh upstream fetch." }, "externalUrl": { "type": [ "string", "null" ], "description": "Human-openable URL for the resource, if available." }, "resourceUri": { "type": "string", "description": "Canonical resource identifier within the connector kind." } } }, "AttributionMap": { "type": "object", "description": "Run-length encoded character-level attribution for a document.\n\nStored as an S3 sidecar (`attribution.json.zst`) alongside the Yjs\nbinary state. Each run maps a contiguous range of characters to the\nactor that last edited them.", "required": [ "version", "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/AttributionRun" }, "description": "Ordered runs covering the full document text." }, "version": { "type": "integer", "format": "int32", "description": "Schema version for forward compatibility.", "minimum": 0 } } }, "AttributionRun": { "type": "object", "description": "A contiguous range of characters attributed to a single actor.", "required": [ "length", "actorId", "actorType", "displayName", "editedAt" ], "properties": { "actorId": { "type": "string", "description": "User or agent ID that last edited these characters." }, "actorType": { "$ref": "#/components/schemas/EntityType", "description": "Whether the actor is a human user or AI agent." }, "displayName": { "type": "string", "description": "Display name at the time of the edit (e.g. \"Alice\" or \"@summarizer\")." }, "editedAt": { "type": "string", "format": "date-time", "description": "When this text was last modified." }, "length": { "type": "integer", "format": "int32", "description": "Number of UTF-16 code units in this run.\n\nUTF-16 code units match JavaScript `String.length` and `ProseMirror`\ntext positions — for BMP characters this equals the character count;\nsupplementary-plane characters (most emoji, CJK Extension B,\nmathematical symbols) occupy 2 code units each.", "minimum": 0 }, "onBehalfOf": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnBehalfOfActor", "description": "Secondary actor when the primary acted on behalf of someone\nelse (today: agent edits driven via MCP carry the human\ndelegator here). Distinct from `suggested_by`, which tracks\nsuggestion provenance. Clients should render the pair as\n`{displayName} ({onBehalfOf.email or .displayName})`." } ] }, "suggestedBy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestedBy", "description": "Optional secondary attribution for the origin of the content.\n\nSet when a human accepts an AI suggestion: the primary actor is the\naccepting user, and `suggested_by` records the agent that proposed\nthe change. `None` for direct edits." } ] }, "synthetic": { "type": "boolean", "description": "`true` when this run is a placeholder for content whose original\nauthorship could not be resolved. Clients SHOULD render synthetic\nruns differently (e.g. a neutral style and an \"attribution unavailable\"\ntooltip) rather than as a real edit by `actor_id`." } } }, "AuditExportCreateResponse": { "type": "object", "description": "Response body for a successful export creation request.", "required": [ "exportId", "status", "estimatedCompletionSecs", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the export was created (RFC 3339)" }, "estimatedCompletionSecs": { "type": "integer", "format": "int32", "description": "Estimated seconds until the export is ready", "minimum": 0 }, "exportId": { "type": "string", "description": "The new export ID" }, "status": { "$ref": "#/components/schemas/AuditExportStatus", "description": "Initial status (always `processing`)" } } }, "AuditExportFilters": { "type": "object", "description": "Optional filters to scope an audit export", "properties": { "action": { "type": [ "string", "null" ], "description": "Filter by action category or exact dot-notation action" }, "actor": { "type": [ "string", "null" ], "description": "Filter by raw actor ID (`usr_…`, `agent_…`, or `\"system\"`)" }, "outcome": { "type": [ "string", "null" ], "description": "Filter by outcome: `\"success\"`, `\"failure\"`, or `\"denied\"`" }, "resource": { "type": [ "string", "null" ], "description": "Filter by raw resource ID" } } }, "AuditExportFormat": { "type": "string", "description": "Output format for an audit log export", "enum": [ "csv", "json" ] }, "AuditExportRequest": { "type": "object", "description": "Request body for creating an audit log export.", "required": [ "format", "from", "to" ], "properties": { "filters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuditExportFilters", "description": "Optional filters to scope the export" } ] }, "format": { "$ref": "#/components/schemas/AuditExportFormat", "description": "Output format (`csv` or `json`)" }, "from": { "type": "string", "format": "date-time", "description": "Inclusive start of the time range (RFC 3339)" }, "to": { "type": "string", "format": "date-time", "description": "Inclusive end of the time range (RFC 3339)" } } }, "AuditExportStatus": { "type": "string", "description": "Processing status for an audit log export", "enum": [ "processing", "complete", "failed" ] }, "AuditExportStatusResponse": { "type": "object", "description": "Response body for an export status poll.", "required": [ "exportId", "status", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the export was requested (RFC 3339)" }, "downloadUrl": { "type": [ "string", "null" ], "description": "Presigned download URL (present when status is `complete`)" }, "errorMessage": { "type": [ "string", "null" ], "description": "Error message (present when status is `failed`)" }, "eventCount": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of events in the export (present when status is `complete`)", "minimum": 0 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the download URL expires (present when `downloadUrl` is set)" }, "exportId": { "type": "string", "description": "Export identifier" }, "fileSizeBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "File size in bytes (present when status is `complete`)", "minimum": 0 }, "progress": { "type": [ "integer", "null" ], "format": "int32", "description": "Processing progress (0–100)", "minimum": 0 }, "status": { "$ref": "#/components/schemas/AuditExportStatus", "description": "Current status" } } }, "AuthEstablishRequest": { "type": "object", "description": "Persist a refresh token the client has just received from the\nupstream identity provider into an `HttpOnly` cookie.\n\nUsed in the **hybrid** flow where the calling page handles sign-in\ndirectly with the upstream identity provider and ends up holding\ntokens in browser memory, then hands the long-lived refresh\ncredential off to this endpoint so it leaves the JavaScript-reachable\nsurface entirely. After the cookie is set, the calling page discards\nits in-memory refresh token; subsequent silent refreshes go through\n`/api/v1/auth/refresh`.", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string", "description": "Refresh token returned by the upstream identity provider after a\nsuccessful authentication. The server stores this verbatim in\nthe cookie without re-validating with the provider — the next\n`/refresh` call will validate at consumption time." } } }, "AuthExchangeRequest": { "type": "object", "description": "Exchange a fresh OAuth authorization code for an access token plus a\nlong-lived refresh credential.\n\nThe refresh credential is returned out-of-band as an `HttpOnly`,\n`Secure`, `SameSite=Strict` cookie scoped to the `/api/v1/auth` path —\nit is never visible to JavaScript on the calling page.", "required": [ "code", "codeVerifier", "redirectUri" ], "properties": { "code": { "type": "string", "description": "Authorization code returned by the identity provider on the OAuth\ncallback. Single-use." }, "codeVerifier": { "type": "string", "description": "PKCE verifier the calling page generated before redirecting to the\nauthorization endpoint. Must be the pre-image of the\n`code_challenge` originally sent." }, "redirectUri": { "type": "string", "description": "`redirect_uri` the calling page used in the authorization request.\nMust match exactly to satisfy the upstream identity provider's\nredirect-binding check." } } }, "AuthGranularity": { "type": "string", "description": "Whether a connector uses a single service-account credential or per-user OAuth.", "enum": [ "serviceAccount", "userDelegated" ] }, "AuthIdTokenClaims": { "type": "object", "description": "Subset of ID-token claims surfaced to the calling SPA.\n\nStrictly the fields the application UI needs to render its first paint —\nkeeps the response narrow and avoids leaking unintended claims.", "required": [ "sub", "email", "mfaSetupRequired", "isFederated" ], "properties": { "email": { "type": "string", "description": "User's primary email address." }, "isFederated": { "type": "boolean", "description": "`true` when the session was established via a federated (SSO)\nidentity provider rather than direct username/password sign-in." }, "mfaSetupRequired": { "type": "boolean", "description": "Whether the user must complete MFA enrollment before mutating\nactions are allowed." }, "sub": { "type": "string", "description": "User identifier (`sub` claim) — the same value the access token\ncarries." }, "tierId": { "type": "string", "description": "Active tier identifier when present in the token claims." } } }, "AuthSessionResponse": { "type": "object", "description": "Successful response from `/auth/exchange` and `/auth/refresh`.\n\nCarries a short-lived access token in JSON for the calling page to keep\nin JavaScript memory only. Expiration is expressed as seconds-from-now\n(matches the OAuth `expires_in` convention) so the page can compute its\nown refresh deadline without trusting clock skew.", "required": [ "accessToken", "expiresIn", "tokenType", "idTokenClaims", "sessionExpiresAt" ], "properties": { "accessToken": { "type": "string", "description": "Access token to attach as `Authorization: Bearer ` on\nsubsequent API calls. Live in JavaScript memory only — never\npersist to `localStorage` or `sessionStorage`." }, "expiresIn": { "type": "integer", "format": "int64", "description": "Seconds until the access token expires (inclusive of any safety\nmargin the server applies). The client should refresh strictly\nbefore this elapses.", "minimum": 0 }, "idToken": { "type": [ "string", "null" ], "description": "ID token JWT issued alongside the access token. Carries the same\nshort lifetime as `accessToken`; SPA SDKs that derive the user\nidentity from the ID token (Amplify, oidc-client, etc.) need the\nraw JWT, not just the decoded claim subset. Memory-only — never\npersist to browser storage." }, "idTokenClaims": { "$ref": "#/components/schemas/AuthIdTokenClaims", "description": "Decoded ID-token claims (subject, email, MFA enrollment state, etc.)\nthe page needs at first paint without making a separate `/me` call.\nOnly the subset of claims the calling SPA is expected to consume is\nsurfaced." }, "sessionExpiresAt": { "type": "integer", "format": "int64", "description": "Absolute Unix timestamp (seconds since epoch) at which the session\nhits its configured maximum duration ceiling. Computed from the\ninitial sign-in time plus the company's `maxSessionTimeoutSecs`,\npreserved across refreshes — independent of `expiresIn`, which\nonly describes access-token rotation.\n\nThe page should treat this as a hard sign-out deadline: render a\ncountdown / warning banner as it approaches, and stop attempting\nto refresh once it elapses (the server will reject with a\n`sessionTimeoutExpired` error past this point). Safe to persist\nin non-sensitive client storage as long as it is cleared on sign-out." }, "tokenType": { "type": "string", "description": "Token type string, always `\"Bearer\"`. Included for OAuth-style\nSDK compatibility." } } }, "AuthorizeGrantResponse": { "type": "object", "description": "Response containing the OAuth redirect URL for user-delegated authorization.", "required": [ "redirectUrl" ], "properties": { "redirectUrl": { "type": "string", "description": "URL to redirect the user to for OAuth authorization." } } }, "AutoResolvedInfo": { "type": "object", "description": "Info about suggestions auto-resolved during an accept/reject.", "required": [ "suggestionId", "agentName", "markCount" ], "properties": { "agentName": { "type": "string", "description": "Display name of the agent that created the auto-resolved group." }, "markCount": { "type": "integer", "format": "int32", "description": "Number of marks removed from the auto-resolved group.", "minimum": 0 }, "suggestionId": { "type": "string", "description": "Suggestion group ID that was auto-resolved." } } }, "AutonomyLevel": { "type": "string", "description": "Level of autonomous operation for an agent.", "enum": [ "fullAutonomy", "suggestMode", "approvalRequired" ] }, "BatchInviteRequest": { "type": "object", "description": "Request to send batch invitations to a company.\n\nAccepts up to 50 email addresses in a single request. Each email is\nprocessed independently — partial success is possible.", "required": [ "emails", "companyRole", "orgId" ], "properties": { "companyRole": { "$ref": "#/components/schemas/TierRole", "description": "Company-level role to assign when invitations are accepted" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses to invite (1–50)" }, "orgId": { "type": "string", "description": "Organization to add users to on acceptance" }, "orgRole": { "$ref": "#/components/schemas/TierRole", "description": "Organization-level role to assign on acceptance" } } }, "BatchInviteResponse": { "type": "object", "description": "Response for a batch invitation request.", "required": [ "results", "totalSent", "totalFailed" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/InviteResult" }, "description": "Per-email results" }, "totalFailed": { "type": "integer", "description": "Number of invitations that were not sent (any non-`Sent` status)", "minimum": 0 }, "totalSent": { "type": "integer", "description": "Number of invitations successfully sent", "minimum": 0 } } }, "BillingInterval": { "type": "string", "description": "How often the subscription bills.\n\n`None` on [`BillingInfo`] means no Stripe subscription exists yet (free\ntenants) or the value has not been observed since the field was\nintroduced — the next webhook fires the first populate.", "enum": [ "monthly", "annual" ] }, "BillingPlan": { "type": "string", "description": "Billing plan for a workspace", "enum": [ "free", "pro", "enterprise" ] }, "BillingPlansResponse": { "type": "object", "description": "Response shape of `GET /api/v1/billing/plans`.\n\nReturns one entry per `BillingPlan` variant in canonical order\n(`free`, `pro`, `enterprise`). Each entry carries every fact the\nstorefront and admin UI need — limits, gated features, allowed\nmodels, and live per-cadence prices.", "required": [ "plans" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanDescriptor" }, "description": "Plan descriptors in canonical order." } } }, "BillingSubscriptionResponse": { "type": "object", "description": "Full subscription response for the billing overview.", "required": [ "plan", "status", "usage", "limits" ], "properties": { "billingInterval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingInterval", "description": "Billing cadence on the active Stripe subscription. Drives the\n\"Billed monthly\" / \"Billed annually\" copy on the billing overview." } ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "End of current billing period." }, "limits": { "$ref": "#/components/schemas/PlanLimits", "description": "Plan limit definitions." }, "monthlyCostCents": { "type": [ "integer", "null" ], "format": "int64", "description": "Monthly cost in USD cents (seat count × price per seat).", "minimum": 0 }, "paymentMethod": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMethodSummary", "description": "Payment method on file (Team plan only)." } ] }, "plan": { "$ref": "#/components/schemas/BillingPlan", "description": "Current billing plan tier." }, "status": { "$ref": "#/components/schemas/BillingSubscriptionStatus", "description": "Subscription lifecycle status." }, "usage": { "$ref": "#/components/schemas/UsageMetrics", "description": "Usage metrics against plan limits." } } }, "BillingSubscriptionStatus": { "type": "string", "description": "Subscription lifecycle status reflecting Stripe subscription state.", "enum": [ "none", "active", "pastDue", "canceling", "canceled" ] }, "BlockChange": { "oneOf": [ { "type": "object", "description": "Block exists only in the newer version.", "required": [ "text", "changeType" ], "properties": { "changeType": { "type": "string", "enum": [ "added" ] }, "children": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BlockDiffEntry" }, "description": "Per-child breakdown for container nodes (lists, tables)." }, "text": { "type": "string", "description": "Plaintext content of the added block." } } }, { "type": "object", "description": "Block exists only in the older version.", "required": [ "text", "changeType" ], "properties": { "changeType": { "type": "string", "enum": [ "removed" ] }, "children": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BlockDiffEntry" }, "description": "Per-child breakdown for container nodes (lists, tables)." }, "text": { "type": "string", "description": "Plaintext content of the removed block." } } }, { "type": "object", "description": "Leaf node text changed — carries word-level diff chunks.", "required": [ "beforeText", "afterText", "chunks", "changeType" ], "properties": { "afterText": { "type": "string", "description": "Text content after the change." }, "attrsChanged": { "type": [ "object", "null" ], "description": "Attribute changes alongside the text change (e.g. `taskItem` checked toggle).", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "beforeText": { "type": "string", "description": "Text content before the change." }, "changeType": { "type": "string", "enum": [ "modified" ] }, "chunks": { "type": "array", "items": { "$ref": "#/components/schemas/DiffChunk" }, "description": "Word-level diff chunks." } } }, { "type": "object", "description": "Container node (list or table) with per-child sub-diffs.", "required": [ "children", "changeType" ], "properties": { "changeType": { "type": "string", "enum": [ "modifiedChildren" ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDiffEntry" }, "description": "Per-child diffs (list items, table rows, or table cells)." } } }, { "type": "object", "description": "Attribute-only change with no text change (e.g. task checked toggle).", "required": [ "text", "attrsChanged", "changeType" ], "properties": { "attrsChanged": { "type": "object", "description": "Map of attribute name → `[before_value, after_value]`.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "changeType": { "type": "string", "enum": [ "modifiedAttrs" ] }, "text": { "type": "string", "description": "Plaintext content (unchanged)." } } }, { "type": "object", "description": "Block moved to a different position within its parent container.", "required": [ "text", "movedFrom", "movedTo", "changeType" ], "properties": { "changeType": { "type": "string", "enum": [ "moved" ] }, "movedFrom": { "type": "integer", "format": "int32", "description": "Original position index (0-based).", "minimum": 0 }, "movedTo": { "type": "integer", "format": "int32", "description": "New position index (0-based).", "minimum": 0 }, "text": { "type": "string", "description": "Plaintext content (unchanged)." } } } ], "description": "How a block changed between two history points.\n\nEach variant carries exactly its required data — no optional fields that\nbelong to other variants. Serialized with `changeType` as the tag field." }, "BlockDiffEntry": { "allOf": [ { "$ref": "#/components/schemas/BlockChange", "description": "What changed — tagged enum flattened into this object." }, { "type": "object", "required": [ "blockId", "blockType" ], "properties": { "beforeBlockType": { "type": [ "string", "null" ], "description": "Previous node type, present when the block type changed." }, "blockId": { "type": "string", "description": "Block ID (positional, e.g. `node_0`)." }, "blockType": { "type": "string", "description": "`ProseMirror` node type (e.g. \"heading\", \"paragraph\", \"listItem\")." } } } ], "description": "A single block diff entry: block identity + the change that occurred.\n\nUses `#[serde(flatten)]` on `change` so the wire format is a single flat\nJSON object with `blockId`, `blockType`, and the `changeType`-tagged fields." }, "BlockResponse": { "type": "object", "required": [ "blockId", "blockType", "content", "version" ], "properties": { "blockId": { "type": "string" }, "blockType": { "type": "string" }, "comments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CommentResponse" } }, "content": { "type": "string" }, "items": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BlockResponse" } }, "level": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "version": { "type": "integer", "format": "int64", "description": "Current version of this block. `0` for blocks with no version history.", "minimum": 0 } } }, "BoolFlag": { "type": "object", "description": "Bool-shaped flag carrying the `enabled` bit and the optional\n`_variant` tag attached by per-user targeting rules.", "properties": { "_variant": { "type": [ "string", "null" ], "description": "Variant name assigned by rule evaluation (only present for\ntargeted evaluations with user context)." }, "enabled": { "type": "boolean", "description": "Whether the flag is enabled for this evaluation." } } }, "BranchInfo": { "type": "object", "description": "A single branch available to the caller.", "required": [ "nodeId", "name", "tierId", "role", "switchRequiresMfa" ], "properties": { "name": { "type": "string", "description": "Display name of the branch." }, "nodeId": { "type": "string", "description": "Depth-0 tier node identifier." }, "role": { "type": "string", "description": "Caller's role within this branch." }, "switchRequiresMfa": { "type": "boolean", "description": "Whether switching into this branch requires an MFA challenge." }, "tierId": { "type": "string", "description": "Tier this branch belongs to (e.g., \"org\", \"region\")." } } }, "BrowseResourcesResponse": { "type": "object", "description": "Response body for the browse endpoint.\n\nToday the endpoint always returns the complete set of resources in a\nsingle response — the underlying `RemoteConnector::list_resources` trait\ndoes not support cursor-based pagination, so exposing a cursor here\nwould be dishonest (feature 075 Principle VIII forbids stub fields).\nWhen the trait gains cursor support, re-add a `next_cursor` field and\nre-introduce an infinite-query on the client.", "required": [ "resources" ], "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BrowsedResource" }, "description": "The resource list. Always complete — no pagination today." } } }, "BrowsedResource": { "type": "object", "description": "A single browsable resource returned from a connector.", "required": [ "resourceUri", "title" ], "properties": { "externalUrl": { "type": [ "string", "null" ], "description": "Human-openable URL in the source app." }, "icon": { "type": [ "string", "null" ], "description": "Icon URL or asset key." }, "mimeType": { "type": [ "string", "null" ], "description": "MIME type of the resource content." }, "modifiedAt": { "type": [ "string", "null" ], "description": "RFC 3339 last-modified timestamp from the source." }, "resourceUri": { "type": "string", "description": "Canonical resource identifier within the connector kind." }, "subtitle": { "type": [ "string", "null" ], "description": "Optional subtitle (e.g. workspace name, channel name)." }, "title": { "type": "string", "description": "Display title." } } }, "BulkDocumentAction": { "type": "string", "description": "Lifecycle action for bulk document operations.", "enum": [ "trash", "restore", "archive" ] }, "BulkDocumentActionRequest": { "type": "object", "description": "Request to perform a lifecycle action on multiple documents at once.", "required": [ "action", "documentIds" ], "properties": { "action": { "$ref": "#/components/schemas/BulkDocumentAction", "description": "The lifecycle action to perform" }, "documentIds": { "type": "array", "items": { "type": "string" }, "description": "Document IDs to act upon" } } }, "BulkDocumentActionResponse": { "type": "object", "description": "Response for a bulk document lifecycle action.", "required": [ "results", "totalSucceeded", "totalFailed" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkDocumentActionResult" }, "description": "Per-document results" }, "totalFailed": { "type": "integer", "description": "Number of documents where the action failed.", "minimum": 0 }, "totalSucceeded": { "type": "integer", "description": "Number of documents where the action succeeded.", "minimum": 0 } } }, "BulkDocumentActionResult": { "type": "object", "description": "Per-document result of a bulk lifecycle action.", "required": [ "documentId", "status" ], "properties": { "documentId": { "type": "string", "description": "The document ID this result pertains to" }, "error": { "type": [ "string", "null" ], "description": "Error message if the action failed" }, "status": { "$ref": "#/components/schemas/BulkDocumentActionStatus", "description": "Outcome of the action for this document" } } }, "BulkDocumentActionStatus": { "type": "string", "description": "Status of a single document in a bulk lifecycle action.", "enum": [ "succeeded", "notFound", "forbidden", "failed" ] }, "BulkSuggestionActionResponse": { "type": "object", "description": "Response after accepting or rejecting all suggestions.", "required": [ "documentId", "count", "documentVersion" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Number of suggestions processed.", "minimum": 0 }, "documentId": { "type": "string", "description": "Document identifier." }, "documentVersion": { "type": "integer", "format": "int64", "description": "Updated document version after the action.", "minimum": 0 }, "language": { "type": [ "string", "null" ], "description": "BCP 47 language tag applied to the document (only on accept with\nlanguage-bearing suggestions)." } } }, "ByoOauthAppDetail": { "type": "object", "description": "Summary of the BYO (bring-your-own) `OAuth` app override for a connector.", "required": [ "clientId" ], "properties": { "clientId": { "type": "string", "description": "`OAuth` client identifier registered at the provider." }, "redirectUri": { "type": [ "string", "null" ], "description": "Redirect URI registered with the provider." } } }, "CardResolution": { "type": "string", "description": "How a card transitioned to the Resolved state.\n\n`Posted` — author posted a reply on the shared thread; `MarkAddressed` —\nauthor cleared the card without posting; `ReviewerResolved` — the\nshared comment was resolved by the reviewer (read at session hydrate\nfrom the comments table, surfaced via this event so open tabs reflect\nthe change in real time).", "enum": [ "posted", "markAddressed", "reviewerResolved" ] }, "CatalogResponse": { "type": "object", "description": "Full connector catalog response.", "required": [ "connectors" ], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorCatalogEntry" }, "description": "Available connector definitions." } } }, "ChangeBillingIntervalRequest": { "type": "object", "description": "Request to swap an active subscription's billing cadence.\n\nTriggers Stripe's price-swap-with-proration on the existing\nsubscription rather than creating a new checkout session — used when\na subscriber switches between monthly and annual without changing\nplan tier.", "required": [ "idempotencyKey", "billingInterval" ], "properties": { "billingInterval": { "$ref": "#/components/schemas/BillingInterval", "description": "New cadence to switch to." }, "idempotencyKey": { "type": "string", "description": "Idempotency key to prevent duplicate Stripe writes." } } }, "ChangeHandleRequest": { "type": "object", "description": "Request to change the caller's handle.", "required": [ "handle" ], "properties": { "handle": { "type": "string", "description": "The new handle to claim. Must pass `Handle::parse` validation." } } }, "ChangeHandleResponse": { "type": "object", "description": "Response from a handle change.", "required": [ "handle", "previousHandle", "redirectExpiresAt" ], "properties": { "handle": { "type": "string", "description": "The new handle." }, "previousHandle": { "type": "string", "description": "The previous handle." }, "redirectExpiresAt": { "type": "string", "description": "When the redirect from old handle expires." } } }, "ChatHealthResponse": { "type": "object", "description": "Response for AI service health check.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "Whether the AI service is available." }, "reason": { "type": [ "string", "null" ], "description": "Reason for unavailability (present when `available` is false)." } } }, "ChatMessageRole": { "type": "string", "description": "Role of a message in a chat session.", "enum": [ "user", "assistant" ] }, "ChatSseEvent": { "oneOf": [ { "type": "object", "description": "Emitted immediately when the stream opens, before the first LLM token.\nLets the frontend show a typing/thinking indicator.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "processing" ] } } }, { "type": "object", "description": "Incremental thinking/reasoning content (extended thinking models).\nRendered as collapsible, hidden-by-default content in the frontend.", "required": [ "delta", "type" ], "properties": { "delta": { "type": "string", "description": "The thinking text fragment." }, "type": { "type": "string", "enum": [ "thinkingDelta" ] } } }, { "type": "object", "description": "Incremental text content from the LLM (forwarded token-by-token).", "required": [ "delta", "type" ], "properties": { "delta": { "type": "string", "description": "The text fragment." }, "type": { "type": "string", "enum": [ "textDelta" ] } } }, { "type": "object", "description": "A tool call has started executing.", "required": [ "toolCallId", "toolName", "description", "arguments", "type" ], "properties": { "arguments": { "description": "Raw argument object the LLM passed to the tool. Small JSON; the\nfrontend renders this in the tool-call card's expanded view so\nusers can see what the assistant asked for without waiting for\nthe result." }, "description": { "type": "string", "description": "Human-readable description." }, "toolCallId": { "type": "string", "description": "The LLM's unique tool-use block ID." }, "toolName": { "type": "string", "description": "Tool name." }, "type": { "type": "string", "enum": [ "toolCallStart" ] } } }, { "type": "object", "description": "Batch of tools requiring user approval before execution.\n\nRead-only tools are auto-executed; only tools with `requires_approval`\nappear here. The frontend renders a batch approval card.", "required": [ "tools", "type" ], "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApprovalItem" }, "description": "Tools awaiting approval." }, "type": { "type": "string", "enum": [ "toolApprovalBatch" ] } } }, { "type": "object", "description": "A tool call has completed (or was rejected).", "required": [ "toolCallId", "toolName", "status", "type" ], "properties": { "durationMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration in milliseconds.", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error message if failed or rejected." }, "resultSummary": { "type": [ "string", "null" ], "description": "One-line summary of the result." }, "status": { "$ref": "#/components/schemas/ToolCallStatus", "description": "Execution status." }, "toolCallId": { "type": "string", "description": "The LLM's unique tool-use block ID." }, "toolName": { "type": "string", "description": "Tool name." }, "type": { "type": "string", "enum": [ "toolCallResult" ] } } }, { "type": "object", "description": "A document was mutated (suggestions created by a tool).", "required": [ "documentId", "suggestionId", "batchId", "suggestionsCreated", "type" ], "properties": { "batchId": { "type": "string", "description": "Batch ID grouping all suggestions from this turn." }, "documentId": { "type": "string", "description": "Mutated document ID." }, "suggestionId": { "type": "string", "description": "Unique suggestion ID for this edit." }, "suggestionsCreated": { "type": "integer", "format": "int32", "description": "Number of suggestions created.", "minimum": 0 }, "type": { "type": "string", "enum": [ "documentMutated" ] } } }, { "type": "object", "description": "Agent delegation progress update.", "required": [ "agentName", "taskId", "elapsedMs", "message", "type" ], "properties": { "agentName": { "type": "string", "description": "Agent display name." }, "elapsedMs": { "type": "integer", "format": "int64", "description": "Elapsed time in milliseconds.", "minimum": 0 }, "message": { "type": "string", "description": "Progress message." }, "taskId": { "type": "string", "description": "Agent task ID." }, "type": { "type": "string", "enum": [ "agentProgress" ] } } }, { "type": "object", "description": "Frontend action directive (navigate, confirm, etc.).", "required": [ "action", "type" ], "properties": { "action": { "$ref": "#/components/schemas/AssistantAction", "description": "The action to perform." }, "type": { "type": "string", "enum": [ "action" ] } } }, { "type": "object", "description": "Error during streaming.", "required": [ "message", "retryable", "type" ], "properties": { "message": { "type": "string", "description": "Human-readable error message." }, "retryable": { "type": "boolean", "description": "Whether the client should retry." }, "type": { "type": "string", "enum": [ "error" ] } } }, { "type": "object", "description": "Stream is complete.", "required": [ "messageSequence", "cancelled", "type" ], "properties": { "cancelled": { "type": "boolean", "description": "Whether the stream was cancelled (Stop button or approval timeout)." }, "messageSequence": { "type": "integer", "format": "int32", "description": "Sequence number of the assistant message that was created.", "minimum": 0 }, "type": { "type": "string", "enum": [ "done" ] }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatUsage", "description": "Token + credit usage for this assistant turn, plus remaining\nmonthly budget. `None` if no LLM was invoked or usage tracking\nwas unavailable." } ] } } } ], "description": "Server-Sent Event payload for the chat streaming endpoint.\n\nEach variant is serialized as JSON in the SSE `data:` field with a `type`\ndiscriminant (e.g. `{\"type\":\"textDelta\",\"delta\":\"Hello\"}`)." }, "ChatUsage": { "type": "object", "description": "Token and credit usage for a single chat turn.\n\nSent back to the client in the final `Done` SSE event so the chat panel\ncan display \"this reply cost N credits\" inline. `remaining_credits` is\nthe company-wide monthly budget left after this turn (a point-read of\n`ai_usage` immediately after `record_chat_usage` increments it).", "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "creditsConsumed", "model" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "description": "Cache-read tokens consumed by this turn.", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "description": "Cache-write tokens consumed by this turn.", "minimum": 0 }, "creditsConsumed": { "type": "number", "format": "double", "description": "Credits consumed by this turn (fractional). Computed from\n`tokens_to_credits` (internally millicredits) and divided by\n`MILLICREDITS_PER_CREDIT` at serialization." }, "effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Effort", "description": "Effort level the request ran at, when the model supports the\n`effort` parameter. `None` for models that do not accept effort\n(Haiku, Llama, GPT-OSS)." } ] }, "inputTokens": { "type": "integer", "format": "int64", "description": "Input tokens consumed by this turn.", "minimum": 0 }, "model": { "$ref": "#/components/schemas/Model", "description": "Model that produced the response." }, "outputTokens": { "type": "integer", "format": "int64", "description": "Output tokens generated by this turn.", "minimum": 0 }, "remainingCredits": { "type": [ "number", "null" ], "format": "double", "description": "Credits remaining in the company's monthly budget after this turn\n(fractional). `None` if the budget read failed (frontend should fall\nback to the `/billing/ai-usage` endpoint)." } } }, "CheckStalenessResponse": { "type": "object", "description": "Response body for `POST /api/v1/documents/{docId}/check-staleness`.", "required": [ "docId", "sourceStatus", "checkedAt" ], "properties": { "checkedAt": { "type": "string", "description": "RFC 3339 timestamp at which the check was performed." }, "docId": { "type": "string", "description": "The document that was checked." }, "sourceStatus": { "$ref": "#/components/schemas/StalenessStatus", "description": "Overall staleness classification." }, "unavailableReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StalenessUnavailableReason", "description": "Present only when `source_status = unavailable`." } ] } } }, "CheckoutSessionResponse": { "type": "object", "description": "Response containing the checkout session URL.", "required": [ "checkoutUrl" ], "properties": { "checkoutUrl": { "type": "string", "description": "URL to redirect the user to for Stripe Checkout." } } }, "CognitoCleanupStats": { "type": "object", "description": "Per-step counters emitted in the success response body and audit record.", "required": [ "userRecordsDeleted", "membershipsDeleted", "oauthTokensDeleted", "personalCompanyDeleted", "documentsPrivateDeleted", "documentsSharedRetained" ], "properties": { "documentsPrivateDeleted": { "type": "integer", "format": "int32", "description": "Count of private documents whose metadata + S3 content were deleted.", "minimum": 0 }, "documentsSharedRetained": { "type": "integer", "format": "int32", "description": "Count of shared documents whose ownership was re-homed to the Company.", "minimum": 0 }, "membershipsDeleted": { "type": "integer", "format": "int32", "description": "Count of per-tenant membership/user profile rows deleted.", "minimum": 0 }, "oauthTokensDeleted": { "type": "integer", "format": "int32", "description": "Count of OAuth client records deleted.", "minimum": 0 }, "personalCompanyDeleted": { "type": "boolean", "description": "`true` when a Personal Company was removed (user was sole member)." }, "userRecordsDeleted": { "type": "integer", "format": "int32", "description": "Count of top-level `USER#{user_id}` rows deleted from the main table\n(usually `0` or `1`).", "minimum": 0 } } }, "CognitoCleanupStep": { "type": "string", "description": "Ordered cascade steps. Declared as an enum so match arms in telemetry /\naudit emission are exhaustive — adding a new step is a compile error at\nevery call site.", "enum": [ "cognito", "userRecord", "memberships", "oauthTokens", "personalCompany", "contentDisposition" ] }, "CollaboratorInfo": { "type": "object", "description": "Read-only projection of a connection record for presence display.\n\nReturned in the `joinedDocument` response to show who is currently\non the document.", "required": [ "entityId", "entityType", "displayName", "color" ], "properties": { "color": { "type": "string", "description": "Deterministic presence color. HSL format." }, "displayName": { "type": "string", "description": "Name for UI display" }, "entityId": { "type": "string", "description": "User or agent ID" }, "entityType": { "$ref": "#/components/schemas/EntityType", "description": "Human or agent" } } }, "CommentAnchorResponse": { "type": "object", "description": "Anchor for a comment to a specific text range in the document (response).\n\nContains Yjs relative positions for precise anchoring and fallback data\nfor re-anchoring when positions become invalid.", "required": [ "startRelative", "endRelative" ], "properties": { "endRelative": { "$ref": "#/components/schemas/YjsRelativePosition", "description": "Yjs relative position for range end." }, "headingContext": { "type": "array", "items": { "type": "string" }, "description": "Heading breadcrumbs at creation time for coarse fallback localization." }, "prefixContext": { "type": [ "string", "null" ], "description": "~50 chars before the anchor for improved fuzzy re-anchoring." }, "quotedText": { "type": [ "string", "null" ], "description": "Quoted text at anchor creation time for fallback re-anchoring." }, "startRelative": { "$ref": "#/components/schemas/YjsRelativePosition", "description": "Yjs relative position for range start." }, "suffixContext": { "type": [ "string", "null" ], "description": "~50 chars after the anchor for improved fuzzy re-anchoring." } } }, "CommentChangeType": { "type": "string", "description": "Type of comment change, used in `CommentChanged` notifications.", "enum": [ "created", "updated", "deleted" ] }, "CommentClassification": { "type": "object", "description": "Canonical, per-document classification of a single comment.\n\nWritten once per `(commentId, sourceVersion)` pair by the synthesis\npipeline. Read by every author of the document — there is no per-author\nview of canonical classifications. Per-author severity overrides live\nseparately on [`ReviewConsoleMeta::severity_overrides`] and are layered\nover the canonical value at render time.\n\n`sourceVersion` is the version of the source comment this classification\nwas derived from. It guards the underlying conditional write and lets\nthe frontend suppress out-of-order updates (drop any incoming event with\n`sourceVersion` strictly less than the observed value for that comment).", "required": [ "commentId", "severity", "sourceVersion", "computedAt" ], "properties": { "commentId": { "$ref": "#/components/schemas/TypedId", "description": "The classified comment." }, "computedAt": { "type": "string", "format": "date-time", "description": "Wall-clock when the classification was written. Display-only." }, "severity": { "$ref": "#/components/schemas/Severity", "description": "Output of the severity classifier; defaults to `Major` when the\nclassifier fails or returns unparseable output." }, "sourceVersion": { "type": "integer", "format": "int64", "description": "Version of the source comment this classification was derived from.", "minimum": 0 }, "themeId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Theme assignment; `None` means \"untagged\" — theme labeling failed\nfor a new-theme candidate. Untagged cards are excluded from theme\nfacets but otherwise fully usable in the inbox." } ] } } }, "CommentResponse": { "type": "object", "required": [ "id", "authorId", "authorEmail", "authorDisplayName", "body", "status", "isRead", "createdAt", "updatedAt" ], "properties": { "anchor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommentAnchorResponse", "description": "Text-range anchor (Yjs relative positions + fallback)." } ] }, "authorDisplayName": { "type": "string" }, "authorEmail": { "type": "string" }, "authorId": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean" }, "failedAgents": { "type": "array", "items": { "$ref": "#/components/schemas/FailedAgentInfo" } }, "id": { "type": "string" }, "isRead": { "type": "boolean" }, "parentCommentId": { "type": [ "string", "null" ] }, "reactions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this thread was resolved." }, "resolvedBy": { "type": [ "string", "null" ], "description": "User who resolved this thread." }, "status": { "$ref": "#/components/schemas/CommentStatus", "description": "Thread status (active, resolved, deleted)." }, "thread": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CommentResponse" } }, "triggeredAgents": { "type": "array", "items": { "$ref": "#/components/schemas/TriggeredAgentInfo" } }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CommentStatus": { "type": "string", "description": "Status of a comment thread.", "enum": [ "active", "resolved", "deleted" ] }, "CompanyAgentSettings": { "type": "object", "description": "Company-level AI agent configuration.\n\nControls which platform agents are available, which models may be used,\nand optional system prompt affixes. Company-wide fields act as the\nceiling/fallback; per-agent overrides in `agent_overrides` can narrow\nmodel access or replace prompts for individual agents.", "required": [ "enabledPlatformAgents", "allowedModels" ], "properties": { "agentOverrides": { "type": "object", "description": "Per-agent overrides keyed by platform agent name.\nAbsent entry = agent uses all company-wide defaults.", "additionalProperties": { "$ref": "#/components/schemas/PlatformAgentOverride" }, "propertyNames": { "type": "string" } }, "allowedModels": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "LLM models that agents are allowed to use (empty = none allowed).\nActs as the ceiling — per-agent overrides must be subsets.", "uniqueItems": true }, "enabledPlatformAgents": { "type": "array", "items": { "type": "string" }, "description": "Platform agent names that are enabled (empty = none enabled).\nWhen all agents are enabled this contains every name from the registry.", "uniqueItems": true }, "systemPromptPrefix": { "type": [ "string", "null" ], "description": "Default text prepended to every agent system prompt." }, "systemPromptSuffix": { "type": [ "string", "null" ], "description": "Default text appended to every agent system prompt." } } }, "CompanyAiSettingsResponse": { "type": "object", "description": "Models the chat assistant may select from, plus the company's default.\n\nDerived from `company.agent_settings.allowed_models` intersected with\n`effective_plan().allowed_models()`. The frontend reads this to render\nthe chat panel's model selector and gray out plan-restricted options.", "required": [ "allowedModels", "defaultModel" ], "properties": { "allowedModels": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "Models the assistant agent may use, given the company settings ∩ plan." }, "defaultModel": { "$ref": "#/components/schemas/Model", "description": "Default model when the client does not specify one." } } }, "CompanyConnectorPolicy": { "type": "object", "description": "The company's connector policy row. Serialized as camelCase for API\nwire consumption; stored on `DynamoDB` with named attributes listed\nin the module docs.", "required": [ "companyId", "disableAll", "defaultGovernance", "overrides", "killedKinds", "updatedAt", "updatedBy" ], "properties": { "companyId": { "$ref": "#/components/schemas/TypedId", "description": "Company that owns this policy row." }, "defaultGovernance": { "$ref": "#/components/schemas/ConnectorGovernance", "description": "Governance applied to any kind that doesn't have an explicit\noverride entry. Set at company-provisioning time based on the\nplan tier (`Personal`/`Team` → `Approved`, `Enterprise` →\n`NotApproved`)." }, "disableAll": { "type": "boolean", "description": "Global kill switch — when `true`, every connector is denied at\nthe resolver regardless of governance state." }, "killedKinds": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorKind" }, "description": "Per-kind kill switches. Each entry overrides both `disable_all` and\n`overrides` for that specific kind — if the kind is in this set, the\nresolver returns `Denied(KillSwitchEngaged)` regardless of governance.\nThis allows admins to kill a single kind without affecting others.", "uniqueItems": true }, "overrides": { "type": "object", "description": "Per-kind explicit overrides. Every entry wins over\n`default_governance` for its kind.", "additionalProperties": { "$ref": "#/components/schemas/ConnectorGovernance" }, "propertyNames": { "type": "string", "description": "An open identifier for a connector type (e.g. `\"slack\"`, `\"mcp\"`, `\"gmail\"`).\n\nValidated on construction: 2-64 chars, `[a-z0-9-:]` only. This is intentionally\n**not** a closed enum — the set of connector kinds grows without framework changes.\nThe closed dispatch dimension is [`ConnectorMode`]." } }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the row was last mutated." }, "updatedBy": { "$ref": "#/components/schemas/TypedId", "description": "Admin user who last mutated the row." } } }, "CompanyDetailResponse": { "type": "object", "description": "Detailed company response (for single-resource views).", "required": [ "id", "name", "slug", "billingPlan", "onboardingComplete", "memberCount", "orgCount", "settings", "aiSettings", "createdAt", "updatedAt", "userTierNodeId", "userRole", "permissions" ], "properties": { "aiSettings": { "$ref": "#/components/schemas/CompanyAiSettingsResponse", "description": "AI model selection settings derived from company settings ∩ plan.\nUsed by the chat panel to render its model selector." }, "billingPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "Billing plan for all child organizations" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the company was created" }, "id": { "type": "string", "description": "Company identifier" }, "memberCount": { "type": "integer", "format": "int32", "description": "Number of company members", "minimum": 0 }, "name": { "type": "string", "description": "Company name" }, "onboardingComplete": { "type": "boolean", "description": "Whether the first-admin onboarding wizard has been completed" }, "orgCount": { "type": "integer", "format": "int32", "description": "Number of child organizations", "minimum": 0 }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" }, "description": "Pre-computed permission set for the requesting user.", "uniqueItems": true }, "settings": { "$ref": "#/components/schemas/CompanySettings", "description": "Governance ceiling settings" }, "slug": { "type": "string", "description": "URL-safe slug" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the company was last updated" }, "upgradeFinalized": { "type": [ "boolean", "null" ], "description": "Whether the post-checkout team-upgrade interstitial has been\ncompleted. See `CompanyResponse.upgradeFinalized` for semantics." }, "userRole": { "$ref": "#/components/schemas/TierRole", "description": "The requesting user's role on this company." }, "userTierNodeId": { "type": "string", "description": "The requesting user's primary tier-node ULID for this company." } } }, "CompanyInvitationPreviewResponse": { "type": "object", "description": "Public preview of a company invitation, decoded from the signed token.\n\nReturned by the unauthenticated preview endpoint so the invitee can see\nwhat they're about to accept (which company, which role) before signing in.", "required": [ "companyId", "companyName", "companySlug", "billingPlan", "email", "role", "expiresAt" ], "properties": { "billingPlan": { "type": "string", "description": "Billing plan tier (drives subdomain routing on acceptance)." }, "companyId": { "type": "string", "description": "Company ID the invitation grants membership in." }, "companyName": { "type": "string", "description": "Human-readable company name." }, "companySlug": { "type": "string", "description": "URL slug for the company (used to route to the vanity subdomain)." }, "email": { "type": "string", "description": "Email the invitation was issued to. The accepter's signed-in email\nmust match this exactly for the accept call to succeed." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the invitation expires." }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Role that will be assigned on acceptance." } } }, "CompanyInvitationResponse": { "type": "object", "description": "Company invitation API response.", "required": [ "email", "role", "invitedBy", "invitedAt", "expiresAt" ], "properties": { "email": { "type": "string", "description": "Invitee's email" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the invitation expires" }, "invitationToken": { "type": [ "string", "null" ], "description": "HMAC-signed invitation token for tokenized invitation links.\nPresent on creation, absent when listing existing invitations." }, "invitedAt": { "type": "string", "format": "date-time", "description": "When the invitation was created" }, "invitedBy": { "type": "string", "description": "Who sent the invitation" }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Role that will be assigned on acceptance" } } }, "CompanyMemberResponse": { "type": "object", "description": "Company member API response.", "required": [ "userId", "email", "displayName", "role", "joinedAt", "scimProvisioned", "idpManaged" ], "properties": { "displayName": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "description": "User's email" }, "idpManaged": { "type": "boolean", "description": "Whether this membership is managed via `IdP` group mapping" }, "joinedAt": { "type": "string", "format": "date-time", "description": "When the user joined the company" }, "provenance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MembershipProvenance", "description": "How the membership was created. Absent on memberships created by\ninvite, manual add, or SCIM provisioning. Present only on\nmemberships materialized by the domain-claim backfill, so the\nadmin members UI can render a \"Joined via domain claim\" badge." } ] }, "provenanceClaimId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Identifier of the domain-claim attempt that produced this\nmembership. Present iff `provenance` is set." } ] }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Role within the company" }, "scimProvisioned": { "type": "boolean", "description": "Whether this membership was provisioned via SCIM" }, "userId": { "type": "string", "description": "User identifier" } } }, "CompanyResponse": { "type": "object", "description": "Summary company response (for listings).", "required": [ "id", "name", "slug", "billingPlan", "onboardingComplete", "memberCount", "orgCount", "createdAt", "userTierNodeId", "userRole", "permissions" ], "properties": { "billingPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "Billing plan for all child organizations" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the company was created" }, "id": { "type": "string", "description": "Company identifier" }, "memberCount": { "type": "integer", "format": "int32", "description": "Number of company members", "minimum": 0 }, "name": { "type": "string", "description": "Company name" }, "onboardingComplete": { "type": "boolean", "description": "Whether the first-admin onboarding wizard has been completed" }, "orgCount": { "type": "integer", "format": "int32", "description": "Number of child organizations", "minimum": 0 }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" }, "description": "Pre-computed permission set for the requesting user on this company\n(`user_role.permissions()`). Frontend `usePermissions` reads this\ndirectly — no client-side role→permission translation.", "uniqueItems": true }, "slug": { "type": "string", "description": "URL-safe slug" }, "upgradeFinalized": { "type": [ "boolean", "null" ], "description": "Whether the post-checkout team-upgrade interstitial has been\ncompleted. Absent on records that pre-date the field and on\nPersonal-plan companies that never went through the\ninterstitial. Owners reading their own company use this to\ndecide whether to gate the rest of the workspace until the\nfinalize step is submitted." }, "userRole": { "$ref": "#/components/schemas/TierRole", "description": "The requesting user's role on this company (capability source of truth)." }, "userTierNodeId": { "type": "string", "description": "The requesting user's primary tier-node ULID for this company —\nwhat should be passed as `orgId` in URL paths. For single-tier\ncompanies (personal/team) this is the only org tier; for enterprise\nit's the user's primary org membership." } } }, "CompanySettings": { "type": "object", "description": "Company-level governance settings that act as ceiling values for child `Organization` settings.\n\n`#[serde(default)]` on the struct (combined with the `Default` impl below)\nkeeps existing records readable when new fields land — missing fields\nfall back to sensible per-field defaults instead of failing the whole\ndeserialize and discarding all the tenant's saved settings.", "properties": { "externalSharingAllowed": { "type": "boolean", "description": "Whether external sharing is allowed (ceiling: if false, no org can enable)", "default": true }, "ipAllowlist": { "type": "array", "items": { "type": "string" }, "description": "IP addresses allowed for login (CIDR notation). Empty = no restriction.", "default": [] }, "maxDocumentSizeBytes": { "type": "integer", "format": "int64", "description": "Maximum document size in bytes (0 = unlimited; if > 0, org max <= company max)", "default": 5242880, "minimum": 0 }, "maxSessionTimeoutSecs": { "type": "integer", "format": "int32", "description": "Maximum session duration in seconds (ceiling: org timeout <= company timeout)", "default": 2592000, "minimum": 0 }, "mfaPolicy": { "oneOf": [ { "$ref": "#/components/schemas/MfaPolicy", "description": "MFA enforcement policy (ceiling: org MFA rank must be >= company rank)" } ], "default": "optional" }, "minTrashRetentionDays": { "type": "integer", "format": "int32", "description": "Minimum trash retention period in days (floor: org retention >= company retention)", "default": 7, "minimum": 0 }, "webSearchPolicy": { "oneOf": [ { "$ref": "#/components/schemas/WebSearchPolicy", "description": "Web-search tool availability for agents in this tenant.\nDefault is `Disabled` — admins must opt in." } ], "default": "disabled" } } }, "CompanySettingsUpdate": { "type": "object", "description": "Partial update for company governance settings.\n\nAll fields are optional; omitted fields retain their existing values.", "properties": { "externalSharingAllowed": { "type": [ "boolean", "null" ], "description": "Whether external sharing is allowed across child orgs" }, "ipAllowlist": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "IP addresses allowed for login (CIDR notation)" }, "maxDocumentSizeBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum document size in bytes (0 = unlimited)", "minimum": 0 }, "maxSessionTimeoutSecs": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum session duration in seconds", "minimum": 0 }, "mfaPolicy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MfaPolicy", "description": "MFA enforcement policy ceiling" } ] }, "minTrashRetentionDays": { "type": [ "integer", "null" ], "format": "int32", "description": "Minimum trash retention period in days (floor for child orgs)", "minimum": 0 }, "webSearchPolicy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchPolicy", "description": "Web-search policy: gates the agent `web_search` tool at the\ncompany level. `disabled` (default) kill-switches it; `adminOnly`\npermits only company admins; `allUsers` permits everyone." } ] } } }, "CompanySharingPolicy": { "type": "object", "description": "Company-level sharing ceiling. Constrains what child `Organization` sharing policies can allow.", "required": [ "externalSharingEnabled", "allowedDomains", "blockedDomains", "publicLinksEnabled", "watermarkOnExport" ], "properties": { "allowedDomains": { "type": "array", "items": { "type": "string" }, "description": "Email domains allowed for external sharing (empty = all allowed)" }, "blockedDomains": { "type": "array", "items": { "type": "string" }, "description": "Email domains blocked from external sharing" }, "externalSharingEnabled": { "type": "boolean", "description": "Whether sharing with users outside the company is allowed" }, "publicLinksEnabled": { "type": "boolean", "description": "Whether public (unauthenticated) links are enabled" }, "watermarkOnExport": { "type": "boolean", "description": "Whether exported documents are watermarked" } } }, "ConnectedSource": { "oneOf": [ { "type": "object", "description": "A Space (knowledge base) connected as a research source.", "required": [ "spaceId", "type" ], "properties": { "documentCount": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of documents in the space (resolved server-side).", "minimum": 0 }, "spaceId": { "type": "string", "description": "Space identifier." }, "spaceName": { "type": [ "string", "null" ], "description": "Space display name (resolved server-side)." }, "type": { "type": "string", "enum": [ "space" ] } } }, { "type": "object", "description": "An individual document connected as a research source.", "required": [ "documentId", "type" ], "properties": { "documentId": { "type": "string", "description": "Document identifier." }, "documentTitle": { "type": [ "string", "null" ], "description": "Document title (resolved server-side)." }, "folderId": { "type": [ "string", "null" ], "description": "Parent folder ID, if any." }, "type": { "type": "string", "enum": [ "document" ] } } }, { "type": "object", "description": "A folder connected as a research source (recursive search scope).", "required": [ "folderId", "type" ], "properties": { "documentCount": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of documents in the folder tree (resolved server-side).", "minimum": 0 }, "folderId": { "type": "string", "description": "Folder identifier." }, "folderPath": { "type": [ "string", "null" ], "description": "Folder path (resolved server-side)." }, "type": { "type": "string", "enum": [ "folder" ] } } }, { "type": "object", "description": "A connector resource connected as a research source.", "required": [ "connectorSourceId", "resourceUri", "type" ], "properties": { "connectorIcon": { "type": [ "string", "null" ], "description": "Asset path for the connector logo." }, "connectorKind": { "type": [ "string", "null" ], "description": "Connector kind for icon resolution (e.g. `slack`, `gmail`, `mcp`)." }, "connectorSourceId": { "type": "string", "description": "Connector source identifier." }, "resourceName": { "type": [ "string", "null" ], "description": "Human-readable resource name (resolved server-side)." }, "resourceUri": { "type": "string", "description": "Connector-defined resource identifier (e.g. `slack://C04ABC/thread-123`)." }, "type": { "type": "string", "enum": [ "connector" ] } } } ], "description": "An entity connected to a chat session for research.\n\nDiscriminated by the `type` field. Each variant represents a different\nsearchable scope: a `Space` (knowledge base), an individual `Document`,\nor a `Folder` (recursive file tree)." }, "ConnectionDirection": { "type": "string", "description": "Direction filter for listing connections relative to a document.\n\nUsed internally for storage-layer query filtering, not for expressing\nuser-facing directionality (connections are symmetric).", "enum": [ "source", "target", "both" ] }, "ConnectionGraphEdge": { "type": "object", "description": "An edge in the connection graph.", "required": [ "id", "sourceNodeId", "connectedNodeId" ], "properties": { "connectedNodeId": { "type": "string", "description": "The other side of the connection." }, "description": { "type": [ "string", "null" ], "description": "Freeform description of the connection." }, "id": { "type": "string", "description": "Connection identifier." }, "sourceNodeId": { "type": "string", "description": "One side of the connection." } } }, "ConnectionGraphNode": { "type": "object", "description": "A node in the connection graph.", "required": [ "nodeId", "nodeType" ], "properties": { "nodeId": { "type": "string", "description": "Node identifier (document ID for `Document` nodes)." }, "nodeType": { "$ref": "#/components/schemas/NodeType", "description": "The type of this node." }, "title": { "type": [ "string", "null" ], "description": "Node title (if available)." } } }, "ConnectionGraphResponse": { "type": "object", "description": "Response containing a graph neighborhood around a starting document.", "required": [ "nodes", "edges" ], "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionGraphEdge" }, "description": "Edges between the discovered nodes." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionGraphNode" }, "description": "Discovered document nodes." } } }, "ConnectionStatus": { "type": "string", "description": "Connection activity state for presence display.", "enum": [ "active", "idle" ] }, "ConnectorAccessRequestResponse": { "type": "object", "description": "Response for `POST /api/v1/connectors/{kind}/access-requests`.", "required": [ "requestedAt" ], "properties": { "requestedAt": { "type": "string", "format": "date-time", "description": "When the access request was recorded or last refreshed." } } }, "ConnectorCapability": { "type": "object", "description": "Derived capability flags that describe what actions a connector\nsupports. Three orthogonal axes: whether resources can become\ndurable knowledge-base documents, whether resources can be referenced\nas ephemeral citations, and whether actions can be called by agents.\n\n- `indexable` — resources can be ingested as knowledge-base documents.\n- `attachable` — resources can be referenced as ephemeral citations.\n- `agentTool` — actions can be invoked by an agent.", "required": [ "indexable", "attachable", "agentTool" ], "properties": { "agentTool": { "type": "boolean", "description": "Whether the agent can invoke callable actions on this connector." }, "attachable": { "type": "boolean", "description": "Whether resources from this connector can be referenced as\nephemeral citations." }, "indexable": { "type": "boolean", "description": "Whether resources from this connector can be ingested as\nknowledge-base documents." } } }, "ConnectorCatalogEntry": { "type": "object", "description": "A single entry in the connector catalog.", "required": [ "kind", "mode", "displayName", "logoAsset", "category", "description", "configSchema", "scopeSchema", "actionTaxonomy", "authGranularity", "requiresOauth", "policyState" ], "properties": { "actionTaxonomy": { "$ref": "#/components/schemas/ActionTaxonomyResponse", "description": "Breakdown of available action types." }, "authGranularity": { "$ref": "#/components/schemas/AuthGranularity", "description": "Whether credentials are per-connection or per-user." }, "category": { "$ref": "#/components/schemas/ConnectorCategory", "description": "UI grouping category." }, "configSchema": { "description": "JSON Schema for the connector configuration." }, "description": { "type": "string", "description": "Short description of the connector." }, "displayName": { "type": "string", "description": "Human-readable display name." }, "governance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectorGovernance", "description": "Underlying governance state before grant promotion. Lets the\nfrontend distinguish a connected-mandated row from a\nconnected-approved row for disconnect gating." } ] }, "kind": { "type": "string", "description": "Connector kind identifier." }, "logoAsset": { "type": "string", "description": "Asset path for the connector logo." }, "mode": { "$ref": "#/components/schemas/ConnectorMode", "description": "Execution mode." }, "policyState": { "$ref": "#/components/schemas/ConnectorPolicyState", "description": "Per-viewer policy state discriminator the frontend uses to pick\nthe row's button label and interactivity. Computed server-side\nagainst the company's [`CompanyConnectorPolicy`] and the viewer's\ngrant table on every catalog fetch. Feature 070." }, "provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthProvider", "description": "`OAuth` provider group for shared auth credentials." } ] }, "requiresOauth": { "type": "boolean", "description": "Whether users must complete an OAuth flow to use this connector." }, "scopeSchema": { "description": "JSON Schema for source scope configuration." } } }, "ConnectorCategory": { "type": "string", "description": "UI category for grouping connectors in the catalog.", "enum": [ "messaging", "docs", "code", "email", "files", "crm", "projectMgmt", "analytics", "other" ] }, "ConnectorConnectionResponse": { "type": "object", "description": "Response for a single connector connection. Slim post-feature-070:\nno lifecycle state, no instance ID, no account name. The natural\nkey is `(company, kind)`.", "required": [ "kind", "mode", "config", "manifestReviewed", "firstEnabledBy", "firstEnabledAt", "updatedAt" ], "properties": { "config": { "description": "Provider-specific configuration blob (secrets redacted)." }, "firstEnabledAt": { "type": "string", "format": "date-time", "description": "When this connector was first enabled." }, "firstEnabledBy": { "type": "string", "description": "User who first enabled this connector for the company." }, "kind": { "type": "string", "description": "Connector kind identifier." }, "manifest": { "description": "`MCP` tool/resource manifest (only set for `mode == Mcp`)." }, "manifestRefreshedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the manifest was last refreshed from the provider." }, "manifestReviewed": { "type": "boolean", "description": "Whether the admin has reviewed the discovered `MCP` manifest.\nAlways `true` for first-party connectors." }, "mode": { "$ref": "#/components/schemas/ConnectorMode", "description": "Execution mode (`native`, `declarative`, `mcp`)." }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderSource", "description": "Credential source for the connector's provider at render time.\nComputed on every read by looking up the company's override\nrepo and the platform `OAuth` app registry. Never persisted." } ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "ConnectorCredentialMode": { "type": "string", "description": "Preferred credential model for a connector kind, declared by the kind's\n[`ConnectorMetadata`](crate::connector::ConnectorMetadata) and consumed by\n[`CredentialsResolver`](crate::connector::credentials_resolver::CredentialsResolver)\nplus the user-facing Connections panel.\n\nDistinct from [`AuthGranularity`]: `AuthGranularity` describes the *auth\nprotocol* the kind supports. `ConnectorCredentialMode` describes the\n*operational policy* — which credentials to prefer when both are possible\nfor a given invocation. See feature 075 research R10.", "enum": [ "userDelegated", "serviceAccount", "either" ] }, "ConnectorDisabledByPolicyDetails": { "type": "object", "description": "Structured error detail for a policy-denied connector authorize call.\nCarries the kind, scope discriminator, and admin attribution so the\nfrontend can render *Disabled by admin* with the correct tooltip.", "required": [ "kind", "scope", "disabledBy", "disabledAt" ], "properties": { "disabledAt": { "type": "string", "description": "When the policy row was last mutated (RFC 3339)." }, "disabledBy": { "type": "string", "description": "Admin user who last mutated the policy row." }, "kind": { "type": "string", "description": "Connector kind that was denied." }, "scope": { "type": "string", "description": "Either `disableAll` or `perConnector`." } } }, "ConnectorGovernance": { "type": "string", "description": "Per-kind governance state. See the module-level docs for the full\nsemantics.", "enum": [ "notApproved", "approved", "mandated" ] }, "ConnectorKind": { "type": "string", "description": "An open identifier for a connector type (e.g. `\"slack\"`, `\"mcp\"`, `\"gmail\"`).\n\nValidated on construction: 2-64 chars, `[a-z0-9-:]` only. This is intentionally\n**not** a closed enum — the set of connector kinds grows without framework changes.\nThe closed dispatch dimension is [`ConnectorMode`]." }, "ConnectorMode": { "type": "string", "description": "Execution mode determining how a connector's actions are dispatched.\n\nThis is the closed dispatch axis — unlike [`ConnectorKind`], it has a\nfixed set of variants for exhaustive matching.", "enum": [ "native", "mcp", "declarative" ] }, "ConnectorPolicyState": { "type": "string", "description": "Per-viewer state discriminator for a single catalog row. Determines\nwhich primary-action button label the frontend renders and whether the\nrow is interactive.\n\nPrecedence is computed in the catalog handler:\n1. `policy.disable_all` → [`Self::DisabledByKillSwitch`] (kill\n switch wins unconditionally)\n2. viewer has a live grant + governance permits → [`Self::Connected`]\n3. governance is `Mandated` → [`Self::Mandated`]\n4. governance is `NotApproved` via explicit override →\n [`Self::DisabledByPolicy`]\n5. governance is `NotApproved` via company default →\n [`Self::NotApproved`]\n6. resolver cannot resolve creds → [`Self::NotConfigured`]\n7. otherwise (governance = `Approved`) → [`Self::Enabled`]", "enum": [ "enabled", "connected", "mandated", "disabledByPolicy", "notApproved", "disabledByKillSwitch", "notConfigured" ] }, "ConnectorResourceSearchResponse": { "type": "object", "description": "Cross-connector resource search response.", "required": [ "results" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Pagination token for the next page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorResourceSearchResult" }, "description": "Search results." } } }, "ConnectorResourceSearchResult": { "type": "object", "description": "A single result from cross-connector resource search.", "required": [ "connectorSourceId", "resourceUri", "resourceTitle", "connectorKind", "alreadyPinned" ], "properties": { "alreadyPinned": { "type": "boolean", "description": "Whether this resource is already pinned in the Space." }, "connectorIcon": { "type": [ "string", "null" ], "description": "Logo asset path." }, "connectorKind": { "type": "string", "description": "Connector kind for icon resolution." }, "connectorSourceId": { "type": "string", "description": "Connector source ID." }, "externalUrl": { "type": [ "string", "null" ], "description": "Link to the original resource." }, "resourceTitle": { "type": "string", "description": "Display title." }, "resourceUri": { "type": "string", "description": "Connector-defined resource identifier." }, "snippet": { "type": [ "string", "null" ], "description": "Preview snippet." } } }, "ConsentTier": { "type": "string", "description": "Consent tier governing what the visitor permits.\n\n`audience` covers anonymous, aggregate measurement (count of pageviews,\nreferrer mix, country breakdown). `attribution` additionally permits\nlinking a visit to the user record at signup so per-channel funnel\nnumbers are possible.", "enum": [ "audience", "attribution" ] }, "ConsoleFilters": { "type": "object", "description": "Persisted inbox filter state.\n\n`themes` and `reviewers` are persistable but may not be user-selectable\nin every release. An empty list means \"all\".", "required": [ "status", "themes", "reviewers" ], "properties": { "reviewers": { "type": "array", "items": { "$ref": "#/components/schemas/TypedId" }, "description": "Selected reviewer ids — empty = all." }, "status": { "$ref": "#/components/schemas/ConsoleStatusFilter", "description": "Open / Resolved / Both." }, "themes": { "type": "array", "items": { "type": "string" }, "description": "Selected theme labels — empty = all." } } }, "ConsoleSort": { "type": "string", "description": "Persisted inbox sort order.", "enum": [ "priority", "section", "reviewer", "theme", "time" ] }, "ConsoleStatusFilter": { "type": "string", "description": "Status filter applied to the inbox list.", "enum": [ "open", "resolved", "both" ] }, "ConsoleView": { "type": "string", "description": "Persisted Console view selector.", "enum": [ "inbox", "themes", "log" ] }, "ContentType": { "type": "string", "description": "Document content type", "enum": [ "markdown", "html", "docx", "pdf", "pptx" ] }, "ConversionIntent": { "type": "string", "description": "Action the gated visitor was trying to take when they hit the\nsignup wall. Mirrors the SPA's `ConversionIntent` union — the two\nsides MUST agree on the wire form here so the resume dispatcher\ncan re-fire the right action after auth.", "enum": [ "download_pdf", "clone_doc", "remix_doc" ] }, "CreateAgentRequest": { "type": "object", "description": "Request to register a new agent.", "required": [ "name", "description", "agentType" ], "properties": { "agentType": { "type": "string", "description": "Agent type: \"builtIn\" or \"custom\"." }, "defaultAutonomy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AutonomyLevel", "description": "Default autonomy level." } ] }, "description": { "type": "string", "description": "Description of what the agent does." }, "enabledTools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tool names to enable (validated against known tools)." }, "modelConfig": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelConfigRequest", "description": "Model configuration (required for custom agents)." } ] }, "name": { "type": "string", "description": "Display name for the agent." }, "permissions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Permission names to grant." }, "scope": { "type": [ "string", "null" ], "description": "Scope: \"global\", \"documents\", or \"folders\"." }, "scopeDocumentIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Document IDs for scope = \"documents\"." }, "scopeFolderIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Folder IDs for scope = \"folders\"." }, "systemPrompt": { "type": [ "string", "null" ], "description": "System prompt (required for custom agents)." } } }, "CreateAttachmentRequest": { "type": "object", "description": "Request body for creating a transient resource attachment.", "required": [ "connectorKind", "resourceUri", "displaySnapshot" ], "properties": { "connectorKind": { "type": "string", "description": "Connector kind slug (e.g. `slack`, `notion`)." }, "displaySnapshot": { "$ref": "#/components/schemas/AttachmentDisplaySnapshotRequest", "description": "Rendered snapshot for display without a fresh upstream fetch." }, "externalUrl": { "type": [ "string", "null" ], "description": "Human-openable URL for the resource." }, "resourceUri": { "type": "string", "description": "Canonical resource identifier within the connector kind." } } }, "CreateCheckoutSessionRequest": { "type": "object", "description": "Request to create a checkout session for plan upgrade.", "required": [ "idempotencyKey" ], "properties": { "billingInterval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingInterval", "description": "Billing cadence. `None` defaults to `Monthly` server-side. Annual is\nonly supported on `personalPro`; `(team, annual)` is rejected with 400." } ] }, "idempotencyKey": { "type": "string", "description": "Idempotency key to prevent duplicate checkout sessions." }, "targetPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "Target plan to upgrade to. Must be `personalPro` or `team`.\nDefaults to `team` for backwards compatibility." } } }, "CreateCommentAnchor": { "type": "object", "description": "Anchor data for creating a text-range comment.\n\nContains Yjs relative positions that survive concurrent edits, plus\nfallback data for re-anchoring after compaction or full rewrites.", "required": [ "startRelative", "endRelative" ], "properties": { "endRelative": { "$ref": "#/components/schemas/YjsRelativePosition", "description": "Yjs relative position for range end." }, "headingContext": { "type": "array", "items": { "type": "string" }, "description": "Heading breadcrumbs at creation time." }, "prefixContext": { "type": [ "string", "null" ], "description": "~50 chars before the anchor for improved fuzzy re-anchoring." }, "quotedText": { "type": [ "string", "null" ], "description": "Quoted text at anchor creation time (max 500 chars)." }, "startRelative": { "$ref": "#/components/schemas/YjsRelativePosition", "description": "Yjs relative position for range start." }, "suffixContext": { "type": [ "string", "null" ], "description": "~50 chars after the anchor for improved fuzzy re-anchoring." } } }, "CreateCommentRequest": { "type": "object", "required": [ "body" ], "properties": { "anchor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateCommentAnchor", "description": "Anchor for text-range comments. When provided, the comment is anchored\nto a specific text range via Yjs relative positions." } ] }, "body": { "type": "string" }, "parentCommentId": { "type": [ "string", "null" ] } } }, "CreateCompanyRequest": { "type": "object", "description": "Request to create a new company.\n\nBacked by a verified domain-claim attempt: the caller must already\nhold a `DomainClaimAttempt` in the `verified` lifecycle state for\nthe domain they want to bind to the new company.", "required": [ "name", "slug", "claimId" ], "properties": { "claimId": { "$ref": "#/components/schemas/TypedId", "description": "Identifier of the verified `DomainClaimAttempt` that backs this\ncompany. The handler refuses requests where the claim is not in\nthe verified state, is not owned by the caller, or has already\nbeen bound to a different company." }, "name": { "type": "string", "description": "Company name" }, "slug": { "type": "string", "description": "Globally unique URL-safe slug" } } }, "CreateDocumentConnectionRequest": { "type": "object", "description": "Request to create a symmetric connection between two nodes.", "required": [ "connectedNodeId" ], "properties": { "connectedNodeId": { "type": "string", "description": "The target node ID (currently always a document ID)." }, "description": { "type": [ "string", "null" ], "description": "Optional freeform description of why these nodes are connected." } } }, "CreateDocumentRequest": { "type": "object", "required": [ "title" ], "properties": { "content": { "type": [ "string", "null" ] }, "contentType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContentType" } ] }, "folderId": { "type": [ "string", "null" ] }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Client-supplied idempotency key for retry-safe creates." }, "title": { "type": "string" } } }, "CreateDomainClaimRequest": { "type": "object", "description": "Request body for `POST /claims`.", "required": [ "requestedDomain", "targetCompanyName", "defaultRole", "joinPolicy" ], "properties": { "defaultRole": { "$ref": "#/components/schemas/TierRole", "description": "Role that newly-joining or migrated members receive on the\nresulting company." }, "joinPolicy": { "$ref": "#/components/schemas/JoinPolicy", "description": "Whether new signups under the claimed domain join automatically\nor must request access." }, "requestedDomain": { "type": "string", "description": "User-entered domain in any form (email or hostname); the server\ncanonicalizes to the registrable eTLD+1 before persisting." }, "targetCompanyName": { "type": "string", "description": "Display name for the company that the verified claim will\nproduce. Required and never auto-derived from the email domain." } } }, "CreateFolderRequest": { "type": "object", "required": [ "name" ], "properties": { "kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FolderKind", "description": "Folder kind: standard or skill. Defaults to standard." } ] }, "name": { "type": "string" }, "parentFolderId": { "type": [ "string", "null" ] }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeId", "description": "Typed scope (`kind` + `id`). Required for root folders; subfolders\ninherit scope from their parent. Immutable after creation." } ] } } }, "CreateIdpMappingRequest": { "type": "object", "description": "Request to create a new `IdP` group-to-tier-node mapping.", "required": [ "scimGroupId", "targetNodeId", "tierRole" ], "properties": { "scimGroupId": { "type": "string", "description": "SCIM group identifier to map" }, "targetNodeId": { "type": "string", "description": "Target tier node identifier for membership provisioning" }, "tierRole": { "$ref": "#/components/schemas/TierRole", "description": "Role assigned to group members in the target tier node" } } }, "CreateMemoryEntryRequest": { "type": "object", "description": "Request body for `POST /users/me/memory/entries`.", "required": [ "type", "name", "content" ], "properties": { "content": { "type": "string", "description": "Entry body." }, "description": { "type": "string", "description": "One-line hook shown in the index." }, "name": { "type": "string", "description": "Short identifier (doc title)." }, "sourceSessionId": { "type": [ "string", "null" ], "description": "Optional chat session ID — when set, frontmatter records provenance." }, "type": { "$ref": "#/components/schemas/MemoryType", "description": "Category — one of `feedback`, `user`, `project`, `reference`." } } }, "CreateOAuthClientRequest": { "type": "object", "description": "Request to create an OAuth client via the management API.", "required": [ "name", "redirectUris" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } } } }, "CreateOAuthClientResponse": { "type": "object", "description": "Response when creating an OAuth client (includes secret shown once).", "required": [ "clientId", "clientSecret", "name", "redirectUris", "scopes", "createdAt" ], "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "CreateOrgInCompanyRequest": { "type": "object", "description": "Request to create a new organization within a company.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Organization name" } } }, "CreatePortalSessionRequest": { "type": "object", "description": "Request to create a billing portal session.", "properties": { "returnUrl": { "type": [ "string", "null" ], "description": "Optional return URL override." } } }, "CreateRepoSourceRequest": { "type": "object", "description": "Request to create a new repository source in a Space.", "required": [ "connectionId", "repoFullName" ], "properties": { "connectionId": { "type": "string", "description": "ID of an `Active` `RepoConnection`" }, "defaultBranch": { "type": [ "string", "null" ], "description": "Branch to track (auto-detected if omitted)" }, "repoFullName": { "type": "string", "description": "Full repository name (owner/repo)" } } }, "CreateS3ExportConfigRequest": { "type": "object", "description": "Request body for creating or updating an S3 export configuration", "required": [ "s3BucketArn", "roleArn" ], "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Whether the export is enabled (defaults to `true`)" }, "roleArn": { "type": "string", "description": "ARN of the IAM role to assume for cross-account writes" }, "s3BucketArn": { "type": "string", "description": "ARN of the customer's S3 bucket" }, "s3Prefix": { "type": [ "string", "null" ], "description": "Key prefix for exported files (defaults to `\"audit/\"`)" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/S3ExportSchedule", "description": "Export schedule (defaults to `Hourly`)" } ] } } }, "CreateScimTierMappingRequest": { "type": "object", "description": "Request body for creating a SCIM tier mapping.", "required": [ "idpGroupId", "nodeId", "tierId", "role" ], "properties": { "idpGroupId": { "type": "string", "description": "External `IdP` group identifier." }, "nodeId": { "type": "string", "description": "Target tier node." }, "role": { "type": "string", "description": "Role to assign. Must be valid for the target tier's template." }, "tierId": { "type": "string", "description": "Hierarchy tier the target node belongs to. Denormalized by the caller\nto avoid a cross-partition lookup at write time." } } }, "CreateScimTokenRequest": { "type": "object", "description": "Request body for creating a SCIM token", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Admin-assigned name for the token (e.g., \"Okta Production\")" } } }, "CreateScimTokenResponse": { "type": "object", "description": "Response returned when a token is first created (includes the raw token value)", "required": [ "id", "name", "token", "tokenPrefix", "status", "createdAt" ], "properties": { "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "id": { "type": "string", "description": "Token ID" }, "name": { "type": "string", "description": "Admin-assigned name" }, "status": { "$ref": "#/components/schemas/ScimTokenStatus", "description": "Token status" }, "token": { "type": "string", "description": "Raw bearer token value (shown exactly once — never stored or returned again)" }, "tokenPrefix": { "type": "string", "description": "First 12 characters of the token for display" } } }, "CreateSessionRequest": { "type": "object", "description": "Request to create a new chat session.", "required": [ "scope" ], "properties": { "initialMemoryDisabled": { "type": "boolean", "description": "Initial per-session memory override. Lets the panel sub-header\nBrain toggle persist its pre-session intent atomically when the\nfirst message implicitly creates the session — without this the\nfrontend would have to fire a follow-up PATCH that races the\nfirst turn." }, "initialToolOverrides": { "type": "object", "description": "Initial per-conversation tool overrides. Same atomicity rationale\nas `initialMemoryDisabled`: the Globe toggle in the sub-header\ncan buffer its intent before any session exists, and that intent\nmust land on the row before the first turn streams. Empty when\nthe user hasn't pre-toggled anything.", "additionalProperties": { "$ref": "#/components/schemas/ToolOverride" }, "propertyNames": { "type": "string" } }, "language": { "type": "string", "description": "ISO 639-1 language code (e.g., `\"en\"`, `\"es\"`). Defaults to `\"en\"`." }, "languageName": { "type": "string", "description": "Human-readable language name (e.g., `\"English\"`, `\"Spanish\"`).\nProvided by the frontend via `Intl.DisplayNames`." }, "scope": { "$ref": "#/components/schemas/AssistantScope", "description": "Which scope this session belongs to." }, "scopeEntityId": { "type": [ "string", "null" ], "description": "The entity this session is scoped to (doc/space ID).\n\nMay be omitted only for `home` sessions; the server stores the active\ncompany ID as the normalized scope entity." } } }, "CreateSpaceFilterRequest": { "type": "object", "description": "Request to create a source filter for a Space.", "required": [ "folderId" ], "properties": { "folderId": { "type": "string", "description": "Target folder ID for recursive document inclusion." } } }, "CreateSpaceRequest": { "type": "object", "description": "Request to create a new Space.\n\n`transitiveAccess` is rejected by `deny_unknown_fields` — the field\nlives on the `Space` entity (always `false` in v1 per US2 / FR-003)\nbut no create endpoint accepts a write for it.", "required": [ "name" ], "properties": { "color": { "type": [ "string", "null" ], "description": "Optional color hex code." }, "coverImage": { "type": [ "string", "null" ], "description": "Optional cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Optional description." }, "icon": { "type": [ "string", "null" ], "description": "Optional icon identifier." }, "name": { "type": "string", "description": "Human-readable Space name (unique within scope)." }, "parentFolderId": { "type": [ "string", "null" ], "description": "Parent folder ID. When provided, scope is derived from the folder's scope." }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeId", "description": "Typed scope discriminator (`kind` + `id`). Required unless\n`parentFolderId` is provided — in that case the server derives the\nscope from the parent folder." } ] } }, "additionalProperties": false }, "CreateSsoConnectionRequest": { "type": "object", "description": "Request to create a new SSO connection for an organization.", "required": [ "name", "protocol", "domains" ], "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Verified domains to associate with this connection" }, "name": { "type": "string", "description": "Display name for the SSO connection (e.g., \"Okta Production\")" }, "oidcClientId": { "type": [ "string", "null" ], "description": "OIDC client identifier (required for OIDC connections)" }, "oidcClientSecret": { "type": [ "string", "null" ], "description": "OIDC client secret (required for OIDC connections)" }, "oidcIssuerUrl": { "type": [ "string", "null" ], "description": "OIDC issuer URL (required for OIDC connections)" }, "protocol": { "$ref": "#/components/schemas/SsoProtocol", "description": "Authentication protocol (`saml` or `oidc`)" }, "samlMetadataDocument": { "type": [ "string", "null" ], "description": "SAML metadata XML document (alternative to URL for `IdPs` without metadata endpoints)" }, "samlMetadataUrl": { "type": [ "string", "null" ], "description": "SAML metadata document URL (required for SAML connections unless document is provided)" } } }, "CreateSuggestionRequest": { "type": "object", "description": "Request to create a human-authored suggestion.", "required": [ "originalText", "replacementText" ], "properties": { "headingContext": { "type": "array", "items": { "type": "string" }, "description": "Heading breadcrumbs for disambiguation when `original_text` appears\nmultiple times." }, "originalText": { "type": "string", "description": "Exact text to replace — server resolves to Yjs positions." }, "rationale": { "type": [ "string", "null" ], "description": "Optional rationale explaining why the change is proposed." }, "replacementText": { "type": "string", "description": "Proposed replacement text (markdown)." }, "severity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionSeverity", "description": "Optional severity level (Nitpick, Improvement, Issue, Critical)." } ] } } }, "CreateSuggestionResponse": { "type": "object", "description": "Response from creating a suggestion.", "required": [ "suggestionId", "documentId", "status", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "documentId": { "type": "string" }, "status": { "$ref": "#/components/schemas/SuggestionStatus" }, "suggestionId": { "type": "string" } } }, "CreateTierNodeRequest": { "type": "object", "description": "Request body for creating a tier node.", "required": [ "tierId", "name", "slug" ], "properties": { "name": { "type": "string", "description": "Human-readable display name." }, "parentNodeId": { "type": [ "string", "null" ], "description": "Parent node ID. Required for depth-1+ nodes, omitted for depth 0." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TierNodeSettings", "description": "Per-node settings. Defaults to parent's settings if omitted." } ] }, "slug": { "type": "string", "description": "URL-safe slug, unique among siblings." }, "tierId": { "type": "string", "description": "Hierarchy tier this node belongs to (must match a tier in the company's\nhierarchy definition)." } } }, "CreateWebSocketTicketRequest": { "type": "object", "description": "Request a short-lived document-scoped WebSocket ticket.", "required": [ "documentId" ], "properties": { "documentId": { "$ref": "#/components/schemas/TypedId", "description": "Document the ticket may join." } } }, "CreateWebSocketTicketResponse": { "type": "object", "description": "Response containing a short-lived WebSocket auth token.", "required": [ "token", "expiresAt" ], "properties": { "expiresAt": { "type": "integer", "format": "int64", "description": "Unix timestamp when the token expires." }, "token": { "type": "string", "description": "HMAC-signed token accepted by `/ws`." } } }, "CreateWebhookConfigRequest": { "type": "object", "description": "Request body for creating or updating a webhook configuration", "required": [ "webhookUrl", "events" ], "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Whether the webhook is enabled (defaults to `true`)" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event glob patterns to subscribe to (e.g., `[\"auth.*\", \"document.*\"]`)" }, "secret": { "type": [ "string", "null" ], "description": "Shared secret for HMAC-SHA256 signatures (min 32 chars; auto-generated if omitted)" }, "webhookUrl": { "type": "string", "description": "HTTPS endpoint URL (must use `https://` scheme)" } } }, "CreditMultiplier": { "type": "object", "description": "Per-model credit multiplier for usage-based billing.\n\nCredits are computed as `tokens × multiplier` for each token category.\n1 credit ≡ 1 Sonnet 4.6 input token (`$3/1M` Bedrock anchor).\nOutput tokens cost ~5× input on Anthropic models, so the `output`\nmultiplier is correspondingly higher. Cache-read is ~10% of input,\ncache-write is ~25% premium over input.", "required": [ "input", "cacheRead", "cacheWrite", "output" ], "properties": { "cacheRead": { "type": "number", "format": "double", "description": "Multiplier for cache-read tokens." }, "cacheWrite": { "type": "number", "format": "double", "description": "Multiplier for cache-write tokens." }, "input": { "type": "number", "format": "double", "description": "Multiplier for input tokens." }, "output": { "type": "number", "format": "double", "description": "Multiplier for output tokens." } } }, "CurrentAuthUserResponse": { "type": "object", "description": "Current authenticated browser user.", "required": [ "userId", "email", "isFederated", "mfaSetupRequired" ], "properties": { "email": { "type": "string", "description": "User's primary email address." }, "isFederated": { "type": "boolean", "description": "`true` when the current session came from a federated identity provider." }, "mfaSetupRequired": { "type": "boolean", "description": "`true` when the user must complete MFA setup before accessing the app." }, "userId": { "type": "string", "description": "Canonical Strata user ID." } } }, "DeleteCommentResponse": { "type": "object", "description": "Response from deleting a comment.", "required": [ "softDeleted" ], "properties": { "softDeleted": { "type": "boolean", "description": "Whether the comment was soft-deleted (true) or hard-deleted (false)." } } }, "DeleteOwnAccountRequest": { "type": "object", "description": "Body of `DELETE /api/v1/account`.", "required": [ "summaryVersion", "confirmation" ], "properties": { "confirmation": { "$ref": "#/components/schemas/AccountDeletionConfirmation", "description": "Explicit confirmation enum (single-variant on purpose — the wire\ncontract requires \"deleteAccount\" verbatim)." }, "summaryVersion": { "type": "string", "description": "The `summaryVersion` returned by the deletion summary the actor\nreviewed." } } }, "DeleteOwnAccountResponse": { "type": "object", "description": "Response body of `DELETE /api/v1/account`.", "required": [ "operationId", "status", "cleanupStats", "sessionAction" ], "properties": { "cleanupStats": { "$ref": "#/components/schemas/LifecycleCleanupStats", "description": "Per-step cleanup totals." }, "operationId": { "$ref": "#/components/schemas/TypedId", "description": "Idempotent lifecycle operation identifier (new or replayed)." }, "sessionAction": { "$ref": "#/components/schemas/SessionAction", "description": "What the client must do with the current session after a\nsuccessful deletion." }, "status": { "$ref": "#/components/schemas/LifecycleOperationStatus", "description": "Final operation state." } } }, "DeleteWorkspaceConfirmation": { "type": "string", "description": "Confirmation token for workspace delete.", "enum": [ "deleteWorkspace" ] }, "DeleteWorkspaceRequest": { "type": "object", "description": "Body of `DELETE /api/v1/companies/{companyId}`.", "required": [ "summaryVersion", "confirmation" ], "properties": { "confirmation": { "$ref": "#/components/schemas/DeleteWorkspaceConfirmation", "description": "Explicit confirmation enum." }, "summaryVersion": { "type": "string", "description": "Summary version returned by the lifecycle summary the actor\nreviewed." } } }, "DeleteWorkspaceResponse": { "type": "object", "description": "Response body of `DELETE /api/v1/companies/{companyId}`.", "required": [ "operationId", "status", "workspaceId", "cleanupStats" ], "properties": { "cleanupStats": { "$ref": "#/components/schemas/WorkspaceCleanupStats", "description": "Per-step cleanup totals." }, "operationId": { "$ref": "#/components/schemas/TypedId", "description": "Idempotent lifecycle operation identifier." }, "status": { "$ref": "#/components/schemas/LifecycleOperationStatus", "description": "Final operation state." }, "workspaceId": { "$ref": "#/components/schemas/TypedId", "description": "Workspace that was deleted." } } }, "DeltaMode": { "type": "string", "description": "Whether a `JoinedDocument` response carries a full state snapshot\nor a WAL-derived delta to apply on top of the client's cached state.", "enum": [ "full", "wal" ] }, "DiffChunk": { "type": "object", "description": "A chunk of text in a word-level diff.", "required": [ "tag", "value" ], "properties": { "tag": { "$ref": "#/components/schemas/DiffTag", "description": "Whether this chunk is equal, inserted, or deleted." }, "value": { "type": "string", "description": "The text content of this chunk." } } }, "DiffStats": { "type": "object", "description": "Aggregate statistics for a history diff.", "required": [ "blocksAdded", "blocksRemoved", "blocksModified" ], "properties": { "blocksAdded": { "type": "integer", "format": "int32", "description": "Number of blocks added.", "minimum": 0 }, "blocksModified": { "type": "integer", "format": "int32", "description": "Number of blocks modified.", "minimum": 0 }, "blocksRemoved": { "type": "integer", "format": "int32", "description": "Number of blocks removed.", "minimum": 0 } } }, "DiffTag": { "type": "string", "description": "Tag indicating how a diff chunk relates to the original text.", "enum": [ "equal", "insert", "delete" ] }, "DisplaySnapshotResponse": { "type": "object", "description": "Rendered snapshot returned in attachment responses.", "required": [ "title" ], "properties": { "excerpt": { "type": [ "string", "null" ], "description": "Short excerpt or description, if available." }, "icon": { "type": [ "string", "null" ], "description": "URL to a small icon representing the connector kind, if available." }, "title": { "type": "string", "description": "Human-readable title of the resource." } } }, "DnsCheckResult": { "type": "object", "description": "DNS check result returned after verifying a domain's TXT records.", "required": [ "found", "txtRecordsFound" ], "properties": { "error": { "type": [ "string", "null" ], "description": "Human-readable error if DNS resolution failed" }, "errorCode": { "type": [ "string", "null" ], "description": "Machine-readable error code" }, "found": { "type": "boolean", "description": "Whether the verification token was found in DNS" }, "txtRecordsFound": { "type": "integer", "format": "int32", "description": "Number of TXT records found on the domain", "minimum": 0 } } }, "DocumentChangeType": { "type": "string", "description": "Type of document change, used in `DocumentChanged` notifications\nfor Space subscribers (FUSE mounts, dashboards).", "enum": [ "edited", "created", "deleted", "metadataChanged" ] }, "DocumentCleanupCounts": { "type": "object", "description": "Aggregate document cleanup preview shared by account and workspace\nsummary endpoints.", "required": [ "privateDocumentsToDelete", "sharedDocumentsToRetain", "documentsWithoutActiveUsersToDelete" ], "properties": { "documentsWithoutActiveUsersToDelete": { "type": "integer", "format": "int32", "description": "Documents whose only remaining grantees are inactive or removed —\nwill be deleted.", "minimum": 0 }, "privateDocumentsToDelete": { "type": "integer", "format": "int32", "description": "Documents private to the leaving/deleting user — will be deleted.", "minimum": 0 }, "sharedDocumentsToRetain": { "type": "integer", "format": "int32", "description": "Documents with at least one remaining active user — will be\nretained.", "minimum": 0 } } }, "DocumentConnectionResponse": { "type": "object", "description": "API response for a single connection.", "required": [ "id", "sourceNodeId", "connectedNodeId", "createdBy", "createdAt" ], "properties": { "connectedNodeId": { "type": "string", "description": "The other side of the connection." }, "connectedNodeTitle": { "type": [ "string", "null" ], "description": "Title of the connected node (if available)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the connection was created." }, "createdBy": { "type": "string", "description": "User who created this connection." }, "description": { "type": [ "string", "null" ], "description": "Freeform description of the connection." }, "id": { "type": "string", "description": "Unique connection identifier." }, "sourceNodeId": { "type": "string", "description": "One side of the connection." }, "sourceNodeTitle": { "type": [ "string", "null" ], "description": "Title of the source node (if available)." } } }, "DocumentContentResponse": { "type": "object", "required": [ "documentId", "title", "contentType", "documentVersion", "blocks" ], "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockResponse" } }, "contentType": { "$ref": "#/components/schemas/ContentType" }, "documentComments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CommentResponse" } }, "documentId": { "type": "string" }, "documentVersion": { "type": "integer", "format": "int64", "description": "Current document-level version. `0` for documents never edited with versioning.", "minimum": 0 }, "rawContent": { "type": "object", "description": "Raw `ProseMirror` JSON document (for WYSIWYG editor loading)" }, "title": { "type": "string" } } }, "DocumentInviteResponse": { "type": "object", "description": "Pending document invitation for an external email.\n\nReturned from `grant_access` when the target email does not resolve to a\nuser in the document's tenant. The invitation is stored with a TTL and\nresolves to an `AccessEntryResponse` at acceptance time.", "required": [ "documentId", "email", "role", "invitedAt" ], "properties": { "documentId": { "type": "string", "description": "Document the recipient is invited to." }, "email": { "type": "string", "description": "Email that received the invitation." }, "invitedAt": { "type": "string", "format": "date-time", "description": "When the invitation was created." }, "role": { "$ref": "#/components/schemas/ResourceRole", "description": "Role the invitee will receive on acceptance (may be capped by policy)." } } }, "DocumentProvenance": { "type": "object", "description": "Provenance metadata stamped onto a document at clone time.\n\nPopulated when a document was created by the public-share clone\nflow (`POST /api/v1/public/by-token/{token}/clone`); absent on\nhand-authored documents and on docs created via any other path.\nThe webapp renders a \"Cloned from `@/`\" label in\nthe editor header — gracefully degrading when handle and/or slug\nare missing (see the `sourceTitle` fallback below).\n\nAll fields are frozen at clone time: subsequent renames of the\nsource author's handle, source-doc title changes, or\nre-publication with a new slug do not propagate to the clone.", "required": [ "sourceDocumentId", "sourceTitle", "clonedAt" ], "properties": { "clonedAt": { "type": "string", "format": "date-time", "description": "Server timestamp at the moment the clone-by-token handler\ncommitted the new document." }, "sourceDocumentId": { "$ref": "#/components/schemas/TypedId", "description": "The source document's id at clone time." }, "sourceHandle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Handle", "description": "The source author's handle at clone time, when the author\nhas claimed one. Public share tokens are independent of the\nhandle-claim flow, so a clone source may be authored by a\nuser who never claimed a handle." } ] }, "sourceSlug": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Slug", "description": "The source document's published slug at clone time, when\nthe source has been published. Public share tokens can grant\naccess to drafts, so a clone source may have no slug." } ] }, "sourceTitle": { "type": "string", "description": "The source document's title at clone time. Always present;\nused as the provenance label fallback when the source has\nno public address (handle + slug pair)." } } }, "DocumentResponse": { "type": "object", "required": [ "id", "title", "contentType", "ownerId", "wordCount", "isPublic", "effectiveRole", "status", "holdCount", "publishedState", "publishCount", "createdAt", "updatedAt" ], "properties": { "agentMetadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMetadata", "description": "Cached agent metadata for documents that live under the agents folder.\n`None` for non-agent documents. Drives the `@mention` picker, the\norchestrator catalog, and the agent settings banner." } ] }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "clonedFrom": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentProvenance", "description": "Provenance reference for documents created by the public-share\nclone flow. `None` on hand-authored documents." } ] }, "contentType": { "$ref": "#/components/schemas/ContentType" }, "createdAt": { "type": "string", "format": "date-time" }, "effectiveRole": { "$ref": "#/components/schemas/ResourceRole" }, "folderId": { "type": [ "string", "null" ] }, "holdCount": { "type": "integer", "format": "int32", "minimum": 0 }, "id": { "type": "string" }, "isPublic": { "type": "boolean" }, "isShared": { "type": "boolean", "description": "Whether the document has one or more active access grants." }, "language": { "type": [ "string", "null" ] }, "lastPublishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent publish. `None` when the document has\nnever been published." }, "latestPublishedVersion": { "type": [ "integer", "null" ], "format": "int32", "description": "Latest published version number. `None` until the document has been\npublished at least once.", "minimum": 0 }, "ownerEmail": { "type": [ "string", "null" ], "description": "Email of the document owner (`None` if the owner account was deactivated)." }, "ownerId": { "type": "string" }, "promptMetadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PromptMetadata", "description": "Cached prompt metadata for documents that live under a prompt folder.\n`None` for non-prompt documents. Drives the slash command slug,\nthe argument sheet UI, and the prompt settings banner." } ] }, "publishCount": { "type": "integer", "format": "int32", "description": "Total number of publish operations on this document.", "minimum": 0 }, "publishedState": { "$ref": "#/components/schemas/PublishedState", "description": "Publishing lifecycle state (`draft` or `published`)." }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time" }, "slug": { "type": [ "string", "null" ], "description": "URL slug assigned on first publish. Immutable afterwards. `None` while\nthe document has never been published." }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImportSourceResponse", "description": "Provenance for imported documents. `None` for hand-authored documents.\nPresent when the document was materialized from an external connector\nresource (e.g. a Notion page, a Slack thread, a Drive file)." } ] }, "status": { "$ref": "#/components/schemas/DocumentStatus" }, "title": { "type": "string" }, "trashedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "wordCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "DocumentStatus": { "type": "string", "description": "Document lifecycle state.\n\nDocuments transition between states via lifecycle operations (trash, archive, restore).\nSerialized as lowercase strings: `\"active\"`, `\"archived\"`, `\"trashed\"`.", "enum": [ "active", "archived", "trashed" ] }, "DomainClaimAttempt": { "type": "object", "description": "A single in-flight or terminal domain-claim attempt.", "required": [ "id", "requestorUserId", "requestedDomain", "verificationToken", "targetCompanyName", "defaultRole", "joinPolicy", "lifecycleState", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the claim was created." }, "defaultRole": { "$ref": "#/components/schemas/TierRole", "description": "Role that new joiners and migrated users receive." }, "failureReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DomainClaimFailureReason", "description": "Why the claim ended in\n[`DomainClaimLifecycleState::Failed`], when applicable." } ] }, "id": { "$ref": "#/components/schemas/TypedId", "description": "Claim attempt identifier (ULID, prefix `claim_`)." }, "joinPolicy": { "$ref": "#/components/schemas/JoinPolicy", "description": "Whether new signups join automatically or must request access." }, "lifecycleState": { "$ref": "#/components/schemas/DomainClaimLifecycleState", "description": "Current point in the claim lifecycle." }, "requestedDomain": { "type": "string", "description": "Canonical registrable form of the domain being claimed\n(lowercase Punycode)." }, "requestorUserId": { "$ref": "#/components/schemas/TypedId", "description": "User who initiated the claim; only this user may verify it." }, "targetCompanyName": { "type": "string", "description": "Display name the new company tenant will adopt on success." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Most recent state transition." }, "verificationToken": { "type": "string", "description": "Full TXT-record value the requestor must publish at the\nregistrable domain.\n\nFormat: `strata-domain-verification=<32-byte-hex>`. Surfaced once\nat create time; persists on the row so the requestor can come\nback to verify later." }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the claim transitioned `pending` → `verified`. Null while\npending or in a non-verified terminal state." } } }, "DomainClaimFailureReason": { "type": "string", "description": "Why a [`DomainClaimAttempt`] terminated in [`DomainClaimLifecycleState::Failed`].", "enum": [ "dnsTxtMissing", "domainTaken", "freeProviderRefused", "internal" ] }, "DomainClaimLifecycleState": { "type": "string", "description": "Lifecycle of a [`DomainClaimAttempt`] from issuance through migration.", "enum": [ "pending", "verified", "succeeded", "failed" ] }, "DomainClaimVerifyResponse": { "type": "object", "description": "Response body for `POST /claims/{id}/verify` after the migration\nbackfill has run.", "required": [ "claim", "companyId", "migratedUserCount" ], "properties": { "claim": { "$ref": "#/components/schemas/DomainClaimAttempt", "description": "Final state of the claim after verification + migration." }, "companyId": { "type": "string", "description": "Identifier of the company tenant the verification produced or\nbound itself to." }, "migratedUserCount": { "type": "integer", "format": "int32", "description": "Number of personal-plan account holders on the canonical domain\nwho were added as members of the new company by the migration.", "minimum": 0 } } }, "DomainVerificationResponse": { "type": "object", "description": "Domain verification status response.", "required": [ "domain", "verificationToken", "verificationStatus", "createdAt", "expiresAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the verification was initiated" }, "dnsCheckResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DnsCheckResult", "description": "DNS check result (present only after a check operation)" } ] }, "domain": { "type": "string", "description": "The email domain being verified" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the verification token expires" }, "verificationStatus": { "$ref": "#/components/schemas/DomainVerificationStatus", "description": "Current verification status" }, "verificationToken": { "type": "string", "description": "DNS TXT record value to publish for verification" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the domain was successfully verified" } } }, "DomainVerificationStatus": { "type": "string", "description": "Domain verification status lifecycle", "enum": [ "pending", "verified", "expired" ] }, "DraftCitation": { "type": "object", "description": "Verified citation extracted from the model's regenerated reply.\n\nCitations are pruned post-generation: only entries whose `section_id`\nresolves against the document heading map at write time are retained;\nthe corresponding inline `[^N]` markers in the reply body are removed\notherwise. The remaining list is what the UI renders below the draft.", "required": [ "anchorId", "sectionId", "snippet" ], "properties": { "anchorId": { "type": "integer", "format": "int32", "description": "Anchor id used in the inline `[^N]` marker in the draft body.", "minimum": 0 }, "sectionId": { "type": "string", "description": "Document section id this citation points to." }, "snippet": { "type": "string", "description": "Up to ~200 characters of paraphrased context from that section." } } }, "EditActor": { "type": "object", "description": "Identifies who performed an edit, used in broadcast messages for attribution.", "required": [ "id", "entityType", "displayName" ], "properties": { "displayName": { "type": "string", "description": "Human-readable name for UI display" }, "entityType": { "$ref": "#/components/schemas/EntityType", "description": "`Human` or `Agent`" }, "id": { "type": "string", "description": "Entity ID (user sub or agent ID)" } } }, "EditDocumentRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "Edit action: `append`, `prepend`, `replaceAll`, or `stringReplace`." }, "content": { "type": [ "string", "null" ], "description": "Content body. Required for `append`, `prepend`, `replaceAll`.\nFor `stringReplace`, this is the text to find (`oldString`)." }, "contentFormat": { "type": [ "string", "null" ], "description": "Content format: `markdown` (default), `html`, or `json`." }, "newString": { "type": [ "string", "null" ], "description": "Replacement text for `stringReplace`. Ignored for other actions." }, "replaceAll": { "type": "boolean", "description": "Whether to replace all occurrences (`stringReplace` only, default false)." }, "sectionVersion": { "type": "integer", "format": "int64", "description": "Expected document version for optimistic concurrency.", "minimum": 0 } } }, "Effort": { "type": "string", "description": "Reasoning depth and overall token spend.\n\nLower values reduce latency and cost; higher values give the model more\nroom to reason before responding. `Max` is supported only on the most\ncapable tier and may produce diminishing returns.", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "EnterpriseMembershipBlocker": { "type": "object", "description": "Identifier and label for an Enterprise membership blocking account\ndeletion.", "required": [ "companyId", "companyName", "reason" ], "properties": { "companyId": { "$ref": "#/components/schemas/TypedId", "description": "Company identifier of the Enterprise workspace." }, "companyName": { "type": "string", "description": "Display name of the Enterprise workspace." }, "reason": { "type": "string", "description": "Stable i18n key describing why this membership blocks deletion." } } }, "EntityType": { "type": "string", "description": "Discriminator for connection entity identity.", "enum": [ "human", "agent" ] }, "ExecutionTrace": { "type": "object", "description": "Complete execution trace for debugging and eval analysis.\n\nCaptures per-iteration details of the LLM tool-calling loop: token usage,\nfinish reasons, tool call records, and timing. Persisted to S3 when\n`include_trace` is set on the invoke request.", "required": [ "iterations", "totalDurationMs", "model" ], "properties": { "iterations": { "type": "array", "items": { "$ref": "#/components/schemas/IterationRecord" }, "description": "Per-iteration records (one per LLM round-trip)." }, "model": { "$ref": "#/components/schemas/Model", "description": "Model used for this execution." }, "totalDurationMs": { "type": "integer", "format": "int64", "description": "Total wall-clock duration of execution (ms).", "minimum": 0 } } }, "FailedAgentInfo": { "type": "object", "description": "Information about an agent `@mention` that failed before task creation.", "required": [ "agentName", "reason" ], "properties": { "agentName": { "type": "string", "description": "Display name of the mentioned agent." }, "reason": { "$ref": "#/components/schemas/AgentInvokeFailReason", "description": "Why the invocation failed." } } }, "FavoritesResponse": { "type": "object", "description": "Response type for the GET/PUT favorites endpoints.", "required": [ "folderIds" ], "properties": { "documentIds": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of favorite document IDs." }, "folderIds": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of favorite folder IDs." }, "spaceIds": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of favorite Space IDs." } } }, "FeatureFlagsResponse": { "type": "object", "description": "Snapshot of every client-visible feature flag, evaluated for the\nrequesting user's context.\n\nThe wire shape is a fixed-key object: every field corresponds to\na flag whose state drives client behavior. Backend-only tuning\nflags (numeric thresholds, etc.) are intentionally excluded.\nUnknown fields from a newer server are silently ignored, so\nolder bundles stay forward-compatible.", "properties": { "attribution": { "oneOf": [ { "$ref": "#/components/schemas/BoolFlag", "description": "Document attribution / \"blame\" feature. Gates the attribution\nview in the editor and the supporting API endpoints." } ], "default": { "enabled": false } }, "exampleToggle": { "oneOf": [ { "$ref": "#/components/schemas/BoolFlag", "description": "Starter bool flag used to exercise the feature flag pipeline\nend-to-end." } ], "default": { "enabled": false } }, "reviewConsoleEnabled": { "oneOf": [ { "$ref": "#/components/schemas/BoolFlag", "description": "Per-document Review Console surface. When off, the\n`/review-console` route 404s and every Console API endpoint\nreturns 404 — the route is invisible, not forbidden." } ], "default": { "enabled": false } } } }, "FeatureGateErrorDetails": { "type": "object", "description": "Structured details for feature-gate enforcement errors.", "required": [ "feature", "requiredPlan", "currentPlan" ], "properties": { "currentPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "The effective billing plan at enforcement time." }, "feature": { "$ref": "#/components/schemas/GatedFeature", "description": "Which feature was blocked." }, "requiredPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "Minimum plan required for this feature." } } }, "FidelityLossResponse": { "type": "object", "description": "Wire representation of a single fidelity-loss annotation.", "required": [ "kind", "note" ], "properties": { "kind": { "type": "string", "description": "Category of the loss." }, "note": { "type": "string", "description": "Short human-readable description." } } }, "FinalizeTeamUpgradeRequest": { "type": "object", "description": "Request to finalize a personal-to-team upgrade after Stripe Checkout\nhas flipped the company onto the Team plan.\n\nCaptured by the post-checkout interstitial: the owner picks a vanity\nslug for the workspace and a display name for the depth-1 team tier\nnode. The handler atomically swaps the company slug, registers the\nvanity subdomain auth callbacks, and creates the team tier so a\nreturning admin reaches the new workspace at\n`https://{slug}.{base}` without the chicken-and-egg of choosing a\nslug on the wrong host.", "required": [ "teamName", "slug" ], "properties": { "slug": { "type": "string", "description": "Requested vanity slug for the workspace. Must satisfy the slug\nformat rules (lowercase alphanumeric and hyphens, 3-50 chars,\nno leading or trailing hyphen)." }, "teamName": { "type": "string", "description": "Display name of the new team — used to label the depth-1 tier\nnode created under the company." } } }, "FinalizeTeamUpgradeResponse": { "type": "object", "description": "Response from the upgrade-finalize handler. Echoes the slug the\ncompany will be reached at after the redirect — identical to the\nrequested slug on the happy path, equal to the still-current slug on\na safe replay (`upgradeFinalized == true` and the requested slug\nmatches what was previously committed).", "required": [ "newSlug" ], "properties": { "newSlug": { "type": "string", "description": "The vanity slug the workspace is now reachable at. The client\nshould redirect the owner to `https://{newSlug}.{base}/app`." } } }, "FirstTimeUserStep": { "type": "string", "description": "Step keys for the first-time-user wizard.\n\nClosed enum — server rejects any string outside this set so a\ndrifted client cannot record progress against an unknown step.", "enum": [ "mcp-setup", "spaces", "prompts", "agents", "ai-chat" ] }, "FolderAccessGrantResponse": { "type": "object", "description": "Response for a folder access grant.", "required": [ "userId", "role", "grantedBy", "grantedAt" ], "properties": { "grantedAt": { "type": "string", "format": "date-time", "description": "When access was granted." }, "grantedBy": { "type": "string", "description": "Who granted access." }, "role": { "$ref": "#/components/schemas/ResourceRole", "description": "Assigned role." }, "userId": { "type": "string", "description": "User ID." } } }, "FolderKind": { "type": "string", "description": "Folder kind — distinguishes standard document folders from skill folders\nconforming to the [agentskills.io](https://agentskills.io/specification) spec,\nfrom memory folders containing a user's persistent assistant memory,\nfrom prompt folders containing reusable prompt templates, and from\nagent folders containing user-authored custom agent definitions.\n\nSerialized as lowercase: `\"standard\"`, `\"skill\"`, `\"memory\"`, `\"prompt\"`,\n`\"agents\"`.", "enum": [ "standard", "skill", "memory", "prompt", "agents" ] }, "FolderPathSegment": { "type": "object", "description": "A segment of a folder breadcrumb path (root → leaf).\n\nUsed in search results to show document location context without\nrequiring a separate folder lookup.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Folder ID." }, "name": { "type": "string", "description": "Folder display name." } } }, "FolderResponse": { "type": "object", "required": [ "id", "name", "path", "scope", "kind", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/FolderKind" }, "name": { "type": "string" }, "parentFolderId": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "root": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FolderRoot", "description": "Platform-provisioned root marker, when present. Frontend uses this\nflag to suppress rename/delete/move and render the appropriate icon\n(home for personal, brain for memory). `None` = regular folder." } ] }, "scope": { "$ref": "#/components/schemas/ScopeId", "description": "Typed scope (`kind` + `id`) — immutable post-creation." }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FolderRoot": { "type": "string", "description": "Tagged role of an auto-provisioned root folder. `None` means a regular\nuser-created folder; `Some(variant)` marks the folder as non-deletable,\nnon-renameable, non-movable and, in the frontend, specially rendered.\n\nReplaces the earlier triple of `is_personal_root` / `is_memory_root` /\n`is_memory_entries_root` booleans — having a single tagged enum makes\ninvalid combinations (e.g. a folder flagged as both personal and memory\nroot) unrepresentable.", "enum": [ "personal", "memory", "memoryEntries", "prompts", "agents" ] }, "ForceRevokeResponse": { "type": "object", "description": "Response for the kind-keyed force-revoke endpoint.", "required": [ "revokedCount" ], "properties": { "revokedCount": { "type": "integer", "format": "int32", "description": "Number of grants deleted.", "minimum": 0 } } }, "FreeProviderEntry": { "type": "object", "description": "One entry in the free-email-provider allowlist.", "required": [ "domain", "addedBy", "addedAt" ], "properties": { "addedAt": { "type": "string", "format": "date-time", "description": "When the entry was added." }, "addedBy": { "$ref": "#/components/schemas/TypedId", "description": "Platform-operator user who added the entry." }, "domain": { "type": "string", "description": "Canonical registrable domain (lowercase Punycode)." }, "note": { "type": [ "string", "null" ], "description": "Optional free-form rationale shown in the operator UI." } } }, "FrontmatterError": { "oneOf": [ { "type": "object", "description": "The leading YAML block was not present, was malformed, or the\nfields did not match the expected schema. `message` is the parser\nerror string, intended for display in the editor banner.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "The leading YAML block was not present, was malformed, or the\nfields did not match the expected schema. `message` is the parser\nerror string, intended for display in the editor banner.", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable description of what went wrong." } } }, "kind": { "type": "string", "enum": [ "invalidFrontmatter" ] } } }, { "type": "object", "description": "The `name` slug collides with another of the user's existing\nprompts. The extractor still computes a deterministic deduped\nslug (`slug-2`, `-3`, …) but flags the collision so the author\ncan disambiguate the source `name`.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "The `name` slug collides with another of the user's existing\nprompts. The extractor still computes a deterministic deduped\nslug (`slug-2`, `-3`, …) but flags the collision so the author\ncan disambiguate the source `name`.", "required": [ "slug", "conflictId" ], "properties": { "conflictId": { "$ref": "#/components/schemas/TypedId", "description": "ID of the other prompt holding the colliding slug." }, "slug": { "type": "string", "description": "Slug the extractor settled on after dedup." } } }, "kind": { "type": "string", "enum": [ "slugCollision" ] } } }, { "type": "object", "description": "One or more `{{placeholder}}` tokens in the body do not match\nany declared argument. Non-fatal — the prompt still renders, but\nthe editor surfaces a warning and the placeholder picks up the\n\"unknown\" decoration class. Names are deduplicated and ordered as\nthey first appear in the body.", "required": [ "details", "kind" ], "properties": { "details": { "type": "object", "description": "One or more `{{placeholder}}` tokens in the body do not match\nany declared argument. Non-fatal — the prompt still renders, but\nthe editor surfaces a warning and the placeholder picks up the\n\"unknown\" decoration class. Names are deduplicated and ordered as\nthey first appear in the body.", "required": [ "names" ], "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Placeholder names that appeared in the body but were not\ndeclared in `arguments`." } } }, "kind": { "type": "string", "enum": [ "undeclaredPlaceholders" ] } } } ], "description": "Reasons a prompt document's frontmatter cannot be used as-is. Each\nvariant is reported alongside the prompt in [`PromptMetadata`] so the\neditor can render a banner and slash-picker / MCP / agent surfaces\ncan drop the prompt from their listings." }, "GateConsumeResponse": { "type": "object", "description": "Resume payload returned by `/api/v1/gate/consume`. Matches what\nthe post-auth dispatcher needs to fire the deferred action.", "required": [ "returnTo", "intent", "documentId", "title", "createdAt" ], "properties": { "createdAt": { "type": "integer", "format": "int64", "description": "Unix millisecond timestamp at issue time. Forwarded so the\ndispatcher's funnel telemetry can measure click→delivery\nlatency across the signup hop." }, "documentId": { "type": "string", "description": "Document id for the action." }, "intent": { "$ref": "#/components/schemas/ConversionIntent", "description": "Intent to resume." }, "returnTo": { "type": "string", "description": "Public-document URL to navigate back to before resuming." }, "title": { "type": "string", "description": "Document title for the resume UX." } } }, "GateIssueRequest": { "type": "object", "description": "Plant a signed conversion-gate cookie for the visitor.\n\nThe cookie envelope carries enough state for the post-auth\ndispatcher on the workspace surface to resume the action the\nvisitor was trying to take when they bounced through signup.\nAnonymous endpoint — anyone can plant a gate cookie. The\ndestination action enforces its own permissions; the gate is\nnavigation intent, not an auth credential.", "required": [ "returnTo", "intent", "documentId", "title" ], "properties": { "documentId": { "type": "string", "description": "Document id (`doc_…` ULID). Carried explicitly so the\npost-auth dispatcher can fire the action regardless of which\n`returnTo` URL shape the visitor came in on. Validated against\nthe ULID shape server-side." }, "intent": { "$ref": "#/components/schemas/ConversionIntent", "description": "Intent to resume after the visitor signs in." }, "returnTo": { "type": "string", "description": "Public-document URL the visitor came from. Whitelisted on the\nserver: only the `/d/{docId}`, `/@{handle}/{slug}`, and\n`/public/{token}` shapes are accepted. Arbitrary URLs are\nrejected so the gate cannot be abused to redirect users\noff-site after sign-in." }, "title": { "type": "string", "description": "Document title — used as the downloaded PDF's filename and\nthe assistant starter copy on remix." } } }, "GateIssueResponse": { "type": "object", "description": "Empty success response — the meaningful payload is the\n`Set-Cookie` header.", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "description": "Always `true` on success. Present so SDK consumers have a\ndeterministic shape to assert on; the cookie is the\nload-bearing part." } } }, "GatedActionError": { "type": "object", "description": "Error payload returned when an anonymous caller hits a route that\nrequires authentication, or exceeds a per-session cap.\n\n`action` is a stable identifier the client maps to per-action signup\ncopy. HTTP status is the source of truth on the response line; the\n`httpStatus` field mirrors it for clients that read the body first.", "required": [ "action", "httpStatus", "message" ], "properties": { "action": { "type": "string", "description": "Stable id matching a client-side gated-action registry entry.\n\nExamples: `ai.chat.send`, `export.pdf`, `publish.publish`,\n`continue_editing`, `mcp.authorize`, `unknown`." }, "httpStatus": { "type": "integer", "format": "int32", "description": "HTTP status the response is sent with (403 for gated, 429 for\ncap-exceeded). Mirrors the response status line.", "minimum": 0 }, "message": { "type": "string", "description": "Human-readable fallback message. Clients prefer the i18n key\nkeyed off `action`; this is shown only when the registry does\nnot recognize the action." } } }, "GatedFeature": { "type": "string", "description": "Feature that requires a minimum billing plan tier.", "enum": [ "sso", "scim", "domainVerification", "legalHolds", "siemWebhooks", "auditExport", "guestAccess", "auditTrail" ] }, "GeoResponse": { "type": "object", "description": "Geo lookup response used by the marketing site to decide banner display.", "properties": { "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code, when known." } } }, "GetSessionResponse": { "type": "object", "description": "Response for getting a session with its messages.", "required": [ "session", "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageResponse" }, "description": "Messages in this session, ordered by sequence." }, "session": { "$ref": "#/components/schemas/SessionResponse", "description": "Session metadata." } } }, "GrantAccessRequest": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/ResourceRole" } } }, "GrantAccessResponse": { "oneOf": [ { "type": "object", "description": "An access grant was written immediately.", "required": [ "grant", "status" ], "properties": { "grant": { "$ref": "#/components/schemas/AccessEntryResponse", "description": "The new access entry." }, "status": { "type": "string", "enum": [ "granted" ] } } }, { "type": "object", "description": "A pending invitation was created; the recipient will gain access on\ntheir next sign-in.", "required": [ "invite", "status" ], "properties": { "invite": { "$ref": "#/components/schemas/DocumentInviteResponse", "description": "The pending invitation." }, "status": { "type": "string", "enum": [ "invited" ] } } } ], "description": "Response for `POST /api/documents/{docId}/access`.\n\nDistinguishes between immediate grant (target resolved to an in-tenant\nuser) and pending invitation (target was external and the sharing policy\nallowed sending an invite)." }, "GrantFolderAccessRequest": { "type": "object", "description": "Request body for granting folder access.", "required": [ "userId", "role" ], "properties": { "role": { "$ref": "#/components/schemas/ResourceRole", "description": "Role to assign (must be `editor`)." }, "userId": { "type": "string", "description": "User ID to grant access to." } } }, "GrantForKindEntry": { "type": "object", "description": "A single user grant entry in the admin grants-for-kind view.", "required": [ "userId", "state", "grantedAt" ], "properties": { "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the grant expires (`null` if it does not expire)." }, "grantedAt": { "type": "string", "format": "date-time", "description": "When the grant was issued." }, "state": { "$ref": "#/components/schemas/GrantStatus", "description": "Current grant lifecycle state." }, "userId": { "type": "string", "description": "User who holds the grant." } } }, "GrantSpaceAccessRequest": { "type": "object", "description": "Request to grant access to a Space.", "required": [ "principalType", "principalId", "grantLevel" ], "properties": { "grantLevel": { "$ref": "#/components/schemas/SpaceGrantLevel", "description": "Access level to grant." }, "principalId": { "type": "string", "description": "ID of the user or team." }, "principalType": { "$ref": "#/components/schemas/SpaceGrantPrincipalType", "description": "Type of principal (user or team). `scopeDefault` is system-managed." } } }, "GrantStatus": { "type": "string", "description": "Status of a per-user grant for user-delegated connectors.", "enum": [ "active", "revoked", "expired" ] }, "GuestAccessResponse": { "type": "object", "description": "Guest access API response.", "required": [ "email", "maxRole", "invitedBy", "invitedAt" ], "properties": { "email": { "type": "string", "description": "Guest's email address" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When guest access expires" }, "invitedAt": { "type": "string", "format": "date-time", "description": "When the guest was invited" }, "invitedBy": { "type": "string", "description": "Who invited this guest" }, "maxRole": { "$ref": "#/components/schemas/ResourceRole", "description": "Maximum role for the guest" }, "userId": { "type": [ "string", "null" ], "description": "User ID if the guest has a Strata account" } } }, "Handle": { "type": "string", "description": "Globally unique user handle for profile URLs (`/@{handle}`).\n\nValidation rules:\n- 3-30 characters\n- Lowercase alphanumeric + hyphens only\n- No leading/trailing hyphens\n- No consecutive hyphens\n- Not a reserved word" }, "HandleAvailabilityResponse": { "type": "object", "description": "Response for handle availability check.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "Whether the handle is available." }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HandleUnavailableReason", "description": "Typed reason the handle is unavailable (absent when `available == true`)." } ] } } }, "HandleUnavailableReason": { "type": "string", "description": "Why a candidate handle is not currently available for registration.\n\nReturned by the handle-availability check so the UI can render a localized\nreason per variant without string-matching backend output. Each variant\nmaps 1:1 to an i18n key under `profile:handleUnavailable.*`.", "enum": [ "reserved", "tooShort", "tooLong", "invalidCharacters", "taken", "takenRecently" ] }, "HealthResponse": { "type": "object", "required": [ "status", "version" ], "properties": { "status": { "type": "string" }, "valkey": { "type": [ "string", "null" ], "description": "Valkey relay connection status (`\"connected\"`, `\"degraded\"`, or `\"disabled\"`)." }, "version": { "type": "string" } } }, "HierarchyDefinition": { "type": "object", "description": "A company-level configuration specifying the ordered list of middle tiers.\n\nImmutable after confirmation, except for per-tier mutable fields\n(`name`, `admin_cascade`, `switch_requires_mfa`).", "required": [ "tiers" ], "properties": { "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/HierarchyTier" }, "description": "Ordered tiers. Length must be 1..=6. Each tier's `depth` must equal\nits index. Each tier's `id` must be unique." } } }, "HierarchyResponse": { "type": "object", "description": "Response for `GET` and `POST /api/companies/{companyId}/hierarchy`.", "required": [ "tiers", "isDefault" ], "properties": { "isDefault": { "type": "boolean", "description": "Whether this definition was explicitly set or is the default." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HierarchyStatus", "description": "`None` for default hierarchies, `Some(Confirmed)` for explicitly set ones." } ] }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/HierarchyTier" }, "description": "Ordered list of hierarchy tiers." } } }, "HierarchyStatus": { "type": "string", "description": "Status of a company's hierarchy definition.", "enum": [ "confirmed" ] }, "HierarchyTemplate": { "type": "object", "description": "A named hierarchy preset for the onboarding wizard.", "required": [ "id", "name", "description", "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/HierarchyDefinition", "description": "The hierarchy definition this template provides." }, "description": { "type": "string", "description": "Short description." }, "id": { "type": "string", "description": "Template identifier (e.g. `\"flat\"`, `\"standard\"`, `\"regional\"`)." }, "name": { "type": "string", "description": "Human-readable name." } } }, "HierarchyTier": { "type": "object", "description": "A single level in a [`HierarchyDefinition`].\n\nEmbedded within the definition — not a standalone record.", "required": [ "id", "name", "depth", "roleTemplate", "adminCascade" ], "properties": { "adminCascade": { "type": "boolean", "description": "Whether admin roles cascade to descendant tiers." }, "depth": { "type": "integer", "format": "int32", "description": "Position in hierarchy (0 = directly under Company). Must equal array index.", "minimum": 0 }, "id": { "$ref": "#/components/schemas/TypedId", "description": "Stable slug identifier (immutable after creation)." }, "name": { "type": "string", "description": "Display name (mutable)." }, "roleTemplate": { "$ref": "#/components/schemas/RoleTemplate", "description": "Which roles are valid for memberships at this tier." }, "switchRequiresMfa": { "type": "boolean", "description": "Whether switching to this tier's nodes requires MFA verification." } } }, "HistoryDiffResponse": { "type": "object", "description": "Response for the history diff endpoint.", "required": [ "documentId", "afterSequenceId", "blockDiffs", "stats" ], "properties": { "afterSequenceId": { "type": "string", "description": "Sequence ID of the \"after\" state." }, "beforeSequenceId": { "type": [ "string", "null" ], "description": "Sequence ID of the \"before\" state (absent when comparing against empty doc)." }, "blockDiffs": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDiffEntry" }, "description": "Per-block diffs (only changed blocks)." }, "documentId": { "type": "string", "description": "Document ID." }, "stats": { "$ref": "#/components/schemas/DiffStats", "description": "Aggregate change statistics." } } }, "HistoryEntryResponse": { "type": "object", "description": "A grouped entry in a document's edit history.\n\nConsecutive WAL records from the same actor within a 60-second window are\ncollapsed into a single entry.", "required": [ "sequenceId", "lastSequenceId", "actorId", "actorType", "actionSummary", "actions", "operationCount", "timestamp", "lastTimestamp" ], "properties": { "actionSummary": { "type": "string", "description": "Human-readable summary (e.g. \"Edited document\")." }, "actions": { "type": "array", "items": { "type": "string" }, "description": "Distinct action names in this group (e.g. `[\"append\", \"stringReplace\"]`)." }, "actorDisplayName": { "type": [ "string", "null" ], "description": "Display name of the actor (enriched at query time)." }, "actorId": { "type": "string", "description": "User ID of the actor who made these edits." }, "actorType": { "$ref": "#/components/schemas/EntityType", "description": "Whether the actor is \"human\" or \"agent\"." }, "lastSequenceId": { "type": "string", "description": "Sequence ID of the last WAL record in this group." }, "lastTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the last WAL record in this group." }, "onBehalfOf": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnBehalfOfActor", "description": "Secondary actor when the primary acted on behalf of someone else.\n\nToday this is set when the primary is an agent invoked through\nMCP and the secondary is the human user who authorized the call.\nClients should render the pair as\n`{actorDisplayName} ({onBehalfOf.email or .displayName})`." } ] }, "operationCount": { "type": "integer", "format": "int32", "description": "Number of individual WAL records in this group.", "minimum": 0 }, "sequenceId": { "type": "string", "description": "Sequence ID of the first WAL record in this group." }, "stats": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DiffStats", "description": "Approximate diff stats derived from WAL action types.\n\n`None` for `replaceAll`-only entries where per-block stats cannot be\nderived without full reconstruction." } ] }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the first WAL record in this group." } } }, "HistoryPreviewResponse": { "type": "object", "description": "Preview of a document at a specific point in its history.", "required": [ "documentId", "sequenceId", "title", "actorId", "timestamp", "blocks" ], "properties": { "actorDisplayName": { "type": [ "string", "null" ], "description": "Display name of the actor (if available)." }, "actorId": { "type": "string", "description": "User ID of the actor who made this edit." }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockResponse" }, "description": "Sections extracted from the reconstructed `ProseMirror` JSON." }, "documentId": { "type": "string", "description": "Document ID." }, "onBehalfOf": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnBehalfOfActor", "description": "Secondary actor when the primary acted on behalf of someone else.\nSee [`HistoryEntryResponse::on_behalf_of`]." } ] }, "rawContent": { "type": "object", "description": "Raw `ProseMirror` JSON document at this point in history." }, "sequenceId": { "type": "string", "description": "Sequence ID of the WAL record this preview is reconstructed to." }, "timestamp": { "type": "string", "description": "Timestamp of the WAL record." }, "title": { "type": "string", "description": "Document title at that point." } } }, "HoldTargetType": { "type": "string", "description": "Target type for a legal hold", "enum": [ "document" ] }, "IdpMappingResponse": { "type": "object", "description": "`IdP` group mapping API response.", "required": [ "id", "scimGroupId", "scimGroupName", "targetNodeId", "targetNodeName", "tierRole", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the mapping was created" }, "id": { "type": "string", "description": "Mapping identifier" }, "scimGroupId": { "type": "string", "description": "SCIM group identifier" }, "scimGroupName": { "type": "string", "description": "SCIM group display name" }, "targetNodeId": { "type": "string", "description": "Target tier node identifier" }, "targetNodeName": { "type": "string", "description": "Target tier node name" }, "tierRole": { "$ref": "#/components/schemas/TierRole", "description": "Role assigned to group members in the target tier node" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the mapping was last updated" } } }, "ImageId": { "type": "string", "description": "A content-addressed image identifier (SHA256 hex digest, 64 characters).\n\nUnlike ULID-based identifiers, `ImageId` is derived from the uploaded\nfile's content hash, enabling per-tenant deduplication." }, "ImageUploadResponse": { "type": "object", "description": "Response returned after a successful image upload.", "required": [ "imageId", "width", "height", "sizeBytes", "mimeType" ], "properties": { "height": { "type": "integer", "format": "int32", "description": "Transcoded image height.", "minimum": 0 }, "imageId": { "$ref": "#/components/schemas/ImageId", "description": "Content-hash identifier." }, "mimeType": { "type": "string", "description": "MIME type of the stored file." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "Stored file size in bytes.", "minimum": 0 }, "width": { "type": "integer", "format": "int32", "description": "Transcoded image width.", "minimum": 0 } } }, "ImportAnonWorkspaceOutcome": { "type": "string", "description": "Outcome of an anonymous-workspace import attempt.\n\n`migrated` indicates a fresh successful migration. `alreadyMigrated`\nindicates the same identity has migrated this session before; the\nresponse carries the existing migrated document id. `noAnonSession`\nindicates the caller did not present a live anonymous-session cookie\n(cookie absent, expired, or already cleared) — the caller should\nproceed with an empty authenticated workspace.", "enum": [ "migrated", "alreadyMigrated", "noAnonSession" ] }, "ImportAnonWorkspaceResponse": { "type": "object", "description": "Response body for the anonymous-workspace import endpoint.\n\n`docId` is the id of the now-migrated document. The field is omitted\nfrom the response when the outcome is `noAnonSession` (nothing to\nmigrate); for `migrated` and `alreadyMigrated` it is always present.", "required": [ "outcome" ], "properties": { "docId": { "type": [ "string", "null" ], "description": "Migrated document id. Present for `migrated` and\n`alreadyMigrated`; omitted from the response for `noAnonSession`." }, "outcome": { "$ref": "#/components/schemas/ImportAnonWorkspaceOutcome", "description": "Outcome of the migration call." } } }, "ImportFromConnectorRequest": { "type": "object", "description": "Request body for importing an external resource as a Space document.", "required": [ "kind", "resourceUri" ], "properties": { "kind": { "type": "string", "description": "Connector kind slug (e.g. `notion`, `slack`, `google-drive`)." }, "resourceUri": { "type": "string", "description": "Canonical identifier of the resource within the source app." }, "title": { "type": [ "string", "null" ], "description": "Optional title override. When present the adapter-derived title is\ndiscarded in favour of this value." } } }, "ImportFromConnectorResponse": { "type": "object", "description": "Response body for the import endpoint.", "required": [ "docId", "importOutcome", "source" ], "properties": { "docId": { "type": "string", "description": "The document that was created or already existed." }, "importOutcome": { "$ref": "#/components/schemas/ImportOutcome", "description": "What the import operation did." }, "source": { "$ref": "#/components/schemas/ImportSourceResponse", "description": "Provenance detail for the document." } } }, "ImportOutcome": { "type": "string", "description": "Outcome of an import operation.", "enum": [ "created", "refreshed", "noChange" ] }, "ImportSourceResponse": { "type": "object", "description": "Portable, JSON-safe rendering of a `DocumentSource` for the import response.", "required": [ "connectorKind", "resourceUri", "importedBy", "importedAt", "contentHash", "sourceStatus" ], "properties": { "connectorKind": { "type": "string", "description": "Connector kind that produced the document." }, "contentHash": { "type": "string", "description": "Hex-encoded SHA-256 of the canonical source bytes." }, "externalUrl": { "type": [ "string", "null" ], "description": "Human-openable URL pointing back at the source, when available." }, "fidelity": { "type": "array", "items": { "$ref": "#/components/schemas/FidelityLossResponse" }, "description": "Fidelity-loss annotations recorded by the adapter." }, "importedAt": { "type": "string", "description": "RFC 3339 timestamp of the first import." }, "importedBy": { "type": "string", "description": "User who triggered the original import." }, "lastRefreshedAt": { "type": [ "string", "null" ], "description": "RFC 3339 timestamp of the last successful refresh, if any." }, "lastStalenessCheckedAt": { "type": [ "string", "null" ], "description": "RFC 3339 timestamp of the last staleness check, if any. The\nclient uses this with a 5-minute threshold to decide whether to\nre-probe the upstream on document open." }, "resourceUri": { "type": "string", "description": "Canonical identifier of the external resource." }, "sourceStatus": { "type": "string", "description": "Current relationship to the upstream source (`fresh`, `stale`,\n`unavailable`, `unknown`)." }, "unavailableReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StalenessUnavailableReason", "description": "Present only when `sourceStatus = unavailable`. Carries the\nmachine-readable reason so UIs can pick the right i18n key." } ] } } }, "InaccessibleSource": { "type": "object", "description": "A source that the user does not have read access to.", "required": [ "sourceType", "id" ], "properties": { "id": { "type": "string", "description": "Entity identifier." }, "sourceType": { "type": "string", "description": "Source type: `\"space\"`, `\"document\"`, or `\"folder\"`." } } }, "IntegrationDetail": { "type": "object", "description": "Full admin detail view for a single integration (connector kind) in a\ncompany. Returned by the integrations list and individual policy mutation\nendpoints.", "required": [ "kind", "mode", "credentialMode", "policyState", "killSwitchEngaged", "activeGrantCount", "pendingAccessRequestCount" ], "properties": { "activeGrantCount": { "type": "integer", "format": "int32", "description": "Number of active personal grants held by company members.", "minimum": 0 }, "byoOauthApp": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ByoOauthAppDetail", "description": "BYO `OAuth` app override in effect for this kind, if any." } ] }, "credentialMode": { "$ref": "#/components/schemas/ConnectorCredentialMode", "description": "Credential mode preference." }, "description": { "type": [ "string", "null" ], "description": "One-line description." }, "displayName": { "type": [ "string", "null" ], "description": "Human-readable display name." }, "killSwitchEngaged": { "type": "boolean", "description": "Whether the per-kind kill switch is currently engaged." }, "kind": { "type": "string", "description": "Connector kind identifier." }, "mcpManifest": { "description": "Cached MCP manifest (only set for `mode == mcp`)." }, "mcpManifestReviewedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the MCP manifest was last reviewed (`null` for non-MCP kinds)." }, "mcpUrl": { "type": [ "string", "null" ], "description": "Registration URL for custom MCP servers (only set for `custom-mcp-*` kinds)." }, "mode": { "$ref": "#/components/schemas/ConnectorMode", "description": "Dispatch mode." }, "pendingAccessRequestCount": { "type": "integer", "format": "int32", "description": "Number of pending access requests from company members.", "minimum": 0 }, "policyState": { "$ref": "#/components/schemas/AdminPolicyState", "description": "Admin-visible policy state for this kind." }, "serviceAccount": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceAccountDetail", "description": "Company-level service-account credential status, if applicable." } ] } } }, "IntegrationsListResponse": { "type": "object", "description": "Response for `GET /api/v1/companies/{companyId}/integrations`.", "required": [ "integrations" ], "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationDetail" }, "description": "One entry per connector kind known to the registry." } } }, "InternalDomainVerificationResponse": { "type": "object", "description": "Response for internally initiated domain verification.", "required": [ "domain", "verificationToken", "expiresAt" ], "properties": { "domain": { "type": "string", "description": "The domain being verified." }, "expiresAt": { "type": "string", "description": "When the verification token expires (RFC 3339)." }, "verificationToken": { "type": "string", "description": "DNS TXT record value to publish." } } }, "InternalEntityResponse": { "type": "object", "description": "Minimal response for internally created entities.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Created entity identifier." }, "name": { "type": "string", "description": "Human-readable name." } } }, "InviteCompanyMemberRequest": { "type": "object", "description": "Request to invite a member to a company by email.", "required": [ "email", "role", "orgId" ], "properties": { "email": { "type": "string", "description": "Invitee's email address" }, "orgId": { "type": "string", "description": "Organization to add the user to on acceptance" }, "orgRole": { "$ref": "#/components/schemas/TierRole", "description": "Organization-level role to assign on acceptance" }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Company-level role to assign when the invitation is accepted" }, "teamIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional team IDs to assign the invitee to upon acceptance." } } }, "InviteGuestRequest": { "type": "object", "description": "Request to invite a guest.", "required": [ "email", "maxRole" ], "properties": { "email": { "type": "string", "description": "Guest's email address" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When guest access expires (optional)" }, "maxRole": { "$ref": "#/components/schemas/ResourceRole", "description": "Maximum role for the guest" } } }, "InviteResult": { "type": "object", "description": "Result of processing a single email in a batch invitation.", "required": [ "email", "status" ], "properties": { "email": { "type": "string", "description": "The email address" }, "status": { "$ref": "#/components/schemas/InviteStatus", "description": "Outcome for this email" } } }, "InviteStatus": { "type": "string", "description": "Per-email outcome of a batch invitation.", "enum": [ "sent", "alreadyMember", "alreadyInvited", "invalidEmail", "failed", "selfInvite" ] }, "InvoiceSummary": { "type": "object", "description": "Summary of a single invoice.", "required": [ "id", "date", "amountDue", "currency", "status" ], "properties": { "amountDue": { "type": "integer", "format": "int64", "description": "Amount due in smallest currency unit (cents for USD)." }, "currency": { "type": "string", "description": "Three-letter ISO currency code." }, "date": { "type": "string", "format": "date-time", "description": "Invoice date." }, "id": { "type": "string", "description": "Stripe Invoice ID." }, "pdfUrl": { "type": [ "string", "null" ], "description": "URL to download the invoice PDF." }, "status": { "type": "string", "description": "Invoice status (e.g., \"paid\", \"open\", \"void\")." } } }, "InvokeAgentRequest": { "type": "object", "description": "Request to invoke an agent.", "required": [ "instruction" ], "properties": { "documentId": { "type": [ "string", "null" ], "description": "Target document ID (optional)." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key (optional)." }, "includeTrace": { "type": [ "boolean", "null" ], "description": "Whether to capture and persist the execution trace (opt-in)." }, "instruction": { "type": "string", "description": "Natural-language instruction." } } }, "InvokeResponse": { "type": "object", "description": "Invoke response.", "required": [ "taskId", "cached" ], "properties": { "cached": { "type": "boolean" }, "taskId": { "type": "string" } } }, "IterationRecord": { "type": "object", "description": "Single LLM round-trip within the executor loop.", "required": [ "index", "durationMs", "inputTokens", "outputTokens", "finishReason" ], "properties": { "assistantText": { "type": [ "string", "null" ], "description": "Text content produced by the model (reasoning/response)." }, "cacheReadTokens": { "type": "integer", "format": "int64", "description": "Cache read tokens (if prompt caching enabled).", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "description": "Cache write tokens.", "minimum": 0 }, "durationMs": { "type": "integer", "format": "int64", "description": "Wall-clock duration of this iteration (ms).", "minimum": 0 }, "finishReason": { "type": "string", "description": "How the LLM decided to end this turn (e.g. `stop`, `tool_use`, `max_tokens`)." }, "index": { "type": "integer", "format": "int32", "description": "0-based iteration index.", "minimum": 0 }, "inputTokens": { "type": "integer", "format": "int64", "description": "Input tokens consumed in this iteration.", "minimum": 0 }, "outputTokens": { "type": "integer", "format": "int64", "description": "Output tokens produced in this iteration.", "minimum": 0 }, "toolCalls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallRecord" }, "description": "Tool calls made in this iteration (empty if `finish_reason` = stop)." } } }, "JoinPolicy": { "type": "string", "description": "Whether users on a verified-claimed domain join the company\nautomatically on signup or wait for an admin to grant access.", "enum": [ "autoJoin", "requestAccess" ] }, "LeaveWorkspaceConfirmation": { "type": "string", "description": "Confirmation token for workspace leave.", "enum": [ "leaveWorkspace" ] }, "LeaveWorkspaceRequest": { "type": "object", "description": "Body of `POST /api/v1/companies/{companyId}/leave`.", "required": [ "summaryVersion", "confirmation" ], "properties": { "confirmation": { "$ref": "#/components/schemas/LeaveWorkspaceConfirmation", "description": "Explicit confirmation enum." }, "summaryVersion": { "type": "string", "description": "Summary version returned by the lifecycle summary the actor\nreviewed." } } }, "LeaveWorkspaceResponse": { "type": "object", "description": "Response body of `POST /api/v1/companies/{companyId}/leave`.", "required": [ "operationId", "status", "workspaceId", "cleanupStats" ], "properties": { "cleanupStats": { "$ref": "#/components/schemas/WorkspaceLeaveCleanupStats", "description": "Per-step cleanup totals for the leaving member." }, "operationId": { "$ref": "#/components/schemas/TypedId", "description": "Idempotent lifecycle operation identifier." }, "status": { "$ref": "#/components/schemas/LifecycleOperationStatus", "description": "Final operation state." }, "workspaceId": { "$ref": "#/components/schemas/TypedId", "description": "Workspace the actor left." } } }, "LegalHoldResponse": { "type": "object", "description": "API response for a legal hold.", "required": [ "id", "tenantId", "targetType", "targetId", "placedBy", "reason", "placedAt" ], "properties": { "id": { "type": "string", "description": "Unique hold identifier" }, "placedAt": { "type": "string", "format": "date-time", "description": "When the hold was placed" }, "placedBy": { "type": "string", "description": "User ID who placed the hold" }, "reason": { "type": "string", "description": "Free-text reason for the hold" }, "targetId": { "type": "string", "description": "Document ID" }, "targetType": { "$ref": "#/components/schemas/HoldTargetType", "description": "Whether this hold targets a document" }, "tenantId": { "type": "string", "description": "Owning organization" } } }, "LifecycleCleanupStats": { "type": "object", "description": "Per-step cleanup counts emitted from a completed account-deletion\noperation.", "required": [ "workspacesLeft", "privateDocumentsDeleted", "sharedDocumentsRetained", "abandonedDocumentsDeleted", "membershipsRemoved", "sessionsRevoked" ], "properties": { "abandonedDocumentsDeleted": { "type": "integer", "format": "int32", "description": "Number of documents deleted because no active user remained.", "minimum": 0 }, "membershipsRemoved": { "type": "integer", "format": "int32", "description": "Total memberships removed.", "minimum": 0 }, "privateDocumentsDeleted": { "type": "integer", "format": "int32", "description": "Number of private documents deleted across all workspaces.", "minimum": 0 }, "sessionsRevoked": { "type": "integer", "format": "int32", "description": "Sessions revoked at the end of cleanup.", "minimum": 0 }, "sharedDocumentsRetained": { "type": "integer", "format": "int32", "description": "Number of shared documents retained for remaining active users.", "minimum": 0 }, "workspacesLeft": { "type": "integer", "format": "int32", "description": "Number of Free/Pro workspaces the user left during deletion.", "minimum": 0 } } }, "LifecycleErrorBody": { "type": "object", "description": "Structured error envelope for every lifecycle endpoint (account or\nworkspace surface). Matches the shapes defined in\n`contracts/account-lifecycle.openapi.yaml` and\n`contracts/workspace-lifecycle.openapi.yaml` — the union of both\nkeeps a single typed shape on the wire while only the fields that\napply to the rejecting surface are populated.", "required": [ "code", "message" ], "properties": { "action": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceLifecycleAction", "description": "Optional workspace lifecycle action discriminator when the\nerror refers to a specific workspace surface." } ] }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/AccountDeletionBlocker" }, "description": "Optional blocker list when the error originated from the\naccount-deletion summary path." }, "code": { "type": "string", "description": "Stable machine-readable error code (see\n`st_api_core::account_lifecycle::error_code`)." }, "message": { "type": "string", "description": "Human-readable explanation; clients SHOULD translate via the\nblocker `messageKey` or the `code` rather than rendering this\nraw." }, "state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceActionState", "description": "Optional workspace action state captured at rejection time." } ] } } }, "LifecycleOperationStatus": { "type": "string", "description": "Lifecycle-wide operation completion status.", "enum": [ "completed", "blocked", "retryableFailure" ] }, "ListAccessEntriesResponse": { "type": "object", "description": "Paginated list of access entries for a document.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AccessEntryResponse" }, "description": "Access entries." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListAccessRequestsForKindResponse": { "type": "object", "description": "Response for `GET .../integrations/{kind}/access-requests`.", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/AccessRequestEntry" }, "description": "Pending access request entries." } } }, "ListAgentToolsResponse": { "type": "object", "description": "Response body for `GET /api/v1/agents/tools`. Flat list, ordered to\nmatch the server's tool registry (alphabetical-by-name today, but\ncallers should not rely on order).", "required": [ "tools" ], "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/AgentToolListItem" }, "description": "Tools an agent's `tools:` allowlist may include." } } }, "ListAgentsResponse": { "type": "object", "description": "Paginated list response.", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentResponse" } }, "nextToken": { "type": [ "string", "null" ] } } }, "ListAiUsageEventsResponse": { "type": "object", "description": "Paginated AI usage ledger response.", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AiUsageEventResponse" }, "description": "Ledger events." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListAiUsageUsersResponse": { "type": "object", "description": "Admin response listing per-user AI usage for a billing cycle.", "required": [ "users", "companyUsage", "unattributedUsage" ], "properties": { "companyUsage": { "$ref": "#/components/schemas/MonthlyAiUsage", "description": "Authoritative company aggregate for reconciliation." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "unattributedUsage": { "$ref": "#/components/schemas/MonthlyAiUsage", "description": "Difference between company totals and summed user-attributed totals.\nSurfaces system/background consumption that has no member attribution." }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/AiUsageUserSummary" }, "description": "User-attributed summaries for this page." } } }, "ListAttachmentsResponse": { "type": "object", "description": "Response for listing attachments on a parent entity.", "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentResponse" }, "description": "The attachments belonging to the parent." } } }, "ListAuditExportsResponse": { "type": "object", "description": "List response for recent audit log exports.", "required": [ "exports" ], "properties": { "exports": { "type": "array", "items": { "$ref": "#/components/schemas/AuditExportStatusResponse" }, "description": "Up to 30 most recent exports, ordered by `createdAt` descending" }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListAuditLogsResponse": { "type": "object", "description": "Response body for the list audit events endpoint.", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "type": "object" }, "description": "Page of audit events, newest first." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque token to pass as `nextToken` in the next request, or `null` when exhausted." } } }, "ListBranchesResponse": { "type": "object", "description": "Response listing a user's available branches (depth-0 tier nodes).", "required": [ "branches" ], "properties": { "activeNodeId": { "type": [ "string", "null" ], "description": "Currently active branch (depth-0 node) if one is set." }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/BranchInfo" }, "description": "Branches the caller has a membership in, across all companies." } } }, "ListCommentsResponse": { "type": "object", "required": [ "comments", "unreadCount", "resolvedCount" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResponse" } }, "nextToken": { "type": [ "string", "null" ] }, "resolvedCount": { "type": "integer", "format": "int32", "description": "Number of resolved comment threads.", "minimum": 0 }, "unreadCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ListCompaniesResponse": { "type": "object", "description": "Paginated list of companies.", "required": [ "companies" ], "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyResponse" }, "description": "Companies the user belongs to." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListCompanyInvitationsResponse": { "type": "object", "description": "Paginated list of company invitations.", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInvitationResponse" }, "description": "Pending invitations." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListCompanyMembersResponse": { "type": "object", "description": "Paginated list of company members.", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMemberResponse" }, "description": "Members of the company." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListCompanyOrgsResponse": { "type": "object", "description": "Paginated list of organizations within a company.", "required": [ "organizations" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/OrgDetailResponse" }, "description": "Organizations in the company." } } }, "ListConnectorsResponse": { "type": "object", "description": "List of connector connections for a company.", "required": [ "connectors" ], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorConnectionResponse" }, "description": "Connection entries." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. `None` when the caller has walked\nthe full result set." } } }, "ListDocumentConnectionsQuery": { "type": "object", "description": "Query parameters for listing document connections.", "properties": { "direction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionDirection", "description": "Filter by direction relative to the document." } ] } } }, "ListDocumentConnectionsResponse": { "type": "object", "description": "Response containing a list of document connections.", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentConnectionResponse" }, "description": "The connections for the requested document." } } }, "ListDocumentInvitesResponse": { "type": "object", "description": "Pending document invitations for a document.\n\nReturned by `GET /api/v1/documents/{docId}/invites`. Invitations carry a\n7-day TTL; the storage backend sweeps expired rows asynchronously, so\ncallers should treat entries whose `invitedAt` is older than 7 days as\nexpired-but-not-yet-swept and ignore them.", "required": [ "invites" ], "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentInviteResponse" }, "description": "Pending invitations." } } }, "ListDocumentsResponse": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponse" } }, "nextToken": { "type": [ "string", "null" ] } } }, "ListDomainClaimsResponse": { "type": "object", "description": "Response body for `GET /claims`.", "required": [ "claims" ], "properties": { "claims": { "type": "array", "items": { "$ref": "#/components/schemas/DomainClaimAttempt" }, "description": "Every claim attempt the authenticated caller has initiated, in\narbitrary order." } } }, "ListDomainsResponse": { "type": "object", "description": "List of domain verification records for an organization.", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/DomainVerificationResponse" }, "description": "Domain verification records" }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListFolderAccessResponse": { "type": "object", "description": "Paginated list of folder access grants.", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/FolderAccessGrantResponse" }, "description": "Folder access grants." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListFoldersResponse": { "type": "object", "required": [ "folders" ], "properties": { "folders": { "type": "array", "items": { "$ref": "#/components/schemas/FolderResponse" } }, "nextToken": { "type": [ "string", "null" ] } } }, "ListFreeProvidersResponse": { "type": "object", "description": "Response body for `GET /admin/free-providers`.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/FreeProviderEntry" }, "description": "Every entry on the free-email-provider allowlist." } } }, "ListGuestsResponse": { "type": "object", "description": "Paginated list of guest access entries.", "required": [ "guests" ], "properties": { "guests": { "type": "array", "items": { "$ref": "#/components/schemas/GuestAccessResponse" }, "description": "Guest access entries." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListHistoryResponse": { "type": "object", "description": "Paginated list of history entries.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryEntryResponse" }, "description": "Grouped history entries in reverse chronological order." }, "nextToken": { "type": [ "string", "null" ], "description": "Pagination token for the next page (ULID of the oldest returned record)." } } }, "ListIdpMappingsResponse": { "type": "object", "description": "Paginated list of `IdP` group-to-tier-node mappings.", "required": [ "mappings" ], "properties": { "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/IdpMappingResponse" }, "description": "`IdP` mappings." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListInvoicesResponse": { "type": "object", "description": "Paginated invoice list response.", "required": [ "invoices" ], "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" }, "description": "Invoice summaries." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListLegalHoldsResponse": { "type": "object", "description": "List response for legal holds.", "required": [ "holds" ], "properties": { "holds": { "type": "array", "items": { "$ref": "#/components/schemas/LegalHoldResponse" }, "description": "Legal holds matching the query" }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListMemoryEntriesResponse": { "type": "object", "description": "Memory entries listing.", "required": [ "entries", "inIndexCount", "total" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryEntry" }, "description": "All active memory entries with metadata." }, "inIndexCount": { "type": "integer", "format": "int32", "description": "How many entries made it into the always-on index (`in_index == true`).", "minimum": 0 }, "total": { "type": "integer", "format": "int32", "description": "Total entry count (includes demoted-to-search entries).", "minimum": 0 } } }, "ListModelsResponse": { "type": "object", "description": "Response for the `GET /api/v1/models` endpoint.", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInfoEntry" }, "description": "All platform-supported models with credit multipliers." } } }, "ListNotificationsResponse": { "type": "object", "description": "List response for notifications.", "required": [ "notifications", "unreadCount" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationResponse" }, "description": "Notifications for the user" }, "unreadCount": { "type": "integer", "format": "int32", "description": "Count of unread notifications", "minimum": 0 } } }, "ListOrgMembersResponse": { "type": "object", "description": "Paginated list of org members (company admin view).", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMemberSummary" }, "description": "Members of the organization." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListPinnedResourcesResponse": { "type": "object", "description": "Paginated list of pinned resources.", "required": [ "pins" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Pagination token for the next page." }, "pins": { "type": "array", "items": { "$ref": "#/components/schemas/PinnedResourceResponse" }, "description": "Pinned resource entries." } } }, "ListPromptsResponse": { "type": "object", "description": "Response body for `GET /api/v1/prompts`. Flat list — slug-collision\ndedup is the extractor's job, so by the time the client reads this\nevery entry has a unique slug.", "required": [ "prompts" ], "properties": { "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/PromptListItem" }, "description": "Prompts in the user's library, sorted most-recently-updated first." } } }, "ListProviderCredentialStatusResponse": { "type": "object", "description": "Response body for `GET /api/v1/companies/{companyId}/oauth-overrides`.", "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderCredentialStatus" }, "description": "One entry per provider in the catalog (eight at launch). Order is\nstable and matches the `OAuthProvider` enum declaration order." } } }, "ListRepoConnectionsResponse": { "type": "object", "description": "Paginated list of repository connections.", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/RepoConnectionResponse" }, "description": "Connection entries" }, "nextToken": { "type": [ "string", "null" ], "description": "Pagination token for the next page" } } }, "ListRepoSourcesResponse": { "type": "object", "description": "Paginated list of repository sources.", "required": [ "repoSources" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Pagination token for the next page" }, "repoSources": { "type": "array", "items": { "$ref": "#/components/schemas/RepoSourceResponse" }, "description": "Source entries" } } }, "ListScimTierMappingsResponse": { "type": "object", "description": "Paginated list of SCIM tier mappings.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScimTierMappingResponse" }, "description": "Mappings in the result set." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListScimTokensResponse": { "type": "object", "description": "Paginated list of SCIM tokens.", "required": [ "tokens" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ScimTokenSummary" }, "description": "SCIM token summaries." } } }, "ListSessionsResponse": { "type": "object", "description": "Response for listing sessions.", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionResponse" }, "description": "The sessions." } } }, "ListSharedDocumentsResponse": { "type": "object", "description": "Paginated list of documents shared with the requesting user.", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/SharedDocumentResponse" }, "description": "Shared documents." }, "nextToken": { "type": [ "string", "null" ], "description": "Pagination token for the next page." } } }, "ListSharedSpacesResponse": { "type": "object", "description": "Paginated list of Spaces shared with the authenticated user.", "required": [ "spaces" ], "properties": { "nextToken": { "type": [ "string", "null" ] }, "spaces": { "type": "array", "items": { "$ref": "#/components/schemas/SharedSpaceResponse" } } } }, "ListSpaceDocumentsResponse": { "type": "object", "description": "Paginated list of Space documents.", "required": [ "documents", "totalCount" ], "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/SpaceDocumentResponse" } }, "nextToken": { "type": [ "string", "null" ] }, "totalCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ListSpaceFiltersResponse": { "type": "object", "description": "List of source filters for a Space.", "required": [ "filters" ], "properties": { "filters": { "type": "array", "items": { "$ref": "#/components/schemas/SpaceFilterResponse" } }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListSpaceFoldersResponse": { "type": "object", "description": "Response for listing folders within a Space.", "required": [ "folders" ], "properties": { "folders": { "type": "array", "items": { "$ref": "#/components/schemas/SpaceFolderNode" } } } }, "ListSpaceGrantsResponse": { "type": "object", "description": "List of grants for a Space.", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/SpaceGrantResponse" } }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListSpacesResponse": { "type": "object", "description": "Paginated list of Spaces.", "required": [ "spaces" ], "properties": { "nextToken": { "type": [ "string", "null" ] }, "spaces": { "type": "array", "items": { "$ref": "#/components/schemas/SpaceResponse" } } } }, "ListSsoConnectionsResponse": { "type": "object", "description": "List of SSO connections for an organization.", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/SsoConnectionResponse" }, "description": "SSO connections" }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListSuggestionsResponse": { "type": "object", "description": "List of pending suggestions in a document.", "required": [ "documentId", "suggestions", "groups" ], "properties": { "documentId": { "type": "string", "description": "Document identifier." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestionGroupSummary" }, "description": "Suggestions grouped by agent task (one entry per `suggestion_id`)." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestionInfoResponse" }, "description": "Pending suggestions (flat list, one per suggestion mark)." } } }, "ListTemplatesResponse": { "type": "object", "description": "Response for `GET /api/hierarchy-templates`.", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/HierarchyTemplate" }, "description": "The preset hierarchy templates." } } }, "ListTierMembersResponse": { "type": "object", "description": "Paginated list of tier memberships.", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/TierMembershipResponse" }, "description": "Members of the tier node." }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." } } }, "ListTierNodesResponse": { "type": "object", "description": "Paginated list of tier nodes.", "required": [ "nodes" ], "properties": { "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/TierNodeResponse" }, "description": "Tier nodes in the result set." } } }, "ListUserAgentsResponse": { "type": "object", "description": "Response body for `GET /api/v1/agents/user-agents`. Flat list of the\ncaller's user-authored agents, separate from the legacy\n`GET /api/v1/agents` listing which merges built-ins.", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListItem" }, "description": "User-authored agents owned by the caller, sorted\nmost-recently-updated first." } } }, "ListUserGrantsForKindResponse": { "type": "object", "description": "Response for `GET .../integrations/{kind}/grants`.", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/GrantForKindEntry" }, "description": "Grant entries." } } }, "ListUserGrantsResponse": { "type": "object", "description": "Paginated list of user grants for admin viewing.", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/UserGrantAdminEntry" }, "description": "Grant entries." } } }, "ListUserTierMembershipsResponse": { "type": "object", "description": "Response for `GET /api/v1/users/me/tier-memberships`.", "required": [ "memberships" ], "properties": { "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/UserTierMembershipEntry" }, "description": "All tier node memberships for the authenticated user, sorted\nleaf-first (depth descending) then name ascending so the sidebar\nsurfaces teams before org/company roots." } } }, "MarkAddressedRequest": { "type": "object", "description": "Request body for marking a card addressed without posting a reply.\n\nCAS-guarded by `sequence_number`: the value must match the card slot's\ncurrent sequence number, otherwise the call returns 409 with the\ncurrent state in the body.", "required": [ "sequenceNumber" ], "properties": { "sequenceNumber": { "type": "integer", "format": "int64", "description": "Most recently observed card slot sequence number (CAS guard).", "minimum": 0 } } }, "MarkAddressedResponse": { "type": "object", "description": "Response body for a successful mark-addressed.", "required": [ "sequenceNumber", "addressedAt" ], "properties": { "addressedAt": { "type": "string", "format": "date-time", "description": "Wall-clock when the card was marked addressed." }, "sequenceNumber": { "type": "integer", "format": "int64", "description": "New sequence number after the write.", "minimum": 0 } } }, "MarkReadResponse": { "type": "object", "description": "Response when marking comments as read.", "required": [ "lastReadAt" ], "properties": { "lastReadAt": { "type": "string", "format": "date-time" } } }, "MembershipProvenance": { "type": "string", "description": "Provenance marker on a `CompanyMembership` row recording how the\nmembership was created.\n\nAbsent on memberships created via invite, manual add, or SCIM\nprovisioning. Present only on memberships materialized by the\ndomain-claim backfill migration so the admin members UI can render\na \"Joined via domain claim\" badge.", "enum": [ "domainClaim" ] }, "MembershipSource": { "type": "string", "description": "How a tier membership was created.", "enum": [ "manual", "scim", "ssoAutoJoin" ] }, "MembershipStatus": { "type": "string", "description": "Workspace membership status as seen by the eligibility evaluator.", "enum": [ "active", "pending", "removed", "inactive", "deactivated", "deleted" ] }, "MemoryCapturedBy": { "type": "string", "description": "Who captured a memory entry.", "enum": [ "agent", "user" ] }, "MemoryEntry": { "type": "object", "description": "A single memory entry packaged for listing surfaces (settings page,\nlisting endpoint). Combines metadata with the document ID so the\nfrontend can link into the editor.", "required": [ "documentId", "meta", "inIndex" ], "properties": { "documentId": { "$ref": "#/components/schemas/TypedId", "description": "Document ID (`doc_01...`)." }, "inIndex": { "type": "boolean", "description": "Whether the entry currently appears in the always-on Tier 1 index.\nWhen false the entry is only reachable via Tier 3 semantic search." }, "meta": { "$ref": "#/components/schemas/MemoryEntryMeta", "description": "Frontmatter metadata." } } }, "MemoryEntryMeta": { "type": "object", "description": "Frontmatter metadata stored on every memory entry document. Matches the\nshape the frontend frontmatter renderer surfaces.", "required": [ "name", "description", "type", "createdAt", "updatedAt" ], "properties": { "capturedBy": { "$ref": "#/components/schemas/MemoryCapturedBy", "description": "Who captured the entry — \"agent\" for auto-capture via `record_memory`\nor \"user\" for explicit `/remember` / manual creation." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the entry was captured." }, "description": { "type": "string", "description": "One-line description used in the index and in UI surfaces." }, "name": { "type": "string", "description": "Short human-readable name. Becomes the document title." }, "sourceSessionId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Chat session the entry was captured in, when captured by the agent.\n`None` for manually-created entries." } ] }, "type": { "$ref": "#/components/schemas/MemoryType", "description": "Memory taxonomy category." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last edit to the entry body or metadata." } } }, "MemoryProfileResponse": { "type": "object", "description": "Profile body response.", "required": [ "content", "maxChars", "charCount" ], "properties": { "charCount": { "type": "integer", "format": "int32", "description": "Current character count.", "minimum": 0 }, "content": { "type": "string", "description": "Current `profile.md` text." }, "maxChars": { "type": "integer", "format": "int32", "description": "Maximum allowed length (server-side cap).", "minimum": 0 } } }, "MemorySettingsResponse": { "type": "object", "description": "Settings payload returned by `GET /users/me/memory/settings`.", "required": [ "enabled", "entryCount", "profileMaxChars", "indexMaxChars" ], "properties": { "enabled": { "type": "boolean", "description": "Whether memory injection is active for this user." }, "entriesFolderId": { "type": [ "string", "null" ], "description": "`Memory/Entries/` folder ID, when provisioned." }, "entryCount": { "type": "integer", "format": "int32", "description": "Total entries currently stored.", "minimum": 0 }, "folderId": { "type": [ "string", "null" ], "description": "Root `Memory/` folder ID, when provisioned." }, "indexDocId": { "type": [ "string", "null" ], "description": "`MEMORY.md` document ID (Tier 1), when lazily seeded." }, "indexMaxChars": { "type": "integer", "format": "int32", "description": "Index budget before deterministic degradation kicks in.", "minimum": 0 }, "profileDocId": { "type": [ "string", "null" ], "description": "`profile.md` document ID (Tier 0), when lazily seeded." }, "profileMaxChars": { "type": "integer", "format": "int32", "description": "Character caps the UI should surface to users.", "minimum": 0 }, "spaceId": { "type": [ "string", "null" ], "description": "Personal memory Space ID, when provisioned." } } }, "MemoryType": { "type": "string", "description": "The closed set of memory categories. Ordering here is load-bearing —\n[`MemoryType::degradation_priority`] uses this ordering when trimming the\nindex to fit the budget.", "enum": [ "feedback", "user", "project", "reference" ] }, "MessageResponse": { "type": "object", "description": "Message in a session response.", "required": [ "sequence", "role", "content", "createdAt" ], "properties": { "actions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssistantAction" }, "description": "Actions the assistant instructs the frontend to perform." }, "content": { "type": "string", "description": "Message text content." }, "context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AssistantContext", "description": "Scope context sent with user messages." } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When this message was created." }, "promptSource": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PromptSourceRef", "description": "Provenance for user messages produced by invoking `/prompt:`." } ] }, "role": { "$ref": "#/components/schemas/ChatMessageRole", "description": "Who sent this message." }, "sequence": { "type": "integer", "format": "int32", "description": "Message sequence number.", "minimum": 0 }, "toolCalls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssistantToolCallRecord" }, "description": "Tool invocations during this message." } } }, "MfaPolicy": { "type": "string", "description": "Multi-factor authentication enforcement policy", "enum": [ "off", "optional", "requiredForAdmins", "required" ] }, "Model": { "type": "string", "description": "Platform-supported LLM model.\n\nEach variant maps to provider-specific model IDs on the server. Adding\na new model requires adding a variant here and the corresponding\nserver-side resolution entry.", "enum": [ "claude-haiku-4-5", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-7", "llama-3-1-8b", "gpt-oss-20b", "gpt-oss-120b" ] }, "ModelCapabilities": { "type": "object", "description": "Inference capability matrix for a model.\n\nSurfaces which reasoning controls and effort levels the model accepts so\nclients can render contextual UI without hardcoding the matrix\nout-of-band. Values are derived from the canonical capability methods on\n[`Model`] — clients should treat this struct as authoritative.", "required": [ "supportsThinking", "supportsEffort", "supportsMaxEffort", "supportsXhighEffort" ], "properties": { "defaultEffort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Effort", "description": "Default effort level for this model, if any." } ] }, "defaultThinking": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ThinkingConfig", "description": "Default reasoning strategy for this model, if any." } ] }, "supportsEffort": { "type": "boolean", "description": "Whether this model accepts the `effort` parameter." }, "supportsMaxEffort": { "type": "boolean", "description": "Whether this model accepts `effort: \"max\"`." }, "supportsThinking": { "type": "boolean", "description": "Whether this model accepts adaptive reasoning (`thinking`)." }, "supportsXhighEffort": { "type": "boolean", "description": "Whether this model accepts `effort: \"xhigh\"` (Opus 4.7+ only)." } } }, "ModelConfigRequest": { "type": "object", "description": "Model config in request.", "properties": { "effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Effort", "description": "Reasoning depth. Omit to use the model's default." } ] }, "enableCaching": { "type": [ "boolean", "null" ], "description": "Enable prompt caching (only effective on models that support it)." }, "maxOutputTokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Max output tokens.", "minimum": 0 }, "model": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Model", "description": "Platform model name (e.g., `\"claude-sonnet-46\"`, `\"llama-3-1-8b\"`).\nUses the platform default if omitted." } ] }, "temperature": { "type": [ "number", "null" ], "format": "float", "description": "Temperature (0.0 - 1.0)." }, "thinking": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ThinkingConfig", "description": "Reasoning strategy. Omit to use the model's default." } ] } } }, "ModelInfoEntry": { "type": "object", "description": "A single entry in the model catalog.\n\nSingle source of truth for client-side model rendering — display label,\nbilling multiplier, and capability matrix all live here so adding a new\nmodel only requires backend changes. Per-token cost class is conveyed by\n`creditMultiplier` itself (no separate badge field).", "required": [ "id", "displayName", "creditMultiplier", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ModelCapabilities", "description": "Inference capability matrix for this model." }, "creditMultiplier": { "$ref": "#/components/schemas/CreditMultiplier", "description": "Credit multiplier for this model — per-token cost is the source of\ntruth for cost-tier rendering. Anchored to Sonnet input = 1×." }, "displayName": { "type": "string", "description": "Short human label for chat UIs (e.g. `\"Sonnet\"`, `\"Opus 4.7\"`,\n`\"GPT-OSS 120B\"`)." }, "id": { "$ref": "#/components/schemas/Model", "description": "Model identifier (kebab-case, e.g. `\"claude-sonnet-4-6\"`)." } } }, "ModelNotAllowedDetails": { "type": "object", "description": "Structured details for model-not-allowed-on-plan enforcement errors.\n\nReturned with HTTP 403 when a caller requests an LLM model that the\ncompany's billing plan does not permit (e.g. Opus on the free Personal\nplan).", "required": [ "requestedModel", "currentPlan", "allowedModels" ], "properties": { "allowedModels": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "Models the current plan does permit." }, "currentPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "The effective billing plan at enforcement time." }, "requestedModel": { "$ref": "#/components/schemas/Model", "description": "The model the caller requested." } } }, "MonthlyAiUsage": { "type": "object", "description": "Monthly AI usage record exposed over the API.\n\nMirrors [`AiUsageRecord`] but exposes `creditCount` in user-facing\ncredits (fractional) instead of internal millicredits.", "required": [ "inputTokenCount", "cacheReadTokenCount", "cacheWriteTokenCount", "outputTokenCount", "creditCount", "operationCount", "isSoftOverage" ], "properties": { "cacheReadTokenCount": { "type": "integer", "format": "int64", "description": "Cache-read tokens consumed this month.", "minimum": 0 }, "cacheWriteTokenCount": { "type": "integer", "format": "int64", "description": "Cache-write tokens consumed this month.", "minimum": 0 }, "creditCount": { "type": "number", "format": "double", "description": "Credits consumed this month (fractional)." }, "inputTokenCount": { "type": "integer", "format": "int64", "description": "Input tokens consumed this month.", "minimum": 0 }, "isSoftOverage": { "type": "boolean", "description": "Whether the company is currently in soft overage (100–110% of credit limit)." }, "operationCount": { "type": "integer", "format": "int64", "description": "Number of AI operations performed this month.", "minimum": 0 }, "outputTokenCount": { "type": "integer", "format": "int64", "description": "Output tokens consumed this month.", "minimum": 0 } } }, "MoveFolderRequest": { "type": "object", "properties": { "parentFolderId": { "type": [ "string", "null" ] } } }, "MyAiUsageResponse": { "type": "object", "description": "AI usage response for the authenticated user.", "required": [ "usage", "cycleStart", "workspaceRemainingCredits" ], "properties": { "cycleEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive end of the cycle when known." }, "cycleStart": { "type": "string", "format": "date-time", "description": "Start of the billing cycle being reported." }, "usage": { "$ref": "#/components/schemas/MyMonthlyAiUsage", "description": "User-attributed usage record for the bucket identified by [`Self::cycle_start`]." }, "workspaceRemainingCredits": { "type": "number", "format": "double", "description": "Credits still available in the shared workspace pool for the cycle\n(fractional credits), for the workspace this request is authenticated\nagainst. Computed as `max(0, derived ceiling - company consumption)`.\nThe member draws from this shared balance and never has a personal\ncap." } } }, "MyConnectorEntry": { "type": "object", "description": "A single entry in the user-facing connector list (Connections panel).\n\nEnriched with the caller's personal grant state, company service-account\nstate, and the effective policy decision so the panel can render the\ncorrect button label and affordances without additional round-trips.", "required": [ "kind", "displayName", "description", "mode", "category", "capabilities", "credentialMode", "policyState" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ConnectorCapability", "description": "What this connector can do — which UI surfaces it participates in.\nDerived from `mode` plus manifest contents for MCP kinds." }, "category": { "$ref": "#/components/schemas/ConnectorCategory", "description": "UI grouping category (e.g. `messaging`, `docs`)." }, "credentialMode": { "$ref": "#/components/schemas/ConnectorCredentialMode", "description": "Credential mode preference for this connector." }, "description": { "type": "string", "description": "One-line description." }, "displayName": { "type": "string", "description": "Human-readable display name." }, "kind": { "type": "string", "description": "Connector kind identifier (e.g. `\"slack\"`)." }, "logoAsset": { "type": [ "string", "null" ], "description": "Asset path for the logo (`null` when unavailable)." }, "mode": { "$ref": "#/components/schemas/ConnectorMode", "description": "Dispatch mode." }, "policyState": { "$ref": "#/components/schemas/UserPolicyState", "description": "Effective policy state as seen by this user." }, "serviceAccount": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceAccountSummary", "description": "Company-level service-account credential status, or `null` if\nno service account has been configured." } ] }, "userGrant": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MyGrantSummary", "description": "The caller's personal grant, or `null` if no grant exists." } ] } } }, "MyConnectorsResponse": { "type": "object", "description": "Response for `GET /api/v1/connectors` — the user-facing connections panel.", "required": [ "connectors" ], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/MyConnectorEntry" }, "description": "Catalog entries visible to this user, enriched with grant and\nservice-account state." } } }, "MyGrantSummary": { "type": "object", "description": "Summary of the caller's personal grant for a connector kind.", "required": [ "state" ], "properties": { "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the grant expires (`null` if it does not expire)." }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the grant was issued." }, "state": { "$ref": "#/components/schemas/GrantStatus", "description": "Current grant lifecycle state." } } }, "MyMonthlyAiUsage": { "type": "object", "description": "Monthly AI usage for the authenticated user.\n\nOmits company-level billing state such as soft overage and limits.", "required": [ "inputTokenCount", "cacheReadTokenCount", "cacheWriteTokenCount", "outputTokenCount", "creditCount", "operationCount" ], "properties": { "cacheReadTokenCount": { "type": "integer", "format": "int64", "description": "Cache-read tokens consumed this month.", "minimum": 0 }, "cacheWriteTokenCount": { "type": "integer", "format": "int64", "description": "Cache-write tokens consumed this month.", "minimum": 0 }, "creditCount": { "type": "number", "format": "double", "description": "Credits consumed this month (fractional)." }, "inputTokenCount": { "type": "integer", "format": "int64", "description": "Input tokens consumed this month.", "minimum": 0 }, "operationCount": { "type": "integer", "format": "int64", "description": "Number of AI operations performed this month.", "minimum": 0 }, "outputTokenCount": { "type": "integer", "format": "int64", "description": "Output tokens consumed this month.", "minimum": 0 } } }, "NodeType": { "type": "string", "description": "Classification of a node in the connection graph.\n\nCurrently only `Document` is active. Future phases will add `Url` (URL\nbookmarks), `Note` (canvas sticky notes), and `External` (third-party\nconnector nodes such as Gmail, Notion, or GitHub).", "enum": [ "document" ] }, "NotificationLink": { "oneOf": [ { "type": "object", "description": "Navigate to a document.", "required": [ "documentId", "type" ], "properties": { "documentId": { "type": "string", "description": "Document to navigate to." }, "type": { "type": "string", "enum": [ "document" ] } } }, { "type": "object", "description": "Navigate to a specific comment on a document.", "required": [ "documentId", "commentId", "type" ], "properties": { "commentId": { "type": "string", "description": "Comment to scroll to." }, "documentId": { "type": "string", "description": "Document containing the comment." }, "type": { "type": "string", "enum": [ "comment" ] } } } ], "description": "Deep-link target for a notification." }, "NotificationResponse": { "type": "object", "description": "API response for an in-app notification.", "required": [ "id", "userId", "tenantId", "notificationType", "title", "body", "isRead", "createdAt" ], "properties": { "body": { "type": "string", "description": "Human-readable detail" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the notification was created" }, "id": { "type": "string", "description": "Unique notification identifier" }, "isRead": { "type": "boolean", "description": "Whether the user has seen this notification" }, "link": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NotificationLink", "description": "Deep-link navigation target." } ] }, "notificationType": { "$ref": "#/components/schemas/NotificationType", "description": "Type of notification" }, "resourceId": { "type": [ "string", "null" ], "description": "Related resource ID (e.g. document ID)" }, "tenantId": { "type": "string", "description": "Organization context" }, "title": { "type": "string", "description": "Human-readable title" }, "userId": { "type": "string", "description": "Recipient user ID" } } }, "NotificationType": { "oneOf": [ { "type": "string", "description": "Document was automatically archived due to inactivity", "enum": [ "autoArchived" ] }, { "type": "object", "description": "A document was returned to the creator's personal root after its folder was deleted.", "required": [ "documentReturned" ], "properties": { "documentReturned": { "type": "object", "description": "A document was returned to the creator's personal root after its folder was deleted.", "required": [ "folderName", "documentTitle" ], "properties": { "documentTitle": { "type": "string", "description": "Title of the returned document." }, "folderName": { "type": "string", "description": "Name of the deleted folder the document was returned from." } } } } }, { "type": "object", "description": "Someone created a new root comment on a document you own.", "required": [ "newCommentOnDocument" ], "properties": { "newCommentOnDocument": { "type": "object", "description": "Someone created a new root comment on a document you own.", "required": [ "commenterName", "documentTitle", "commentPreview" ], "properties": { "commentPreview": { "type": "string", "description": "First ~120 characters of the comment body." }, "commenterName": { "type": "string", "description": "Display name of the commenter." }, "documentTitle": { "type": "string", "description": "Title of the document." } } } } }, { "type": "object", "description": "Someone resolved a comment thread you started.", "required": [ "commentThreadResolved" ], "properties": { "commentThreadResolved": { "type": "object", "description": "Someone resolved a comment thread you started.", "required": [ "resolverName", "documentTitle", "threadPreview" ], "properties": { "documentTitle": { "type": "string", "description": "Title of the document." }, "resolverName": { "type": "string", "description": "Display name of the person who resolved." }, "threadPreview": { "type": "string", "description": "First ~120 characters of the original comment body." } } } } }, { "type": "object", "description": "Someone replied to a comment thread you started.", "required": [ "commentThreadReply" ], "properties": { "commentThreadReply": { "type": "object", "description": "Someone replied to a comment thread you started.", "required": [ "replierName", "documentTitle", "replyPreview" ], "properties": { "documentTitle": { "type": "string", "description": "Title of the document." }, "replierName": { "type": "string", "description": "Display name of the replier." }, "replyPreview": { "type": "string", "description": "First ~120 characters of the reply body." } } } } }, { "type": "object", "description": "Someone shared a document with you.", "required": [ "documentSharedWithYou" ], "properties": { "documentSharedWithYou": { "type": "object", "description": "Someone shared a document with you.", "required": [ "sharerName", "documentTitle", "role" ], "properties": { "documentTitle": { "type": "string", "description": "Title of the document." }, "role": { "type": "string", "description": "Role granted (e.g. \"editor\", \"viewer\")." }, "sharerName": { "type": "string", "description": "Display name of the person who shared." } } } } }, { "type": "object", "description": "The user was automatically migrated into a company when an admin\nverified a domain claim covering their email domain.", "required": [ "domainClaimMigration" ], "properties": { "domainClaimMigration": { "type": "object", "description": "The user was automatically migrated into a company when an admin\nverified a domain claim covering their email domain.", "required": [ "companyName", "companyId" ], "properties": { "companyId": { "$ref": "#/components/schemas/TypedId", "description": "ID of the company they were added to." }, "companyName": { "type": "string", "description": "Display name of the company they were added to." }, "subscriptionAction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubscriptionAction", "description": "What happened to the user's personal subscription, if any.\n`null` means no active personal subscription existed at migration time." } ] } } } } } ], "description": "Type of notification" }, "OAuthAppSource": { "type": "string", "description": "Which level of the credential hierarchy served a given OAuth authorize\ncall.\n\nDistinct from `ProviderSource` (which also models the \"no source at all\"\ncase). `OAuthAppSource` only tags a *successful* resolution, so there are\nexactly two variants.", "enum": [ "platform", "companyOverride" ] }, "OAuthClientInfo": { "type": "object", "description": "OAuth client information (API response).", "required": [ "clientId", "name", "redirectUris", "scopes", "createdAt" ], "properties": { "clientId": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "OAuthOverrideResponse": { "type": "object", "description": "Response shape for `PUT` and for the per-provider entry of\n`GET …/oauth-overrides` when `source == companyOverride`. Present only\nwhen an override row exists.\n\n**No `clientSecret` field exists on this type.** That omission is a\ncompile-enforced invariant of FR-011.", "required": [ "provider", "clientId", "createdAt", "createdBy", "updatedAt", "updatedBy" ], "properties": { "clientId": { "type": "string", "description": "Non-sensitive client identifier — the only value the settings UI\never renders to the admin." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the row was first written." }, "createdBy": { "$ref": "#/components/schemas/TypedId", "description": "Admin user who first saved the override." }, "provider": { "$ref": "#/components/schemas/OAuthProvider", "description": "Provider the override was saved for." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the row was last upserted." }, "updatedBy": { "$ref": "#/components/schemas/TypedId", "description": "Admin user who most recently saved the override." } } }, "OAuthProvider": { "type": "string", "description": "The closed set of OAuth identity providers the system knows about at\nlaunch.\n\nThe wire format is `kebab-case`, matching the URL segment used in the\noverride admin endpoints (`/oauth-overrides/{provider}`) and the audit\nlog resource tag.", "enum": [ "slack", "notion", "github", "linear", "dropbox", "atlassian", "google", "microsoft" ] }, "OnBehalfOfActor": { "type": "object", "description": "Secondary actor identity carried alongside a primary [`WalActor`].\n\nSurfaces the human delegator when an agent acts via MCP, or the\nagent that proposed text when a human accepts a suggestion. The\ndirectionality is decided by the call site that builds the\n[`WalActor`]; this struct is just the carrier.\n\n`email` is populated when the on-behalf-of party is an authenticated\nhuman user, so the history panel can render `Claude (noah@strata.space)`\n(the email disambiguates two users with the same display name and\nmatches the git-author convention).", "required": [ "actorId", "displayName", "entityType" ], "properties": { "actorId": { "type": "string", "description": "User or agent ID of the secondary actor." }, "displayName": { "type": "string", "description": "Display name of the secondary actor." }, "email": { "type": [ "string", "null" ], "description": "Email of the secondary actor when it is an authenticated human user." }, "entityType": { "$ref": "#/components/schemas/EntityType", "description": "Whether the secondary actor is a human or an agent." } } }, "OnboardingState": { "type": "object", "description": "Per-user, per-wizard, per-version completion state.", "required": [ "userId", "tenantId", "wizardKey", "version", "updatedAt" ], "properties": { "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the user clicked the final \"Finish\" button. `null` until then." }, "skipped": { "type": "boolean", "description": "`true` if the user dismissed the wizard without finishing it. The\nwizard's resume affordance stays visible until the user either\ndismisses permanently (toggles this `true`) or finishes the wizard\n(sets `completed_at`)." }, "stepsSeen": { "type": "array", "items": { "$ref": "#/components/schemas/FirstTimeUserStep" }, "description": "Set of step keys the user has marked as seen. Wire format is a JSON\narray; duplicates are coalesced.", "uniqueItems": true }, "tenantId": { "$ref": "#/components/schemas/TypedId", "description": "Tenant isolation." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last modification timestamp." }, "userId": { "$ref": "#/components/schemas/TypedId", "description": "Owner of the onboarding state." }, "version": { "type": "integer", "format": "int32", "description": "Wizard version. The server accepts a small allow-list of versions\nper wizard; sending an unknown version returns `400 BadRequest`.", "minimum": 0 }, "wizardKey": { "$ref": "#/components/schemas/WizardKey", "description": "Which wizard this record tracks." } } }, "OrgDetailResponse": { "type": "object", "description": "Organization details visible to company admins.", "required": [ "id", "name", "slug", "memberCount", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the organization was created." }, "id": { "type": "string", "description": "Organization (tenant) identifier." }, "memberCount": { "type": "integer", "format": "int32", "description": "Number of members in this org.", "minimum": 0 }, "name": { "type": "string", "description": "Organization name." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrgOwnerSummary", "description": "Organization owner (if one exists)." } ] }, "slug": { "type": "string", "description": "URL-safe slug." } } }, "OrgLegalHoldsResponse": { "type": "object", "description": "List response for all active legal holds scoped to an org.", "required": [ "holds", "totalCount" ], "properties": { "holds": { "type": "array", "items": { "$ref": "#/components/schemas/LegalHoldResponse" }, "description": "All active holds for the org" }, "nextToken": { "type": [ "string", "null" ], "description": "Opaque pagination token for the next page." }, "totalCount": { "type": "integer", "format": "int32", "description": "Total number of active holds", "minimum": 0 } } }, "OrgMemberSummary": { "type": "object", "description": "Summary of an org member for company admin views.", "required": [ "userId", "displayName", "email", "role", "joinedAt" ], "properties": { "displayName": { "type": "string", "description": "User's display name." }, "email": { "type": "string", "description": "User's email." }, "joinedAt": { "type": "string", "format": "date-time", "description": "When the user joined the organization." }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Role within the organization." }, "userId": { "type": "string", "description": "User identifier." } } }, "OrgOwnerSummary": { "type": "object", "description": "Summary of an org's owner for company admin views.", "required": [ "userId", "displayName", "email" ], "properties": { "displayName": { "type": "string", "description": "User's display name." }, "email": { "type": "string", "description": "User's email." }, "userId": { "type": "string", "description": "User identifier." } } }, "OwnerType": { "type": "string", "description": "Which identity space owns a document.\n\n`Tier` is the default and covers every authenticated workspace\ndocument. `AnonSession` flags a document owned by a cookie-only\nanonymous session, which downstream surfaces (admin listings,\nbilling rollups, search indexer, audit feeds) MUST filter out so\nanonymous content cannot leak to other identities.", "enum": [ "TIER", "ANON_SESSION" ] }, "PausedReason": { "type": "string", "description": "Why a `RepoSource` is paused.\n\nDistinguishes user-initiated pauses from system-initiated pauses\n(e.g., provider installation suspended). On unsuspend, only\n`ProviderSuspended` sources are restored — `UserRequested` remain paused.", "enum": [ "userRequested", "providerSuspended" ] }, "PaymentMethodSummary": { "type": "object", "description": "Summary of the payment method on file.", "required": [ "brand", "last4", "expMonth", "expYear" ], "properties": { "brand": { "type": "string", "description": "Card brand (e.g., \"visa\", \"mastercard\")." }, "expMonth": { "type": "integer", "format": "int32", "description": "Expiration month (1-12).", "minimum": 0 }, "expYear": { "type": "integer", "format": "int32", "description": "Expiration year (4-digit).", "minimum": 0 }, "last4": { "type": "string", "description": "Last four digits of the card." } } }, "PdfExportError": { "type": "object", "description": "JSON error body returned by the PDF export endpoints when the\nsuccess path cannot produce `application/pdf` bytes.", "required": [ "code", "message", "requestId" ], "properties": { "code": { "$ref": "#/components/schemas/PdfExportErrorCode", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message suitable for surfacing to the user." }, "requestId": { "type": "string", "description": "Server-side request identifier for log correlation." } } }, "PdfExportErrorCode": { "type": "string", "description": "Coarse-grained error code for PDF export failures.\n\nUser-facing messages are derived from the code; operational detail\nstays in the request log identified by [`PdfExportError::request_id`].", "enum": [ "notAuthenticated", "forbidden", "notFound", "rateLimited", "renderFailed" ] }, "PdfExportSurface": { "type": "string", "description": "Which export surface produced the request.\n\nThe editor surface is the in-app authoring view (signed-in author);\nthe public surface is the gated download from a published document\npage (signed-in reader, post-gate).", "enum": [ "editor", "public" ] }, "PdfGateIntent": { "type": "string", "description": "The user action that triggered the gate redirect.\n\nClosed enum so metric labels stay bounded. Add new variants here\nonly when a real consumer needs them.", "enum": [ "download_pdf" ] }, "PdfGateRedirectRequest": { "type": "object", "description": "Request body for the gate-redirect ping.\n\nCarries the user-visible action that triggered the redirect. The\nlabel is closed-set so a typo in the webapp cannot pollute the\nmetric cardinality at runtime.", "required": [ "intent" ], "properties": { "intent": { "$ref": "#/components/schemas/PdfGateIntent", "description": "What the user was trying to do when the gate fired." } } }, "Permission": { "type": "string", "description": "Fine-grained authorization atom.\n\nEach variant represents a single capability that can be checked at\nauthorization time. Roles map to sets of these atoms via their\n`permissions()` methods.\n\n# Groups\n\n| Group | Count | Cedar actions |\n|-----------------|-------|----------------|\n| Document | 12 | Yes |\n| Comment | 6 | Yes |\n| Review Console | 4 | Yes |\n| Folder | 6 | Yes |\n| Organization | 7 | Yes |\n| Tier Node | 8 | Yes |\n| Company | 7 | Yes |\n| Trace | 2 | Yes |\n| Space | 4 | Yes |\n| Connector | 2 | Yes |\n| Agent | 4 | Partial |\n| Section | 3 | No (type-only) |\n| Publishing | 2 | Yes |\n| Domain Claim | 4 | Yes |", "enum": [ "documentRead", "documentEdit", "documentSuggest", "documentDelete", "documentShare", "documentExport", "documentManagePermissions", "documentManageComments", "documentTransferOwnership", "documentArchive", "documentRestore", "documentPublish", "commentCreate", "commentDelete", "commentDeleteOwn", "commentResolve", "commentReopen", "suggestionWithdraw", "reviewConsoleEnable", "reviewConsoleRead", "reviewConsoleScratchpadWrite", "reviewConsoleReplyPost", "folderRead", "folderEdit", "folderCreate", "folderDelete", "folderShare", "folderManagePermissions", "orgRead", "orgManage", "orgDelete", "orgManageSecurity", "orgManageBilling", "orgViewAuditLogs", "orgManageWebhooks", "tierNodeRead", "tierNodeManage", "tierNodeDelete", "tierNodeManageUsers", "tierNodeManageSecurity", "tierNodeManageBilling", "tierNodeViewAuditLogs", "tierNodeManageWebhooks", "companyRead", "companyManage", "companyDelete", "companyManageSecurity", "companyManageBilling", "companyManageOrgs", "companyManageAi", "traceCreate", "traceRead", "spaceRead", "spaceEdit", "spaceManage", "spaceCreate", "connectorRead", "connectorManage", "agentCreate", "agentInvoke", "agentManage", "webSearchInvoke", "sectionRead", "sectionEdit", "sectionSuggest", "manageProfile", "domainClaimCreate", "domainClaimVerify", "domainClaimRevoke", "freeProviderManage" ] }, "PinResourceRequest": { "type": "object", "description": "Request to pin an external resource to a Space.", "required": [ "connectorSourceId", "resourceUri", "resourceTitle" ], "properties": { "connectorSourceId": { "type": "string", "description": "ID of the connector source to fetch from." }, "resourceTitle": { "type": "string", "description": "Human-readable title for the pinned resource." }, "resourceUri": { "type": "string", "description": "Connector-defined resource identifier (e.g. `slack://C04ABC/thread-123`)." } } }, "PinnedItem": { "oneOf": [ { "type": "object", "description": "A pinned published document.", "required": [ "documentId", "position", "type" ], "properties": { "documentId": { "$ref": "#/components/schemas/TypedId", "description": "The document ID." }, "position": { "type": "integer", "format": "int32", "description": "Display position (0-indexed).", "minimum": 0 }, "type": { "type": "string", "enum": [ "document" ] } } } ], "description": "An item pinned to the top of a creator's profile page.\n\nMaximum 10 pinned items per profile. Items must be owned by the user\nand in Published state." }, "PinnedResourceContentResponse": { "type": "object", "description": "Content snapshot of a pinned resource.", "required": [ "pinId", "resourceTitle", "content", "contentType", "lastFetchedAt", "truncated" ], "properties": { "content": { "type": "string", "description": "The fetched content." }, "contentType": { "type": "string", "description": "Content MIME type." }, "externalUrl": { "type": [ "string", "null" ], "description": "Link to the original resource." }, "lastFetchedAt": { "type": "string", "format": "date-time", "description": "When the content was last fetched." }, "pinId": { "type": "string", "description": "Pin identifier." }, "resourceTitle": { "type": "string", "description": "Display name." }, "truncated": { "type": "boolean", "description": "Whether the content was truncated." } } }, "PinnedResourceResponse": { "type": "object", "description": "Response for a single pinned resource.", "required": [ "pinId", "spaceId", "connectorSourceId", "connectionId", "resourceUri", "resourceTitle", "connectorKind", "contentSizeBytes", "contentHash", "pinnedBy", "pinnedAt", "lastFetchedAt", "status" ], "properties": { "connectionId": { "type": "string", "description": "Parent connection (denormalized for cascade lookups)." }, "connectorIcon": { "type": [ "string", "null" ], "description": "Logo asset path for display." }, "connectorKind": { "type": "string", "description": "Connector kind (e.g. `slack`, `gmail`, `mcp`)." }, "connectorSourceId": { "type": "string", "description": "Connector source this was fetched from." }, "contentHash": { "type": "string", "description": "SHA-256 of fetched content (for change detection on refresh)." }, "contentSizeBytes": { "type": "integer", "format": "int64", "description": "Size of the stored snapshot in bytes.", "minimum": 0 }, "externalUrl": { "type": [ "string", "null" ], "description": "Link back to the original resource in the external service." }, "lastFetchedAt": { "type": "string", "format": "date-time", "description": "When the content snapshot was last fetched/refreshed." }, "pinId": { "type": "string", "description": "Pin identifier." }, "pinnedAt": { "type": "string", "format": "date-time", "description": "When the resource was first pinned." }, "pinnedBy": { "type": "string", "description": "User who pinned this resource." }, "resourceTitle": { "type": "string", "description": "Display name." }, "resourceUri": { "type": "string", "description": "Connector-defined resource identifier." }, "spaceId": { "type": "string", "description": "Parent Space." }, "status": { "$ref": "#/components/schemas/PinnedResourceStatus", "description": "Current lifecycle status." } } }, "PinnedResourceStatus": { "type": "string", "description": "Lifecycle status of a pinned external resource within a Space.", "enum": [ "active", "sourceUnavailable" ] }, "PlaceLegalHoldRequest": { "type": "object", "description": "Request to place a legal hold on a document.", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Free-text reason for the hold" } } }, "PlanDescriptor": { "type": "object", "description": "Full plan descriptor: every fact about a tier that the frontend needs to\nrender pricing cards, gating UI, and admin panels.\n\nAll numeric facts derive from the `BillingPlan` enum so the wire payload\nstays the single source of truth — duplicating these values in frontend\nconstants is a drift bug.", "required": [ "plan", "auditEnabled", "allowedModels", "gatedFeatures", "prices" ], "properties": { "allowedModels": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "Models permitted on this plan." }, "auditEnabled": { "type": "boolean", "description": "Whether tenants on this plan get an audit trail (emission + viewing)." }, "creditsPerSeat": { "type": [ "integer", "null" ], "format": "int64", "description": "Per-seat monthly credit allotment in user-facing whole credits, for\npaid tiers whose pool scales by seat (`Pro`). `None` for flat (`Free`)\nor negotiated (`Enterprise`) tiers.", "minimum": 0 }, "creditsPerWorkspace": { "type": [ "integer", "null" ], "format": "int64", "description": "Flat monthly workspace credit allotment in user-facing whole credits,\nfor tiers whose allowance does not scale by seat (`Free`). `None` for\nper-seat (`Pro`) or negotiated (`Enterprise`) tiers.", "minimum": 0 }, "gatedFeatures": { "type": "array", "items": { "$ref": "#/components/schemas/GatedFeature" }, "description": "Plan-gated features unlocked at this tier." }, "maxFoldersPerOrg": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum folders per organization (`None` = unlimited).", "minimum": 0 }, "maxMembers": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum members (`None` = unlimited).", "minimum": 0 }, "maxOrganizations": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum organizations (`None` = unlimited).", "minimum": 0 }, "maxStorageGb": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum storage in GB (`None` = unlimited).", "minimum": 0 }, "maxWatchesPerDocument": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum watches per document scope (`None` = unlimited).", "minimum": 0 }, "maxWatchesPerEdge": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum watches per subscription edge (`None` = unlimited).", "minimum": 0 }, "plan": { "$ref": "#/components/schemas/BillingPlan", "description": "Plan tier." }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PlanPriceInfo" }, "description": "Active per-cadence prices configured upstream. May be empty when\nthe tier is free or sales-quoted." } } }, "PlanLimitDetails": { "type": "object", "description": "Structured details for plan-limit enforcement errors.", "required": [ "resource", "current", "limit", "plan" ], "properties": { "current": { "type": "integer", "format": "int32", "description": "Current count of the resource.", "minimum": 0 }, "limit": { "type": "integer", "format": "int32", "description": "Maximum allowed by the plan.", "minimum": 0 }, "plan": { "$ref": "#/components/schemas/BillingPlan", "description": "The plan that imposed the limit." }, "resource": { "$ref": "#/components/schemas/PlanResource", "description": "Which resource type hit the limit." } } }, "PlanLimits": { "type": "object", "description": "Plan limit definitions for a tier.", "properties": { "maxMembers": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum members (`None` = unlimited).", "minimum": 0 }, "maxOrganizations": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum organizations (`None` = unlimited).", "minimum": 0 }, "maxStorageGb": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum storage in GB (`None` = unlimited).", "minimum": 0 }, "pricePerSeatCents": { "type": [ "integer", "null" ], "format": "int32", "description": "Monthly price per seat in USD cents (`None` = free or custom).", "minimum": 0 } } }, "PlanPriceInfo": { "type": "object", "description": "One plan/cadence price as configured in the upstream billing provider.\n\nReturned by `GET /api/v1/billing/plans`. Lets the frontend render plan\nprices without hardcoding amounts that have to be hand-synced with the\nprovider every time the price ladder shifts.", "required": [ "plan", "interval", "unitAmountCents", "currency" ], "properties": { "currency": { "type": "string", "description": "ISO-4217 currency code (e.g. `usd`)." }, "interval": { "$ref": "#/components/schemas/BillingInterval", "description": "Billing cadence (`monthly` or `annual`)." }, "plan": { "$ref": "#/components/schemas/BillingPlan", "description": "Plan tier this price covers." }, "unitAmountCents": { "type": "integer", "format": "int64", "description": "Unit amount in the smallest currency unit (cents for USD).\nFor per-seat plans this is the per-seat amount; the storefront\nmultiplies by seat count to render a workspace total.", "minimum": 0 } } }, "PlanResource": { "type": "string", "description": "Resource types that have plan-based quantity limits.\n\nUsed by the plan enforcement function to look up the per-plan cap\nfor a given resource category.", "enum": [ "member", "organization", "folder", "storage", "watchesPerEdge", "watchesPerDocument" ] }, "PlatformAgentMeta": { "type": "object", "description": "Metadata describing a built-in platform agent.\n\nExposed via the admin API so company admins can see which agents\nexist and selectively enable/disable them.", "required": [ "name", "displayName", "description", "enabledTools", "requiredPermissions", "supportsIncremental" ], "properties": { "description": { "type": "string", "description": "Human-readable description of what this agent does." }, "displayName": { "type": "string", "description": "Display name shown in the UI (e.g. `\"@formatter\"`)." }, "enabledTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names this agent is allowed to call." }, "name": { "type": "string", "description": "Canonical machine name (e.g. `\"formatter\"`)." }, "requiredPermissions": { "type": "array", "items": { "type": "string" }, "description": "Permission atoms required to run this agent (serialized `camelCase`)." }, "supportsIncremental": { "type": "boolean", "description": "Whether this agent supports incremental (diff-based) execution." } } }, "PlatformAgentOverride": { "type": "object", "description": "Per-agent overrides for a built-in platform agent.\n\nEach field is optional: `None` means the agent inherits the company-wide\ndefault from [`CompanyAgentSettings`]. `Some` narrows or replaces the\ncompany default for this specific agent.", "properties": { "allowedModels": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Model" }, "description": "Models this agent may use. Must be a subset of the company ceiling.\n`None` = inherit `CompanyAgentSettings::allowed_models`.", "uniqueItems": true }, "defaultModel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Model", "description": "Default model for this agent. `None` = platform default." } ] }, "systemPromptPrefix": { "type": [ "string", "null" ], "description": "Prompt prefix override. `None` = inherit company default." }, "systemPromptSuffix": { "type": [ "string", "null" ], "description": "Prompt suffix override. `None` = inherit company default." } } }, "PolicyDenialReason": { "type": "string", "description": "Machine-readable reason a connector policy denied a request.", "enum": [ "companyPolicyDisallowed", "killSwitchEngaged", "customMcpUnapproved", "unknownKind" ] }, "PolicyDenialResponse": { "type": "object", "description": "Policy denial payload returned with `403` responses on connector endpoints.", "required": [ "reason" ], "properties": { "message": { "type": [ "string", "null" ], "description": "Optional human-readable explanation." }, "reason": { "$ref": "#/components/schemas/PolicyDenialReason", "description": "Machine-readable denial reason." } } }, "PortalSessionResponse": { "type": "object", "description": "Response containing the portal session URL.", "required": [ "portalUrl" ], "properties": { "portalUrl": { "type": "string", "description": "URL to redirect the user to for the Stripe Customer Portal." } } }, "PostReplyRequest": { "type": "object", "description": "Request body for posting a card's draft as a reply on the shared\ncomment thread.\n\n`idempotency_key` is a client-generated `UUIDv4` nonce that lets the\nserver replay-safely deduplicate retries: the same nonce, paired with\nthe `(user, doc, comment)` tuple, returns the original reply id and\ntimestamp without creating a second reply on the shared thread.", "required": [ "body", "idempotencyKey" ], "properties": { "body": { "type": "string", "description": "Final reply body. 1..=65,536 UTF-8 bytes, validated as the raw\nstring (no leading/trailing trim applied at validation time —\ncallers that want to reject whitespace-only bodies should trim\nbefore submitting)." }, "idempotencyKey": { "type": "string", "description": "Client-generated `UUIDv4` nonce for idempotency." } } }, "PostReplyResponse": { "type": "object", "description": "Response body for a successful post.", "required": [ "replyCommentId", "postedAt", "sequenceNumber" ], "properties": { "postedAt": { "type": "string", "format": "date-time", "description": "Wall-clock when the reply was created." }, "replyCommentId": { "$ref": "#/components/schemas/TypedId", "description": "The reply created on the shared comment thread." }, "sequenceNumber": { "type": "integer", "format": "int64", "description": "New sequence number after the card-slot write.", "minimum": 0 } } }, "ProfileResponse": { "type": "object", "required": [ "id", "email", "displayName", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" } } }, "ProfileVisibility": { "type": "string", "description": "Public-presence state for a creator profile.\n\nControls whether the profile page (`/@{handle}`) and the creator's\npublished documents are reachable by the public. New profiles default to\n`Private`: hidden and excluded from search engines until the creator opts\nin. Serialized as lowercase: `\"private\"`, `\"public\"`.", "enum": [ "private", "public" ] }, "PromptArgument": { "type": "object", "description": "One named argument declared in a prompt's frontmatter. Mirrors the\nshape used by the MCP `prompts/list` payload, so the same struct\nserializes cleanly into both Strata's REST API and the MCP wire\nformat.", "required": [ "name", "description" ], "properties": { "description": { "type": "string", "description": "Short human-readable description shown in the slash-picker argument\nsheet, the MCP `prompts/list` payload, and the `loadUserPrompt`\ncatalog so the user (or the model) knows what to fill in. 1-200 chars." }, "name": { "type": "string", "description": "Identifier matched verbatim against the body's `{{name}}` placeholders.\nMatching is case-sensitive — `{{Focus}}` and `{{focus}}` are distinct\nplaceholders. Restricted to ASCII letters, digits, and underscores\n(1-48 chars) so the same identifier is valid in YAML and the\nplaceholder grammar." }, "required": { "type": "boolean", "description": "When true, the slash-picker argument sheet blocks submit until a\nvalue is supplied; the `loadUserPrompt` catalog also flags it so\nthe model knows it must ask the user to clarify. When false\n(default), an omitted argument substitutes the empty string into\nits placeholders at render time." } } }, "PromptFrontmatter": { "type": "object", "description": "The prompt's leading YAML frontmatter, parsed and validated.\n\nAuthors edit this directly in the prompt document; the server extracts\nit on every save and stores a derived [`PromptMetadata`] alongside the\ndocument row.", "required": [ "name", "description" ], "properties": { "arguments": { "type": "array", "items": { "$ref": "#/components/schemas/PromptArgument" }, "description": "Declared arguments — see the `PromptArgument` reference below for\nthe per-entry shape. Order is preserved across the wire so the\nslash-picker renders fields in the author's chosen order. Maximum\n16 entries. Empty when the prompt takes no arguments." }, "autoInvokable": { "type": "boolean", "description": "Default false. When true, the prompt is added to the per-request\n`loadUserPrompt` catalog so the chat model may call it on its\nown. Always false at MCP `prompts/list` (MCP is a user-picked\nsurface; gating it would hide the user's library from their own\nMCP client)." }, "description": { "type": "string", "description": "One-line description shown in the slash picker, the MCP listing,\nand the `loadUserPrompt` catalog so the model can decide whether\nto call the prompt for this user request." }, "name": { "type": "string", "description": "Human-readable name. Becomes the slash-picker label and is the\nsource of the URL-safe slug." } } }, "PromptListItem": { "type": "object", "description": "One entry in the slash picker / settings list / MCP `prompts/list`\nresponse — the prompt's identity plus the cached metadata needed to\nrender its label without fetching the body.", "required": [ "id", "title", "metadata", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/TypedId", "description": "Document ID." }, "metadata": { "$ref": "#/components/schemas/PromptMetadata", "description": "Cached prompt metadata. Always present; the listing endpoint\nfilters out documents whose `prompt_metadata` is `None` (e.g.\ndocuments under a non-prompt folder)." }, "title": { "type": "string", "description": "Document title (separate from frontmatter `name` when the user\nhas renamed the document — slug always derives from\nfrontmatter `name`)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp, surfaced so the slash picker can sort\nrecently-edited prompts to the top." } } }, "PromptMetadata": { "allOf": [ { "$ref": "#/components/schemas/PromptFrontmatter", "description": "Inlined canonical frontmatter. `#[serde(flatten)]` keeps the\nstored DDB JSON wire-flat so existing rows deserialize cleanly\n(same key set as before this refactor — no migration needed)." }, { "type": "object", "required": [ "slug" ], "properties": { "frontmatterError": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FrontmatterError", "description": "Set when the extractor refused to accept the frontmatter as-is,\neither because the YAML failed to parse, because the slug\ncollided with another prompt, or because the body referenced\nundeclared placeholders. Cleared on the next clean save." } ] }, "slug": { "type": "string", "description": "Deduplicated kebab-case slug derived from `frontmatter.name`.\nDrives the in-app slash token (`/prompt:`) and the MCP\n`prompts/get` lookup key. Genuinely derived (not in the\nfrontmatter) so it stays as an extension field rather than\nfolding into the flattened frontmatter." } } } ], "description": "Cached, derived metadata persisted alongside every prompt document.\nPopulated by the server-side frontmatter extractor on save and read\nby every prompt-aware surface (slash picker, MCP, `loadUserPrompt`,\nsettings page) so the body never has to be reparsed at request time.\n\nComposed of the canonical [`PromptFrontmatter`] (flattened, so the\nwire shape stays a flat camelCase JSON object) plus two derived\nextensions: `slug` (deduplicated kebab-case identifier computed\nfrom `frontmatter.name`) and `frontmatter_error`. Adding a field\nto `PromptFrontmatter` automatically extends `PromptMetadata` —\ncallers reach into `metadata.frontmatter.` for canonical\nfields and `metadata.{slug,frontmatter_error}` for the derived\nslots." }, "PromptSourceRef": { "type": "object", "description": "Provenance reference attached to a user chat message that was produced\nby invoking `/prompt:`. Carries just enough identity to render a\n\"from /prompt:...\" chip in chat history and link back to the underlying\nprompt document. Optional on every chat message — only populated when\nthe user actually invoked a prompt.", "required": [ "id", "slug", "name" ], "properties": { "id": { "$ref": "#/components/schemas/TypedId", "description": "Document ID of the source prompt. Suitable for routing to the\ndocument detail surface." }, "name": { "type": "string", "description": "Display name from the prompt's frontmatter." }, "slug": { "type": "string", "description": "Slug from the prompt's frontmatter (`/prompt:`)." } } }, "PromptsSettingsResponse": { "type": "object", "description": "Response body for `GET /api/v1/prompts/settings` and the body of\n`PATCH /api/v1/prompts/settings` (re-used so the client can read\nback the new state without an extra round-trip).", "required": [ "enabled", "totalPromptCount", "autoInvokableCount", "autoInvokableAdvisoryCap" ], "properties": { "autoInvokableAdvisoryCap": { "type": "integer", "format": "int32", "description": "Soft advisory cap surfaced in the settings page once\n`auto_invokable_count` exceeds it. Echoed in the response so the\nclient can render the advisory message without hardcoding the\nnumber.", "minimum": 0 }, "autoInvokableCount": { "type": "integer", "format": "int32", "description": "Number of prompt documents with `autoInvokable: true` and a\nvalid frontmatter (i.e. visible to `loadUserPrompt`).", "minimum": 0 }, "enabled": { "type": "boolean", "description": "Master toggle. When false, the `loadUserPrompt` tool and the\nMCP `prompts` capability are both suppressed for this user, and\nthe in-app `/prompt:` slash namespace returns an empty list." }, "folderId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "ID of the auto-provisioned `Prompts/` folder, when present.\n`None` only if provisioning has not yet completed (effectively\nalways populated for a logged-in user)." } ] }, "totalPromptCount": { "type": "integer", "format": "int32", "description": "Total number of prompt documents owned by this user (including\ndrafts with frontmatter errors).", "minimum": 0 } } }, "ProviderCredentialStatus": { "type": "object", "description": "Per-provider status row in the GET list response. Exactly one entry\nper provider in `PROVIDERS` (not just one per configured override).\n\nThis is the type that satisfies FR-019: UI and resolver agree on which\nlevel is active for each provider.", "required": [ "provider", "source", "byoOnly", "platformAvailable" ], "properties": { "byoOnly": { "type": "boolean", "description": "`true` when at least one connector metadata entry for this\nprovider sets `byo_only = true`. When `source == Unconfigured` the\nUI uses this to pick between the FR-003 and FR-004 instruction\ncopy." }, "hasLiveUserGrants": { "type": "boolean", "description": "`true` when the company has at least one `UserConnectorGrant` row\nagainst any connector under this provider. Drives the visibility\nof the `Revoke all user grants` menu item in the Company `OAuth`\napps table (FR-059). Computed at response-build time in the list\nhandler by counting grant rows per provider." }, "overrideInfo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthOverrideResponse", "description": "Present only when `source == CompanyOverride`. `None` for\n`Platform` and `Unconfigured`. Never contains secret material." } ] }, "platformAvailable": { "type": "boolean", "description": "`true` when a Strata platform `OAuth` application is currently\nloaded in the `PlatformOAuthAppRegistry` for this provider.\nRemains `true` even when `source == CompanyOverride` — the admin\ncan remove the override and fall back to the platform app." }, "provider": { "$ref": "#/components/schemas/OAuthProvider", "description": "The provider this row describes." }, "source": { "$ref": "#/components/schemas/ProviderSource", "description": "Current active source for this `(company, provider)` pair." } } }, "ProviderSource": { "type": "string", "description": "Which level of the credential hierarchy is *currently* serving a given\nprovider for a company. Distinct from `OAuthAppSource` in that it\nincludes the \"no source at all\" case, which the UI surfaces as \"needs\nsetup\".", "enum": [ "platform", "companyOverride", "unconfigured" ] }, "ProvisionEnterpriseRequest": { "type": "object", "description": "Request to provision an enterprise company via internal API.", "required": [ "companyName", "slug", "adminEmail" ], "properties": { "adminEmail": { "type": "string", "description": "Admin email address" }, "companyName": { "type": "string", "description": "Company name" }, "slug": { "type": "string", "description": "URL-safe slug" } } }, "ProvisionEnterpriseResponse": { "type": "object", "description": "Response after provisioning an enterprise company.", "required": [ "companyId", "tenantId", "adminUserId", "activationToken", "activationUrl" ], "properties": { "activationToken": { "type": "string", "description": "Activation token (ULID)" }, "activationUrl": { "type": "string", "description": "Full activation URL" }, "adminUserId": { "type": "string", "description": "Created admin user ID" }, "companyId": { "type": "string", "description": "Created company ID" }, "tenantId": { "type": "string", "description": "Created organization (tenant) ID" } } }, "ProvisioningMethod": { "type": "string", "description": "User provisioning method for SSO connections", "enum": [ "jit", "scim" ] }, "PublicDocumentResponse": { "type": "object", "description": "Safe subset of [`Document`] fields for unauthenticated public-link access.\n\nOmits internal-only fields (`owner_id`, `folder_id`, `tenant_id`,\n`hold_count`, `pending_ops_count`, etc.) that must not be disclosed to\nunauthenticated callers. Used as the response body for\n`GET /api/v1/public/documents/{token}`.", "required": [ "id", "title", "contentType", "documentVersion", "publishedState", "publishCount", "effectiveRole", "createdAt", "updatedAt" ], "properties": { "contentType": { "$ref": "#/components/schemas/ContentType", "description": "Content format (markdown, html, docx, etc.)." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "documentVersion": { "type": "integer", "format": "int64", "description": "Document-level version counter.", "minimum": 0 }, "effectiveRole": { "$ref": "#/components/schemas/ResourceRole", "description": "The caller's effective role on this document, derived from the public link." }, "id": { "type": "string", "description": "Document identifier." }, "lastPublishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent publish. `None` when never published." }, "latestPublishedVersion": { "type": [ "integer", "null" ], "format": "int32", "description": "Latest published version number. `None` until first publish.", "minimum": 0 }, "publishCount": { "type": "integer", "format": "int32", "description": "Total number of publish operations.", "minimum": 0 }, "publishedState": { "$ref": "#/components/schemas/PublishedState", "description": "Publishing lifecycle state (`draft` or `published`)." }, "slug": { "type": [ "string", "null" ], "description": "URL slug assigned on first publish. `None` while never published." }, "title": { "type": "string", "description": "Document title." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "PublicLinkResponse": { "type": "object", "required": [ "token", "url", "role", "createdAt", "passwordProtected", "accessCount", "watermarked" ], "properties": { "accessCount": { "type": "integer", "format": "int64", "description": "Number of times this link has been accessed", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxAccessCount": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum number of accesses allowed", "minimum": 0 }, "passwordProtected": { "type": "boolean", "description": "Whether a password is required to access this link" }, "role": { "$ref": "#/components/schemas/ResourceRole" }, "token": { "type": "string" }, "url": { "type": "string" }, "watermarked": { "type": "boolean", "description": "Whether watermarks are applied" } } }, "PublicShareCloneRequest": { "type": "object", "description": "Request body for the clone-by-token endpoint. Currently empty —\nthe shape exists so future options (e.g. a `targetSpaceId` that\nplaces the clone into a specific Space rather than the\nrequester's personal workspace) can extend it without breaking\nthe URL pattern. Callers MAY send `{}` or omit the body entirely." }, "PublicShareCloneResponse": { "type": "object", "description": "Response body for the clone-by-token endpoint. The webapp\nnavigates to `redirect_url` after a successful clone — for\n`clone_doc` the URL is `/app/documents/{newDocId}`; for the\n`remix_doc` variant the webapp appends `?openChat=1` client-side\nto drive the chat-panel auto-open.", "required": [ "documentId", "ownerId", "tenantId", "redirectUrl", "clonedFrom" ], "properties": { "clonedFrom": { "$ref": "#/components/schemas/DocumentProvenance", "description": "Provenance reference back to the source document." }, "documentId": { "$ref": "#/components/schemas/TypedId", "description": "The newly-created document's id (typed ULID, prefix `doc_`)." }, "ownerId": { "$ref": "#/components/schemas/TypedId", "description": "The requester's user id (JWT subject) — same identity that\nowns the new document." }, "redirectUrl": { "type": "string", "description": "Relative URL the webapp should navigate to after the clone\nlands. Always ends in `/app/documents/{documentId}`." }, "tenantId": { "$ref": "#/components/schemas/TypedId", "description": "The requester's personal workspace tenant — where the new\ndocument landed regardless of the source document's tenant." } } }, "PublishDocumentRequest": { "type": "object", "description": "Optional body for publish request.", "properties": { "pinToProfile": { "type": "boolean", "description": "Whether to pin this document to the author's profile." }, "slug": { "type": [ "string", "null" ], "description": "Caller-supplied slug for the published URL.\n\nHonored **only on first publish** — slugs are immutable once assigned.\nPassing a slug on a republish is rejected with `Conflict`. When `None`\non first publish, the slug is derived from the document title.\nValidated server-side; malformed values return `BadRequest`." } } }, "PublishDocumentResponse": { "type": "object", "description": "Response from a successful publish operation.", "required": [ "url", "version", "publishedAt", "slug", "hasUnpublishedChanges" ], "properties": { "hasUnpublishedChanges": { "type": "boolean", "description": "Whether the document has unpublished changes." }, "publishedAt": { "type": "string", "description": "When this version was published." }, "slug": { "type": "string", "description": "URL slug for the published document." }, "url": { "type": "string", "description": "Public URL for the published document." }, "version": { "type": "integer", "format": "int32", "description": "Version number of this publish.", "minimum": 0 } } }, "PublishStatusResponse": { "oneOf": [ { "type": "object", "description": "Document has never been published.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "neverPublished" ] } } }, { "type": "object", "description": "Document is currently published. `hasUnpublishedChanges` is true when\nthe live Yjs state has diverged from the latest published snapshot.", "required": [ "slug", "url", "lastPublishedAt", "hasUnpublishedChanges", "kind" ], "properties": { "hasUnpublishedChanges": { "type": "boolean", "description": "True when the document has edits that have not been re-published." }, "kind": { "type": "string", "enum": [ "published" ] }, "lastPublishedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent publish." }, "slug": { "type": "string", "description": "URL slug assigned at first publish." }, "url": { "type": "string", "description": "Canonical public URL (`/@handle/slug`)." } } }, { "type": "object", "description": "Document was published but has since been unpublished. The slug/URL\nare retained for display but currently 404.", "required": [ "slug", "url", "lastPublishedAt", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "unpublished" ] }, "lastPublishedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent publish (preserved across\nunpublish — see `DocumentRepository::mark_unpublished`)." }, "slug": { "type": "string", "description": "The slug the document was last published at." }, "url": { "type": "string", "description": "The URL the document was last published at (now 404)." } } } ], "description": "Publish status for a document.\n\nThree wire states capture the 4-state UI pill: the `Published` variant\ncarries `hasUnpublishedChanges` so the frontend can render \"published\" vs\n\"published · edits pending\" from the same payload. Modeled as a\ndiscriminated union so callers exhaustively match — adding a future\nstate (e.g. scheduled) becomes a compile error at call sites." }, "PublishedState": { "type": "string", "description": "Publishing lifecycle state for documents.\n\nSerialized as lowercase: `\"draft\"`, `\"published\"`.", "enum": [ "draft", "published" ] }, "PublishingProfileResponse": { "type": "object", "description": "Response for authenticated profile read/update.", "required": [ "userId", "handle", "visibility", "pinned", "createdAt" ], "properties": { "avatarUrl": { "type": [ "string", "null" ], "description": "Avatar URL." }, "bio": { "type": [ "string", "null" ], "description": "Short biography." }, "createdAt": { "type": "string", "description": "When the profile was created." }, "handle": { "type": "string", "description": "Globally unique handle." }, "handleChangedAt": { "type": [ "string", "null" ], "description": "When the handle was last changed." }, "pinned": { "type": "array", "items": { "$ref": "#/components/schemas/PinnedItem" }, "description": "Pinned items on profile." }, "userId": { "type": "string", "description": "User ID." }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility", "description": "Public-presence state. `Private` means the profile page is hidden and\nthe creator's documents cannot be published." } } }, "PutOAuthOverrideRequest": { "type": "object", "description": "Request body for `PUT /api/v1/companies/{companyId}/oauth-overrides/{provider}`.\n\nBoth fields are required and bounded by `garde` at the handler\nboundary. The `client_secret` is encrypted server-side and never echoed\nback in any response.", "required": [ "clientId", "clientSecret" ], "properties": { "clientId": { "type": "string", "description": "The `OAuth` client ID registered at the third-party provider." }, "clientSecret": { "type": "string", "description": "The `OAuth` client secret. Encrypted by the credential vault before\nstorage; never echoed back in any response." } } }, "QuotaDetails": { "type": "object", "description": "Structured details for quota-exceeded errors.", "required": [ "meter", "current", "limit", "resetsAt" ], "properties": { "current": { "type": "integer", "format": "int64", "description": "Current usage count.", "minimum": 0 }, "limit": { "type": "integer", "format": "int64", "description": "Maximum allowed by the plan.", "minimum": 0 }, "meter": { "type": "string", "description": "Which meter was exceeded (e.g. `\"aiTokens\"`)." }, "resetsAt": { "type": "string", "description": "ISO 8601 date when the quota resets." } } }, "RateLimitResponse": { "type": "object", "description": "Response for rate limit status.", "required": [ "messagesUsed", "dailyLimit", "resetsAt" ], "properties": { "dailyLimit": { "type": "integer", "format": "int32", "description": "Plan-based daily limit.", "minimum": 0 }, "messagesUsed": { "type": "integer", "format": "int32", "description": "Messages sent today.", "minimum": 0 }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the counter resets." } } }, "ReconciliationResponse": { "type": "object", "description": "Response from the reconciliation endpoint.", "required": [ "status", "actualCount" ], "properties": { "actualCount": { "type": "integer", "format": "int32", "description": "Current member count.", "minimum": 0 }, "status": { "$ref": "#/components/schemas/ReconciliationStatus", "description": "Reconciliation outcome." }, "stripeQuantity": { "type": [ "integer", "null" ], "format": "int32", "description": "Stripe subscription quantity (`None` if no subscription).", "minimum": 0 } } }, "ReconciliationStatus": { "type": "string", "description": "Reconciliation status after comparing member count to Stripe quantity.", "enum": [ "synced", "corrected", "skipped" ] }, "ReferencedDoc": { "type": "object", "description": "One resolved reference. Same-company-but-unreadable docs are returned\nwith `can_read = false` and `title = None` so the UI can render a\ndisabled row without leaking the title. Cross-company IDs are not\nreturned at all.", "required": [ "docId", "canRead", "alreadyConnected" ], "properties": { "alreadyConnected": { "type": "boolean", "description": "Whether a connection between the source and this doc already exists\n(in either direction). Lets the UI skip the \"Connect\" affordance for\nalready-connected refs without a separate roundtrip." }, "canRead": { "type": "boolean", "description": "Whether the caller has read access to the document." }, "docId": { "type": "string", "description": "The document ID that was resolved." }, "title": { "type": [ "string", "null" ], "description": "The document's title, if the caller can read it." } } }, "RefreshFromSourceResponse": { "type": "object", "description": "Response body for `POST /api/v1/documents/{docId}/refresh-from-source`.", "required": [ "docId", "refreshOutcome", "source" ], "properties": { "docId": { "type": "string", "description": "The document that was refreshed." }, "refreshOutcome": { "$ref": "#/components/schemas/RefreshOutcome", "description": "What the refresh operation did." }, "source": { "$ref": "#/components/schemas/ImportSourceResponse", "description": "Updated provenance for the document." } } }, "RefreshOutcome": { "type": "string", "description": "Outcome of a refresh-from-source operation.", "enum": [ "contentUpdated", "noChange", "sourceUnavailable" ] }, "RegenerateDraftRequest": { "type": "object", "description": "Request body for regenerating a card's reply draft.\n\n`author_hint` is a free-form steering string. The hint is carried\nend-to-end so a future UI iteration can surface it; today's UI sends\nthe empty string.", "required": [ "authorHint" ], "properties": { "authorHint": { "type": "string", "description": "Author hint biasing the draft (tone, position, length). Required\non the wire; pass an empty string when no hint is being supplied.\nAt most 500 characters." } } }, "RegenerateDraftResponse": { "type": "object", "description": "Response body for a successful regenerate.\n\n`tokens_remaining` reflects the user's AI quota after this call;\n`sequence_number` is the post-write CAS token the client must use on\nsubsequent edits to the same card slot to maintain CAS coherence.", "required": [ "draftBody", "citations", "tokensUsed", "tokensRemaining", "sequenceNumber" ], "properties": { "citations": { "type": "array", "items": { "$ref": "#/components/schemas/DraftCitation" }, "description": "Verified citations referenced by the draft body." }, "draftBody": { "type": "string", "description": "Newly generated reply body, with verified `[^N]` markers retained." }, "sequenceNumber": { "type": "integer", "format": "int64", "description": "New sequence number after the write — clients use this on\nsubsequent edits to the same card to maintain CAS coherence.", "minimum": 0 }, "tokensRemaining": { "type": "integer", "format": "int64", "description": "Tokens remaining in the caller's quota window after this call.", "minimum": 0 }, "tokensUsed": { "type": "integer", "format": "int64", "description": "Tokens consumed by this regenerate call.", "minimum": 0 } } }, "RegisterCustomMcpRequest": { "type": "object", "description": "Registers a custom MCP server by URL. Discovery runs immediately; the\nresulting manifest requires admin approval before users can see the\nconnector in their Connections panel.", "required": [ "url" ], "properties": { "displayName": { "type": [ "string", "null" ], "description": "Optional human-readable display name. Falls back to the server name\ndiscovered from the MCP handshake if omitted." }, "url": { "type": "string", "description": "HTTPS URL of the MCP server endpoint." } } }, "RegisterMcpConnectorRequest": { "type": "object", "description": "Request to register a custom `MCP` connector. First-party\ndeclarative connectors (Slack, Notion, GitHub, …) are lazy-created\non the first authorize call and do NOT use this endpoint.", "required": [ "kind", "config" ], "properties": { "config": { "description": "Provider-specific configuration blob — at minimum the `MCP`\nURL, optionally auth config (bearer token reference, mTLS\nmaterial ref)." }, "kind": { "type": "string", "description": "Namespaced kind for the custom `MCP` server. Should follow the\n`mcp:{slug}` convention (e.g. `mcp:engineering-wiki`) so\nmultiple custom servers per company don't collide." } } }, "RememberMessageRequest": { "type": "object", "description": "Request body for `POST /chat/sessions/{sessionId}/messages/{messageId}/remember`.\nOne-shot \"remember this message\" action. The server fetches the referenced\nmessage by `(sessionId, messageId)` and uses its content — the caller does\nnot supply body text, so the `memoryType` and `name` fields are the only\nper-request knobs (both optional). `messageId` in the URL is the message\nsequence number (stringified `u32`).", "properties": { "memoryType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MemoryType", "description": "Optional explicit type — defaults to `feedback` (the most typical\nsignal when a user hand-picks a message to remember)." } ] }, "name": { "type": [ "string", "null" ], "description": "Short name for the entry. When absent, derived from the message\ncontent fetched server-side." } } }, "RenderPromptRequest": { "type": "object", "description": "Request body for `POST /prompts/{id}/render`. Empty for prompts with\nno declared arguments. Unknown keys are ignored; missing required\nkeys cause a 400 with the offending names listed.", "properties": { "arguments": { "type": "object", "description": "Map of argument name → value. Values are interpolated verbatim\ninto the body's `{{name}}` placeholders.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "RenderedPrompt": { "type": "object", "description": "Server-rendered prompt body returned by `POST /prompts/{id}/render`,\nthe MCP `prompts/get` handler, and the `loadUserPrompt` agent tool.\n\n`content` is the rendered markdown body. When the caller supplied\narguments, declared `{{name}}` placeholders are substituted; missing\noptional arguments are replaced with empty strings, and unknown\nplaceholders are left intact. The agent path always passes an empty\nargument map so the model receives the template verbatim and can\ndecide whether to substitute from context or ask the user.", "required": [ "promptId", "content" ], "properties": { "arguments": { "type": "array", "items": { "$ref": "#/components/schemas/PromptArgument" }, "description": "Argument descriptors, returned alongside the body so the model\ncan read each argument's description without parsing the body\nitself. Empty for prompts that declare no arguments." }, "content": { "type": "string", "description": "Rendered markdown body." }, "promptId": { "$ref": "#/components/schemas/TypedId", "description": "Prompt ID, echoed back so callers (especially the MCP handler)\ndon't have to track it separately." } } }, "ReopenCommentResponse": { "type": "object", "description": "Response from reopening a resolved comment thread.", "required": [ "commentId", "status", "reopenedBy" ], "properties": { "commentId": { "type": "string" }, "reopenedBy": { "type": "string" }, "status": { "$ref": "#/components/schemas/CommentStatus" } } }, "RepoConnectionResponse": { "type": "object", "description": "Response for a single repository connection.", "required": [ "id", "companyId", "provider", "providerInstallationId", "providerAccountName", "status", "scopes", "repoSourceCount", "createdAt", "updatedAt" ], "properties": { "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Approval timestamp" }, "approvedBy": { "type": [ "string", "null" ], "description": "User who approved (if approved)" }, "companyId": { "type": "string", "description": "Owning company" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "id": { "type": "string", "description": "Connection identifier" }, "provider": { "$ref": "#/components/schemas/RepoProvider", "description": "Code hosting provider" }, "providerAccountName": { "type": "string", "description": "Human-readable provider account name" }, "providerInstallationId": { "type": "string", "description": "Provider-side installation identifier" }, "repoSourceCount": { "type": "integer", "format": "int32", "description": "Number of repo sources using this connection", "minimum": 0 }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permission scopes granted" }, "status": { "$ref": "#/components/schemas/RepoConnectionStatus", "description": "Current lifecycle status" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "RepoConnectionStatus": { "type": "string", "description": "Repository connection lifecycle state.\n\nConnections transition: `Pending` → `Active` (approve) → `Revoked` (terminal).\nGitHub can also `Suspend`/`Unsuspend` active connections.\nSerialized as camelCase: `\"pending\"`, `\"active\"`, `\"suspended\"`, `\"revoked\"`.", "enum": [ "pending", "active", "suspended", "revoked" ] }, "RepoProvider": { "type": "string", "description": "Code hosting provider.\n\nSupports `GitHub`, `GitLab`, and `Bitbucket`.\nSerialized as camelCase: `\"gitHub\"`, `\"gitLab\"`, `\"bitbucket\"`.", "enum": [ "gitHub", "gitLab", "bitbucket" ] }, "RepoSourceResponse": { "type": "object", "description": "Response for a single repository source.", "required": [ "id", "companyId", "spaceId", "connectionId", "provider", "repoFullName", "defaultBranch", "status", "createdBy", "createdAt", "updatedAt" ], "properties": { "companyId": { "type": "string", "description": "Owning company" }, "connectionId": { "type": "string", "description": "Parent connection" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "createdBy": { "type": "string", "description": "User who created this source" }, "defaultBranch": { "type": "string", "description": "Tracked branch" }, "errorMessage": { "type": [ "string", "null" ], "description": "Error details when status is `Error`" }, "id": { "type": "string", "description": "Source identifier" }, "pausedReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PausedReason", "description": "Why this source is paused (only present when `status == paused`)" } ] }, "provider": { "$ref": "#/components/schemas/RepoProvider", "description": "Code hosting provider" }, "repoFullName": { "type": "string", "description": "Full repository name" }, "spaceId": { "type": "string", "description": "Target Space" }, "status": { "$ref": "#/components/schemas/RepoSourceStatus", "description": "Current lifecycle status" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "RepoSourceStatus": { "type": "string", "description": "Repository source lifecycle state.\n\nSources start `Active` and can be `Paused` manually or set to\n`Error` by the system. Serialized as camelCase.", "enum": [ "active", "paused", "error" ] }, "RepositoryList": { "type": "object", "description": "Paginated list of repositories from a provider.", "required": [ "repositories" ], "properties": { "nextPage": { "type": [ "integer", "null" ], "format": "int32", "description": "Next page number (absent if this is the last page)", "minimum": 0 }, "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/RepositoryListItem" }, "description": "The repositories on this page" } } }, "RepositoryListItem": { "type": "object", "description": "A single repository from the provider's repository listing.", "required": [ "fullName", "defaultBranch", "private", "updatedAt" ], "properties": { "defaultBranch": { "type": "string", "description": "Default branch name" }, "description": { "type": [ "string", "null" ], "description": "Repository description" }, "fullName": { "type": "string", "description": "Full repository name (owner/repo format)" }, "private": { "type": "boolean", "description": "Whether the repository is private" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "RequestConnectorAccessBody": { "type": "object", "description": "Request body for `POST /api/v1/connectors/{kind}/access-requests`.", "properties": { "reason": { "type": [ "string", "null" ], "description": "Optional justification for the access request (max 500 chars)." } } }, "RequestSuggestionRevisionRequest": { "type": "object", "description": "Request body for requesting a revision on a suggestion.", "required": [ "feedback" ], "properties": { "feedback": { "type": "string", "description": "Free-text feedback for the agent describing the desired revision." } } }, "RequestSuggestionRevisionResponse": { "type": "object", "description": "Response after requesting a revision on a suggestion.", "required": [ "suggestionId", "commentId" ], "properties": { "commentId": { "type": "string", "description": "The comment thread created with the revision feedback." }, "suggestionId": { "type": "string", "description": "The suggestion that was flagged for revision." } } }, "ResolveCommentResponse": { "type": "object", "description": "Response from resolving a comment thread.", "required": [ "commentId", "status", "resolvedBy", "resolvedAt" ], "properties": { "commentId": { "type": "string" }, "resolvedAt": { "type": "string", "format": "date-time" }, "resolvedBy": { "type": "string" }, "status": { "$ref": "#/components/schemas/CommentStatus" } } }, "ResolveImageUrlsRequest": { "type": "object", "description": "Request body for batch URL resolution.\n\n`document_id` must reference a document the caller has `DocumentRead` on.\nThe check is a necessary but not sufficient proof of containment: the\nsystem verifies that the caller can read the stated document, but does not\nverify that every image ID is embedded in that document (no per-doc image\nindex exists). The check closes the unauthenticated-access path (DOC-16);\nthe residual intra-tenant bypass requires a future doc→image containment\nindex to fully close (DOC-17 partial mitigation).", "required": [ "documentId", "imageIds" ], "properties": { "documentId": { "$ref": "#/components/schemas/TypedId", "description": "Document the images belong to. The caller must have `DocumentRead` on\nthis document." }, "imageIds": { "type": "array", "items": { "$ref": "#/components/schemas/ImageId" }, "description": "Image IDs to resolve (max 50)." } } }, "ResolveImageUrlsResponse": { "type": "object", "description": "Response for batch URL resolution.", "required": [ "urls" ], "properties": { "urls": { "type": "object", "description": "Map of image ID → resolved URL info.", "additionalProperties": { "$ref": "#/components/schemas/ResolvedImageUrl" }, "propertyNames": { "type": "string" } } } }, "ResolvedImageUrl": { "type": "object", "description": "A resolved presigned URL for an image.", "required": [ "url", "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "When the URL expires." }, "url": { "type": "string", "description": "Presigned download URL." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedImageVariantUrl" }, "description": "Optional responsive image variant URLs." } } }, "ResolvedImageVariantUrl": { "type": "object", "description": "A resolved presigned URL for a responsive image variant.", "required": [ "width", "url", "expiresAt", "mimeType" ], "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "When the URL expires." }, "mimeType": { "type": "string", "description": "MIME type of the variant." }, "url": { "type": "string", "description": "Presigned download URL." }, "width": { "type": "integer", "format": "int32", "description": "Width descriptor in pixels.", "minimum": 0 } } }, "ResourceRole": { "type": "string", "description": "Access role levels for documents and folders.\n\nCapabilities are expressed via `can_*` methods. The enum no longer\nderives `Ord`/`PartialOrd` — authorization checks MUST use capability\nmethods or the exhaustive-match aggregator [`effective_resource_role`]\nso variant reordering or insertion can't silently change authz\nsemantics.", "enum": [ "suggestOnly", "viewer", "commenter", "editor", "owner" ] }, "RetentionPolicyResponse": { "type": "object", "description": "API response for the organization's retention policy.", "required": [ "trashRetentionDays" ], "properties": { "autoArchiveDays": { "type": [ "integer", "null" ], "format": "int32", "description": "Days of inactivity before auto-archiving (absent means disabled)", "minimum": 0 }, "trashRetentionDays": { "type": "integer", "format": "int32", "description": "Days trashed documents are retained before permanent purge", "minimum": 0 } } }, "RetentionPolicyUpdateRequest": { "type": "object", "description": "Request to update the organization's retention policy.", "properties": { "autoArchiveDays": { "type": [ "integer", "null" ], "format": "int32", "description": "Days of inactivity before auto-archiving; `null` to disable", "minimum": 0 }, "trashRetentionDays": { "type": [ "integer", "null" ], "format": "int32", "description": "Days to retain trashed documents (1-3650)", "minimum": 0 } } }, "RevertDocumentRequest": { "type": "object", "description": "Request to revert a document to a prior point in its history.", "required": [ "sequenceId" ], "properties": { "sequenceId": { "type": "string", "description": "Sequence ID of the WAL record to revert to." } } }, "ReviewConsoleCardSlot": { "type": "object", "description": "Per-author-per-document-per-comment scratchpad slot.\n\nCreated on first per-card mutation. Subsequent writes use compare-and-swap\non `sequence_number`. The drafting fields (`draft_body`, `author_notes`,\n`addressed`, `last_regenerated_at`) round-trip the wire shape but may\nremain at their defaults until the drafting flow is wired.", "required": [ "userId", "documentId", "commentId", "sequenceNumber", "updatedAt" ], "properties": { "addressed": { "type": "boolean", "description": "Mark-addressed flag." }, "addressedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Wall-clock when the card was first marked addressed (whether by a\npost or by an explicit Mark addressed action). `None` while the\ncard is open." }, "addressedBy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "User who marked the card addressed; always equals `user_id` on the\nrow but tracked separately for audit clarity." } ] }, "authorNotes": { "type": "string", "description": "Author's private notes about the comment." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/DraftCitation" }, "description": "Verified citations from the most recent regenerate. Empty until the\nfirst regenerate completes; pruned to anchors that resolve against\nthe document heading map at write time." }, "commentId": { "$ref": "#/components/schemas/TypedId", "description": "Comment this slot is keyed by." }, "documentId": { "$ref": "#/components/schemas/TypedId", "description": "Document this card belongs to." }, "draftBody": { "type": "string", "description": "Reply draft body — empty until first regenerate." }, "lastRegeneratedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last regenerate timestamp." }, "postedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Wall-clock when the reply was posted to the shared thread." }, "postedReplyId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Reply id created on the shared comment thread when the card was\nposted. `None` for cards that were marked addressed without posting\nor that are still open." } ] }, "regenerateCount": { "type": "integer", "format": "int32", "description": "Number of times the draft has been regenerated for this card.", "minimum": 0 }, "sequenceNumber": { "type": "integer", "format": "int64", "description": "Slot sequence number — every CAS write must match this.", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last write timestamp." }, "userId": { "$ref": "#/components/schemas/TypedId", "description": "Owner." } } }, "ReviewConsoleEvent": { "oneOf": [ { "type": "object", "description": "A severity has been written for the comment for the first time, or\nrewritten at a strictly newer source version than the prior\nclassification.", "required": [ "commentId", "severity", "sourceVersion", "kind" ], "properties": { "commentId": { "$ref": "#/components/schemas/TypedId", "description": "The classified comment." }, "kind": { "type": "string", "enum": [ "severityClassified" ] }, "severity": { "$ref": "#/components/schemas/Severity", "description": "Canonical severity (does not include per-author overrides)." }, "sourceVersion": { "type": "integer", "format": "int64", "description": "Source comment version this severity was derived from.", "minimum": 0 } } }, { "type": "object", "description": "A theme assignment has been written for the comment, either joining\nan existing theme or seeding a new one.", "required": [ "commentId", "themeId", "themeLabel", "sourceVersion", "kind" ], "properties": { "commentId": { "$ref": "#/components/schemas/TypedId", "description": "The classified comment." }, "kind": { "type": "string", "enum": [ "themeAssigned" ] }, "sourceVersion": { "type": "integer", "format": "int64", "description": "Source comment version this assignment was derived from.", "minimum": 0 }, "themeId": { "$ref": "#/components/schemas/TypedId", "description": "Assigned theme." }, "themeLabel": { "type": "string", "description": "Inline theme label so the consumer can render the chip without\na follow-up fetch. Always matches the label on the corresponding\ntheme registry record." } } }, { "type": "object", "description": "A reply was posted on the shared comment thread for this card.\nFanned out on the per-document channel so collaborators see the\nnew reply without a chassis reload. Carries the source comment\nversion so consumers can drop out-of-order events.", "required": [ "commentId", "replyCommentId", "sourceVersion", "postedAt", "kind" ], "properties": { "commentId": { "$ref": "#/components/schemas/TypedId", "description": "Parent comment the reply was attached to." }, "kind": { "type": "string", "enum": [ "replyPosted" ] }, "postedAt": { "type": "string", "format": "date-time", "description": "Wall-clock when the reply was created on the shared thread." }, "replyCommentId": { "$ref": "#/components/schemas/TypedId", "description": "Newly created reply on the shared thread." }, "sourceVersion": { "type": "integer", "format": "int64", "description": "Source comment version this event was derived from.", "minimum": 0 } } }, { "type": "object", "description": "A card moved to the Resolved state on the author's private\nscratchpad. Used by the author's other tabs to advance focus and\nre-render the inbox without polling.", "required": [ "commentId", "resolution", "sourceVersion", "kind" ], "properties": { "commentId": { "$ref": "#/components/schemas/TypedId", "description": "The resolved comment." }, "kind": { "type": "string", "enum": [ "cardResolved" ] }, "resolution": { "$ref": "#/components/schemas/CardResolution", "description": "How the card was resolved." }, "sourceVersion": { "type": "integer", "format": "int64", "description": "Source comment version this event was derived from.", "minimum": 0 } } } ], "description": "Classifier-derived events the Console consumes from the per-document\nrealtime channel.\n\nPhase 2 produces and consumes only the synthesis variants\n(`severityClassified`, `themeAssigned`). Comment lifecycle events\n(`commentAdded` / `commentEdited` / `commentDeleted`) ride the existing\ncomments fan-out and are merged into the Console cache by the consumer\nwithout going through this enum.\n\nEvery variant carries `sourceVersion` so the consumer can suppress\nout-of-order updates: an incoming event with `sourceVersion` strictly\nless than the observed value for that comment is discarded." }, "ReviewConsoleFlagsView": { "type": "object", "description": "Classifier tuning thresholds returned alongside a Console session.\n\nThe wire shape is locked here so the session response doesn't change\nwhen classifier tuning is wired; the field set is empty until then." }, "ReviewConsoleMeta": { "type": "object", "description": "Per-author-per-document Console session.\n\nLazily created on first enable; subsequent writes use compare-and-swap on\n`sequence_number`. `severity_overrides` is sparse — entries only exist for\ncomments where the author has overridden the canonical classifier.", "required": [ "userId", "documentId", "view", "sort", "filters", "sequenceNumber", "updatedAt" ], "properties": { "documentId": { "$ref": "#/components/schemas/TypedId", "description": "Document the session is scoped to." }, "filters": { "$ref": "#/components/schemas/ConsoleFilters", "description": "Persisted inbox filters." }, "groundedSpaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypedId", "description": "Selected Space for evidence retrieval. None until the user picks one." } ] }, "sequenceNumber": { "type": "integer", "format": "int64", "description": "Slot sequence number — every CAS write must match this.", "minimum": 0 }, "severityOverrides": { "type": "object", "description": "Sparse per-comment severity overrides; empty = use canonical\nclassification.", "additionalProperties": { "$ref": "#/components/schemas/Severity" }, "propertyNames": { "type": "string" } }, "sort": { "$ref": "#/components/schemas/ConsoleSort", "description": "Persisted inbox sort." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last write timestamp." }, "userId": { "$ref": "#/components/schemas/TypedId", "description": "Owner." }, "view": { "$ref": "#/components/schemas/ConsoleView", "description": "Persisted view selector." } } }, "ReviewConsoleSessionResponse": { "type": "object", "description": "Single-round-trip hydration response for the Console surface.\n\nReturns the meta slot plus every existing card slot for the\n`(user_id, document_id)` pair, the classifier-tuning view, the\nper-document theme registry, and the canonical classification map.", "required": [ "meta", "cards", "featureFlags" ], "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewConsoleCardSlot" }, "description": "All known card slots for this `(user, doc)`." }, "classifications": { "type": "object", "description": "Canonical classification map for every classified comment on the\ndocument. Comments not yet classified are absent — consumers render\nthem with a \"synthesizing\" placeholder.", "additionalProperties": { "$ref": "#/components/schemas/CommentClassification" }, "propertyNames": { "type": "string" } }, "featureFlags": { "$ref": "#/components/schemas/ReviewConsoleFlagsView", "description": "Classifier-tuning thresholds." }, "meta": { "$ref": "#/components/schemas/ReviewConsoleMeta", "description": "META slot (lazily created on first read)." }, "themes": { "type": "array", "items": { "$ref": "#/components/schemas/ThemeRecord" }, "description": "Per-document theme registry. Sorted by `created_at` ascending.\nEmpty when no themes exist yet." } } }, "RevokeUserGrantsResponse": { "type": "object", "description": "Response body for\n`POST /api/v1/companies/{companyId}/oauth-overrides/{provider}/revoke-user-grants`.", "required": [ "revokedCount" ], "properties": { "revokedCount": { "type": "integer", "format": "int32", "description": "Exact number of end-user grants removed by this call.", "minimum": 0 } } }, "RoleTemplate": { "type": "string", "description": "Controls which [`TierRole`](crate::tier::TierRole) variants are valid at a\ngiven tier.", "enum": [ "fullCapability", "standard", "flatMembership" ] }, "S3ExportConfigResponse": { "type": "object", "description": "Response body for S3 export configuration endpoints", "required": [ "s3BucketArn", "s3Prefix", "roleArn", "format", "schedule", "enabled", "updatedAt" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the export is enabled" }, "externalId": { "type": [ "string", "null" ], "description": "Stable UUID v4 to use as the `ExternalId` condition in the customer's\n`IAM` trust policy. Present on all configs created after F-07-06\nremediation. Admins must add a `sts:ExternalId` condition matching this\nvalue to protect against confused-deputy attacks." }, "format": { "type": "string", "description": "Export format" }, "lastError": { "type": [ "string", "null" ], "description": "Error from last export attempt (if any)" }, "lastExportAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last export completed" }, "roleArn": { "type": "string", "description": "ARN of the IAM role to assume" }, "s3BucketArn": { "type": "string", "description": "ARN of the customer's S3 bucket" }, "s3Prefix": { "type": "string", "description": "Key prefix for exported files" }, "schedule": { "$ref": "#/components/schemas/S3ExportSchedule", "description": "Export schedule" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the config was last updated" } } }, "S3ExportSchedule": { "type": "string", "description": "Schedule for S3 audit export", "enum": [ "hourly", "daily" ] }, "ScanReferencesRequest": { "type": "object", "description": "Request to resolve a list of candidate document IDs into a connection-ready\nshape. Callers extract candidate IDs client-side (e.g. from pasted URLs in\nthe document body or from comment bodies) and send them in. Cross-company\nor unknown IDs are silently dropped from the response.", "required": [ "docIds" ], "properties": { "docIds": { "type": "array", "items": { "type": "string" }, "description": "Candidate document IDs the caller has detected as potential\nconnections. Bounded in size to keep a single panel scan cheap." } } }, "ScanReferencesResponse": { "type": "object", "description": "Response: the resolvable subset of the requested doc IDs. IDs that did\nnot resolve (cross-company, deleted, malformed) are simply absent.", "required": [ "resolved" ], "properties": { "resolved": { "type": "array", "items": { "$ref": "#/components/schemas/ReferencedDoc" }, "description": "The resolved references, in input order." } } }, "ScimTierMappingResponse": { "type": "object", "description": "API response for a single SCIM tier mapping.", "required": [ "id", "idpGroupId", "nodeId", "tierId", "nodeName", "role", "createdAt" ], "properties": { "createdAt": { "type": "string", "description": "Creation timestamp (RFC 3339)." }, "id": { "type": "string", "description": "Unique mapping identifier." }, "idpGroupId": { "type": "string", "description": "External `IdP` group identifier." }, "nodeId": { "type": "string", "description": "Target tier node identifier." }, "nodeName": { "type": "string", "description": "Display name of the target node (best-effort; empty if the node could\nnot be resolved at read time)." }, "role": { "type": "string", "description": "Role to assign on provisioning." }, "tierId": { "type": "string", "description": "Hierarchy tier identifier." } } }, "ScimTokenStatus": { "type": "string", "description": "Lifecycle status of a SCIM bearer token", "enum": [ "active", "revoked" ] }, "ScimTokenSummary": { "type": "object", "description": "Summary of a SCIM token (never includes the raw token value or hash)", "required": [ "id", "name", "tokenPrefix", "status", "createdBy", "createdAt" ], "properties": { "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "createdBy": { "type": "string", "description": "User ID of the creator" }, "id": { "type": "string", "description": "Token ID" }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO 8601 last-used timestamp (if ever used)" }, "name": { "type": "string", "description": "Admin-assigned name" }, "revokedAt": { "type": [ "string", "null" ], "description": "ISO 8601 revocation timestamp (if revoked)" }, "status": { "$ref": "#/components/schemas/ScimTokenStatus", "description": "Token status" }, "tokenPrefix": { "type": "string", "description": "First 12 characters of the token for display" } } }, "ScopeId": { "oneOf": [ { "type": "object", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "tier" ] } } }, { "type": "object", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal" ] } } } ], "description": "Wire-level mirror of [`ScopeId`] used to validate prefix/variant agreement\nat (de)serialization time.\n\nKept private — every public call site operates on [`ScopeId`] directly.\nIncoming JSON with `\"kind\": \"company\"` is rejected at this boundary." }, "ScopeInfo": { "type": "object", "description": "Scope metadata for a folder, used when a document moves between scopes.", "required": [ "scope", "folderId", "folderName" ], "properties": { "folderId": { "type": "string", "description": "Folder ID." }, "folderName": { "type": "string", "description": "Folder name for display purposes." }, "scope": { "$ref": "#/components/schemas/ScopeId", "description": "Typed folder scope (`kind` + `id`)." } } }, "SearchRequest": { "type": "object", "required": [ "q" ], "properties": { "createdAfter": { "type": [ "string", "null" ], "format": "date-time", "description": "Only return documents created on or after this timestamp (RFC 3339)." }, "createdBefore": { "type": [ "string", "null" ], "format": "date-time", "description": "Only return documents created on or before this timestamp (RFC 3339)." }, "excludeDocIds": { "type": "array", "items": { "type": "string" }, "description": "Document IDs to exclude from results." }, "folderId": { "type": [ "string", "null" ], "description": "Narrow results to documents in this folder." }, "isPublic": { "type": [ "boolean", "null" ], "description": "Filter by public link visibility (`true` = only public, `false` = only private)." }, "limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "minScope": { "type": [ "string", "null" ], "description": "Minimum document audience to include. Audience is folder-derived and\ntwo-valued: `personal` (owner-only) and `tier` (the tier node's members).\n`personal` returns everything; `tier` excludes owner-only documents." }, "orgId": { "type": [ "string", "null" ], "description": "Narrow results to documents in this org." }, "ownerId": { "type": [ "string", "null" ], "description": "Filter results to documents owned by this user ID." }, "q": { "type": "string" }, "spaceId": { "type": [ "string", "null" ], "description": "Narrow results to documents in this `Space`." }, "status": { "type": [ "string", "null" ] }, "updatedAfter": { "type": [ "string", "null" ], "format": "date-time", "description": "Only return documents updated on or after this timestamp (RFC 3339)." }, "updatedBefore": { "type": [ "string", "null" ], "format": "date-time", "description": "Only return documents updated on or before this timestamp (RFC 3339)." } } }, "SearchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/UnifiedSearchHit" } } } }, "SearchResult": { "type": "object", "description": "Internal document result from Postgres full-text search.\n\nUsed by [`SearchRepository`] and mapped to [`UnifiedSearchHit::Document`]\nin the search handler.", "required": [ "documentId", "title", "snippet", "score" ], "properties": { "documentId": { "type": "string" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SearchResultMetadata" } ] }, "score": { "type": "number", "format": "float" }, "snippet": { "type": "string" }, "title": { "type": "string" } } }, "SearchResultMetadata": { "type": "object", "description": "Metadata enrichment for a search result.\n\n`None` at the parent level means metadata fetch failed for this item;\n`Some(...)` means successfully enriched.", "required": [ "isPublic", "ownerId", "createdAt", "updatedAt", "wordCount" ], "properties": { "createdAt": { "type": "string" }, "folderId": { "type": [ "string", "null" ] }, "isPublic": { "type": "boolean" }, "ownerId": { "type": "string" }, "updatedAt": { "type": "string" }, "wordCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SelectionContext": { "type": "object", "description": "Editor selection context sent with a user message.\n\nCaptures the user's cursor position or text selection at message-send time.\nFollows the [`CommentAnchor`](crate::comment::CommentAnchor) pattern:\nYjs relative positions for CRDT-stable anchoring, plus a short excerpt\nfor prompt context and fallback re-anchoring.", "required": [ "startRelative", "endRelative" ], "properties": { "endRelative": { "$ref": "#/components/schemas/YjsRelativePosition", "description": "Yjs relative position for selection end." }, "quotedText": { "type": [ "string", "null" ], "description": "Highlighted text excerpt at selection time (max 500 chars). Used for\nprompt context and as fallback when position resolution is unavailable.\nAbsent when the cursor is positioned but no text is highlighted." }, "sectionHeading": { "type": [ "string", "null" ], "description": "Nearest heading text (e.g., \"Architecture\"). Resolved by the frontend\nfrom the `ProseMirror` node tree. Absent when the cursor is before\nthe first heading." }, "startRelative": { "$ref": "#/components/schemas/YjsRelativePosition", "description": "Yjs relative position for selection start." } } }, "SelectiveUndoRequest": { "type": "object", "description": "Request to selectively undo a specific history entry.", "required": [ "sequenceId", "beforeSequenceId" ], "properties": { "beforeSequenceId": { "type": "string", "description": "Sequence ID of the record before the target group (the \"before\" state)." }, "forceConflicts": { "type": "boolean", "description": "If true, apply the undo even when conflicts exist (conflicted blocks\nare left unchanged)." }, "sequenceId": { "type": "string", "description": "Sequence ID of the newest WAL record in the target group." } } }, "SelectiveUndoResponse": { "type": "object", "description": "Result of a selective undo preview or application.", "required": [ "canApply", "previewDiffs", "previewStats", "conflicts" ], "properties": { "canApply": { "type": "boolean", "description": "Whether the undo can be applied without conflicts." }, "conflicts": { "type": "array", "items": { "$ref": "#/components/schemas/UndoConflict" }, "description": "Conflicts where the targeted edit's content was subsequently modified." }, "previewDiffs": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDiffEntry" }, "description": "Block-level preview of what the undo would change in the current\ndocument." }, "previewStats": { "$ref": "#/components/schemas/DiffStats", "description": "Aggregate stats for the preview." }, "skippedChanges": { "type": "array", "items": { "$ref": "#/components/schemas/SkippedChange" }, "description": "Block changes that were skipped because automatic undo is not yet\nsupported for their change type (e.g. removed blocks, moved blocks)." } } }, "SendMessageRequest": { "type": "object", "description": "Request to send a message in a chat session (SSE streaming endpoint).", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The user's message content." }, "effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Effort", "description": "Optional effort override. When `None`, the server uses the model's\ndefault ([`crate::agent::Model::default_effort`]). Validated against\nthe resolved model's capabilities; an unsupported value returns a\n400." } ] }, "model": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Model", "description": "Optional model override. When `None`, the server resolves the model\nfrom the company's effective default. When `Some`, the model is\nvalidated against the intersection of the company's `allowed_models`\nand the billing plan's permitted set; rejected requests return a\n403 `modelNotAllowedForPlan` error." } ] }, "promptSource": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PromptSourceRef", "description": "Provenance for messages produced by invoking a `/prompt:`\ncustom prompt. When set, the resulting user message is persisted\nwith this reference so chat history can render a chip linking\nback to the prompt document." } ] }, "selectionContext": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SelectionContext", "description": "Editor selection context at message-send time. Present when the user\nhas a cursor in a section or text highlighted in the document editor." } ] }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceWireFormat" }, "description": "Connected research sources for this message (wire format: `{ type, id, mode }`)." }, "thinking": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ThinkingConfig", "description": "Optional reasoning strategy override. When `None`, the server uses\nthe model's default ([`crate::agent::Model::default_thinking`]).\nValidated against the resolved model's capabilities; an unsupported\nvalue returns a 400." } ] } } }, "ServerMessage": { "oneOf": [ { "type": "object", "description": "Confirmation of joining a document with current collaborators\nand initial Yjs state for sync.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Confirmation of joining a document with current collaborators\nand initial Yjs state for sync.", "required": [ "documentId", "collaborators", "yjsState", "documentVersion" ], "properties": { "collaborators": { "type": "array", "items": { "$ref": "#/components/schemas/CollaboratorInfo" }, "description": "Current collaborators on the document" }, "deltaMode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeltaMode", "description": "Whether `yjsState` is a full snapshot or a WAL-derived\ndelta. Absent from older servers; clients treat absence as\n`Full` for backward compatibility." } ] }, "documentId": { "type": "string", "description": "Document that was joined" }, "documentVersion": { "type": "integer", "format": "int64", "description": "Document-level version counter at join time.", "minimum": 0 }, "serverTaskId": { "type": [ "string", "null" ], "description": "Opaque identifier of the server instance handling this\nconnection. Stable for the connection's lifetime; a\ndifferent value after a reconnect means the connection\nmoved to a different instance. Surfaced only for\nmulti-instance debugging. Absent from older servers." }, "walUlid": { "type": [ "string", "null" ], "description": "WAL `sequence_id` the response is current to. Clients\npersist this alongside the merged state so the next\nreconnect can request a delta from this point. Absent when\nthe document has no WAL records yet." }, "yjsState": { "type": "string", "description": "Base64-encoded Yjs binary payload. Interpretation depends on\n`deltaMode`: when `full`, replaces the client's local state;\nwhen `wal`, applies on top of the client's locally-cached\nstate (which is at the `lastSeenWalUlid` it sent). Encoding\ndepends on `yjsStateEncoding`; absence means raw Base64." }, "yjsStateEncoding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/YjsStateEncoding", "description": "Encoding applied to `yjsState`. Absent from older servers;\nclients treat absence as [`YjsStateEncoding::Base64`]." } ] } } }, "type": { "type": "string", "enum": [ "joinedDocument" ] } } }, { "type": "object", "description": "Response to a `RequestSync` (Yjs sync step 2).\n\nCarries exactly the updates the requesting client was missing, plus the\nserver's own state vector. The client applies `update`, then computes\nthe updates the server is missing from `serverStateVector` and sends\nthem as a `YjsSync` — converging both replicas regardless of how far\nthey had diverged.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Response to a `RequestSync` (Yjs sync step 2).\n\nCarries exactly the updates the requesting client was missing, plus the\nserver's own state vector. The client applies `update`, then computes\nthe updates the server is missing from `serverStateVector` and sends\nthem as a `YjsSync` — converging both replicas regardless of how far\nthey had diverged.", "required": [ "documentId", "update", "serverStateVector" ], "properties": { "documentId": { "type": "string", "description": "Document that was reconciled." }, "serverStateVector": { "type": "string", "description": "Base64-encoded Yjs v1 state vector of the server's replica. The\nclient diffs its own state against this to find the updates the\nserver is missing." }, "update": { "type": "string", "description": "Base64-encoded Yjs update with the operations the client was\nmissing. May be a near-empty no-op when the client is already\ncurrent. Encoding is given by `updateEncoding`; absence means raw\nBase64." }, "updateEncoding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/YjsStateEncoding", "description": "Encoding applied to `update`. Absent means raw Base64." } ] }, "walUlid": { "type": [ "string", "null" ], "description": "WAL `sequence_id` the server's state is current to. The client\npersists this as its catch-up anchor. Absent when the document has\nno WAL records yet." } } }, "type": { "type": "string", "enum": [ "syncResponse" ] } } }, { "type": "object", "description": "Confirmation of leaving a document", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Confirmation of leaving a document", "required": [ "documentId" ], "properties": { "documentId": { "type": "string", "description": "Document that was left" } } }, "type": { "type": "string", "enum": [ "leftDocument" ] } } }, { "type": "object", "description": "Response to client heartbeat", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Response to client heartbeat" }, "type": { "type": "string", "enum": [ "heartbeatAck" ] } } }, { "type": "object", "description": "A new collaborator joined the document", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A new collaborator joined the document", "required": [ "collaborator" ], "properties": { "collaborator": { "$ref": "#/components/schemas/CollaboratorInfo", "description": "Info about the new collaborator" } } }, "type": { "type": "string", "enum": [ "collaboratorJoined" ] } } }, { "type": "object", "description": "A collaborator left the document", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A collaborator left the document", "required": [ "entityId", "entityType" ], "properties": { "entityId": { "type": "string", "description": "Entity that left" }, "entityType": { "$ref": "#/components/schemas/EntityType", "description": "Human or agent" } } }, "type": { "type": "string", "enum": [ "collaboratorLeft" ] } } }, { "type": "object", "description": "Yjs sync protocol message relayed from another client or\nfrom a REST/MCP edit applied server-side.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Yjs sync protocol message relayed from another client or\nfrom a REST/MCP edit applied server-side.", "required": [ "documentId", "payload", "origin" ], "properties": { "documentId": { "type": "string", "description": "Document being edited" }, "origin": { "$ref": "#/components/schemas/EditActor", "description": "Who produced this update (for attribution UI)" }, "payload": { "type": "string", "description": "Base64-encoded binary Yjs update" }, "walUlid": { "type": [ "string", "null" ], "description": "WAL `sequence_id` of the durable record this broadcast\noriginates from. Modern servers stamp live broadcasts only\nafter WAL/S3 durability is established; older servers may\nomit it." } } }, "type": { "type": "string", "enum": [ "yjsSync" ] } } }, { "type": "object", "description": "Durable acknowledgement for one or more client-originated Yjs updates.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Durable acknowledgement for one or more client-originated Yjs updates.", "required": [ "documentId", "updateIds", "walUlid" ], "properties": { "documentId": { "type": "string", "description": "Document whose updates were committed." }, "updateIds": { "type": "array", "items": { "type": "string" }, "description": "Client `updateId`s covered by `walUlid`." }, "walUlid": { "type": "string", "description": "WAL `sequence_id` that durably contains the acknowledged updates." } } }, "type": { "type": "string", "enum": [ "yjsAck" ] } } }, { "type": "object", "description": "Yjs awareness protocol message relayed from another client.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Yjs awareness protocol message relayed from another client.", "required": [ "documentId", "payload" ], "properties": { "documentId": { "type": "string", "description": "Document for awareness state" }, "payload": { "type": "string", "description": "Base64-encoded binary Yjs awareness update" } } }, "type": { "type": "string", "enum": [ "yjsAwareness" ] } } }, { "type": "object", "description": "A document in a subscribed Space changed (for FUSE mounts / dashboards).\n\nReplaces the per-section `SectionUpdated`/`SectionDeleted` broadcasts.\nClients fetch updated content via REST if needed.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A document in a subscribed Space changed (for FUSE mounts / dashboards).\n\nReplaces the per-section `SectionUpdated`/`SectionDeleted` broadcasts.\nClients fetch updated content via REST if needed.", "required": [ "documentId", "changeType" ], "properties": { "changeType": { "$ref": "#/components/schemas/DocumentChangeType", "description": "Type of change" }, "documentId": { "type": "string", "description": "Document that changed" } } }, "type": { "type": "string", "enum": [ "documentChanged" ] } } }, { "type": "object", "description": "Server-side error", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Server-side error", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" } } }, "type": { "type": "string", "enum": [ "error" ] } } }, { "type": "object", "description": "Real-time agent task progress update.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Real-time agent task progress update.", "required": [ "taskId", "agentId", "agentName", "status", "toolCallsSoFar" ], "properties": { "agentId": { "type": "string", "description": "Agent ID" }, "agentName": { "type": "string", "description": "Agent display name" }, "message": { "type": [ "string", "null" ], "description": "Optional status message" }, "status": { "$ref": "#/components/schemas/TaskStatus", "description": "Current task status" }, "taskId": { "type": "string", "description": "Agent task ID" }, "toolCallsSoFar": { "type": "integer", "format": "int32", "description": "Number of tool calls completed so far", "minimum": 0 } } }, "type": { "type": "string", "enum": [ "agentTaskUpdate" ] } } }, { "type": "object", "description": "Notification for `JoinSpace` subscribers when a document in the\nSpace is added/removed.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Notification for `JoinSpace` subscribers when a document in the\nSpace is added/removed.", "required": [ "spaceId" ], "properties": { "spaceId": { "type": "string", "description": "Space that changed" } } }, "type": { "type": "string", "enum": [ "spaceDocumentChanged" ] } } }, { "type": "object", "description": "A comment on a document was created, updated, or deleted.\n\nClients use this to invalidate their comments query cache and\nrefetch without polling.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A comment on a document was created, updated, or deleted.\n\nClients use this to invalidate their comments query cache and\nrefetch without polling.", "required": [ "documentId", "commentId", "changeType" ], "properties": { "changeType": { "$ref": "#/components/schemas/CommentChangeType", "description": "Type of change" }, "commentId": { "type": "string", "description": "Comment that changed" }, "documentId": { "type": "string", "description": "Document the comment belongs to" } } }, "type": { "type": "string", "enum": [ "commentChanged" ] } } }, { "type": "object", "description": "A comment thread was resolved.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A comment thread was resolved.", "required": [ "documentId", "commentId", "resolvedBy" ], "properties": { "commentId": { "type": "string", "description": "Root comment of the resolved thread" }, "documentId": { "type": "string", "description": "Document the thread belongs to" }, "resolvedBy": { "type": "string", "description": "User who resolved the thread" } } }, "type": { "type": "string", "enum": [ "threadResolved" ] } } }, { "type": "object", "description": "A previously resolved comment thread was reopened.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A previously resolved comment thread was reopened.", "required": [ "documentId", "commentId", "reopenedBy" ], "properties": { "commentId": { "type": "string", "description": "Root comment of the reopened thread" }, "documentId": { "type": "string", "description": "Document the thread belongs to" }, "reopenedBy": { "type": "string", "description": "User who reopened the thread" } } }, "type": { "type": "string", "enum": [ "threadReopened" ] } } }, { "type": "object", "description": "A suggestion's status or metadata changed.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A suggestion's status or metadata changed.", "required": [ "documentId", "suggestionId", "changeType" ], "properties": { "changeType": { "$ref": "#/components/schemas/SuggestionChangeType", "description": "Type of change" }, "documentId": { "type": "string", "description": "Document the suggestion belongs to" }, "suggestionId": { "type": "string", "description": "Suggestion that changed" } } }, "type": { "type": "string", "enum": [ "suggestionChanged" ] } } }, { "type": "object", "description": "Server is shutting down — client should reconnect immediately\nwithout backoff. Sent during graceful shutdown (rolling deployments,\ntask draining).", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "Server is shutting down — client should reconnect immediately\nwithout backoff. Sent during graceful shutdown (rolling deployments,\ntask draining).", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Human-readable reason for the shutdown." } } }, "type": { "type": "string", "enum": [ "serverGoAway" ] } } }, { "type": "object", "description": "A classifier-derived synthesis event for the Review Console surface.\n\nWraps the `ReviewConsoleEvent` discriminated union — `severityClassified`\nor `themeAssigned` — so it can ride the same per-document broadcast\nchannel as comment-lifecycle notifications. Each variant of the inner\nevent carries a `sourceVersion` so the consumer can suppress out-of-order\nupdates.", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "description": "A classifier-derived synthesis event for the Review Console surface.\n\nWraps the `ReviewConsoleEvent` discriminated union — `severityClassified`\nor `themeAssigned` — so it can ride the same per-document broadcast\nchannel as comment-lifecycle notifications. Each variant of the inner\nevent carries a `sourceVersion` so the consumer can suppress out-of-order\nupdates.", "required": [ "documentId", "event" ], "properties": { "documentId": { "type": "string", "description": "Document the event applies to." }, "event": { "$ref": "#/components/schemas/ReviewConsoleEvent", "description": "The synthesis event payload." } } }, "type": { "type": "string", "enum": [ "reviewConsoleEvent" ] } } } ], "description": "Server-to-client WebSocket message.\n\nTagged enum using `\"type\"` as the discriminator and `\"payload\"` for\nthe variant data, matching the wire format:\n```json\n{ \"type\": \"joinedDocument\", \"payload\": { \"documentId\": \"...\", \"collaborators\": [] } }\n```" }, "ServiceAccountDetail": { "type": "object", "description": "Admin detail for the company-level service-account credential.", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "Whether a service-account credential is currently active." }, "connectedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the service account was first connected (`null` if unknown)." } } }, "ServiceAccountSummary": { "type": "object", "description": "Summary of the company-level service-account credential for a connector.", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "Whether the service-account credential is currently active." }, "connectedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the service-account was first connected (`null` if unknown)." } } }, "SessionAction": { "type": "string", "description": "Client-side post-success behaviour for the current session.", "enum": [ "signOutRequired" ] }, "SessionResponse": { "type": "object", "description": "Response for a created or retrieved session.", "required": [ "id", "scope", "scopeEntityId", "messageCount", "status", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the session was created." }, "id": { "type": "string", "description": "Unique session identifier." }, "memoryDisabled": { "type": "boolean", "description": "Per-session memory override. When `true`, the assistant does not\nsee `profile.md` / `MEMORY.md` and `record_memory` is omitted\nfrom its tools — regardless of the user's global memory setting." }, "messageCount": { "type": "integer", "format": "int32", "description": "Current message count.", "minimum": 0 }, "scope": { "$ref": "#/components/schemas/AssistantScope", "description": "Which scope this session belongs to." }, "scopeEntityId": { "type": "string", "description": "The entity this session is scoped to." }, "status": { "$ref": "#/components/schemas/SessionStatus", "description": "Lifecycle status." }, "title": { "type": [ "string", "null" ], "description": "Auto-generated title from first user message." }, "toolOverrides": { "type": "object", "description": "Per-conversation tool overrides. Today only `web_search` reads\nthis map; future per-tool gates can read it without a contract\nchange. Empty when no overrides have been set.", "additionalProperties": { "$ref": "#/components/schemas/ToolOverride" }, "propertyNames": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last activity timestamp." } } }, "SessionSource": { "allOf": [ { "$ref": "#/components/schemas/ConnectedSource", "description": "The connected entity." }, { "type": "object", "required": [ "mode", "connectedAt" ], "properties": { "connectedAt": { "type": "string", "format": "date-time", "description": "When this source was connected." }, "mode": { "$ref": "#/components/schemas/SourceConnectionMode", "description": "How this source was connected." } } } ], "description": "A source attached to a chat session with connection metadata." }, "SessionStatus": { "type": "string", "description": "Lifecycle status of a chat session.", "enum": [ "active", "archived" ] }, "SetByoOauthAppRequest": { "type": "object", "description": "Request body for `PUT .../integrations/{kind}/byo-oauth-app`.", "required": [ "clientId", "clientSecret", "redirectUri" ], "properties": { "clientId": { "type": "string", "description": "`OAuth` client ID registered at the provider." }, "clientSecret": { "type": "string", "description": "`OAuth` client secret (plaintext, encrypted at rest in the vault)." }, "redirectUri": { "type": "string", "description": "Redirect URI registered with the provider." } } }, "SetDisableAllRequest": { "type": "object", "description": "Request body for the global kill switch toggle.", "required": [ "value" ], "properties": { "value": { "type": "boolean", "description": "New value for the `disable_all` flag." } } }, "SetGovernanceRequest": { "type": "object", "description": "Request body for setting a per-kind governance override.", "required": [ "governance" ], "properties": { "governance": { "$ref": "#/components/schemas/ConnectorGovernance", "description": "Governance state to apply for this connector kind." } } }, "SetHierarchyRequest": { "type": "object", "description": "Request body for `POST /api/companies/{companyId}/hierarchy`.", "required": [ "tiers" ], "properties": { "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierInput" }, "description": "Ordered list of tier definitions. Depth is derived from array index." } } }, "SetIntegrationPolicyRequest": { "type": "object", "description": "Request body for `PUT .../integrations/{kind}/policy`.", "required": [ "policyState" ], "properties": { "policyState": { "$ref": "#/components/schemas/AdminPolicyState", "description": "New policy state for the kind." } } }, "SetKillSwitchRequest": { "type": "object", "description": "Request body for `PUT .../integrations/{kind}/kill-switch`.", "required": [ "engaged" ], "properties": { "engaged": { "type": "boolean", "description": "Whether the kill switch should be engaged." } } }, "SetProfileVisibilityRequest": { "type": "object", "description": "Request to set the caller's public-presence state.\n\nSwitching to `private` is a full retreat: every published document the\ncaller owns is unpublished (reverted to draft) and the profile page is\nhidden. Switching to `public` only re-opens the profile; documents are not\nautomatically re-published.", "required": [ "visibility" ], "properties": { "visibility": { "$ref": "#/components/schemas/ProfileVisibility", "description": "The desired public-presence state." } } }, "SetProfileVisibilityResponse": { "type": "object", "description": "Response after changing public-presence state.", "required": [ "visibility", "documentsUnpublished" ], "properties": { "documentsUnpublished": { "type": "integer", "format": "int32", "description": "Number of documents unpublished as a result of the change. Always `0`\nwhen switching to `public`.", "minimum": 0 }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility", "description": "The visibility now in effect." } } }, "Severity": { "type": "string", "description": "Comment-severity vocabulary.\n\nUsed by the canonical classifier and by author-supplied per-card overrides\nstored on `ReviewConsoleMeta::severity_overrides`. Distinct from the\nexisting AI-suggestion severity enum: this vocabulary describes\n\"how-blocking-is-this-concern\" (a shipping-gate signal); the suggestion\nvocabulary describes \"how-bad-is-this-flaw\" (a quality signal). They will\nnot unify.", "enum": [ "blocker", "major", "minor", "nitpick" ] }, "SharedDocumentResponse": { "type": "object", "description": "A document shared with the requesting user via direct or team grant.", "required": [ "documentId", "title", "contentType", "ownerId", "wordCount", "isPublic", "effectiveRole", "grantedBy", "grantedAt", "createdAt", "updatedAt" ], "properties": { "contentType": { "$ref": "#/components/schemas/ContentType", "description": "Content type (markdown, html, etc.)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the document was created." }, "documentId": { "type": "string", "description": "Document ID." }, "effectiveRole": { "$ref": "#/components/schemas/ResourceRole", "description": "The user's effective role on this document." }, "folderId": { "type": [ "string", "null" ], "description": "Folder the document is in." }, "grantedAt": { "type": "string", "format": "date-time", "description": "When access was granted." }, "grantedBy": { "type": "string", "description": "User ID who granted access." }, "isPublic": { "type": "boolean", "description": "Whether the document has a public link." }, "ownerEmail": { "type": [ "string", "null" ], "description": "Email of the document owner (`None` if the owner account was deactivated)." }, "ownerId": { "type": "string", "description": "User ID of the document owner." }, "ownerName": { "type": [ "string", "null" ], "description": "Display name of the owner (`None` if the owner account was deactivated)." }, "title": { "type": "string", "description": "Document title." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the document was last updated." }, "wordCount": { "type": "integer", "format": "int32", "description": "Word count of the document.", "minimum": 0 } } }, "SharedSpaceResponse": { "type": "object", "description": "API response for a Space shared with the authenticated user.", "required": [ "spaceId", "name", "scope", "documentCount", "grantLevel", "grantedBy", "grantedAt", "createdAt", "updatedAt" ], "properties": { "color": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "documentCount": { "type": "integer", "format": "int32", "minimum": 0 }, "grantLevel": { "$ref": "#/components/schemas/SpaceGrantLevel" }, "grantedAt": { "type": "string", "format": "date-time" }, "grantedBy": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/ScopeId", "description": "Typed scope of the shared Space." }, "spaceId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SharingPolicyResponse": { "type": "object", "description": "Response for sharing policy.", "required": [ "externalSharingEnabled", "allowedDomains", "blockedDomains", "maxExternalRole", "publicLinksEnabled", "requirePublicLinkPassword", "watermarkOnExport" ], "properties": { "allowedDomains": { "type": "array", "items": { "type": "string" }, "description": "If non-empty, only allow sharing with users from these email domains." }, "blockedDomains": { "type": "array", "items": { "type": "string" }, "description": "Block sharing with users from these email domains." }, "externalSharingEnabled": { "type": "boolean", "description": "Whether sharing with users outside the organization is allowed." }, "maxExternalRole": { "$ref": "#/components/schemas/ResourceRole", "description": "Maximum role that can be granted to external users." }, "maxPublicLinkExpiryHours": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum expiry time for public links in hours.", "minimum": 0 }, "publicLinksEnabled": { "type": "boolean", "description": "Whether public links are enabled." }, "requirePublicLinkPassword": { "type": "boolean", "description": "Whether public links require a password." }, "watermarkOnExport": { "type": "boolean", "description": "Whether watermarks are applied on document export." }, "watermarkTemplate": { "type": [ "string", "null" ], "description": "Custom watermark template." } } }, "SignupAttribution": { "type": "object", "description": "First-touch marketing attribution payload submitted at signup.\n\nAll fields are optional — a direct visit (no UTM tags, no click IDs)\nproduces a payload with most fields `None`. This is the same shape that\nrides as Cognito custom attributes on the email/password signup path,\nwhere the post-confirmation handler reads them and persists them onto\nthe user record. The handler enforces the consent boundary: when the\ncaller's tier is anything other than `attribution`, every field is\ndropped server-side.", "properties": { "fbclid": { "type": [ "string", "null" ], "description": "Meta (Facebook) click identifier." }, "firstSeenAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the first touch." }, "firstVisitorId": { "type": [ "string", "null" ], "description": "Visitor identifier captured on the first attribution-tier visit.\nOpaque to the consumer; treat as an equality-comparable token." }, "gclid": { "type": [ "string", "null" ], "description": "Google Ads click identifier." }, "msclkid": { "type": [ "string", "null" ], "description": "Microsoft Advertising click identifier." }, "signupLandingPath": { "type": [ "string", "null" ], "description": "Pathname of the landing page where the first touch was captured." }, "signupReferrer": { "type": [ "string", "null" ], "description": "HTTP referrer at the visit that produced this first touch." }, "utmCampaign": { "type": [ "string", "null" ], "description": "`utm_campaign` campaign tag." }, "utmContent": { "type": [ "string", "null" ], "description": "`utm_content` campaign tag." }, "utmMedium": { "type": [ "string", "null" ], "description": "`utm_medium` campaign tag." }, "utmSource": { "type": [ "string", "null" ], "description": "`utm_source` campaign tag." }, "utmTerm": { "type": [ "string", "null" ], "description": "`utm_term` campaign tag." } } }, "SignupDomainCheckOutcome": { "type": "string", "description": "The four possible outcomes the unauthenticated signup-domain probe\nreturns to the webapp.\n\n`personalOk` and `freeProvider` both proceed to personal-plan signup;\nthey differ only in whether the user could ever turn the domain into\na claim later (free-provider domains never can).", "enum": [ "personalOk", "autoJoin", "requestAccess", "freeProvider" ] }, "SignupDomainCheckResponse": { "type": "object", "description": "Response body for `GET /auth/signup-domain-check`.", "required": [ "outcome" ], "properties": { "companyDisplayName": { "type": [ "string", "null" ], "description": "Public display name of the claimed company. Present iff\n`outcome` is [`SignupDomainCheckOutcome::AutoJoin`] or\n[`SignupDomainCheckOutcome::RequestAccess`]." }, "companyId": { "type": [ "string", "null" ], "description": "Identifier of the claimed company. Present on the same outcomes\nas `company_display_name`. The webapp uses it to construct the\n`/auth/join/{companyId}` deep link when routing the user away\nfrom personal signup." }, "outcome": { "$ref": "#/components/schemas/SignupDomainCheckOutcome", "description": "Routing decision for the webapp." } } }, "SimilarDocument": { "type": "object", "description": "A semantically similar document, ranked by cosine similarity.", "required": [ "docId", "title", "similarityScore", "bestMatchContext", "updatedAt" ], "properties": { "bestMatchContext": { "type": "string", "description": "Heading context from the best-matching section in the candidate doc." }, "docId": { "type": "string", "description": "Document ID." }, "similarityScore": { "type": "number", "format": "float", "description": "Best section-pair cosine similarity (0.0–1.0)." }, "title": { "type": "string", "description": "Document title." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the document was last updated." } } }, "SimilarDocumentsRequest": { "type": "object", "description": "Query parameters for the similar documents endpoint.", "properties": { "excludeDocIds": { "type": "array", "items": { "type": "string" }, "description": "Document IDs to exclude from results (e.g., already-subscribed)." }, "limit": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of suggestions to return (default 10, max 20).", "minimum": 0 } } }, "SimilarDocumentsResponse": { "type": "object", "description": "Response for the similar documents endpoint.", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/SimilarDocument" }, "description": "Ranked list of similar documents." } } }, "SkillProperties": { "type": "object", "description": "Extracted skill properties from `SKILL.md` frontmatter.", "required": [ "name", "description" ], "properties": { "allowedTools": { "type": [ "string", "null" ], "description": "Space-delimited list of allowed tools." }, "compatibility": { "type": [ "string", "null" ], "description": "Optional compatibility notes." }, "description": { "type": "string", "description": "Human-readable description of the skill." }, "license": { "type": [ "string", "null" ], "description": "Optional license identifier." }, "metadata": { "type": [ "object", "null" ], "description": "Arbitrary key-value metadata.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Skill name (should match folder name, kebab-case)." } } }, "SkillValidationResult": { "type": "object", "description": "Result of validating a skill folder against the agentskills.io spec.", "required": [ "isValid", "warnings" ], "properties": { "isValid": { "type": "boolean", "description": "Whether the skill folder passes all advisory validations." }, "properties": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillProperties", "description": "Extracted skill properties (if `SKILL.md` frontmatter is parseable)." } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/SkillWarning" }, "description": "Advisory warnings (never blocking)." } } }, "SkillWarning": { "oneOf": [ { "type": "object", "description": "Folder does not contain a document titled \"SKILL.md\".", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "missingSkillDocument" ] } } }, { "type": "object", "description": "`SKILL.md` frontmatter is missing or unparseable.", "required": [ "detail", "type" ], "properties": { "detail": { "type": "string", "description": "Description of the parse error." }, "type": { "type": "string", "enum": [ "invalidFrontmatter" ] } } }, { "type": "object", "description": "A required field is missing from frontmatter.", "required": [ "field", "type" ], "properties": { "field": { "type": "string", "description": "Field name (e.g. \"name\", \"description\")." }, "type": { "type": "string", "enum": [ "missingRequiredField" ] } } }, { "type": "object", "description": "Frontmatter `name` does not match the folder name.", "required": [ "expected", "actual", "type" ], "properties": { "actual": { "type": "string", "description": "Actual value from frontmatter." }, "expected": { "type": "string", "description": "Expected value (folder name)." }, "type": { "type": "string", "enum": [ "nameMismatch" ] } } }, { "type": "object", "description": "Frontmatter `name` is not valid kebab-case.", "required": [ "detail", "type" ], "properties": { "detail": { "type": "string", "description": "Description of the format issue." }, "type": { "type": "string", "enum": [ "nameFormatError" ] } } }, { "type": "object", "description": "Description exceeds 1024 characters.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "descriptionTooLong" ] } } }, { "type": "object", "description": "Compatibility field exceeds 500 characters.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "compatibilityTooLong" ] } } }, { "type": "object", "description": "Frontmatter contains fields not in the spec.", "required": [ "fields", "type" ], "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "The unrecognised field names." }, "type": { "type": "string", "enum": [ "unexpectedFields" ] } } } ], "description": "Advisory warning about a skill folder's agentskills.io compliance." }, "SkippedChange": { "type": "object", "description": "A block change that was skipped during selective undo because the change\ntype does not support automatic reversal.", "required": [ "blockId", "blockType", "reason" ], "properties": { "blockId": { "type": "string", "description": "Positional block ID (e.g. `\"node_3\"`)." }, "blockType": { "type": "string", "description": "Block type (e.g. `\"paragraph\"`, `\"heading\"`)." }, "reason": { "type": "string", "description": "Human-readable description of why this change was skipped." } } }, "Slug": { "type": "string", "description": "URL-safe slug for published documents.\n\nGenerated from the document title on first publish. Immutable after\ncreation. Unique within a handle's namespace (two creators can have\nthe same slug)." }, "SlugCheckResponse": { "type": "object", "description": "Response for slug availability check.", "required": [ "slug", "available" ], "properties": { "available": { "type": "boolean", "description": "Whether the slug is available for use" }, "slug": { "type": "string", "description": "The slug that was checked" } } }, "SourceConnectionMode": { "type": "string", "description": "How a source was connected to the session.", "enum": [ "auto", "pinned" ] }, "SourceReason": { "type": "string", "description": "Why this result was included (used for default-view section grouping).", "enum": [ "contextual", "favorite", "top", "search", "connector" ] }, "SourceSearchResponse": { "type": "object", "description": "Unified search results returned by the source picker.", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSearchResult" }, "description": "Ranked results across all source types." } } }, "SourceSearchResult": { "type": "object", "description": "A single search result for the source picker.", "required": [ "id", "sourceType", "name" ], "properties": { "connectorIcon": { "type": [ "string", "null" ], "description": "Asset path for the connector logo (present when `source_type` is `connector`)." }, "connectorKind": { "type": [ "string", "null" ], "description": "Connector kind for icon resolution (present when `source_type` is `connector`)." }, "connectorSourceId": { "type": [ "string", "null" ], "description": "Connector source ID (present when `source_type` is `connector`)." }, "documentCount": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of documents (spaces and folders only).", "minimum": 0 }, "folderPath": { "type": [ "string", "null" ], "description": "Full folder path (documents and folders)." }, "id": { "type": "string", "description": "Entity identifier." }, "name": { "type": "string", "description": "Display name (space name, document title, or folder name)." }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SourceReason", "description": "Why this result is included." } ] }, "resourceUri": { "type": [ "string", "null" ], "description": "Connector-defined resource URI (present when `source_type` is `connector`)." }, "scopeLevel": { "type": [ "string", "null" ], "description": "Scope level (spaces only)." }, "sourceType": { "$ref": "#/components/schemas/SourceType", "description": "Entity type." } } }, "SourceType": { "type": "string", "description": "The type of source entity.", "enum": [ "space", "document", "folder", "connector" ] }, "SourceWireFormat": { "type": "object", "description": "Minimal wire format for sources sent by the client in WebSocket payloads.\n\nContains only `type` + `id` + `mode`. The backend resolves metadata\n(names, counts, paths) server-side to avoid stale client data.", "required": [ "type", "id", "mode" ], "properties": { "id": { "type": "string", "description": "Entity identifier." }, "mode": { "$ref": "#/components/schemas/SourceConnectionMode", "description": "Connection mode." }, "name": { "type": [ "string", "null" ], "description": "Optional display name (document title, space name, folder path).\nSent by the frontend for system prompt context; avoids an extra\nserver-side lookup when the frontend already has the metadata." }, "type": { "type": "string", "description": "Source type: `\"space\"`, `\"document\"`, `\"folder\"`, or `\"connector\"`." } } }, "SpaceDocumentResponse": { "type": "object", "description": "API response for a document in a Space.", "required": [ "documentId", "source", "addedBy", "addedAt" ], "properties": { "addedAt": { "type": "string", "format": "date-time" }, "addedBy": { "type": "string" }, "documentId": { "type": "string" }, "filterId": { "type": [ "string", "null" ] }, "folder": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpaceFolderSummary", "description": "Folder metadata for this document. `None` if the folder no longer exists." } ] }, "source": { "$ref": "#/components/schemas/SpaceDocumentSource" }, "spaceRelativePath": { "type": [ "string", "null" ], "description": "Path of this document relative to the Space, using folder display names\njoined by `/`, e.g. `Architecture Decisions/Rejected`. `None` means the\ndocument belongs at the Space root: an explicitly added document that is\nnot inside any linked folder. Clients use this to render a Space-relative\ntree on disk or in a browser, independent of where the document otherwise\nlives in the workspace." }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the document was last modified." } } }, "SpaceDocumentSource": { "type": "string", "description": "How a document was included in a Space.", "enum": [ "explicit", "filter" ] }, "SpaceFilterResponse": { "type": "object", "description": "API response for a source filter (linked folder).\n\nThe `folder_name` and `folder_path` fields are resolved at read time from\nthe target folder's current metadata. When both are `None`, the linked\nfolder no longer exists or is inaccessible — this is the \"broken link\"\nsignal for the UI.", "required": [ "id", "spaceId", "folderId", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "documentCount": { "type": [ "integer", "null" ], "format": "int32", "description": "Approximate document count in the folder tree. `None` = broken link.", "minimum": 0 }, "folderId": { "type": "string" }, "folderName": { "type": [ "string", "null" ], "description": "Resolved folder name. `None` = broken link (folder deleted or inaccessible)." }, "folderPath": { "type": [ "string", "null" ], "description": "Resolved materialized folder path. `None` = broken link." }, "id": { "type": "string" }, "spaceId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SpaceFolderNode": { "type": "object", "description": "A folder node visible within a Space's browse view.\n\nReturned by `GET /api/v1/spaces/{spaceId}/folders`. At the top level,\nnodes are filter roots (linked folders). At deeper levels, nodes are\nsubfolders within a linked folder's tree.", "required": [ "folderId", "name", "isFilterRoot", "documentCount", "subfolderCount", "isBroken" ], "properties": { "documentCount": { "type": "integer", "format": "int32", "description": "Number of direct child documents in this folder.", "minimum": 0 }, "filterId": { "type": [ "string", "null" ], "description": "Which source filter links this folder. Only present for filter roots." }, "folderId": { "type": "string", "description": "Folder ID." }, "isBroken": { "type": "boolean", "description": "`true` if the folder no longer exists or is inaccessible from the Space's scope." }, "isFilterRoot": { "type": "boolean", "description": "`true` if this folder is the direct target of a source filter (top-level symlink)." }, "name": { "type": "string", "description": "Display name of the folder." }, "subfolderCount": { "type": "integer", "format": "int32", "description": "Number of direct child subfolders.", "minimum": 0 } } }, "SpaceFolderSummary": { "type": "object", "description": "Summary of a folder within a Space document listing.", "required": [ "id", "name", "kind", "scope" ], "properties": { "id": { "type": "string", "description": "Folder ID." }, "kind": { "$ref": "#/components/schemas/FolderKind", "description": "Folder kind (standard or skill)." }, "name": { "type": "string", "description": "Folder display name." }, "scope": { "$ref": "#/components/schemas/ScopeId", "description": "Typed folder scope." } } }, "SpaceGrantLevel": { "type": "string", "description": "Permission level granted to a principal on a `Space`.\n\nImplements `Ord` so levels can be compared: `Read < Edit < Manage`.\nUse `max()` to find the highest grant across multiple sources.\nAligned to Cedar permission atoms: `SpaceRead`, `SpaceEdit`, `SpaceManage`.", "enum": [ "read", "edit", "manage" ] }, "SpaceGrantPrincipalType": { "type": "string", "description": "Type of principal in a `SpaceGrant`.", "enum": [ "user", "team" ] }, "SpaceGrantResponse": { "type": "object", "description": "API response for a Space grant.", "required": [ "spaceId", "principalType", "principalId", "grantLevel", "grantedBy", "grantedAt" ], "properties": { "grantLevel": { "$ref": "#/components/schemas/SpaceGrantLevel" }, "grantedAt": { "type": "string", "format": "date-time" }, "grantedBy": { "type": "string" }, "principalId": { "type": "string" }, "principalType": { "$ref": "#/components/schemas/SpaceGrantPrincipalType" }, "spaceId": { "type": "string" } } }, "SpaceResponse": { "type": "object", "description": "API response for a single Space.", "required": [ "id", "companyId", "scope", "name", "tenantId", "documentCount", "transitiveAccess", "createdBy", "createdAt", "updatedAt" ], "properties": { "color": { "type": [ "string", "null" ] }, "companyId": { "type": "string" }, "coverImage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "documentCount": { "type": "integer", "format": "int32", "minimum": 0 }, "icon": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "parentFolderId": { "type": [ "string", "null" ] }, "scope": { "$ref": "#/components/schemas/ScopeId", "description": "Typed scope (`kind` + `id`) — immutable post-creation." }, "tenantId": { "type": "string" }, "transitiveAccess": { "type": "boolean", "description": "When `true`, `Space` membership projects onto contained documents\nvia the member's [`SpaceGrantLevel`]. Always `false` in v1\n(US2 / FR-003) — response field for forward compatibility." }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SpaceSearchChunk": { "type": "object", "description": "A single search result chunk with source attribution.", "required": [ "docId", "docTitle", "sectionId", "content", "headingContext", "score" ], "properties": { "content": { "type": "string" }, "docId": { "type": "string" }, "docTitle": { "type": "string" }, "headingContext": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number", "format": "double" }, "sectionId": { "type": "string" } } }, "SpaceSearchQuery": { "type": "object", "description": "Query parameters for in-app Space search.", "required": [ "q" ], "properties": { "limit": { "type": [ "integer", "null" ], "format": "int32", "description": "Max results (default 10, max 50).", "minimum": 0 }, "q": { "type": "string", "description": "Search query (1-1000 characters)." } } }, "SpaceSearchResponse": { "type": "object", "description": "Response from in-app Space search.", "required": [ "chunks", "totalFound", "tokensUsed" ], "properties": { "chunks": { "type": "array", "items": { "$ref": "#/components/schemas/SpaceSearchChunk" } }, "tokensUsed": { "type": "integer", "format": "int32", "minimum": 0 }, "totalFound": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SsoConfigLookupResponse": { "type": "object", "description": "Public SSO config lookup response for login-time domain resolution.\n\nDeliberately omits the underlying SSO protocol (`SsoProtocol`) so that\nunauthenticated callers cannot enumerate the company's `IdP` type.\nThe `cognito_provider_name` is the minimum required for Cognito Hosted\nUI redirect construction.", "required": [ "domain", "cognitoProviderName" ], "properties": { "cognitoProviderName": { "type": "string", "description": "`Cognito` identity provider name for login redirect" }, "domain": { "type": "string", "description": "The email domain" } } }, "SsoConfigResponse": { "type": "object", "description": "Organization-level SSO configuration response.", "required": [ "ssoEnabled", "ssoEnforced", "provisioningMethod" ], "properties": { "provisioningMethod": { "$ref": "#/components/schemas/ProvisioningMethod", "description": "How new users are provisioned" }, "ssoEnabled": { "type": "boolean", "description": "Whether SSO login is enabled" }, "ssoEnforced": { "type": "boolean", "description": "Whether SSO is the only allowed authentication method" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the configuration was last modified" } } }, "SsoConnectionResponse": { "type": "object", "description": "SSO connection details response.", "required": [ "id", "name", "protocol", "cognitoProviderName", "domains", "enabled", "createdAt", "updatedAt" ], "properties": { "cognitoProviderName": { "type": "string", "description": "`Cognito` user pool identity provider name" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the connection was created" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Email domains routed through this connection" }, "enabled": { "type": "boolean", "description": "Whether the connection is active" }, "id": { "type": "string", "description": "Unique connection identifier" }, "name": { "type": "string", "description": "Display name for the connection" }, "oidcClientId": { "type": [ "string", "null" ], "description": "OIDC client identifier" }, "oidcIssuerUrl": { "type": [ "string", "null" ], "description": "OIDC issuer URL" }, "protocol": { "$ref": "#/components/schemas/SsoProtocol", "description": "Authentication protocol" }, "samlMetadataDocument": { "type": [ "string", "null" ], "description": "SAML metadata XML document (alternative to URL for `IdPs` without metadata endpoints)" }, "samlMetadataUrl": { "type": [ "string", "null" ], "description": "SAML metadata document URL" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the connection was last modified" } } }, "SsoProtocol": { "type": "string", "description": "SSO authentication protocol", "enum": [ "saml", "oidc" ] }, "StalenessStatus": { "type": "string", "description": "Staleness classification returned by the staleness-check endpoint.\n\nMirrors the `source_status` written to an imported document, flattened\ninto a wire-friendly shape with a machine-readable `reason` when the\nsource is unavailable.", "enum": [ "fresh", "stale", "unavailable", "unknown" ] }, "StalenessUnavailableReason": { "type": "string", "description": "Reason the upstream source is currently unavailable.", "enum": [ "resourceDeleted", "resourceForbidden", "importerNoLongerMember", "credentialsRevoked" ] }, "StartServiceAccountResponse": { "type": "object", "description": "Response for `POST .../integrations/{kind}/service-account`.", "required": [ "authorizeUrl", "state" ], "properties": { "authorizeUrl": { "type": "string", "description": "`OAuth` authorization URL the admin must visit." }, "state": { "type": "string", "description": "Opaque state token for CSRF protection." } } }, "SubscriptionAction": { "type": "string", "description": "What happened to the migrated user's personal subscription.", "enum": [ "canceled" ] }, "SuggestedBy": { "type": "object", "description": "Secondary attribution for content that originated from an AI suggestion.", "required": [ "actorId", "displayName" ], "properties": { "actorId": { "type": "string", "description": "Agent ID that proposed the content." }, "displayName": { "type": "string", "description": "Display name of the suggesting agent." } } }, "SuggestionActionRequest": { "type": "object", "description": "Request body for accept/reject suggestion actions.", "properties": { "clientApplied": { "type": "boolean", "description": "When `true`, the client has already applied the document edit locally\n(through the TipTap/Yjs binding) and the server should only update the\nsuggestion status without modifying the document." }, "force": { "type": "boolean", "description": "When `true`, auto-resolve overlapping suggestions from other groups\nwithout prompting. When `false` (default), return 409 Conflict if\noverlapping groups exist." } } }, "SuggestionActionResponse": { "type": "object", "description": "Response after accepting or rejecting a suggestion.", "required": [ "documentId", "success", "documentVersion" ], "properties": { "autoResolvedSuggestions": { "type": "array", "items": { "type": "string" }, "description": "IDs of overlapping suggestions that were auto-resolved (marks removed)." }, "documentId": { "type": "string", "description": "Document identifier." }, "documentVersion": { "type": "integer", "format": "int64", "description": "Updated document version after the action.", "minimum": 0 }, "language": { "type": [ "string", "null" ], "description": "BCP 47 language tag applied to the document (only on accept with\nlanguage-bearing suggestions)." }, "success": { "type": "boolean", "description": "Whether the suggestion was found and processed." } } }, "SuggestionChangeType": { "type": "string", "description": "Type of suggestion change, used in `SuggestionChanged` notifications.", "enum": [ "created", "updated", "accepted", "rejected", "stale", "withdrawn" ] }, "SuggestionConflictResponse": { "type": "object", "description": "Structured 409 response for suggestion overlap conflicts.", "required": [ "error", "overlappingGroups" ], "properties": { "error": { "type": "string", "description": "Error type identifier." }, "overlappingGroups": { "type": "array", "items": { "$ref": "#/components/schemas/AutoResolvedInfo" }, "description": "Overlapping suggestion groups that would be auto-resolved." } } }, "SuggestionGroupSummary": { "type": "object", "description": "Summary of a single suggestion group (one agent task / batch).\n\nThe `batch_id` is the identifier a client should use when calling the\nbatch-scoped accept/reject endpoints. For suggestions that were created\nwithout a batch (direct REST, human-authored), the group's `batch_id`\nequals the underlying suggestion's id so clients still have a single\nwell-defined identifier to act on.", "required": [ "batchId", "agentName", "agentId", "createdAt", "markCount" ], "properties": { "agentId": { "type": "string", "description": "Agent identifier." }, "agentName": { "type": "string", "description": "Display name of the agent that created this group." }, "batchId": { "$ref": "#/components/schemas/TypedId", "description": "Batch identifier grouping all suggestions from one agent task.\nFalls back to the single suggestion's id for unbatched records." }, "createdAt": { "type": "string", "description": "When the suggestion group was created (RFC 3339)." }, "language": { "type": [ "string", "null" ], "description": "BCP 47 language tag (`None` for non-translation suggestions)." }, "markCount": { "type": "integer", "format": "int32", "description": "Number of individual suggestion marks in this group.", "minimum": 0 } } }, "SuggestionInfoResponse": { "type": "object", "description": "Information about a single pending suggestion.", "required": [ "suggestionId", "batchId", "agentId", "agentName", "deletedText", "insertedText", "createdAt" ], "properties": { "agentId": { "type": "string", "description": "Agent that produced the suggestion." }, "agentName": { "type": "string", "description": "Display name of the agent." }, "batchId": { "$ref": "#/components/schemas/TypedId", "description": "Batch identifier shared with sibling suggestions from the same agent\ntask. Clients use this to call the batch-scoped accept/reject\nendpoints. Falls back to the suggestion's own id for legacy records\nwithout a batch." }, "confidence": { "type": [ "number", "null" ], "format": "float", "description": "AI confidence score (0.0–1.0)." }, "createdAt": { "type": "string", "description": "When the suggestion was created (RFC 3339)." }, "deletedText": { "type": "string", "description": "Text marked for deletion (empty if insertion-only)." }, "endRelative": { "type": [ "string", "null" ], "description": "Yjs relative position for range end (for frontend position resolution)." }, "insertedContentJson": { "type": [ "object", "null" ], "description": "`ProseMirror` JSON of `inserted_text` for rendered preview.\nPopulated for full-doc rewrites (replacement text > 200 chars)." }, "insertedText": { "type": "string", "description": "Text marked for insertion (empty if deletion-only)." }, "language": { "type": [ "string", "null" ], "description": "BCP 47 language tag from insert marks (`None` for non-translation\nsuggestions)." }, "overlappingSuggestionIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of other suggestions that overlap with this one (share text nodes)." }, "rationale": { "type": [ "string", "null" ], "description": "Why the change was proposed." }, "severity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionSeverity", "description": "Severity level (nitpick, improvement, issue, critical)." } ] }, "startRelative": { "type": [ "string", "null" ], "description": "Yjs relative position for range start (for frontend position resolution)." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionStatus", "description": "Current lifecycle status." } ] }, "suggestionId": { "type": "string", "description": "Unique suggestion identifier." }, "threadCommentId": { "type": [ "string", "null" ], "description": "Linked comment thread for discussion." } } }, "SuggestionSeverity": { "type": "string", "description": "Severity level for a suggestion (typically set by AI agents).", "enum": [ "nitpick", "improvement", "issue", "critical" ] }, "SuggestionStatus": { "type": "string", "description": "Lifecycle status of a suggestion.", "enum": [ "pending", "accepted", "rejected", "stale", "withdrawn" ] }, "SwitchBranchRequest": { "type": "object", "description": "Request body for `POST /api/v1/auth/switch-branch`.", "required": [ "nodeId" ], "properties": { "mfaCode": { "type": [ "string", "null" ], "description": "Second-factor proof. Required when the target tier sets\n`switchRequiresMfa: true`." }, "nodeId": { "type": "string", "description": "Target depth-0 tier node identifier." } } }, "SwitchBranchResponse": { "type": "object", "description": "Response for `POST /api/v1/auth/switch-branch`.", "required": [ "message", "nodeId", "nodeName" ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation message." }, "nodeId": { "type": "string", "description": "The newly active branch." }, "nodeName": { "type": "string", "description": "Display name of the newly active branch." } } }, "SwitchTenantRequest": { "type": "object", "description": "Request to switch the active tenant.", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string", "description": "Tenant ID to switch to. Must be a valid ULID-prefixed identifier." } } }, "SwitchTenantResponse": { "type": "object", "description": "Response after switching tenants.", "required": [ "tenantId", "tierRole", "message" ], "properties": { "message": { "type": "string", "description": "Status message." }, "tenantId": { "type": "string", "description": "New active tenant ID." }, "tierRole": { "$ref": "#/components/schemas/TierRole", "description": "User's unified [`TierRole`] in the new tenant." } } }, "TaskResponse": { "type": "object", "description": "Task status response.", "required": [ "id", "agentId", "status", "toolCallCount", "createdAt", "updatedAt" ], "properties": { "agentId": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "executionTrace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionTrace", "description": "Full execution trace (populated only when `?include=trace` is requested\nand the task was invoked with `include_trace: true`)." } ] }, "id": { "type": "string" }, "output": {}, "status": { "$ref": "#/components/schemas/TaskStatus" }, "tokenUsage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsageResponse" } ] }, "toolCallCount": { "type": "integer", "format": "int32", "minimum": 0 }, "updatedAt": { "type": "string" } } }, "TaskStatus": { "type": "string", "description": "Status of an agent task execution.", "enum": [ "pending", "running", "completed", "failed", "cancelled", "timedOut" ] }, "TeamSignupRequest": { "type": "object", "description": "Request to create a new Team-plan workspace for the authenticated\ncaller alongside their existing Personal account.", "required": [ "workspaceName", "slug" ], "properties": { "slug": { "type": "string", "description": "Globally unique URL-safe slug (3-50 characters)" }, "workspaceName": { "type": "string", "description": "Workspace name (2-100 characters). On Team plans the root tier\nIS the workspace, so this is also the team name shown in the\nsidebar." } } }, "TeamSignupResponse": { "type": "object", "description": "Response after successful team signup upgrade.", "required": [ "id", "name", "slug", "billingPlan", "onboardingComplete", "createdAt", "updatedAt" ], "properties": { "billingPlan": { "$ref": "#/components/schemas/BillingPlan", "description": "Billing plan (always `team` after upgrade)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the company was created" }, "id": { "type": "string", "description": "Company identifier" }, "name": { "type": "string", "description": "Company name" }, "onboardingComplete": { "type": "boolean", "description": "Onboarding wizard completion status (always `false` after team signup)" }, "slug": { "type": "string", "description": "URL-safe slug" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the company was last updated" } } }, "TenantResolveResponse": { "type": "object", "description": "Response for `GET /api/tenant/resolve/{slug}`.\n\nReturns minimal public company info for unauthenticated tenant\ncontext display (e.g., \"Sign in to Acme Corp\" on the login page).", "required": [ "slug", "name", "companyId" ], "properties": { "companyId": { "type": "string", "description": "The company identifier (ULID with `company_` prefix)." }, "name": { "type": "string", "description": "The company display name." }, "slug": { "type": "string", "description": "The company slug (matches the subdomain)." } } }, "ThemeRecord": { "type": "object", "description": "Per-document theme registry entry.\n\nOne record per theme on a document. The id and `label` are immutable\nafter first write; `centroid` (a 256-dimensional running mean of member\nembeddings) and `memberCount` are updated as new comments join the\ntheme. Themes are append-only — a theme is never deleted, even when\nevery member comment is removed.", "required": [ "themeId", "label", "centroid", "memberCount", "createdAt" ], "properties": { "centroid": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "256-dimensional running mean of member-comment embeddings. Updated\nas new comments join the theme." }, "createdAt": { "type": "string", "format": "date-time", "description": "Wall-clock at first write. Used for display-stable ordering of the\ntheme registry." }, "label": { "type": "string", "description": "Short human-readable label (a few words, max 64 chars). Generated by\nthe synthesis pipeline on first write; never re-generated." }, "memberCount": { "type": "integer", "format": "int32", "description": "Number of comments currently assigned to this theme. Increments on\njoin; never decrements (zero-member themes are allowed to remain).", "minimum": 0 }, "themeId": { "$ref": "#/components/schemas/TypedId", "description": "Stable theme identifier." } } }, "ThinkingConfig": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "adaptive" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "disabled" ] } } } ], "description": "Reasoning strategy for models that support extended thinking.\n\n`Adaptive` lets the model decide when and how much to think — generally\nthe best balance of quality and cost. `Disabled` forces direct response." }, "TierInput": { "type": "object", "description": "A single tier in a [`SetHierarchyRequest`].", "required": [ "id", "name", "roleTemplate", "adminCascade" ], "properties": { "adminCascade": { "type": "boolean", "description": "Whether admin roles cascade to descendant tiers." }, "id": { "type": "string", "description": "Stable slug identifier (immutable after creation)." }, "name": { "type": "string", "description": "Display name for this tier." }, "roleTemplate": { "$ref": "#/components/schemas/RoleTemplate", "description": "Which roles are valid for memberships at this tier." }, "switchRequiresMfa": { "type": "boolean", "description": "Whether switching to this tier's nodes requires MFA verification." } } }, "TierMembershipResponse": { "type": "object", "description": "API response for a single tier membership.", "required": [ "id", "userId", "nodeId", "tierId", "role", "joinedAt", "source" ], "properties": { "id": { "type": "string", "description": "Unique membership identifier." }, "joinedAt": { "type": "string", "format": "date-time", "description": "When the user joined." }, "nodeId": { "type": "string", "description": "Target node identifier." }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Role held in this node." }, "source": { "$ref": "#/components/schemas/MembershipSource", "description": "How this membership was created." }, "tierId": { "type": "string", "description": "Tier identifier." }, "userId": { "type": "string", "description": "User identifier." } } }, "TierNodeOrigin": { "type": "string", "description": "How a tier node was created.", "enum": [ "manual", "scim" ] }, "TierNodeResponse": { "type": "object", "description": "API response for a single tier node.", "required": [ "id", "companyId", "tierId", "depth", "name", "slug", "settings", "ancestorChain", "origin", "status", "createdAt", "updatedAt" ], "properties": { "ancestorChain": { "type": "array", "items": { "type": "string" }, "description": "Materialized path from depth 0 to this node's parent." }, "companyId": { "type": "string", "description": "Parent company identifier." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "depth": { "type": "integer", "format": "int32", "description": "Depth in the hierarchy (0 = directly under Company).", "minimum": 0 }, "id": { "type": "string", "description": "Unique node identifier." }, "name": { "type": "string", "description": "Human-readable display name." }, "origin": { "$ref": "#/components/schemas/TierNodeOrigin", "description": "How this node was created." }, "parentNodeId": { "type": [ "string", "null" ], "description": "Parent node identifier. `None` for depth-0 nodes." }, "settings": { "$ref": "#/components/schemas/TierNodeSettings", "description": "Per-node settings (inherited from parent, can restrict but never relax)." }, "slug": { "type": "string", "description": "URL-safe slug, unique among siblings." }, "status": { "$ref": "#/components/schemas/TierNodeStatus", "description": "Lifecycle status." }, "tierId": { "type": "string", "description": "Which hierarchy tier this node belongs to." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last modification timestamp." } } }, "TierNodeSettings": { "type": "object", "description": "Per-node settings that inherit top-down through the hierarchy.\n\nChild nodes inherit parent settings on creation and may restrict\n(but never relax) them.", "properties": { "autoArchiveDays": { "type": [ "integer", "null" ], "format": "int32", "description": "Days of inactivity after which an active document is auto-archived.\n`None` = auto-archive disabled.", "minimum": 0 }, "externalSharingAllowed": { "type": "boolean", "description": "Whether external sharing is allowed from this node." }, "ipAllowlist": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "IP addresses allowed to access this node. `None` = no restriction." }, "maxStorageBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum storage in bytes. `None` = unlimited (inherits parent).", "minimum": 0 }, "mfaRequired": { "type": "boolean", "description": "Whether MFA is required for this node's members." }, "trashRetentionDays": { "type": "integer", "format": "int32", "description": "Days to keep trashed documents before permanent purge.", "minimum": 0 } } }, "TierNodeStatus": { "type": "string", "description": "Lifecycle status of a tier node.", "enum": [ "active", "deleting" ] }, "TierNodeTreeResponse": { "allOf": [ { "$ref": "#/components/schemas/TierNodeResponse", "description": "The root node of this subtree." }, { "type": "object", "required": [ "children" ], "properties": { "children": { "type": "array", "items": { "$ref": "#/components/schemas/TierNodeTreeResponse" }, "description": "Direct children, each with their own recursive subtree." } } } ], "description": "API response for a tier node subtree." }, "TierRole": { "type": "string", "description": "Role a user holds in a tier node. Consolidated per\n`specs/073-tier-unification/contracts/tier-role.md` — supersedes\n`CompanyRole` and `OrgRole` with a single 5-variant enum plus capability\nmethods.\n\nValidity per tier is constrained by the tier's [`RoleTemplate`]. Wire\nformat is `PascalCase` to match the JWT `tier_roles` contract.", "enum": [ "Owner", "Admin", "Manager", "Member", "Guest" ] }, "ToggleReactionRequest": { "type": "object", "description": "Request to toggle a reaction on a comment.", "required": [ "reactionType" ], "properties": { "reactionType": { "type": "string" } } }, "TokenUsageResponse": { "type": "object", "description": "Token usage in response.", "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ToolApprovalBatchRequest": { "type": "object", "description": "Request body for the batch tool approval endpoint.", "required": [ "decisions" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApprovalDecisionWire" }, "description": "Per-tool approval decisions." } } }, "ToolApprovalDecisionWire": { "type": "object", "description": "A single tool approval decision from the user.", "required": [ "toolCallId", "approved" ], "properties": { "approved": { "type": "boolean", "description": "`true` to approve, `false` to reject." }, "reason": { "type": [ "string", "null" ], "description": "Optional rejection reason (shown to the LLM)." }, "toolCallId": { "type": "string", "description": "The tool-use block ID to approve or reject." } } }, "ToolApprovalItem": { "type": "object", "description": "A single tool pending user approval within a [`ChatSseEvent::ToolApprovalBatch`].", "required": [ "toolCallId", "toolName", "description", "arguments" ], "properties": { "arguments": { "description": "Tool arguments (so the frontend can render a preview)." }, "description": { "type": "string", "description": "Human-readable description of what the tool will do." }, "toolCallId": { "type": "string", "description": "The LLM's unique tool-use block ID." }, "toolName": { "type": "string", "description": "Tool name." } } }, "ToolCallRecord": { "type": "object", "description": "Record of a single tool invocation within an iteration.", "required": [ "toolName", "input", "isError", "outputSummary", "durationMs" ], "properties": { "durationMs": { "type": "integer", "format": "int64", "description": "Duration of tool execution (ms).", "minimum": 0 }, "input": { "description": "Input parameters (sanitized — large content truncated to 1KB)." }, "isError": { "type": "boolean", "description": "Whether the tool returned an error." }, "outputSummary": { "type": "string", "description": "Output summary (truncated to 2KB to keep trace size manageable)." }, "toolName": { "type": "string", "description": "Tool name (e.g., `edit_document`, `read_document`)." } } }, "ToolCallStatus": { "type": "string", "description": "Execution status of a tool call.", "enum": [ "running", "completed", "failed" ] }, "ToolOverride": { "type": "string", "description": "Per-conversation tool-availability mode.", "enum": [ "allow", "allowOnce", "deny" ] }, "TransferOrgOwnerRequest": { "type": "object", "description": "Request to transfer org ownership to a different company member.", "required": [ "newOwnerId" ], "properties": { "newOwnerId": { "type": "string", "description": "User ID of the new org owner. Must be a company member." } } }, "TransferRecipient": { "type": "object", "description": "Candidate for ownership transfer.", "required": [ "userId", "displayName", "membershipStatus" ], "properties": { "displayName": { "type": "string", "description": "Display name for the recipient at evaluation time." }, "membershipStatus": { "$ref": "#/components/schemas/MembershipStatus", "description": "Current membership status — listed candidates are always\n`active`, but the field is preserved so stale clients can\ndistinguish if the recipient changed between summary and submit." }, "userId": { "$ref": "#/components/schemas/TypedId", "description": "Recipient user identifier." } } }, "TransferWorkspaceOwnershipRequest": { "type": "object", "description": "Body of `POST /api/v1/companies/{companyId}/transfer-ownership`.", "required": [ "summaryVersion", "newOwnerUserId" ], "properties": { "newOwnerUserId": { "$ref": "#/components/schemas/TypedId", "description": "Identifier of the active member receiving ownership." }, "summaryVersion": { "type": "string", "description": "Summary version returned by the lifecycle summary the actor\nreviewed." } } }, "TransferWorkspaceOwnershipResponse": { "type": "object", "description": "Response body of `POST /api/v1/companies/{companyId}/transfer-ownership`.", "required": [ "operationId", "status", "workspaceId", "previousOwnerUserId", "newOwnerUserId" ], "properties": { "newOwnerUserId": { "$ref": "#/components/schemas/TypedId", "description": "New owner." }, "operationId": { "$ref": "#/components/schemas/TypedId", "description": "Idempotent lifecycle operation identifier." }, "previousOwnerUserId": { "$ref": "#/components/schemas/TypedId", "description": "Prior owner (now demoted to `Member`)." }, "status": { "$ref": "#/components/schemas/LifecycleOperationStatus", "description": "Final operation state." }, "workspaceId": { "$ref": "#/components/schemas/TypedId", "description": "Workspace whose ownership changed." } } }, "TriggeredAgentInfo": { "type": "object", "description": "Information about an agent triggered by an `@mention` in a comment.", "required": [ "agentName", "taskId", "status" ], "properties": { "agentName": { "type": "string", "description": "Display name of the agent." }, "status": { "$ref": "#/components/schemas/TaskStatus", "description": "Current status of the task (may already be `completed` on Lambda\nwhere the agent runs inline before the HTTP response returns)." }, "taskId": { "type": "string", "description": "Task ID for tracking execution progress." } } }, "TypedId": { "type": "string" }, "UndoConflict": { "type": "object", "description": "A conflict where automatic undo is not possible because subsequent\nedits modified the same content.", "required": [ "blockId", "blockType", "editProduced", "currentContent", "reason" ], "properties": { "blockId": { "type": "string", "description": "Positional block ID (e.g. `\"node_3\"`)." }, "blockType": { "type": "string", "description": "Block type (e.g. `\"paragraph\"`, `\"heading\"`)." }, "currentContent": { "type": "string", "description": "What the block currently contains (after subsequent edits)." }, "editProduced": { "type": "string", "description": "What the targeted edit changed this block to." }, "reason": { "type": "string", "description": "Human-readable description of why automatic undo is not possible." } } }, "UnifiedSearchHit": { "oneOf": [ { "type": "object", "description": "A matching document (from Postgres full-text + fuzzy search).", "required": [ "documentId", "title", "snippet", "score", "type" ], "properties": { "documentId": { "type": "string" }, "folderPath": { "type": "array", "items": { "$ref": "#/components/schemas/FolderPathSegment" }, "description": "Folder breadcrumb path from root to parent folder." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SearchResultMetadata" } ] }, "score": { "type": "number", "format": "float" }, "snippet": { "type": "string" }, "spaceIds": { "type": "array", "items": { "type": "string" }, "description": "Space IDs this document belongs to (for grouping in Discovery Hub)." }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "document" ] } } }, { "type": "object", "description": "A matching Space (from name search).", "required": [ "spaceId", "name", "scopeLevel", "documentCount", "score", "type" ], "properties": { "description": { "type": [ "string", "null" ] }, "documentCount": { "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "scopeLevel": { "type": "string" }, "score": { "type": "number", "format": "float" }, "spaceId": { "type": "string" }, "type": { "type": "string", "enum": [ "space" ] } } } ], "description": "A single result in the unified search response, tagged by entity type." }, "UnpublishDocumentResponse": { "type": "object", "description": "Response from an unpublish operation.", "required": [ "unpublishedAt" ], "properties": { "unpublishedAt": { "type": "string", "description": "When the document was unpublished." } } }, "UnreadCountResponse": { "type": "object", "description": "Unread notification count for badge display.", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Number of unread notifications.", "minimum": 0 } } }, "UpdateAgentPolicyRequest": { "type": "object", "description": "Request to update the agent policy (all fields optional for partial update).", "properties": { "allowAgentOnExternalDocs": { "type": [ "boolean", "null" ], "description": "Whether agents can operate on external documents" }, "allowedAgentTypes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Agent types allowed to run (empty = all types allowed)" }, "allowedPermissions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Set of permissions that agents are allowed to use" }, "emergencyStop": { "type": [ "boolean", "null" ], "description": "Emergency stop: if true, all agent executions are blocked org-wide" }, "maxAgentsPerUser": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of agents each user can create", "minimum": 0 }, "rateLimitPerHour": { "type": [ "integer", "null" ], "format": "int32", "description": "Max invocations per agent per hour (0 = unlimited)", "minimum": 0 }, "restrictedFolders": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Folder IDs that agents are not allowed to access" } } }, "UpdateAgentRequest": { "type": "object", "description": "Request to update an agent.", "properties": { "defaultAutonomy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AutonomyLevel", "description": "Updated default autonomy level." } ] }, "description": { "type": [ "string", "null" ], "description": "New description." }, "enabledTools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Updated tool names." }, "permissions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Updated permissions." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentStatus", "description": "Updated status." } ] } } }, "UpdateAgentSettingsRequest": { "type": "object", "description": "Request body for `PUT /api/v1/companies/{companyId}/agent-settings`.", "required": [ "enabledPlatformAgents", "allowedModels" ], "properties": { "agentOverrides": { "type": "object", "description": "Per-agent overrides keyed by platform agent name.", "additionalProperties": { "$ref": "#/components/schemas/PlatformAgentOverride" }, "propertyNames": { "type": "string" } }, "allowedModels": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "LLM models that agents are allowed to use (empty = none allowed).\nActs as the company-wide ceiling — per-agent overrides must be subsets.", "uniqueItems": true }, "enabledPlatformAgents": { "type": "array", "items": { "type": "string" }, "description": "Platform agent names that are enabled (empty = none enabled).", "uniqueItems": true }, "systemPromptPrefix": { "type": [ "string", "null" ], "description": "Optional text prepended to every agent system prompt." }, "systemPromptSuffix": { "type": [ "string", "null" ], "description": "Optional text appended to every agent system prompt." } } }, "UpdateAgentsSettingsRequest": { "type": "object", "description": "Request body for `PATCH /api/v1/agents/settings`.", "properties": { "creatorMode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentsCreatorMode", "description": "New value for `creator_mode`. `None` keeps the current value." } ] }, "enabled": { "type": [ "boolean", "null" ], "description": "New value for the master toggle. `None` keeps the current value." } } }, "UpdateCommentRequest": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" } } }, "UpdateCompanyMemberRoleRequest": { "type": "object", "description": "Request to update a company member's role.", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/TierRole", "description": "New role for the member" } } }, "UpdateCompanyRequest": { "type": "object", "description": "Request to update an existing company.", "properties": { "name": { "type": [ "string", "null" ], "description": "Updated company name" }, "onboardingComplete": { "type": [ "boolean", "null" ], "description": "Mark onboarding as complete (only `false` → `true` transition allowed)" } } }, "UpdateDocumentRequest": { "type": "object", "properties": { "folderId": { "type": [ "string", "null" ], "description": "Absent → unchanged, `null` → clear folder, value → set folder." }, "language": { "type": [ "string", "null" ], "description": "BCP 47 language tag. Absent → unchanged, `null` → clear, value → set." }, "title": { "type": [ "string", "null" ] } } }, "UpdateDocumentResponse": { "allOf": [ { "$ref": "#/components/schemas/DocumentResponse", "description": "Updated document metadata." }, { "type": "object", "properties": { "scopeChanged": { "type": [ "boolean", "null" ], "description": "Whether the move crosses scope boundaries (convenience flag for the frontend)." }, "sourceScope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeInfo", "description": "Source folder scope (populated only when the move crosses scope boundaries)." } ] }, "targetScope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeInfo", "description": "Target folder scope (populated only when the move crosses scope boundaries)." } ] } } } ], "description": "Response for `PATCH /documents/{docId}`.\n\nExtends `DocumentResponse` with optional scope-change metadata. When the\ndocument's `folderId` changes to a folder with a different scope, `sourceScope`\nand `targetScope` are populated so the frontend can show a confirmation dialog." }, "UpdateFavoritesRequest": { "type": "object", "description": "Request type for the PUT favorites endpoint.", "properties": { "documentIds": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of document IDs to set as favorites." }, "folderIds": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of folder IDs to set as favorites." }, "spaceIds": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of Space IDs to set as favorites." } } }, "UpdateFolderRequest": { "type": "object", "description": "Request to update an existing folder.\n\nFolder `scope` is immutable post-creation; the extractor rejects any\npayload carrying `scope` via `deny_unknown_fields`.", "required": [ "name" ], "properties": { "kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FolderKind", "description": "Folder kind toggle. Absent = no change." } ] }, "name": { "type": "string" } }, "additionalProperties": false }, "UpdateIdpMappingRequest": { "type": "object", "description": "Request to update an existing `IdP` group mapping's role.", "required": [ "tierRole" ], "properties": { "tierRole": { "$ref": "#/components/schemas/TierRole", "description": "Updated role for group members in the target tier node" } } }, "UpdateMemoryProfileRequest": { "type": "object", "description": "Profile update payload.", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Full replacement body. Rejected with 422 when longer than\n[`MEMORY_PROFILE_MAX_CHARS`]." } } }, "UpdateMemorySettingsRequest": { "type": "object", "description": "Request body for `PATCH /users/me/memory/settings`.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "When `true` enables memory; provisions folders + Space if missing.\nWhen `false` disables injection — existing data is preserved." } } }, "UpdateOnboardingRequest": { "type": "object", "description": "PATCH body for `/api/v1/users/me/onboarding/{wizardKey}/{version}`.\n\nAll fields are optional; omitted fields leave existing state untouched.\nWhen `steps_seen` is provided, it replaces the entire existing set\n(clients send the full union, not a delta).\n\n`completed_at` and `skipped` are *signals*, not values:\n- Sending `completed_at: ` requests completion. The\n server stamps the timestamp itself on the first transition and\n freezes it; subsequent requests leave it untouched.\n- Sending `skipped: true` requests skip. Once true, the server never\n accepts `skipped: false` (this would defeat the resume affordance).", "properties": { "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Signal that the wizard is complete. The server stamps the\ntimestamp itself on the first transition; idempotent thereafter.\nAudit emits `OnboardingCompleted` once." }, "skipped": { "type": [ "boolean", "null" ], "description": "Signal that the wizard was skipped. Monotonic — once `true`, it\nstays `true`. Audit emits `OnboardingSkipped` once." }, "stepsSeen": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/FirstTimeUserStep" }, "description": "Replacement set of seen step keys.", "uniqueItems": true } } }, "UpdateProfileRequest": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string" } } }, "UpdatePromptsSettingsRequest": { "type": "object", "description": "Request body for `PATCH /api/v1/prompts/settings`.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "New value for the master toggle." } } }, "UpdatePublishingProfileRequest": { "type": "object", "description": "Request to update publishing profile.", "properties": { "avatarImageId": { "type": [ "string", "null" ], "description": "Uploaded avatar reference. Absent → no change; empty string → clear\n(revert to Gravatar fallback); non-empty → set to this image id.\nThe image must already exist in the caller's tenant (uploaded via\n`POST /api/v1/images`)." }, "bio": { "type": [ "string", "null" ], "description": "Short biography (max 160 chars)." }, "pinned": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PinnedItem" }, "description": "Pinned items (max 10)." } } }, "UpdateRepoSourceRequest": { "type": "object", "description": "Request to update a repository source configuration.", "properties": { "defaultBranch": { "type": [ "string", "null" ], "description": "New default branch to track" } } }, "UpdateSessionMemoryRequest": { "type": "object", "description": "Request body for `PATCH /chat/sessions/{sessionId}/memory`.\n\nToggles the per-session memory override without touching the user's\nglobal `memoryEnabled` preference.", "required": [ "disabled" ], "properties": { "disabled": { "type": "boolean", "description": "When `true`, memory is silenced for this session only. When\n`false`, restores the global behavior." } } }, "UpdateSessionToolOverrideRequest": { "type": "object", "description": "Request body for `PATCH /chat/sessions/{sessionId}/tool-overrides`.\n\nSets the per-conversation override for a single tool. Today only\n`web_search` consults this map; future per-conversation tool gates\ncan read it without changing the contract.", "required": [ "toolName" ], "properties": { "overrideValue": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolOverride", "description": "`null` removes the override (back to per-tool default);\notherwise sets it to `Allow` / `AllowOnce` / `Deny`." } ] }, "toolName": { "type": "string", "description": "Tool name (e.g. `\"web_search\"`). Must match an entry in the\nagent runtime's `ALL_AGENT_TOOLS` registry." } } }, "UpdateSharingPolicyRequest": { "type": "object", "description": "Request to update the sharing policy (all fields optional for partial update).", "properties": { "allowedDomains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Allowed email domains for external sharing." }, "blockedDomains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Blocked email domains for external sharing." }, "externalSharingEnabled": { "type": [ "boolean", "null" ], "description": "Whether sharing with users outside the organization is allowed." }, "maxExternalRole": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceRole", "description": "Maximum role for external users." } ] }, "maxPublicLinkExpiryHours": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum expiry time for public links in hours.", "minimum": 0 }, "publicLinksEnabled": { "type": [ "boolean", "null" ], "description": "Whether public links are enabled." }, "requirePublicLinkPassword": { "type": [ "boolean", "null" ], "description": "Whether public links require a password." }, "watermarkOnExport": { "type": [ "boolean", "null" ], "description": "Whether watermarks are applied on document export." }, "watermarkTemplate": { "type": [ "string", "null" ], "description": "Custom watermark template." } } }, "UpdateSpaceFilterRequest": { "type": "object", "description": "Request to update a source filter.", "required": [ "folderId" ], "properties": { "folderId": { "type": "string", "description": "Updated folder ID." } } }, "UpdateSpaceRequest": { "type": "object", "description": "Request to update an existing Space.\n\n`scope` is immutable post-creation and the extractor rejects any payload\ncarrying it (400 with field name) via `deny_unknown_fields`.", "properties": { "color": { "type": [ "string", "null" ], "description": "Updated color. `null` clears the field." }, "coverImage": { "type": [ "string", "null" ], "description": "Updated cover image. `null` clears the field." }, "description": { "type": [ "string", "null" ], "description": "Updated description. `null` clears the field." }, "icon": { "type": [ "string", "null" ], "description": "Updated icon. `null` clears the field." }, "name": { "type": [ "string", "null" ], "description": "Updated name (unique within scope)." } }, "additionalProperties": false }, "UpdateSsoConfigRequest": { "type": "object", "description": "Request to update organization-level SSO settings.", "properties": { "provisioningMethod": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProvisioningMethod", "description": "How new users are provisioned" } ] }, "ssoEnabled": { "type": [ "boolean", "null" ], "description": "Whether SSO login is enabled" }, "ssoEnforced": { "type": [ "boolean", "null" ], "description": "Whether SSO is the only allowed authentication method" } } }, "UpdateSsoConnectionRequest": { "type": "object", "description": "Request to update an existing SSO connection.\n\nAll fields are optional; omitted fields retain their existing values.\n`protocol` and `cognitoProviderName` are immutable and excluded from this\nschema.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Whether the connection is active" }, "name": { "type": [ "string", "null" ], "description": "Updated display name for the connection" }, "oidcClientId": { "type": [ "string", "null" ], "description": "Updated OIDC client identifier (OIDC connections only)" }, "oidcClientSecret": { "type": [ "string", "null" ], "description": "Updated OIDC client secret (OIDC connections only)" }, "oidcIssuerUrl": { "type": [ "string", "null" ], "description": "Updated OIDC issuer URL (OIDC connections only)" }, "samlMetadataDocument": { "type": [ "string", "null" ], "description": "SAML metadata XML document (alternative to URL for `IdPs` without metadata endpoints)" }, "samlMetadataUrl": { "type": [ "string", "null" ], "description": "Updated SAML metadata document URL (SAML connections only)" } } }, "UpdateTierMemberRoleRequest": { "type": "object", "description": "Request body for updating a member's role.", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/TierRole", "description": "New role (must be valid for the tier's role template)." } } }, "UpdateTierNodeRequest": { "type": "object", "description": "Request body for updating a tier node (partial).", "properties": { "name": { "type": [ "string", "null" ], "description": "Updated display name." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TierNodeSettings", "description": "Updated settings." } ] }, "slug": { "type": [ "string", "null" ], "description": "Updated slug." } } }, "UpdateTierRequest": { "type": "object", "description": "Request body for `PATCH /api/companies/{companyId}/hierarchy/tiers/{tierId}`.", "properties": { "adminCascade": { "type": [ "boolean", "null" ], "description": "Updated admin cascade setting." }, "name": { "type": [ "string", "null" ], "description": "Updated display name." }, "switchRequiresMfa": { "type": [ "boolean", "null" ], "description": "Updated MFA-on-switch setting." } } }, "UsageMetrics": { "type": "object", "description": "Usage metrics for a company against plan limits.", "required": [ "memberCount", "organizationCount", "storageUsedGb" ], "properties": { "maxMembers": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum members for the plan (`None` = unlimited).", "minimum": 0 }, "maxOrganizations": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum organizations for the plan (`None` = unlimited).", "minimum": 0 }, "maxStorageGb": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum storage in GB (`None` = unlimited).", "minimum": 0 }, "memberCount": { "type": "integer", "format": "int32", "description": "Current member count.", "minimum": 0 }, "organizationCount": { "type": "integer", "format": "int32", "description": "Current organization count.", "minimum": 0 }, "storageUsedGb": { "type": "number", "format": "double", "description": "Current storage used in GB." } } }, "UsageResponse": { "type": "object", "description": "Current usage metrics against effective plan limits.\n\nReturned by `GET /api/companies/{companyId}/billing/usage`.", "required": [ "effectivePlan", "subscriptionStatus", "usage", "limits", "warningThresholds" ], "properties": { "effectivePlan": { "$ref": "#/components/schemas/BillingPlan", "description": "Plan used for limit enforcement (accounts for subscription status)." }, "estimatedMonthlyCost": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated monthly cost in cents (`seat_count` x `unit_price`). `None` for free plans." }, "limits": { "$ref": "#/components/schemas/PlanLimits", "description": "Plan limit definitions." }, "nextInvoiceDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Next invoice date from Stripe subscription. `None` for free plans." }, "subscriptionStatus": { "$ref": "#/components/schemas/BillingSubscriptionStatus", "description": "Current subscription lifecycle status." }, "usage": { "$ref": "#/components/schemas/UsageMetrics", "description": "Current resource usage counts." }, "warningThresholds": { "$ref": "#/components/schemas/WarningThresholds", "description": "Resources at or above 80% usage." } } }, "UserGrantAdminEntry": { "type": "object", "description": "Admin view of a single user's grant on a connection.", "required": [ "userId", "status", "grantedAt" ], "properties": { "grantedAt": { "type": "string", "format": "date-time", "description": "When the grant was issued." }, "status": { "$ref": "#/components/schemas/GrantStatus", "description": "Current grant status." }, "userId": { "type": "string", "description": "User who holds the grant." } } }, "UserGrantResponse": { "type": "object", "description": "Response for the authenticated user's grant status on a connection.", "required": [ "status" ], "properties": { "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the grant expires." }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the grant was issued." }, "status": { "$ref": "#/components/schemas/GrantStatus", "description": "Current grant status." } } }, "UserPolicyState": { "type": "string", "description": "Policy visibility state for a connector entry as seen by a non-admin user.\n\nMapped from the internal `PolicyDecision` + `DenyReason` by the handler —\n`Allowed` → `allowed`, `Denied(KillSwitchEngaged)` → `killSwitched`, etc.", "enum": [ "allowed", "allowedPendingApproval", "disallowed", "killSwitched" ] }, "UserTierMembershipEntry": { "type": "object", "description": "API response for a single tier node membership entry, enriched with node\nmetadata for direct use by the sidebar without a second round-trip.", "required": [ "nodeId", "companyId", "tierId", "tierLabel", "role", "depth", "name", "slug" ], "properties": { "companyId": { "type": "string", "description": "Parent company identifier." }, "depth": { "type": "integer", "format": "int32", "description": "Depth in the hierarchy (0 = directly under Company).", "minimum": 0 }, "name": { "type": "string", "description": "Human-readable display name." }, "nodeId": { "type": "string", "description": "Unique node identifier." }, "parentNodeId": { "type": [ "string", "null" ], "description": "Parent node identifier. `None` for depth-0 nodes." }, "role": { "$ref": "#/components/schemas/TierRole", "description": "Role held in this node." }, "slug": { "type": "string", "description": "URL-safe slug, unique among siblings." }, "tierId": { "type": "string", "description": "Hierarchy tier slug (e.g. `\"org\"`, `\"team\"`)." }, "tierLabel": { "type": "string", "description": "Display label for the hierarchy tier this node belongs to\n(e.g. `\"Team\"`, `\"Organization\"`, or an enterprise-renamed `\"Tribe\"`).\nResolved from the company's [`HierarchyDefinition`] at request time." } } }, "VersionConflictResponse": { "type": "object", "description": "Structured 409 response body for version conflicts.\n\nGives clients everything needed to rebase and retry without an additional read.", "required": [ "error", "code", "currentVersion", "providedVersion", "currentContent", "documentVersion" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "HTTP status code (always 409).", "minimum": 0 }, "currentContent": { "type": "string", "description": "Current plaintext content of the document." }, "currentVersion": { "type": "integer", "format": "int64", "description": "Current server-side version of the document.", "minimum": 0 }, "documentVersion": { "type": "integer", "format": "int64", "description": "Current document-level version.", "minimum": 0 }, "error": { "type": "string", "description": "Human-readable conflict description." }, "providedVersion": { "type": "integer", "format": "int64", "description": "Version the client sent (the stale version).", "minimum": 0 } } }, "VisitEvent": { "type": "object", "description": "Body of a visit-ingest request.", "required": [ "path", "consentTier" ], "properties": { "consentTier": { "$ref": "#/components/schemas/ConsentTier", "description": "Consent tier the visitor is operating under at submission time." }, "fbclid": { "type": [ "string", "null" ], "description": "Meta (Facebook) click identifier." }, "gclid": { "type": [ "string", "null" ], "description": "Google Ads click identifier." }, "msclkid": { "type": [ "string", "null" ], "description": "Microsoft Advertising click identifier." }, "path": { "type": "string", "description": "Pathname of the page the visitor is on." }, "referrer": { "type": [ "string", "null" ], "description": "HTTP referrer reported by the browser." }, "utmCampaign": { "type": [ "string", "null" ], "description": "`utm_campaign` campaign tag." }, "utmContent": { "type": [ "string", "null" ], "description": "`utm_content` campaign tag." }, "utmMedium": { "type": [ "string", "null" ], "description": "`utm_medium` campaign tag." }, "utmSource": { "type": [ "string", "null" ], "description": "`utm_source` campaign tag." }, "utmTerm": { "type": [ "string", "null" ], "description": "`utm_term` campaign tag." } } }, "VisitResponse": { "type": "object", "description": "Response body for a visit-ingest request.\n\n`visitor_id` is populated only when the visitor consented to attribution;\nit lets the client persist the same identifier across the session for\nlater submission with the signup form. The value is an opaque\n26-character string the consumer should not parse beyond equality.", "properties": { "visitorId": { "type": [ "string", "null" ], "description": "Visitor identifier — present only on the attribution tier." } } }, "WaitlistSignupRequest": { "type": "object", "description": "Request to join the waitlist.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address to add to the waitlist." } } }, "WaitlistSignupResponse": { "type": "object", "description": "Response after successfully joining the waitlist.", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Confirmation message." } } }, "WarningThresholds": { "type": "object", "description": "Warning threshold flags for resources approaching their limits.", "required": [ "members", "organizations", "storage" ], "properties": { "members": { "type": "boolean", "description": "Members at or above 80% of limit." }, "organizations": { "type": "boolean", "description": "Organizations at or above 80% of limit." }, "storage": { "type": "boolean", "description": "Storage at or above 80% of limit." } } }, "WebSearchPolicy": { "type": "string", "description": "Web-search tool availability for the tenant.\n\nLayered governance: company admins set this; per-conversation\ntoggles in the chat composer can opt out within an `AllUsers`\ntenant, but cannot opt in past `Disabled` / `AdminOnly`.\n\nDefault is `Disabled` — agents cannot egress tenant prompts to a\nthird-party search provider unless an admin explicitly enables it.", "enum": [ "disabled", "adminOnly", "allUsers" ] }, "WebhookConfigResponse": { "type": "object", "description": "Response body for webhook configuration endpoints", "required": [ "webhookUrl", "secret", "events", "enabled", "updatedAt" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the webhook is enabled" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event glob patterns" }, "secret": { "type": "string", "description": "Masked secret (only last 4 chars visible)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the config was created or last updated" }, "webhookUrl": { "type": "string", "description": "HTTPS endpoint URL" } } }, "WebhookDeliveryStatus": { "type": "object", "description": "Aggregate delivery status for a tenant's webhook", "required": [ "enabled", "totalDispatched", "totalFailed", "dlqCount" ], "properties": { "dlqCount": { "type": "integer", "format": "int64", "description": "Number of entries in the DLQ", "minimum": 0 }, "enabled": { "type": "boolean", "description": "Whether the webhook is enabled" }, "lastFailureAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of last failed delivery" }, "lastStatusCode": { "type": [ "integer", "null" ], "format": "int32", "description": "HTTP status code of last delivery attempt", "minimum": 0 }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of last successful delivery" }, "totalDispatched": { "type": "integer", "format": "int64", "description": "Total number of events dispatched", "minimum": 0 }, "totalFailed": { "type": "integer", "format": "int64", "description": "Total number of failed deliveries", "minimum": 0 } } }, "WebhookDlqEntry": { "type": "object", "description": "A single entry in the webhook dead-letter queue", "required": [ "entryId", "payload", "eventCount", "createdAt", "expiresAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the entry was created" }, "entryId": { "type": "string", "description": "DLQ entry identifier." }, "eventCount": { "type": "integer", "format": "int64", "description": "Number of events in this DLQ batch", "minimum": 0 }, "expiresAt": { "type": "integer", "format": "int64", "description": "When the entry expires (TTL)" }, "payload": { "type": "string", "description": "Serialized event payload (JSON string)" } } }, "WebhookDlqListResponse": { "type": "object", "description": "Paginated DLQ listing response", "required": [ "entries", "totalCount" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDlqEntry" }, "description": "DLQ entries in this page" }, "nextToken": { "type": [ "string", "null" ], "description": "Pagination cursor for next page" }, "totalCount": { "type": "integer", "format": "int64", "description": "Total number of DLQ entries for this tenant", "minimum": 0 } } }, "WebhookDlqReplayResponse": { "type": "object", "description": "Response from replaying all DLQ entries", "required": [ "replayed", "failed", "remaining" ], "properties": { "failed": { "type": "integer", "format": "int64", "description": "Number of entries that failed to replay", "minimum": 0 }, "remaining": { "type": "integer", "format": "int64", "description": "Number of entries remaining in the DLQ", "minimum": 0 }, "replayed": { "type": "integer", "format": "int64", "description": "Number of entries successfully replayed", "minimum": 0 } } }, "WebhookTestResponse": { "type": "object", "description": "Response from testing a webhook endpoint", "required": [ "success", "latencyMs" ], "properties": { "error": { "type": [ "string", "null" ], "description": "Error message if delivery failed" }, "latencyMs": { "type": "integer", "format": "int64", "description": "Round-trip latency in milliseconds", "minimum": 0 }, "statusCode": { "type": [ "integer", "null" ], "format": "int32", "description": "HTTP status code returned by the endpoint", "minimum": 0 }, "success": { "type": "boolean", "description": "Whether the test delivery succeeded" } } }, "WithdrawSuggestionResponse": { "type": "object", "description": "Response from withdrawing a suggestion.", "required": [ "suggestionId", "status" ], "properties": { "status": { "$ref": "#/components/schemas/SuggestionStatus" }, "suggestionId": { "type": "string" } } }, "WizardKey": { "type": "string", "description": "A named onboarding wizard.\n\nClosed enum — adding a new wizard requires extending this enum, declaring\na sibling step enum below, and shipping the corresponding frontend wizard\nin the same change.", "enum": [ "first-time-user" ] }, "WorkspaceActionState": { "type": "string", "description": "Availability state for a single workspace lifecycle action.", "enum": [ "available", "blockedEnterpriseManaged", "blockedNotOwner", "blockedOwnerMustTransfer", "blockedNotMember", "blockedNoActiveRecipient", "blockedPendingOperation", "blockedStaleSummary" ] }, "WorkspaceActorRole": { "type": "string", "description": "Actor membership shape for a workspace.", "enum": [ "owner", "admin", "member", "viewer", "notMember" ] }, "WorkspaceCleanupStats": { "type": "object", "description": "Cleanup totals for a workspace-delete operation.", "required": [ "documentsDeleted", "membershipsRemoved", "grantsRemoved", "commentsDeleted" ], "properties": { "commentsDeleted": { "type": "integer", "format": "int32", "description": "Comments deleted.", "minimum": 0 }, "documentsDeleted": { "type": "integer", "format": "int32", "description": "Documents deleted from the workspace.", "minimum": 0 }, "grantsRemoved": { "type": "integer", "format": "int32", "description": "Access grants removed.", "minimum": 0 }, "membershipsRemoved": { "type": "integer", "format": "int32", "description": "Memberships removed.", "minimum": 0 } } }, "WorkspaceLeaveCleanupStats": { "type": "object", "description": "Cleanup totals returned from a successful leave.", "required": [ "privateDocumentsDeleted", "sharedDocumentsRetained", "abandonedDocumentsDeleted", "membershipsRemoved" ], "properties": { "abandonedDocumentsDeleted": { "type": "integer", "format": "int32", "description": "Documents deleted because no active user remained.", "minimum": 0 }, "membershipsRemoved": { "type": "integer", "format": "int32", "description": "Memberships removed (always 1 for leave, but uniform with the\nother lifecycle stats envelopes).", "minimum": 0 }, "privateDocumentsDeleted": { "type": "integer", "format": "int32", "description": "Documents private to the leaving member that were deleted.", "minimum": 0 }, "sharedDocumentsRetained": { "type": "integer", "format": "int32", "description": "Documents retained for remaining active users.", "minimum": 0 } } }, "WorkspaceLifecycleAction": { "type": "string", "description": "Discriminator naming a specific destructive workspace action — used\ninside error envelopes when the API needs to identify which action\nwas rejected.", "enum": [ "deleteWorkspace", "transferOwnership", "leaveWorkspace" ] }, "WorkspaceLifecycleActions": { "type": "object", "description": "Per-action availability bundle returned in\n[`WorkspaceLifecycleSummaryResponse`].", "required": [ "deleteWorkspace", "transferOwnership", "leaveWorkspace" ], "properties": { "deleteWorkspace": { "$ref": "#/components/schemas/WorkspaceActionState", "description": "Whether delete is available, and if not, why." }, "leaveWorkspace": { "$ref": "#/components/schemas/WorkspaceActionState", "description": "Whether the leave action is available, and if not, why." }, "transferOwnership": { "$ref": "#/components/schemas/WorkspaceActionState", "description": "Whether ownership transfer is available, and if not, why." } } }, "WorkspaceLifecyclePolicy": { "type": "string", "description": "Lifecycle policy assigned to a workspace by its billing plan and\norg-level configuration.", "enum": [ "selfServiceFreePro", "enterpriseManaged" ] }, "WorkspaceLifecycleSummaryResponse": { "type": "object", "description": "Computed action availability for a single workspace as seen by the\ncurrent actor. Drives both the UI control visibility and the\n`summaryVersion` that mutating requests must echo back.", "required": [ "workspaceId", "workspaceName", "plan", "lifecyclePolicy", "actorRole", "summaryVersion", "activeMemberCount", "actions", "cleanupPreview" ], "properties": { "actions": { "$ref": "#/components/schemas/WorkspaceLifecycleActions", "description": "Per-action availability for delete, transfer, and leave." }, "activeMemberCount": { "type": "integer", "format": "int32", "description": "Total active members at evaluation time.", "minimum": 0 }, "actorRole": { "$ref": "#/components/schemas/WorkspaceActorRole", "description": "The actor's role in this workspace." }, "cleanupPreview": { "$ref": "#/components/schemas/DocumentCleanupCounts", "description": "Document cleanup preview for the leave flow." }, "lifecyclePolicy": { "$ref": "#/components/schemas/WorkspaceLifecyclePolicy", "description": "High-level policy classification — Enterprise workspaces fail\nclosed for every mutating action." }, "plan": { "$ref": "#/components/schemas/BillingPlan", "description": "Billing plan that determines whether self-service applies." }, "summaryVersion": { "type": "string", "description": "Server-computed digest of the eligibility inputs; required on the\nmutating endpoints." }, "transferRecipients": { "type": "array", "items": { "$ref": "#/components/schemas/TransferRecipient" }, "description": "Active candidates the current owner can transfer to. Omitted when\ntransfer is unavailable." }, "workspaceId": { "$ref": "#/components/schemas/TypedId", "description": "Workspace identifier (root tier node / company identifier)." }, "workspaceName": { "type": "string", "description": "Display name of the workspace at evaluation time." } } }, "WorkspaceOwnerState": { "type": "string", "description": "The actor's owner-state relative to a workspace entry.", "enum": [ "owner", "nonOwner", "soloOwner" ] }, "WorkspaceResolution": { "type": "string", "description": "What the actor must do for a workspace before account deletion completes.", "enum": [ "noActionRequired", "leaveOnAccountDeletion", "deleteOrTransferRequired", "deleteOnlyRequired", "enterpriseManaged" ] }, "WorkspaceSsoConfigResponse": { "type": "object", "description": "Public SSO config lookup response for workspace-slug resolution.\n\nUsed by the SPA at `app.{base}/w/{slug}/...` to decide whether to render\nthe password sign-in form or redirect the visitor to the workspace's\nconfigured identity provider before any session exists. The endpoint is\nunauthenticated by design — the slug is already in the URL the visitor\nis on and the response carries only what the redirect flow needs.\n\n`sso_enabled` is `false` for any workspace whose plan does not unlock\nSSO (Free, Pro) and for Enterprise workspaces with no active connection;\nin both cases `cognito_provider_name` is `None` and the SPA falls back\nto password sign-in. When `sso_enabled` is `true` the SPA passes\n`cognito_provider_name` to the existing `signInWithRedirect` flow.", "required": [ "slug", "ssoEnabled" ], "properties": { "cognitoProviderName": { "type": [ "string", "null" ], "description": "`Cognito` identity provider name to pass to the redirect flow when\n`sso_enabled` is `true`. `None` when SSO is not available for this\nworkspace; the SPA renders the password sign-in form in that case." }, "slug": { "type": "string", "description": "The workspace slug echoed back from the request path." }, "ssoEnabled": { "type": "boolean", "description": "`true` when the workspace has an active SSO connection a visitor\ncan sign in with. `false` for any other case (no connection, plan\ndoes not include SSO, slug not found is a 404 not a `false`)." } } }, "YjsRelativePosition": { "type": "string", "description": "Base64-encoded Yjs relative position.\n\nWraps the output of `Y.encodeRelativePosition()` → bytes → base64.\nYjs relative positions survive concurrent edits — they reference\na specific item in the CRDT history, not an absolute offset.\n\nThe inner `String` is opaque at this layer; decoding from base64 into\nthe wire bytes is the server's responsibility." }, "YjsStateEncoding": { "type": "string", "description": "Wire encoding for the `JoinedDocument.yjsState` payload.", "enum": [ "base64", "base64+gzip" ] } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "cookie_csrf": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Double-submit CSRF token. Mirror the JS-readable CSRF nonce cookie value into this header on every unsafe-method (POST/PUT/PATCH/DELETE) request authenticated via browser session cookies." } } }, "tags": [ { "name": "health", "description": "Health check endpoints" }, { "name": "documents", "description": "Document CRUD operations" }, { "name": "history", "description": "Document edit history" }, { "name": "comments", "description": "Document comment operations" }, { "name": "access", "description": "Document access and sharing" }, { "name": "folders", "description": "Folder management" }, { "name": "profile", "description": "User profile management" }, { "name": "search", "description": "Full-text document search" }, { "name": "oauth", "description": "OAuth client management" }, { "name": "public", "description": "Public document access" }, { "name": "tenant", "description": "Tenant resolution" }, { "name": "organizations", "description": "Organization management" }, { "name": "members", "description": "Organization membership management" }, { "name": "auth", "description": "Authentication and tenant switching" }, { "name": "Folder Access", "description": "Folder-level sharing" }, { "name": "Sharing Policy", "description": "Organization sharing policy management" }, { "name": "Guest Access", "description": "Guest access management" }, { "name": "Agent Policy", "description": "AI agent policy management" }, { "name": "Spaces", "description": "Space management, document membership, source filters, and access grants" }, { "name": "Repo Connections", "description": "GitHub App connection management" }, { "name": "Repo Sources", "description": "Repository source configuration and sync management" }, { "name": "Agents", "description": "Platform agent management and invocation" }, { "name": "Companies", "description": "Company management, membership, and settings" }, { "name": "Audit Logs", "description": "Audit event querying and export" }, { "name": "SIEM Webhook", "description": "Real-time SIEM webhook configuration and delivery management" }, { "name": "S3 Export", "description": "Scheduled S3 audit export configuration" }, { "name": "Retention Policy", "description": "Organization data retention policy management" }, { "name": "Legal Holds", "description": "Compliance legal hold placement and release" }, { "name": "Domain Verification", "description": "Company domain verification" }, { "name": "SSO", "description": "SSO connection and enforcement configuration" }, { "name": "SCIM Tokens", "description": "SCIM bearer token management" }, { "name": "IdP Mappings", "description": "IdP group-to-Organization mappings" }, { "name": "Company Sharing Policy", "description": "Company-level sharing policy ceiling" }, { "name": "Notifications", "description": "In-app notification management" }, { "name": "Billing", "description": "Billing plans, invoices, and usage" }, { "name": "Suggestions", "description": "AI suggestion review and resolution" }, { "name": "Discovery", "description": "Document similarity and discovery" }, { "name": "Document Connections", "description": "Directional connections between documents" }, { "name": "Connectors", "description": "Stargate connector connection lifecycle" }, { "name": "Connector Sources", "description": "Space-scoped connector source management" }, { "name": "Connector Grants", "description": "User-delegated OAuth grant management" }, { "name": "Pinned Resources", "description": "External resource pinning and management" }, { "name": "Attachments", "description": "Transient resource references on documents and chat messages" }, { "name": "telemetry", "description": "Anonymous client-side telemetry (e.g., PDF gate-redirect counter)" }, { "name": "feature-flags", "description": "Runtime feature flags evaluated for the requesting user" }, { "name": "marketing", "description": "Public marketing-site visit ingest and geo lookup" } ] }