{ "openapi": "3.1.0", "info": { "title": "Timbal Platform API", "description": "Public API documentation for the Timbal platform", "license": { "name": "" }, "version": "2.0.0" }, "servers": [ { "url": "https://api.timbal.ai", "description": "Production" }, { "url": "https://api.dev.timbal.ai", "description": "Development" } ], "paths": { "/ace/{ace_uid}/jobs": { "get": { "tags": [ "ace" ], "description": "List jobs for an ACE, most recent first.", "operationId": "list", "parameters": [ { "name": "ace_uid", "in": "path", "description": "ACE uid (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max rows to return (clamped to 200). Defaults to 50.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAceJobsResBody" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "ACE not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/jobs/{job_uid}": { "get": { "tags": [ "ace" ], "description": "Fetch a single job. Poll this until `status` reaches a terminal value (`succeeded`, `failed`, `cancelled`, `error`).", "operationId": "get_one", "parameters": [ { "name": "ace_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "job_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AceJobView" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Job or ACE not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/jobs/{job_uid}/cancel": { "post": { "tags": [ "ace" ], "description": "Cancel an active job. The job transitions to `status = 'cancelled'` once the cancellation takes effect. Returns `204` on accept; `409` if the job is not currently active.", "operationId": "cancel", "parameters": [ { "name": "ace_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "job_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Cancel signal sent" }, "403": { "description": "Forbidden" }, "404": { "description": "Job not found" }, "409": { "description": "Job is not currently queued/running" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/jobs/{job_uid}/retry": { "post": { "tags": [ "ace" ], "description": "Re-enqueue a failed/cancelled/errored job with the same kind and input, returning a new `job_uid`. Returns `409` if the source job is still active or already succeeded, or if another job is active on this ACE.", "operationId": "retry", "parameters": [ { "name": "ace_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "job_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Retry enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueJobResBody" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Job not found" }, "409": { "description": "Source job not retriable, or ACE has a live job" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/policies": { "get": { "tags": [ "ace" ], "description": "List the policies declared on an ACE.", "operationId": "list", "parameters": [ { "name": "ace_uid", "in": "path", "description": "ACE uid (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPoliciesResBody" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "ACE not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/v1/chat/completions": { "post": { "tags": [ "ace" ], "description": "OpenAI-compatible **Chat Completions** endpoint scoped to an ACE. Accepts the native OpenAI `/v1/chat/completions` request body; set `stream: true` for an SSE response. The upstream provider is resolved from the `model` field: either explicit (`anthropic/claude-opus-4-7`, `google/gemini-2.5-pro`, …) or best-effort from the model name prefix (`gpt-*`, `claude-*`, `gemini-*`, `grok-*`); otherwise falls back to OpenAI. Supported providers: `openai`, `google`, `togetherai`, `xai`, `groq`, `fireworks`, `xiaomi`, `byteplus`. Request body remains OpenAI-shaped regardless of provider. Authenticate with a Timbal API key via `Authorization: Bearer \u003Ckey\u003E`. Usage is billed to the organization that owns the ACE.", "operationId": "handler", "parameters": [ { "name": "ace_uid", "in": "path", "description": "ACE uid (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upstream response (JSON or SSE depending on `stream`)" }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid credentials" }, "402": { "description": "Credits limit exceeded" }, "404": { "description": "ACE not found" }, "500": { "description": "Upstream provider error" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/v1/messages": { "post": { "tags": [ "ace" ], "description": "Anthropic-compatible **Messages** endpoint scoped to an ACE. Accepts the native Anthropic `/v1/messages` request body; set `stream: true` for an SSE response. The `model` field accepts either a bare model name (`claude-opus-4-7`) or an explicit `anthropic/\u003Cmodel\u003E` prefix; any other provider prefix is rejected with `400`. Authenticate with a Timbal API key passed in the `x-api-key` header (same header the Anthropic SDK sends). Optional `anthropic-version` and `anthropic-beta` headers are forwarded upstream. Usage is billed to the organization that owns the ACE.", "operationId": "handler", "parameters": [ { "name": "ace_uid", "in": "path", "description": "ACE uid (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upstream response (JSON or SSE depending on `stream`)" }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid credentials" }, "402": { "description": "Credits limit exceeded" }, "404": { "description": "ACE not found" }, "500": { "description": "Upstream provider error" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/v1/responses": { "post": { "tags": [ "ace" ], "description": "OpenAI-compatible **Responses API** endpoint scoped to an ACE. Accepts the native OpenAI `/v1/responses` request body; streaming responses are delivered as SSE. The upstream provider is resolved from the `model` field: either explicit (`google/gemini-2.5-pro`, `xai/grok-3`, …) or best-effort from the model name prefix (`gpt-*`, `gemini-*`, `grok-*`); otherwise falls back to OpenAI. Supported providers: `openai`, `google`, `togetherai`, `xai`, `groq`, `fireworks`. Request body remains OpenAI-shaped regardless of provider. Authenticate with a Timbal API key via `Authorization: Bearer \u003Ckey\u003E`. Usage is billed to the organization that owns the ACE.", "operationId": "handler", "parameters": [ { "name": "ace_uid", "in": "path", "description": "ACE uid (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upstream response (JSON or SSE depending on `stream`)" }, "400": { "description": "Bad request" }, "401": { "description": "Missing or invalid credentials" }, "402": { "description": "Credits limit exceeded" }, "404": { "description": "ACE not found" }, "500": { "description": "Upstream provider error" } }, "security": [ { "bearer_auth": [] } ] } }, "/ace/{ace_uid}/vars": { "get": { "tags": [ "ace" ], "description": "List the variables declared on an ACE.", "operationId": "list", "parameters": [ { "name": "ace_uid", "in": "path", "description": "ACE uid (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Variables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVarsResBody" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "ACE not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/files": { "post": { "tags": [ "files" ], "description": "Upload a short-lived file (auto-deleted ~24h after upload).", "operationId": "handler", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Binary contents of the file. Max 100 MB.", "contentMediaType": "application/octet-stream" } } } } }, "required": true }, "responses": { "200": { "description": "File uploaded", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Max requests per window for this user." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the current window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias of `RateLimit-Limit`." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias of `RateLimit-Remaining`." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias of `RateLimit-Reset`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TempFile" } } } }, "413": { "description": "File exceeds 100MB limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "Per-user rate limit exceeded", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Max requests per window for this user." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds the client should wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias of `RateLimit-Limit`." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias of `RateLimit-Remaining`." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias of `RateLimit-Reset`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/me/orgs": { "get": { "tags": [ "orgs" ], "description": "List organizations the authenticated user belongs to", "operationId": "handler", "parameters": [ { "name": "q", "in": "query", "description": "Optional search query to filter orgs by name", "required": false, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Page token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organizations listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgsResult" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}": { "get": { "tags": [ "orgs" ], "description": "Get an organization by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "orgs" ], "description": "Partially update an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOrgReqBody" } } }, "required": true }, "responses": { "204": { "description": "Organization updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/billing/overage": { "post": { "tags": [ "billing" ], "description": "Enable or disable usage-based overage billing and set an optional credit cap for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingOverageReqBody" } } }, "required": true }, "responses": { "204": { "description": "Overage settings updated", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Cannot apply overage (plan, payments, or subscription state)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/contacts": { "get": { "tags": [ "orgs" ], "description": "Account-side contacts assigned to an organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contacts for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgContactsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/domains": { "get": { "tags": [ "orgs" ], "description": "List connected domains for an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domains listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Add a custom domain to an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainReqBody" } } }, "required": true }, "responses": { "204": { "description": "Domain created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/domains/{domain_id}": { "get": { "tags": [ "orgs" ], "description": "Get a domain by ID. This endpoint triggers DNS validation and returns the live certificate status.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "orgs" ], "description": "Delete a domain", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Domain deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/embedding-models": { "get": { "tags": [ "embeddings" ], "description": "List all available embedding models for the organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Array of embedding models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmbeddingModelsResBody" }, "example": { "embedding_models": [ "text-embedding-ada-002", "text-embedding-3-small", "text-embedding-3-large" ] } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2": { "get": { "tags": [ "k2" ], "description": "List knowledge bases in an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Knowledge bases listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListK2Response" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Create a new knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2Request" } } }, "required": true }, "responses": { "201": { "description": "Knowledge base created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2Response" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}": { "get": { "tags": [ "k2" ], "description": "Get knowledge base details", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge base details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Detail" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "k2" ], "description": "Delete a knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Knowledge base deleted" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "k2" ], "description": "Update a knowledge base.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditK2Request" } } }, "required": true }, "responses": { "200": { "description": "Updated knowledge base", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Detail" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/backups": { "get": { "tags": [ "k2" ], "description": "List backups for a knowledge base.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Backup list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBackupsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Create an on-demand backup of a knowledge base. While running, all read/write traffic on the KB returns 503 (Maintenance). A mutually-exclusive lock prevents concurrent backup/restore on the same KB (409 Conflict). `dry_run = true` skips the lock and the upload.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBackupRequest" } } }, "required": true }, "responses": { "201": { "description": "Backup accepted; KB is already paused for maintenance (non-dry-run). Poll via GET /backups/{id}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbBackupResponse" } } } }, "409": { "description": "KB is already under maintenance (no backup row created)" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/backups/{backup_id}": { "get": { "tags": [ "k2" ], "description": "Get a single backup.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Backup details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbBackupResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/directories": { "post": { "tags": [ "k2" ], "description": "Create a virtual directory in the knowledge base", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2VirtualDirectoryRequest" } } }, "required": true }, "responses": { "200": { "description": "Folder already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2VirtualDirectoryResponse" } } } }, "201": { "description": "Folder created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2VirtualDirectoryResponse" } } } }, "409": { "description": "A file with the same name already exists at this path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/files": { "get": { "tags": [ "k2" ], "description": "List files and directories in a knowledge base", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "directory", "in": "query", "description": "Filter files by directory path (e.g. \"docs/reports\")", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Files listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListK2FilesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Upload a file to a knowledge base for parsing and embedding", "operationId": "add", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Request body for uploading a file to a knowledge base.", "required": [ "file", "metadata" ], "properties": { "directory": { "type": [ "string", "null" ], "description": "Optional subdirectory path to organize the file within the knowledge base." }, "file": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "The file to upload.", "contentMediaType": "application/octet-stream" }, "metadata": { "type": "object", "description": "Optional JSON metadata to attach to the file." } } } } }, "required": true }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2File" } } } }, "409": { "description": "A file with the same name already exists in this directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/files/{file_id}": { "get": { "tags": [ "k2" ], "description": "Get a file with its parsings and embeddings metadata", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File details with parsings and embeddings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetK2FileResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "k2" ], "description": "Delete a file from a knowledge base", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "File deleted" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/files/{file_id}/chunks": { "get": { "tags": [ "k2" ], "description": "List chunks for a knowledge base file, in document order. Layout metadata (`blocks`) is omitted from each item to keep responses small; fetch a single chunk by `uid` to retrieve it.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Cursor: pass `next_page_token` from the previous response to fetch\nthe next page. Treat the value as opaque.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Page size. Defaults to 100; max 500.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Chunks listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListK2ChunksResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Insert a new chunk. Place via `after_uid` / `before_uid` (mutually exclusive) or omit both to append.", "operationId": "insert", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertK2ChunkRequest" } } }, "required": true }, "responses": { "201": { "description": "Chunk inserted. Search results reflect the change after re-indexing completes (`index_status` field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Chunk" } } } }, "400": { "description": "Invalid placement or payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "No insertion slot available between the specified neighbors. Retry with a different placement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/files/{file_id}/chunks/{chunk_uid}": { "get": { "tags": [ "k2" ], "description": "Get a single chunk by uid.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chunk_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Chunk", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Chunk" } } } }, "404": { "description": "Chunk not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "k2" ], "description": "Delete a chunk. Requires `If-Match: \u003Crevision\u003E` from the prior GET. The chunk disappears from listings immediately and stops affecting search after the next re-index pass.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chunk_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Chunk deleted" }, "404": { "description": "Chunk not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "`If-Match` revision does not match the current chunk", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "k2" ], "description": "Edit a chunk's content / embed / page range. Requires `If-Match: \u003Crevision\u003E` from the prior GET.", "operationId": "patch", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chunk_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchK2ChunkRequest" } } }, "required": true }, "responses": { "200": { "description": "Chunk updated. Search results reflect the change after re-indexing completes (`index_status` field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Chunk" } } } }, "400": { "description": "Empty patch or empty content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Chunk not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "`If-Match` revision does not match the current chunk", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/query": { "post": { "tags": [ "k2" ], "description": "Execute a SQL query against the knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryK2Request" } } }, "required": true }, "responses": { "200": { "description": "Query results as JSON", "content": { "application/json": { } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/restart": { "post": { "tags": [ "k2" ], "description": "Drop the knowledge base's in-memory connections so the next request opens a fresh database handle. Caller must be an org admin.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connections dropped", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Caller is not an admin of this knowledge base", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/restores": { "get": { "tags": [ "k2" ], "description": "List restore attempts for a knowledge base.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Restore list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRestoresResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Restore a knowledge base from a previously completed backup. While running, all read/write traffic on the KB returns 503 (Maintenance). A mutually-exclusive lock prevents concurrent backup/restore on the same KB (409 Conflict).", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRestoreRequest" } } }, "required": true }, "responses": { "201": { "description": "Restore accepted; KB is already paused for maintenance. Poll via GET /restores/{id}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbRestoreResponse" } } } }, "409": { "description": "KB is already under maintenance (no restore row created)" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/restores/{restore_id}": { "get": { "tags": [ "k2" ], "description": "Get a single restore.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "restore_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restore details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbRestoreResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/schema": { "get": { "tags": [ "k2" ], "description": "Get the schema for a knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format: \"structured\" (default) or \"sql\"", "required": false, "schema": { "type": "string", "enum": [ "structured", "sql" ] } } ], "responses": { "200": { "description": "Schema (structured by default, or SQL DDL statements when ?format=sql)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/K2Schema", "description": "Structured schema with tables, columns, indexes, and constraints (default)" }, { "$ref": "#/components/schemas/K2SchemaSql", "description": "SQL DDL statements (CREATE TABLE, CREATE INDEX, etc.)" } ], "description": "Response for the schema endpoint — structured (default) or SQL DDL." } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/upload": { "post": { "tags": [ "k2" ], "description": "Upload a data file (CSV, Parquet, JSON) into the knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "File upload with optional table_name and mode fields", "content": { "multipart/form-data": { } } }, "responses": { "200": { "description": "Upload result", "content": { "application/json": { } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/channels": { "get": { "tags": [ "notifications" ], "summary": "List notification channels for the org", "description": "Returns all `NotificationChannels` rows for this organization (email and future types). Any org member may call.", "operationId": "list_org_notification_channels", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channels for the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgNotificationChannelsResBody" } } } }, "403": { "description": "Caller is not a member of this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "notifications" ], "summary": "Create a notification channel", "description": "Create or reuse a notification channel for this org.", "operationId": "create_org_notification_channel", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationChannelReq" }, "examples": { "Email": { "value": { "type": "email", "name": "Finance inbox", "config": { "to": "finance@example.com" } } }, "Slack": { "value": { "type": "slack", "name": "Deploy alerts", "config": { "token": "xoxb-1234567890123-1234567890123", "channel": "C0123456789" } } } } } }, "required": true }, "responses": { "201": { "description": "Channel id and whether it was created or reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationChannelOut" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/channels/{channel_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete a notification channel.", "description": "Removes the channel for this org. Fails with 409 if rules reference it unless `force: true`.", "operationId": "delete_org_notification_channel", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional — omit entirely or send `{}` for default (non-force) behavior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteChannelBody" } } }, "required": true }, "responses": { "204": { "description": "Channel deleted" }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Channel not found for this org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Channel is referenced by rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/rules": { "get": { "tags": [ "notifications" ], "summary": "List org-wide notification rules", "description": "List org-wide notification rules with their linked channels.", "operationId": "list_org_notification_rules", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of rules with channels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgNotificationRulesResBody" } } } }, "403": { "description": "Caller is not a member of this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "notifications" ], "summary": "Create an org-wide notification rule", "description": "Create an org-wide notification rule.", "operationId": "create_org_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleReq" }, "examples": { "Email channel": { "value": { "name": "Credits usage alert", "event_type": "org.credits.usage", "cooldown_seconds": 3600, "condition": { "threshold_pct": 80 }, "channel": { "type": "email", "config": { "to": "finance@example.com" } } } }, "Slack channel": { "value": { "name": "Credits usage to Slack", "event_type": "org.credits.usage", "channel": { "type": "slack", "config": { "token": "xoxb-1234567890123-1234567890123", "channel": "C0123456789" } } } } } } }, "required": true }, "responses": { "201": { "description": "Rule and channel link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleOut" } } } }, "400": { "description": "Validation error (event type, channel config, empty name, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/rules/{rule_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete an org-wide notification rule", "description": "Deletes a rule with `project_id` unset only. **Org admin** only.", "operationId": "delete_org_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Rule deleted" }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Rule not found or not org-scoped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/previews": { "get": { "tags": [ "preview" ], "description": "List project previews for the organization", "operationId": "list_previews", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "preview_status", "in": "query", "description": "Return only previews in this lifecycle state. Omit to include every active preview (`starting` or `running`).", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PreviewStatus" } ] } } ], "responses": { "200": { "description": "Previews listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPreviewsResponse" } } } }, "403": { "description": "Caller is not a member of the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects": { "get": { "tags": [ "projects" ], "description": "List projects for an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "Response detail level: \"list\" (default) returns a lightweight preview, \"full\" returns all project details", "required": false, "schema": { "type": "string", "enum": [ "list", "full" ] } } ], "responses": { "200": { "description": "Projects listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectReqBody" } } }, "required": true }, "responses": { "200": { "description": "Project created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}": { "get": { "tags": [ "projects" ], "description": "Get a project by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDetail" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Project deleted successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditProjectReqBody" } } }, "required": true }, "responses": { "204": { "description": "Project updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/analytics/credits": { "get": { "tags": [ "analytics" ], "description": "Time-binned credits and USD cost breakdown for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "Bucket size for aggregation (`minute`, `hour`, or `day`).", "required": false, "schema": { "$ref": "#/components/schemas/BinSize" } }, { "name": "from", "in": "query", "description": "Inclusive range start (epoch milliseconds). Defaults: 1h / 1d / 30d before `to` by `group_by`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Exclusive range end (epoch milliseconds). Defaults to now.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "user_id", "in": "query", "description": "Restrict to a specific user’s runs.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Credits analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAnalyticsCreditsBody" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "500": { "description": "Error" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/analytics/usage": { "get": { "tags": [ "analytics" ], "description": "Time-binned run counts, user counts, and duration percentiles for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "Bucket size for aggregation (`minute`, `hour`, or `day`).", "required": false, "schema": { "$ref": "#/components/schemas/BinSize" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Usage analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAnalyticsUsageBody" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "500": { "description": "Error" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/analytics/users": { "get": { "tags": [ "analytics" ], "description": "Per-user run and spend aggregates for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Inclusive range start (epoch milliseconds).", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "description": "Exclusive range end (epoch milliseconds).", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Opaque offset for the next page (from the previous response’s `next_page_token`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "User analytics page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAnalyticsUsersBody" } } } }, "403": { "description": "Forbidden" }, "500": { "description": "Error" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose": { "post": { "tags": [ "compose" ], "description": "Send a prompt to the Timbal Composer agent. The `prompt` field accepts a plain string, an array of content blocks, or a full Message object. Content blocks can be text or files (base64, URL, or server-side path). Supported file types: images (png/jpg/gif/webp/svg), PDFs, and text-readable formats (json, csv, md, yaml, py, rs, etc.).", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeRequest" }, "examples": { "File from URL": { "value": { "rev": "main", "prompt": [ "Review this config file", { "type": "file", "file": { "name": "config.json", "source": { "type": "url", "url": "https://example.com/config.json" } } } ] } }, "File from server path": { "value": { "rev": "main", "prompt": [ "Analyze this log file", { "type": "file", "file": { "name": "app.log", "source": { "type": "path", "path": "/mnt/efs/uploads/app.log" } } } ] } }, "File without name (media_type required)": { "value": { "rev": "main", "prompt": [ "What is in this image?", { "type": "file", "file": { "media_type": "image/png", "source": { "type": "base64", "data": "iVBORw0KGgo..." } } } ] } }, "Full Message object": { "value": { "rev": "main", "prompt": { "role": "user", "content": [ { "type": "text", "text": "Refactor this to use async/await" } ] } } }, "Plain string": { "value": { "rev": "main", "prompt": "Add error handling to the upload endpoint" } }, "Plan mode (read-only, produces a plan)": { "value": { "rev": "main", "prompt": "How would you refactor the upload endpoint for better error handling?", "mode": "plan" } }, "Text with inline image (base64)": { "value": { "rev": "main", "prompt": [ "Describe what you see in this screenshot and fix the layout", { "type": "file", "file": { "name": "screenshot.png", "source": { "type": "base64", "data": "iVBORw0KGgo..." } } } ] } } } } }, "required": true }, "responses": { "200": { "description": "SSE stream of Claude responses", "content": { "text/event-stream": { } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/plans": { "get": { "tags": [ "compose" ], "description": "List plan files produced by compose plan-mode sessions, most recently modified first", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plans listed successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectPlan" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/plans/{plan_id}": { "get": { "tags": [ "compose" ], "description": "Get a plan's metadata and full markdown body", "operationId": "single", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plan_id", "in": "path", "description": "Plan id — the markdown filename without the `.md` extension.", "required": true, "schema": { "type": "string" }, "example": "create-a-new-section-logical-hennessy" } ], "responses": { "200": { "description": "Plan details with content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanDetail" } } } }, "404": { "description": "Plan not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/sessions": { "get": { "tags": [ "compose" ], "description": "List sessions for a project, most recent first", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Filter sessions by user ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "rev", "in": "query", "description": "Filter sessions by git branch (worktree revision)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Sessions listed successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSession" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/sessions/{session_id}": { "get": { "tags": [ "compose" ], "description": "Get session details including token usage, cost, and message history", "operationId": "single", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session UUID (e.g. \"019d1bbe-2f61-7393-afa7-6bb770878c9b\")", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019d1bbe-2f61-7393-afa7-6bb770878c9b" } ], "responses": { "200": { "description": "Session details with messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetail" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/sessions/{session_id}/stop": { "post": { "tags": [ "compose" ], "description": "Stop a running compose session by sending SIGTERM to the Claude process", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session UUID (e.g. \"019d1bbe-2f61-7393-afa7-6bb770878c9b\")", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019d1bbe-2f61-7393-afa7-6bb770878c9b" } ], "responses": { "204": { "description": "Session stopped" }, "404": { "description": "No active process for this session" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/connections": { "get": { "tags": [ "projects" ], "description": "List connections for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connections listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectionsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Connect a resource (KB or integration) to a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectToProject" } } }, "required": true }, "responses": { "201": { "description": "Connection created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/connections/{connection_id}": { "delete": { "tags": [ "projects" ], "description": "Delete a project connection", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connection deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/deployments": { "get": { "tags": [ "projects" ], "description": "List deployments for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_env_id", "in": "query", "description": "DEPRECATED: use `rev` (git branch name) instead. Will be removed once all\nfrontends migrate. When both are passed, `rev` wins.", "required": false, "deprecated": true, "schema": { "type": [ "string", "null" ] } }, { "name": "rev", "in": "query", "description": "Git branch name of the env to filter by (e.g. `main`). Resolved\nserver-side against `ProjectEnvs.branch` for the current project.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "manifest_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "trigger", "in": "query", "description": "Optional trigger filter. Accepts:\n * `latest` — return every row sharing the most recent `trigger_id` for\n the resolved env; if the most recent row has no `trigger_id` (legacy\n data), falls back to `DISTINCT ON (image_type, manifest_id)` i.e.\n the latest row per component.\n * a UUID — return every row with `trigger_id = \u003Cuuid\u003E`.\nRequires an env filter (`rev` or `project_env_id`). No-op otherwise.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Deployments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeploymentsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/deployments/{deployment_id}": { "get": { "tags": [ "projects" ], "description": "Get a deployment by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deployment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs": { "get": { "tags": [ "projects" ], "description": "List environments for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Environments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvReqBody" } } }, "required": true }, "responses": { "201": { "description": "Environment created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}": { "delete": { "tags": [ "projects" ], "description": "Delete an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Environment deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/branch": { "patch": { "tags": [ "projects" ], "description": "Set or clear the branch for an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnvBranchReqBody" } } }, "required": true }, "responses": { "200": { "description": "Branch updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/config": { "patch": { "tags": [ "projects" ], "description": "Update environment configuration (CPU, memory, etc.)", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvConfigReqBody" } } }, "required": true }, "responses": { "200": { "description": "Configuration updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/deploy": { "post": { "tags": [ "projects" ], "description": "Deploy an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployEnvReqBody" } } }, "required": true }, "responses": { "202": { "description": "Deployment initiated" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/domain": { "patch": { "tags": [ "projects" ], "description": "Associate or disassociate a custom domain with an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnvDomainReqBody" } } }, "required": true }, "responses": { "200": { "description": "Domain updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/metrics/{metric_type}": { "get": { "tags": [ "projects" ], "description": "Query environment metrics", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metric_type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MetricType" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Metrics data" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/stop": { "post": { "tags": [ "projects" ], "description": "Stop an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Stop initiated" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/k2": { "put": { "tags": [ "projects" ], "description": "Link a K2 knowledge base to a project. Replaces any previously linked KB.", "operationId": "put", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkKbRequest" } } }, "required": true }, "responses": { "200": { "description": "Knowledge base linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbPreview" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Knowledge base not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Unlink the K2 knowledge base from a project.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Knowledge base unlinked" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/notifications/rules": { "get": { "tags": [ "notifications" ], "summary": "List project notification rules", "description": "Returns rules scoped to a single **project** (e.g. deployment lifecycle emails). Each rule includes linked channels. Any authenticated project member may call; **POST** on the same path requires **project admin**.", "operationId": "list_project_notification_rules", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of rules with channels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectNotificationRulesResBody" } } } }, "403": { "description": "Caller is not a member of this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "notifications" ], "summary": "Create a project-scoped notification rule", "description": "Create a project-scoped notification rule.", "operationId": "create_project_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleReq" }, "examples": { "Email channel": { "value": { "name": "Deployment failures", "event_type": "project.deployment.failed", "cooldown_seconds": 3600, "channel": { "type": "email", "config": { "to": "oncall@example.com" } } } }, "Slack channel": { "value": { "name": "Deployment failures to Slack", "event_type": "project.deployment.failed", "channel": { "type": "slack", "config": { "token": "xoxb-1234567890123-1234567890123", "channel": "C0123456789" } } } } } } }, "required": true }, "responses": { "201": { "description": "Rule and channel link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleOut" } } } }, "400": { "description": "Validation error (event type, channel config, empty name, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/notifications/rules/{rule_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete a project-scoped notification rule", "description": "Deletes a rule tied to this project. **Project admin** only.", "operationId": "delete_project_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Rule deleted" }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Rule not found for this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/preview": { "get": { "tags": [ "preview" ], "description": "Get preview status (starting or running) and health when running", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name of the preview to inspect (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewInfo" } } } }, "403": { "description": "Caller has no access to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No preview or start in progress for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "preview" ], "description": "Start dev preview servers (API/UI) for a branch worktree; returns starting immediately, then ready after health checks", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "Preview starting or already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewInfo" } } } }, "400": { "description": "Invalid branch or worktree not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "Org preview concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/preview/logs": { "get": { "tags": [ "preview" ], "description": "Tail the last N lines of a running preview component's dev server log (stdout+stderr merged). Admin only. Logs disappear when the preview exits.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name of the preview to read logs from (for example `main`).", "required": true, "schema": { "type": "string" } }, { "name": "component", "in": "query", "description": "Which component to fetch logs for.", "required": true, "schema": { "type": "string", "enum": [ "api", "ui" ] } }, { "name": "tail", "in": "query", "description": "Max number of lines to return from the end of the log. Default 200, max 10000.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Last N lines of the log as plain text.", "headers": { "x-log-truncated": { "schema": { "type": "boolean" }, "description": "`true` if the log had more lines than `tail` (or more than ~16 MiB of tail content was skipped); `false` if the full log fits." } }, "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid component", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No running preview for this branch/component, or log file missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/preview/stop": { "post": { "tags": [ "preview" ], "description": "Stop preview dev servers for a branch", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopPreviewRequest" } } }, "required": true }, "responses": { "204": { "description": "Preview stopped", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No preview running for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs": { "get": { "tags": [ "runs" ], "description": "List runs for a specific project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Filter runs by user ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "description": "Filter runs by status", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "sentiment", "in": "query", "description": "Filter runs by sentiment", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "group_id", "in": "query", "description": "Filter runs by group ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "workforce_id", "in": "query", "description": "Filter runs by workforce ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "rev", "in": "query", "description": "Filter runs by the git branch they were executed against (e.g. `main`).\nRuns without a recorded branch are always included for backwards\ncompatibility with rows created before this field was tracked.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "description": "Filter runs by start time (epoch timestamp in milliseconds)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" }, "example": 1729540800000 }, { "name": "to", "in": "query", "description": "Filter runs by end time (epoch timestamp in milliseconds)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" }, "example": 1729627200000 }, { "name": "metadata", "in": "query", "description": "Filter runs by metadata", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Page token", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Runs listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs/{run_id}": { "get": { "tags": [ "runs" ], "description": "Get a single run for a project (by run id or idempotency key)", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetail" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs/{run_id}/reactions": { "get": { "tags": [ "runs" ], "description": "List reactions for a project run (admin only)", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Reactions listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReactionsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "runs" ], "description": "Add a reaction to a project run", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewReactionReqBody" } } }, "required": true }, "responses": { "204": { "description": "Reaction created" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/users": { "get": { "tags": [ "projects" ], "description": "List users for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectUsersResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Add a user to a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProjectUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User added successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/users/{user_id}": { "delete": { "tags": [ "projects" ], "description": "Remove a user from a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "User removed successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a user's role in a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditProjectUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User role updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars": { "get": { "tags": [ "projects" ], "description": "List variables for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_ids", "in": "query", "description": "Comma-separated list of environment IDs to filter by", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Variables listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVarsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new variable", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVarReqBody" } } }, "required": true }, "responses": { "201": { "description": "Variable created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/batch": { "post": { "tags": [ "projects" ], "description": "Batch create variables", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateVarsReqBody" } } }, "required": true }, "responses": { "201": { "description": "Variables created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/{var_id}": { "get": { "tags": [ "projects" ], "description": "Get a variable by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Variable details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Var" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a variable", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Variable deleted successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a variable", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVarReqBody" } } }, "required": true }, "responses": { "204": { "description": "Variable updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce": { "get": { "tags": [ "projects" ], "description": "List workforce components for the project. When `rev` is provided the response is scoped to that git branch and includes deployment URLs; when omitted all registered components are returned.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`). When omitted, all registered (non-deleted) workforce components are returned without deployment status.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of workforce items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkforceResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a workforce component (agent or workflow) on the git **branch** given by `rev`.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkforceReqBody" } } }, "required": true }, "responses": { "201": { "description": "Workforce component created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkforceResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a workforce component on the git **branch** given by `rev`.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkforceReqBody" } } }, "required": true }, "responses": { "204": { "description": "Workforce component deleted", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce/{workforce}/ace": { "put": { "tags": [ "ace" ], "description": "Link an existing ACE to a workforce component. Replaces any previously linked ACE.", "operationId": "link", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAceReqBody" } } }, "required": true }, "responses": { "204": { "description": "ACE linked", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Forbidden" }, "404": { "description": "ACE or workforce not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "ace" ], "description": "Create a new ACE attached to a workforce component and enqueue the initial generation job, seeded from the component's current source on the given branch. Returns `202` immediately with `{ace_uid, job_uid}`; poll `GET /ace/{ace_uid}/jobs/{job_uid}` for terminal state. The ACE's name defaults to `{project_name}/{workforce_name}`.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "ACE created; generation job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueJobResBody" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "404": { "description": "Workforce not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "ace" ], "description": "Detach the ACE currently attached to a workforce component. The ACE itself is preserved and can be reattached to any workforce component. Active jobs on the ACE are NOT cancelled — use `POST /ace/{ace_uid}/jobs/{job_uid}/cancel` if that's what you want.", "operationId": "unlink", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "ACE unlinked", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Workforce not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce/{workforce}/{*path}": { "get": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). For non-serverless deployments, the method and most headers pass through; JSON bodies on paths ending in `/run` or `/stream` get `context.platform_config` merged in (same shape as serverless / `timbal.server.http` + `RunContext`). For `type = serverless`, the request is handled like `timbal codegen test`. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. Responses include `X-Timbal-Workforce-Deployment-Type` (`serverless` | `ecs` | `on-premise`). WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). For non-serverless deployments, the method and most headers pass through; JSON bodies on paths ending in `/run` or `/stream` get `context.platform_config` merged in (same shape as serverless / `timbal.server.http` + `RunContext`). For `type = serverless`, the request is handled like `timbal codegen test`. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. Responses include `X-Timbal-Workforce-Deployment-Type` (`serverless` | `ecs` | `on-premise`). WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_put", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). For non-serverless deployments, the method and most headers pass through; JSON bodies on paths ending in `/run` or `/stream` get `context.platform_config` merged in (same shape as serverless / `timbal.server.http` + `RunContext`). For `type = serverless`, the request is handled like `timbal codegen test`. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. Responses include `X-Timbal-Workforce-Deployment-Type` (`serverless` | `ecs` | `on-premise`). WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_post", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). For non-serverless deployments, the method and most headers pass through; JSON bodies on paths ending in `/run` or `/stream` get `context.platform_config` merged in (same shape as serverless / `timbal.server.http` + `RunContext`). For `type = serverless`, the request is handled like `timbal codegen test`. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. Responses include `X-Timbal-Workforce-Deployment-Type` (`serverless` | `ecs` | `on-premise`). WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_delete", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). For non-serverless deployments, the method and most headers pass through; JSON bodies on paths ending in `/run` or `/stream` get `context.platform_config` merged in (same shape as serverless / `timbal.server.http` + `RunContext`). For `type = serverless`, the request is handled like `timbal codegen test`. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. Responses include `X-Timbal-Workforce-Deployment-Type` (`serverless` | `ecs` | `on-premise`). WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_patch", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/users": { "get": { "tags": [ "orgs" ], "description": "List users in an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Optional search query to filter users by name", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Users listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgUsersResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Invite a user to an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteOrgUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User invited successfully" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "orgs" ], "description": "Remove a user from an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveOrgUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User removed successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "orgs" ], "description": "Update a user's role in an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOrgUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User role updated successfully" } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AceJobView": { "type": "object", "description": "Public view of a background job against an ACE.", "required": [ "uid", "kind", "status", "iteration_count", "tool_call_count", "queued_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "error_message": { "type": [ "string", "null" ], "description": "Present when the job terminated unsuccessfully (`failed`, `error`, `cancelled`)." }, "iteration_count": { "type": "integer", "format": "int32" }, "kind": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "tool_call_count": { "type": "integer", "format": "int32" }, "uid": { "type": "string", "format": "uuid" } } }, "AcePolicy": { "type": "object", "description": "A single policy entry.\n\n- `id` is the human-readable stable key (e.g. `\"ev_subsidy\"`).\n- `requires` / `provides` / `tool_action` are kept as raw JSON because\n their shape is still evolving.", "required": [ "id", "condition", "action" ], "properties": { "action": { "type": "string" }, "condition": { "type": "string" }, "id": { "type": "string" }, "provides": { "type": "array", "items": { "type": "string" } }, "requires": { }, "tool_action": { } } }, "AceVar": { "type": "object", "description": "A single variable declaration.\n\n- `id` is the human-readable stable key (e.g. `\"flow\"`, `\"presupuesto_max\"`).\n- `choices`, when present, restricts the variable to an enum of string values.\n- `match_mode` tweaks how the matcher compares extracted vs expected values\n (e.g. `\"semantic\"`).", "required": [ "id" ], "properties": { "choices": { "type": [ "array", "null" ], "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "match_mode": { "type": [ "string", "null" ] } } }, "AddProjectUserReqBody": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "format": "int64" } } }, "AppType": { "type": "string", "enum": [ "agent", "workflow", "unknown" ] }, "BatchCreateVarsReqBody": { "type": "object", "required": [ "vars" ], "properties": { "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "vars": { "type": "array", "items": { "$ref": "#/components/schemas/VarInput" } } } }, "BillingOverageReqBody": { "type": "object", "required": [ "enabled" ], "properties": { "cap_credits": { "type": [ "integer", "null" ], "format": "int64", "description": "Max overage **credits** the user allows (null = unlimited)." }, "enabled": { "type": "boolean" } } }, "BinSize": { "type": "string", "enum": [ "minute", "hour", "day" ] }, "ChannelAction": { "type": "string", "description": "How the rule was wired to `NotificationChannels` for this create call.", "enum": [ "linked", "reused", "created" ] }, "ComposeEffort": { "type": "string", "description": "Reasoning effort level for the session.", "enum": [ "low", "medium", "high", "max" ] }, "ComposeMode": { "type": "string", "description": "Compose session behavior.", "enum": [ "default", "plan" ] }, "ComposeModel": { "type": "string", "description": "Model family to use for the session. Always resolves to the latest released version.", "enum": [ "sonnet", "opus", "haiku" ] }, "ComposeRequest": { "type": "object", "required": [ "rev", "prompt" ], "properties": { "effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComposeEffort", "description": "Reasoning effort level. Higher levels let the model think longer before responding,\nat proportionally higher cost and latency." } ] }, "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComposeMode", "description": "Session behavior mode. `default` bypasses all tool-permission prompts and lets the agent\nedit files, run shell commands, and call MCP tools freely. `plan` restricts the agent to\nread-only tools — it analyses the codebase and produces a plan, without mutating anything." } ] }, "model": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComposeModel", "description": "Model family to use. Always resolves to the latest version of that family —\nspecific version pinning is not exposed." } ] }, "prompt": { "$ref": "#/components/schemas/Message", "description": "The prompt: a plain string, an array of content blocks, or a full Message object." }, "rev": { "type": "string", "description": "Branch to run against (worktree is checked out at this rev)", "example": "main" }, "session_id": { "type": [ "string", "null" ], "description": "Existing session ID to continue a conversation. Omit to start a new session." } } }, "ConnectToProject": { "oneOf": [ { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "kb" ] } } }, { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "integration" ] } } } ] }, "Content": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "file", "type" ], "properties": { "file": { "$ref": "#/components/schemas/FileRef" }, "type": { "type": "string", "enum": [ "file" ] } } } ] }, "Cost": { "type": "object", "required": [ "id", "name", "unit", "usd", "credits" ], "properties": { "credits": { "type": "number", "format": "double" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "unit": { "type": "string" }, "usd": { "type": "number", "format": "double" } } }, "CostBin": { "type": "object", "required": [ "interval_starts_at", "interval_ends_at", "costs" ], "properties": { "costs": { "type": "array", "items": { "$ref": "#/components/schemas/Cost" } }, "interval_ends_at": { "type": "integer", "format": "int64" }, "interval_starts_at": { "type": "integer", "format": "int64" } } }, "CreateBackupRequest": { "type": "object", "properties": { "dry_run": { "type": "boolean", "description": "When omitted or when the request has no JSON body, treated as `false`." } } }, "CreateChannelReq": { "type": "object", "properties": { "config": { "type": "object", "description": "Omitted or null when linking by `id` only." }, "id": { "type": [ "string", "null" ], "description": "Existing `NotificationChannels.id` for this org. When set, `type` / `config` / `name` are ignored." }, "name": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/NotificationChannelType" } } }, "CreateDomainReqBody": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Custom domain name", "example": "custom.timbal.ai" } } }, "CreateEnvReqBody": { "type": "object", "required": [ "name", "color" ], "properties": { "color": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "CreateK2Request": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Name for the new knowledge base" } } }, "CreateK2Response": { "type": "object", "required": [ "id", "uid", "name", "path" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "uid": { "type": "string" } } }, "CreateK2VirtualDirectoryRequest": { "type": "object", "required": [ "directory" ], "properties": { "directory": { "type": "string", "description": "Folder path, same format as the `directory` field on file upload (e.g. `docs/reports`)." } } }, "CreateK2VirtualDirectoryResponse": { "type": "object", "required": [ "directory", "placeholder_file_id", "created" ], "properties": { "created": { "type": "boolean", "description": "`true` if this call created the folder, `false` if it already existed." }, "directory": { "type": "string" }, "placeholder_file_id": { "type": "string", "description": "Listing id for this folder; remove it with `DELETE /orgs/{org_id}/k2/{kb_id}/files/{file_id}`." } } }, "CreateNotificationChannelOut": { "type": "object", "required": [ "id", "channel_action" ], "properties": { "channel_action": { "$ref": "#/components/schemas/ChannelAction" }, "id": { "type": "integer", "format": "int64" } } }, "CreateNotificationChannelReq": { "type": "object", "description": "Body for **POST** `/orgs/{org_id}/notifications/channels` (standalone channel; same validation as inline rule channel, no `id`).", "properties": { "config": { "type": "object" }, "name": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/NotificationChannelType" } } }, "CreateNotificationRuleOut": { "type": "object", "required": [ "id", "channel_id", "channel_action" ], "properties": { "channel_action": { "$ref": "#/components/schemas/ChannelAction" }, "channel_id": { "type": "integer", "format": "int64" }, "id": { "type": "integer", "format": "int64" } } }, "CreateNotificationRuleReq": { "type": "object", "description": "Body for POST org-wide or project-scoped notification rules (same shape).", "required": [ "name", "event_type", "channel" ], "properties": { "channel": { "$ref": "#/components/schemas/CreateChannelReq", "description": "Channel: inline `type` + `config`, or reuse with `{ \"id\": \u003Cchannel id\u003E }` (same org)." }, "condition": { "type": [ "object", "null" ] }, "cooldown_seconds": { "type": "integer", "format": "int32" }, "event_type": { "$ref": "#/components/schemas/NotificationEventType" }, "name": { "type": "string" } } }, "CreateProjectReqBody": { "type": "object", "required": [ "origin" ], "properties": { "name": { "type": [ "string", "null" ] }, "origin": { "$ref": "#/components/schemas/ProjectOrigin" } } }, "CreateProjectResBody": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "CreateRestoreRequest": { "type": "object", "required": [ "source_backup_id" ], "properties": { "source_backup_id": { "type": "string" } } }, "CreateVarReqBody": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "description": { "type": [ "string", "null" ] }, "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/VarType" }, "value": { "type": "string" } } }, "CreateWorkforceReqBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Optional display name for the new component. If omitted, a unique name is generated." }, "type": { "type": "string", "description": "Either `agent` or `workflow`. Defaults to `agent`." } } }, "CreateWorkforceResponse": { "type": "object", "description": "Response returned when a new workforce component is created.", "required": [ "id", "uid", "type", "name", "path" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string", "description": "Path to the new component inside the repository worktree (for example `workforce/my-agent`)." }, "type": { "type": "string" }, "uid": { "type": "string", "description": "Identifier assigned in the project manifest for this component." } } }, "DeleteChannelBody": { "type": "object", "properties": { "force": { "type": [ "boolean", "null" ], "description": "When `true`, delete even if rules reference this channel (cascading unlink)." } } }, "DeleteWorkforceReqBody": { "type": "object", "required": [ "workforce" ], "properties": { "workforce": { "type": "string", "description": "Component to delete: numeric id, manifest UUID (`uid`), or configured name." } } }, "DeployEnvReqBody": { "type": "object", "properties": { "rev": { "type": [ "string", "null" ] } } }, "Deployment": { "type": "object", "required": [ "id", "type", "project_env_id", "target", "status", "created_at", "updated_at" ], "properties": { "build_finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "build_logs": { "type": [ "string", "null" ] }, "build_started_at": { "type": [ "string", "null" ], "format": "date-time" }, "cpu": { "type": [ "integer", "null" ], "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "desired_count": { "type": [ "integer", "null" ], "format": "int32" }, "domain": { "type": [ "string", "null" ] }, "ephemeral_storage": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "integer", "format": "int64" }, "memory": { "type": [ "integer", "null" ], "format": "int32" }, "project_env_id": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "status_detail": { "type": [ "string", "null" ] }, "target": { "$ref": "#/components/schemas/Target" }, "type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Domain": { "type": "object", "required": [ "id", "domain", "validation_records", "validation_status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "domain": { "type": "string", "description": "Custom domain name" }, "id": { "type": "string", "description": "Unique domain identifier" }, "project_env": { "description": "Project environment this domain is linked to, if any" }, "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp in epoch milliseconds" }, "validation_records": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationRecord" }, "description": "DNS records required for SSL certificate validation" }, "validation_status": { "$ref": "#/components/schemas/ValidationStatus", "description": "Current SSL certificate validation status" } } }, "EditK2Request": { "type": "object", "properties": { "backup_enabled": { "type": [ "boolean", "null" ] }, "backup_retention_days": { "type": [ "integer", "null" ], "format": "int32" }, "backup_s3_bucket": { "type": [ "string", "null" ] }, "backup_s3_key_prefix": { "type": [ "string", "null" ] }, "backup_schedule_cron": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "EditOrgReqBody": { "type": "object", "properties": { "banner_url": { "type": [ "string", "null" ], "description": "URL of the organization's banner image", "deprecated": true }, "contact_email": { "type": [ "string", "null" ], "description": "Contact email address" }, "contact_name": { "type": [ "string", "null" ], "description": "Contact person's name" }, "contact_phone": { "type": [ "string", "null" ], "description": "Contact phone number" }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code" }, "description": { "type": [ "string", "null" ], "description": "Organization description" }, "name": { "type": [ "string", "null" ], "description": "Organization name" }, "photo_url": { "type": [ "string", "null" ], "description": "URL of the organization's profile photo" } } }, "EditOrgUserReqBody": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "description": "User's email address" }, "role": { "type": "string", "description": "User's role in the organization. Standard values are `admin` and `user`. Custom roles are available — contact sales for more information", "example": "user" } } }, "EditProjectReqBody": { "type": "object", "properties": { "banner_url": { "type": [ "string", "null" ] }, "default_role": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_public_template": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "use_platform_iam": { "type": [ "boolean", "null" ] } } }, "EditProjectUserReqBody": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string" } } }, "EmbeddingModel": { "type": "string" }, "EnqueueJobResBody": { "type": "object", "description": "Response body returned by any endpoint that enqueues a new job. The\nHTTP status is `202 Accepted` — poll `GET /ace/{ace_uid}/jobs/{job_uid}`\nfor terminal state.", "required": [ "ace_uid", "job_uid", "kind" ], "properties": { "ace_uid": { "type": "string", "format": "uuid" }, "job_uid": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "Job kind (e.g. `\"generate_initial\"`, `\"regenerate\"`)." } } }, "EnvPreview": { "type": "object", "required": [ "id", "name", "color" ], "properties": { "color": { "type": "string", "description": "Environment color" }, "id": { "type": "string", "description": "Environment identifier" }, "last_deployment_status": { "type": [ "string", "null" ], "description": "Status of the latest deployment in this environment" }, "name": { "type": "string", "description": "Environment name" } } }, "ErrorMessage": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g. `ALREADY_EXISTS`, `BAD_REQUEST`)." }, "message": { "type": "string", "description": "Human-readable description." } } }, "FileRef": { "type": "object", "required": [ "source" ], "properties": { "media_type": { "type": [ "string", "null" ], "description": "MIME type. Inferred from `name` extension when omitted." }, "name": { "type": [ "string", "null" ], "description": "Filename (e.g. \"screenshot.png\"). Used for display and media-type inference.\nOptional — when omitted, `media_type` must be provided explicitly." }, "source": { "$ref": "#/components/schemas/FileSource", "description": "How to obtain the file bytes." } } }, "FileSource": { "oneOf": [ { "type": "object", "description": "Inline base64-encoded content.", "required": [ "data", "type" ], "properties": { "data": { "type": "string" }, "type": { "type": "string", "enum": [ "base64" ] } } }, { "type": "object", "description": "Local filesystem path (server-side).", "required": [ "path", "type" ], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "path" ] } } }, { "type": "object", "description": "Remote URL to fetch.", "required": [ "url", "type" ], "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } } } ] }, "GetK2FileResponse": { "allOf": [ { "$ref": "#/components/schemas/K2File" }, { "type": "object", "required": [ "parsings", "embeddings" ], "properties": { "embeddings": { "type": "array", "items": { "$ref": "#/components/schemas/K2FileEmbedding" } }, "parsings": { "type": "array", "items": { "$ref": "#/components/schemas/K2FileParsing" } } } } ] }, "GetOrgResBody": { "type": "object", "required": [ "org" ], "properties": { "org": { "$ref": "#/components/schemas/Org" } } }, "InsertK2ChunkRequest": { "type": "object", "required": [ "content" ], "properties": { "after_uid": { "type": [ "string", "null" ], "format": "uuid", "description": "Place the new chunk immediately after this `chunk_uid`. Mutually\nexclusive with `before_uid`. If neither is set, the chunk is\nappended at the end of the file." }, "before_uid": { "type": [ "string", "null" ], "format": "uuid", "description": "Place the new chunk immediately before this `chunk_uid`. Mutually\nexclusive with `after_uid`." }, "content": { "type": "string" }, "embed": { "type": [ "string", "null" ], "description": "Text used for vector / full-text indexing. Defaults to `content`\nwhen omitted; provide an explicit value to keep an\nindexing-optimized variant distinct from the user-visible text." }, "page_end": { "type": [ "integer", "null" ], "format": "int32" }, "page_start": { "type": [ "integer", "null" ], "format": "int32" } } }, "IntegrationPreview": { "type": "object", "required": [ "id", "provider", "name" ], "properties": { "id": { "type": "string", "description": "Integration identifier" }, "logo_url": { "type": [ "string", "null" ], "description": "Integration logo URL" }, "name": { "type": "string", "description": "Integration display name" }, "provider": { "type": "string", "description": "Integration provider key" } } }, "InviteOrgUserReqBody": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } }, "K2Chunk": { "type": "object", "required": [ "uid", "kb_file_id", "ordinal", "content", "embed", "blocks", "index_status", "revision", "source", "created_at", "updated_at" ], "properties": { "blocks": { "type": "object", "description": "Source-document layout metadata (e.g. bounding boxes, page coords)\nwhen available. `null` for chunks created or edited by the user." }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "embed": { "type": "string" }, "index_error": { "type": [ "string", "null" ] }, "index_status": { "type": "string", "description": "Indexing state. One of `pending`, `indexing`, `indexed`, `failed`.\nWhile not `indexed`, the chunk's contribution to search results may\nbe stale." }, "indexed_at": { "type": [ "string", "null" ], "format": "date-time" }, "kb_file_id": { "type": "string" }, "ordinal": { "type": "string", "description": "Ordering key. Chunks in a file are returned in ascending `ordinal`\norder. Treat the value as opaque — placement on insert is controlled\nby `after_uid` / `before_uid`, not by setting `ordinal` directly." }, "page_end": { "type": [ "integer", "null" ], "format": "int32" }, "page_start": { "type": [ "integer", "null" ], "format": "int32" }, "revision": { "type": "string", "description": "Optimistic concurrency token. Send back as `If-Match: \u003Crevision\u003E`\non the next mutation (`PATCH` / `DELETE`)." }, "source": { "type": "string", "description": "Origin of the chunk: `parser`, `user_edit`, or `insert`." }, "uid": { "type": "string", "format": "uuid", "description": "Stable per-chunk identity." }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2ChunkSummary": { "type": "object", "description": "List-endpoint payload. Same fields as [`K2Chunk`] except `blocks`,\nwhich is omitted to keep list responses small. Fetch a single chunk\nby `uid` to retrieve `blocks`.", "required": [ "uid", "kb_file_id", "ordinal", "content", "embed", "index_status", "revision", "source", "created_at", "updated_at" ], "properties": { "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "embed": { "type": "string" }, "index_error": { "type": [ "string", "null" ] }, "index_status": { "type": "string" }, "indexed_at": { "type": [ "string", "null" ], "format": "date-time" }, "kb_file_id": { "type": "string" }, "ordinal": { "type": "string" }, "page_end": { "type": [ "integer", "null" ], "format": "int32" }, "page_start": { "type": [ "integer", "null" ], "format": "int32" }, "revision": { "type": "string" }, "source": { "type": "string" }, "uid": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2Column": { "type": "object", "required": [ "name", "data_type", "is_nullable" ], "properties": { "data_type": { "type": "string" }, "is_nullable": { "type": "boolean" }, "name": { "type": "string" } } }, "K2Constraint": { "type": "object", "required": [ "constraint_type" ], "properties": { "columns": { "type": "array", "items": { "type": "string" }, "description": "Columns involved (for PK, UNIQUE, NOT_NULL). Empty for CHECK." }, "constraint_type": { "$ref": "#/components/schemas/K2ConstraintType" }, "expression": { "type": [ "string", "null" ], "description": "CHECK expression, if applicable." }, "foreign_keys": { "type": "array", "items": { "$ref": "#/components/schemas/K2ForeignKey" }, "description": "Foreign key references, if applicable." } } }, "K2ConstraintType": { "type": "string", "enum": [ "PRIMARY_KEY", "UNIQUE", "FOREIGN_KEY", "CHECK", "NOT_NULL" ] }, "K2Detail": { "type": "object", "required": [ "id", "uid", "name", "data_size_bytes", "table_count", "row_count", "vector_count", "index_count", "backup_enabled", "created_at", "updated_at" ], "properties": { "backup_enabled": { "type": "boolean" }, "backup_last_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "backup_last_error": { "type": [ "string", "null" ] }, "backup_last_started_at": { "type": [ "string", "null" ], "format": "date-time" }, "backup_last_status": { "type": [ "string", "null" ] }, "backup_retention_days": { "type": [ "integer", "null" ], "format": "int32" }, "backup_s3_bucket": { "type": [ "string", "null" ] }, "backup_s3_key_prefix": { "type": [ "string", "null" ] }, "backup_schedule_cron": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "data_size_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "index_count": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string" }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "table_count": { "type": "integer", "format": "int64", "minimum": 0 }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "vector_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "K2File": { "type": "object", "required": [ "id", "uid", "kb_id", "name", "content_type", "content_length", "metadata", "parse_state", "url", "created_at", "updated_at" ], "properties": { "content_length": { "type": "integer", "format": "int64" }, "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "directory": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "kb_id": { "type": "integer", "format": "int64" }, "metadata": { }, "name": { "type": "string" }, "parse_state": { "type": "string", "description": "Pipeline state for parsing + embedding.\n\nOne of `pending` (pipeline in flight), `success` (parse + embed both completed),\n`failed` (latest attempt failed), or `skipped` (format unsupported, never parsed).\nUnsupported files are stored as-is; the indicator lets clients flag them in listings\nrather than rejecting the upload." }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } }, "K2FileEmbedding": { "type": "object", "required": [ "id", "kb_file_id", "provider", "model", "status", "created_at", "updated_at" ], "properties": { "chunk_count": { "type": [ "integer", "null" ], "format": "int32" }, "cost_usd": { "type": [ "number", "null" ], "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "kb_file_id": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "parsing_id": { "type": [ "integer", "null" ], "format": "int64" }, "provider": { "type": "string" }, "status": { "type": "string" }, "token_count": { "type": [ "integer", "null" ], "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2FileParsing": { "type": "object", "required": [ "id", "kb_file_id", "provider", "status", "created_at", "updated_at" ], "properties": { "chunk_count": { "type": [ "integer", "null" ], "format": "int32" }, "cost_usd": { "type": [ "number", "null" ], "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "kb_file_id": { "type": "integer", "format": "int64" }, "num_pages": { "type": [ "integer", "null" ], "format": "int32" }, "provider": { "type": "string" }, "provider_job_id": { "type": [ "string", "null" ] }, "s3_bucket": { "type": [ "string", "null" ] }, "s3_key": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2ForeignKey": { "type": "object", "required": [ "column", "ref_table", "ref_column" ], "properties": { "column": { "type": "string" }, "ref_column": { "type": "string" }, "ref_table": { "type": "string" } } }, "K2Index": { "type": "object", "required": [ "name", "table_name", "columns", "is_unique" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "is_unique": { "type": "boolean" }, "name": { "type": "string" }, "table_name": { "type": "string" } } }, "K2Preview": { "type": "object", "required": [ "id", "uid", "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "data_size_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2Schema": { "type": "object", "required": [ "tables" ], "properties": { "tables": { "type": "array", "items": { "$ref": "#/components/schemas/K2Table" } } } }, "K2SchemaSql": { "type": "object", "required": [ "statements" ], "properties": { "statements": { "type": "array", "items": { "type": "string" }, "description": "DDL statements (CREATE TABLE, CREATE INDEX, etc.)" } } }, "K2Table": { "type": "object", "required": [ "name", "source", "columns", "indexes", "constraints", "estimated_row_count" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/K2Column" } }, "constraints": { "type": "array", "items": { "$ref": "#/components/schemas/K2Constraint" } }, "estimated_row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "indexes": { "type": "array", "items": { "$ref": "#/components/schemas/K2Index" } }, "name": { "type": "string" }, "schema": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/K2TableSource" } } }, "K2TableSource": { "type": "string", "enum": [ "primary", "vectors" ] }, "KbBackupResponse": { "type": "object", "required": [ "id", "kb_id", "status", "triggered_by", "dry_run", "started_at" ], "properties": { "bytes_uploaded": { "type": [ "integer", "null" ], "format": "int64" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dry_run": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "kb_id": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "triggered_by": { "type": "string" } } }, "KbPreview": { "type": "object", "required": [ "id", "uid", "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Knowledge base description" }, "id": { "type": "string", "description": "Knowledge base identifier" }, "name": { "type": "string", "description": "Knowledge base name" }, "uid": { "type": "string", "description": "Knowledge base unique identifier" } } }, "KbRestoreResponse": { "type": "object", "required": [ "id", "kb_id", "source_backup_id", "status", "triggered_by", "started_at" ], "properties": { "bytes_downloaded": { "type": [ "integer", "null" ], "format": "int64" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "kb_id": { "type": "string" }, "source_backup_id": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "triggered_by": { "type": "string" } } }, "LinkAceReqBody": { "type": "object", "description": "Request body for linking an existing ACE to a workforce.", "required": [ "ace_uid" ], "properties": { "ace_uid": { "type": "string", "format": "uuid", "description": "`uid` of an existing ACE in the same organization." } } }, "LinkKbRequest": { "type": "object", "required": [ "kb_id" ], "properties": { "kb_id": { "type": "string", "description": "ID of the K2 knowledge base to link to this project" } } }, "ListAceJobsResBody": { "type": "object", "required": [ "jobs", "total" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/AceJobView" } }, "total": { "type": "string" } } }, "ListBackupsResponse": { "type": "object", "required": [ "backups" ], "properties": { "backups": { "type": "array", "items": { "$ref": "#/components/schemas/KbBackupResponse" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "ListConnectionsResBody": { "type": "object", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectConnection" } } } }, "ListDeploymentsResBody": { "type": "object", "required": [ "deployments" ], "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } } } }, "ListDomainsResBody": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } }, "ListEmbeddingModelsResBody": { "type": "object", "required": [ "embedding_models" ], "properties": { "embedding_models": { "type": "array", "items": { "$ref": "#/components/schemas/EmbeddingModel" } } } }, "ListEnvsResBody": { "type": "object", "required": [ "envs" ], "properties": { "envs": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEnv" } } } }, "ListK2ChunksResponse": { "type": "object", "required": [ "chunks" ], "properties": { "chunks": { "type": "array", "items": { "$ref": "#/components/schemas/K2ChunkSummary" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "ListK2FilesResponse": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/K2File" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "ListK2Response": { "type": "object", "required": [ "k2" ], "properties": { "k2": { "type": "array", "items": { "$ref": "#/components/schemas/K2Preview" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "ListOrgContactsResBody": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/OrgContact" } } } }, "ListOrgNotificationChannelsResBody": { "type": "object", "title": "ListOrgNotificationChannelsResponse", "required": [ "channels" ], "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannelOut" } } } }, "ListOrgNotificationRulesResBody": { "type": "object", "title": "ListOrgNotificationRulesResponse", "description": "Wrapper for **GET** `/orgs/{org_id}/notifications/rules` — org-scoped rules only (`project_id` is null in storage).", "required": [ "rules" ], "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationRuleOut" } } } }, "ListOrgUsersResBody": { "type": "object", "required": [ "org_users" ], "properties": { "next_page_token": { "type": [ "string", "null" ], "description": "Token to fetch the next page, or null if this is the last page" }, "org_users": { "type": "array", "items": { "$ref": "#/components/schemas/OrgUser" }, "description": "List of users in the organization" } } }, "ListOrgsResult": { "type": "object", "required": [ "orgs" ], "properties": { "next_page_token": { "type": [ "string", "null" ], "description": "Next page token" }, "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/OrgPreview" }, "description": "List of organizations" } } }, "ListPoliciesResBody": { "type": "object", "required": [ "policies" ], "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/AcePolicy" } } } }, "ListPreviewsResponse": { "type": "object", "description": "Previews currently visible for the organization.", "required": [ "previews" ], "properties": { "previews": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewInfo" } } } }, "ListProjectNotificationRulesResBody": { "type": "object", "title": "ListProjectNotificationRulesResponse", "description": "Wrapper for **GET** `/orgs/{org_id}/projects/{project_id}/notifications/rules`.", "required": [ "rules" ], "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationRuleOut" } } } }, "ListProjectUsersResBody": { "type": "object", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserWithRole" } } } }, "ListProjectsResBody": { "oneOf": [ { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectPreview" } } } }, { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDetail" } } } } ] }, "ListReactionsResBody": { "type": "object", "required": [ "reactions" ], "properties": { "next_page_token": { "type": [ "string", "null" ] }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/Reaction" } } } }, "ListRestoresResponse": { "type": "object", "required": [ "restores" ], "properties": { "next_page_token": { "type": [ "string", "null" ] }, "restores": { "type": "array", "items": { "$ref": "#/components/schemas/KbRestoreResponse" } } } }, "ListRunsResBody": { "type": "object", "required": [ "runs" ], "properties": { "next_page_token": { "type": [ "string", "null" ], "description": "Cursor for the next page" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunPreview" }, "description": "List of runs" } } }, "ListVarsResBody": { "type": "object", "required": [ "vars" ], "properties": { "vars": { "type": "array", "items": { "$ref": "#/components/schemas/Var" } } } }, "ListWorkforceResBody": { "type": "object", "description": "Workforce components registered for the project. The `url` field is set only when the component has a **running** deployment for the git **branch** you queried (`rev`).", "required": [ "workforce" ], "properties": { "workforce": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforcePreview" } } } }, "Message": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/Content" } }, "role": { "$ref": "#/components/schemas/Role" } } }, "NewReactionReqBody": { "type": "object", "required": [ "sentiment" ], "properties": { "feedback": { "type": [ "string", "null" ] }, "sentiment": { "type": "string" } } }, "NotificationChannelOut": { "type": "object", "required": [ "id", "type", "config" ], "properties": { "config": { "type": "object" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/NotificationChannelType" } } }, "NotificationChannelType": { "type": "string", "enum": [ "email", "slack" ] }, "NotificationEventType": { "type": "string", "enum": [ "org.credits.usage", "project.deployment.failed", "project.deployment.running" ] }, "NotificationRuleOut": { "type": "object", "required": [ "id", "name", "event_type", "cooldown_seconds", "enabled", "channels" ], "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannelOut" } }, "condition": { "type": [ "object", "null" ] }, "cooldown_seconds": { "type": "integer", "format": "int32" }, "enabled": { "type": "boolean" }, "event_type": { "$ref": "#/components/schemas/NotificationEventType" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Org": { "type": "object", "required": [ "id", "name", "plan", "plan_metadata", "overage_enabled", "credits_per_usd", "created_at", "role" ], "properties": { "banner_url": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "credits_per_usd": { "type": "number", "format": "double" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "overage_cap_credits": { "type": [ "integer", "null" ], "format": "int64" }, "overage_enabled": { "type": "boolean" }, "photo_url": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "plan_metadata": { }, "role": { "type": "string" }, "stripe_customer_id": { "type": [ "string", "null" ] } } }, "OrgContact": { "type": "object", "required": [ "id", "type", "name", "channels" ], "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/OrgContactChannel" }, "description": "Ways to reach this contact." }, "id": { "type": "string", "description": "Unique contact identifier." }, "name": { "type": "string", "description": "Display name (e.g. \"Jane Doe\")." }, "photo_url": { "type": [ "string", "null" ], "description": "Optional profile photo URL." }, "title": { "type": [ "string", "null" ], "description": "Optional job title (e.g. \"Senior AI Solutions Architect\")." }, "type": { "$ref": "#/components/schemas/OrgContactType", "description": "Role this contact plays for the org." } } }, "OrgContactChannel": { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "$ref": "#/components/schemas/OrgContactChannelKind" }, "label": { "type": [ "string", "null" ], "description": "Optional display label like \"Mobile\" or \"Work\"." }, "primary": { "type": "boolean", "description": "Marks the preferred channel of this kind when multiple are listed." }, "value": { "type": "string", "description": "Channel-specific identifier: email address, E.164 phone number, slack\nhandle, calendly URL, etc. Format is enforced by the channel kind." } } }, "OrgContactChannelKind": { "type": "string", "enum": [ "email", "phone", "whatsapp", "telegram", "slack", "calendly", "linkedin", "signal", "other" ] }, "OrgContactType": { "type": "string", "description": "Role a contact plays for the org. Free-form on the wire/DB so new roles\ncan be introduced without a migration; unknown values fall back to `Other`.", "enum": [ "aisa", "account_executive", "account_manager", "csm", "other" ] }, "OrgPreview": { "type": "object", "required": [ "id", "name", "plan", "n_projects", "role", "created_at" ], "properties": { "banner_url": { "type": [ "string", "null" ], "description": "URL of the organization's banner image", "deprecated": true }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "description": { "type": [ "string", "null" ], "description": "Organization description" }, "id": { "type": "string", "description": "Unique organization identifier" }, "n_projects": { "type": "integer", "format": "int64", "description": "Number of projects in the organization" }, "name": { "type": "string", "description": "Organization name" }, "photo_url": { "type": [ "string", "null" ], "description": "URL of the organization's profile photo" }, "plan": { "type": "string", "description": "Subscription plan" }, "role": { "type": "string", "description": "Authenticated user's role in the organization" } } }, "OrgUser": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "description": "User's email address" }, "id": { "type": [ "string", "null" ], "description": "Unique user identifier. Null for pending invites that haven't been accepted yet" }, "name": { "type": [ "string", "null" ], "description": "User's display name" }, "photo_url": { "type": [ "string", "null" ], "description": "URL of the user's profile photo" }, "role": { "type": "string", "description": "User's role in the organization" } } }, "PatchK2ChunkRequest": { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "embed": { "type": [ "string", "null" ], "description": "Text used for vector / full-text indexing. When `content` is\nprovided and `embed` is omitted, `embed` is auto-set to the new\n`content`. Send an explicit value to keep an indexing-optimized\nvariant distinct from the user-visible text." }, "page_end": { "type": [ "integer", "null" ], "format": "int32" }, "page_start": { "type": [ "integer", "null" ], "format": "int32", "description": "Tri-state: omit to leave unchanged, send `null` to clear, send an\ninteger to set." } } }, "PlanDetail": { "allOf": [ { "$ref": "#/components/schemas/ProjectPlan" }, { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Raw markdown body of the plan file." } } } ], "description": "A plan markdown file plus its full body." }, "PreviewComponent": { "type": "object", "required": [ "component" ], "properties": { "component": { "type": "string", "description": "Which part of the preview this row describes: `api` (backend dev server) or `ui` (frontend dev server)." }, "healthy": { "type": [ "boolean", "null" ], "description": "Whether the dev server answered a health check on its port. Absent when no check was performed." } } }, "PreviewInfo": { "type": "object", "required": [ "slug", "started_at", "rev", "components" ], "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewComponent" } }, "project_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Included on organization-wide preview listings so you can tell which project a row belongs to." }, "rev": { "type": "string", "description": "Git branch name this preview is tied to." }, "slug": { "type": "string", "description": "Opaque token used with your organization’s preview hostname." }, "started_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when acceptance of the preview start was recorded." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PreviewStatus" } ] }, "url": { "type": [ "string", "null" ], "description": "Public HTTPS URL for the running preview, when preview hosting is configured for your organization." } } }, "PreviewStatus": { "type": "string", "enum": [ "starting", "running" ] }, "ProjectAnalyticsCreditsBody": { "type": "object", "required": [ "group_by", "from", "to", "bins" ], "properties": { "bins": { "type": "array", "items": { "$ref": "#/components/schemas/CostBin" } }, "from": { "type": "integer", "format": "int64" }, "group_by": { "$ref": "#/components/schemas/BinSize" }, "to": { "type": "integer", "format": "int64" } } }, "ProjectAnalyticsUsageBody": { "type": "object", "required": [ "group_by", "from", "to", "bins" ], "properties": { "bins": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBin" } }, "from": { "type": "integer", "format": "int64" }, "group_by": { "$ref": "#/components/schemas/BinSize" }, "to": { "type": "integer", "format": "int64" } } }, "ProjectAnalyticsUsersBody": { "type": "object", "required": [ "from", "to", "users" ], "properties": { "from": { "type": "integer", "format": "int64" }, "next_page_token": { "type": [ "string", "null" ] }, "to": { "type": "integer", "format": "int64" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserRow" } } } }, "ProjectConnection": { "type": "object", "required": [ "id", "type", "resource_id", "resource_data", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int64" }, "resource_data": { }, "resource_id": { "type": "integer", "format": "int64" }, "resource_name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectDetail": { "type": "object", "required": [ "id", "name", "has_ui", "role", "use_platform_iam", "is_public_template", "template_uses", "publishable_api_key", "environments", "knowledge_bases", "integrations", "created_at", "updated_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "default_role": { "type": [ "string", "null" ], "description": "Project's default role. All organization members will be assigned this role by default for this project" }, "description": { "type": [ "string", "null" ], "description": "Project description" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/EnvPreview" }, "description": "Project environments with their latest deployment status" }, "has_ui": { "type": "boolean", "description": "Whether the project has a UI interface" }, "id": { "type": "string", "description": "Unique project identifier" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationPreview" }, "description": "Integrations active in this project" }, "is_public_template": { "type": "boolean", "description": "Whether the project is a public template" }, "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KbPreview" }, "description": "Knowledge bases connected to this project (new KB system only)" }, "name": { "type": "string", "description": "Project name" }, "publishable_api_key": { "type": "string", "description": "Publishable API key for this project" }, "repository_url": { "type": [ "string", "null" ], "description": "URL of the project's source code repository. When null, the project does not have source code available" }, "role": { "type": "string", "description": "Authenticated user's role in the project" }, "screenshot_url": { "type": [ "string", "null" ], "description": "URL of the project's screenshot image" }, "template_uses": { "type": "integer", "format": "int64", "description": "Number of times this template has been used" }, "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp in epoch milliseconds" }, "use_platform_iam": { "type": "boolean", "description": "Whether the project uses the platform's IAM system for access control" } } }, "ProjectEnv": { "type": "object", "required": [ "id", "name", "color", "subdomain", "created_at", "updated_at" ], "properties": { "branch": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "cpu": { "type": [ "integer", "null" ], "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "custom_domain": { }, "description": { "type": [ "string", "null" ] }, "desired_count": { "type": [ "integer", "null" ], "format": "int32" }, "ephemeral_storage": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "integer", "format": "int64" }, "memory": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "subdomain": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectOrigin": { "oneOf": [ { "type": "object", "required": [ "project_id", "type" ], "properties": { "project_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "Template" ] } } }, { "type": "object", "required": [ "has_ui", "app_type", "type" ], "properties": { "app_type": { "$ref": "#/components/schemas/AppType" }, "has_ui": { "type": "boolean" }, "kb_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Knowledge base to attach to the project. Provide an existing KB's\nid to link it, or omit to auto-create an empty one." }, "type": { "type": "string", "enum": [ "Scratch" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "Blank" ] } } } ] }, "ProjectPlan": { "type": "object", "description": "A plan markdown file produced by a compose `plan` mode session. Plans live\non EFS at `{EFS}/orgs/{org_id}/projects/{project_id}/.claude/plans/*.md`\nand are authored by the Claude CLI — the API only reads them.", "required": [ "id", "size_bytes", "modified_at" ], "properties": { "id": { "type": "string", "description": "Filename without the `.md` extension (e.g. `create-a-new-section-logical-hennessy`)." }, "modified_at": { "type": "string", "format": "date-time" }, "preview": { "type": [ "string", "null" ], "description": "Short body preview (first non-empty paragraph after the title, trimmed)." }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "title": { "type": [ "string", "null" ], "description": "Title parsed from the first `# ` heading (with an optional `Plan: ` prefix stripped)." } } }, "ProjectPreview": { "type": "object", "required": [ "id", "name", "role", "created_at", "is_public_template", "template_uses" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "default_role": { "type": [ "string", "null" ], "description": "Project's default role. All organization members will be assigned this role by default for this project" }, "description": { "type": [ "string", "null" ], "description": "Project description" }, "id": { "type": "string", "description": "Unique project identifier" }, "is_public_template": { "type": "boolean", "description": "Whether the project is a public template" }, "name": { "type": "string", "description": "Project name" }, "role": { "type": "string", "description": "Authenticated user's role in the project" }, "screenshot_url": { "type": [ "string", "null" ], "description": "URL of the project's screenshot image" }, "template_uses": { "type": "integer", "format": "int64", "description": "Number of times this template has been used" } } }, "ProjectSession": { "type": "object", "required": [ "id", "uid", "user_id", "rev", "status", "turn_count", "iteration_count", "tool_call_count", "created_at", "last_active_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "first_prompt": { "type": [ "string", "null" ], "description": "Truncated text of the first user prompt — used as a session title." }, "id": { "type": "string" }, "iteration_count": { "type": "integer", "format": "int32", "description": "Total LLM calls (including mid-turn iterations)" }, "last_active_at": { "type": "string", "format": "date-time" }, "model": { "type": [ "string", "null" ], "description": "Model used in this session" }, "rev": { "type": "string", "description": "Git branch the session is scoped to" }, "status": { "type": "string", "description": "Session status: \"active\" or \"idle\"" }, "tool_call_count": { "type": "integer", "format": "int32", "description": "Total tool_use blocks across all calls" }, "turn_count": { "type": "integer", "format": "int32", "description": "Number of user prompts sent" }, "uid": { "type": "string" }, "user_id": { "type": "string" } } }, "QueryK2Request": { "type": "object", "required": [ "sql" ], "properties": { "explain": { "type": "boolean", "description": "When true, runs EXPLAIN ANALYZE and includes the query plan in the response." }, "params": { "type": "array", "items": { }, "description": "Optional parameters for the query. Parameters passed to the vector\nsearch functions (`lance_vector_search`, `lance_hybrid_search`) are\nautomatically converted to embedding vectors before the query runs." }, "sql": { "type": "string", "description": "SQL query to execute against the knowledge base.\nUse $1, $2, etc. for parameter placeholders." } } }, "Reaction": { "type": "object", "required": [ "id", "user", "sentiment", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "feedback": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "sentiment": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserRef" } } }, "RemoveOrgUserReqBody": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the user to remove from the organization" } } }, "Role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "RunDetail": { "type": "object", "required": [ "id", "user", "status", "cost_usd", "cost_credits", "created_at", "idempotency_key" ], "properties": { "cost_credits": { "type": "number", "format": "double" }, "cost_usd": { "type": "number", "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "group_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "last_reaction_sentiment": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_detail": { }, "trace": { }, "user": { "$ref": "#/components/schemas/UserRef" } }, "additionalProperties": { } }, "RunPreview": { "type": "object", "required": [ "id", "user", "workforce", "status", "cost_usd", "cost_credits", "created_at", "idempotency_key" ], "properties": { "cost_credits": { "type": "number", "format": "double" }, "cost_usd": { "type": "number", "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "group_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "last_reaction_sentiment": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserRef" }, "workforce": { "$ref": "#/components/schemas/WorkforcePreview" } } }, "SessionDetail": { "allOf": [ { "$ref": "#/components/schemas/ProjectSession" }, { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { }, "description": "Message history from the Claude session file (same format as compose stream events)" } } } ] }, "SetEnvBranchReqBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "When null, the branch will be cleared" } } }, "SetEnvDomainReqBody": { "type": "object", "properties": { "domain_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "StartPreviewRequest": { "type": "object", "required": [ "rev" ], "properties": { "force": { "type": "boolean", "description": "If true and the org preview concurrency cap is reached, evict the\noldest running (or in-flight) preview in the org to free a slot\ninstead of returning 429. Defaults to false." }, "rev": { "type": "string", "description": "Git branch name to run the preview for (for example `main`)." } } }, "StopPreviewRequest": { "type": "object", "required": [ "rev" ], "properties": { "rev": { "type": "string", "description": "Git branch name you used when starting the preview (for example `main`)." } } }, "Target": { "type": "object", "required": [ "type", "id" ], "properties": { "commit": { }, "id": { "type": "integer", "format": "int64" }, "manifest_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "version_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "TempFile": { "type": "object", "description": "Stateless temporary file metadata. Stored under a dedicated `tmp/` prefix\nin object storage and removed by storage lifecycle policy ~24h after upload.\nNo database row is created; clients must persist the URL/name themselves\nif they need to track it.", "required": [ "name", "content_type", "content_length", "url", "created_at", "expires_at" ], "properties": { "content_length": { "type": "integer", "format": "int64", "description": "Size of the uploaded payload in bytes." }, "content_type": { "type": "string", "description": "MIME type as reported by the client." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the file was uploaded." }, "expires_at": { "type": "string", "format": "date-time", "description": "Advisory expiration (~24h after upload). Object deletion is performed by\nstorage lifecycle and may lag this timestamp by up to a day. Treat HTTP\n404 from `url` as \"expired\"." }, "name": { "type": "string", "description": "Original filename (sanitized — slashes / control characters replaced)." }, "url": { "type": "string", "description": "Public URL where the file can be downloaded until it expires." } } }, "UpdateEnvConfigReqBody": { "type": "object", "properties": { "cpu": { "type": [ "integer", "null" ], "format": "int32" }, "desired_count": { "type": [ "integer", "null" ], "format": "int32" }, "ephemeral_storage": { "type": [ "integer", "null" ], "format": "int32" }, "memory": { "type": [ "integer", "null" ], "format": "int32" } } }, "UpdateVarReqBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "value": { "type": [ "string", "null" ] } } }, "UsageBin": { "type": "object", "required": [ "interval_starts_at", "interval_ends_at", "n_success", "n_error", "n_running", "n_timeout", "n_users" ], "properties": { "interval_ends_at": { "type": "integer", "format": "int64" }, "interval_starts_at": { "type": "integer", "format": "int64" }, "n_error": { "type": "integer", "format": "int64" }, "n_running": { "type": "integer", "format": "int64" }, "n_success": { "type": "integer", "format": "int64" }, "n_timeout": { "type": "integer", "format": "int64" }, "n_users": { "type": "integer", "format": "int64" }, "p50": { "type": [ "number", "null" ], "format": "double" }, "p90": { "type": [ "number", "null" ], "format": "double" }, "p95": { "type": [ "number", "null" ], "format": "double" }, "p99": { "type": [ "number", "null" ], "format": "double" } } }, "UserRef": { "type": "object", "required": [ "id", "name", "email" ], "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "photo_url": { "type": [ "string", "null" ] } } }, "UserRow": { "type": "object", "required": [ "user_id", "user_name", "user_email", "n_success", "n_error", "n_running", "n_timeout", "usd", "credits" ], "properties": { "credits": { "type": "number", "format": "double" }, "n_error": { "type": "integer", "format": "int64" }, "n_running": { "type": "integer", "format": "int64" }, "n_success": { "type": "integer", "format": "int64" }, "n_timeout": { "type": "integer", "format": "int64" }, "usd": { "type": "number", "format": "double" }, "user_email": { "type": "string" }, "user_id": { "type": "integer", "format": "int64" }, "user_name": { "type": "string" }, "user_photo_url": { "type": [ "string", "null" ] } } }, "UserWithRole": { "type": "object", "required": [ "id", "email", "name", "role" ], "properties": { "email": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "photo_url": { "type": [ "string", "null" ] }, "role": { "type": "string" } } }, "ValidationRecord": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "name": { "type": "string", "description": "DNS record name" }, "type": { "type": "string", "description": "DNS record type (e.g. `CNAME`)" }, "value": { "type": "string", "description": "DNS record value" } } }, "ValidationStatus": { "type": "string", "description": "SSL certificate validation status", "enum": [ "pending", "issued", "inactive", "expired", "revoked", "failed", "validationtimedout" ] }, "Var": { "type": "object", "required": [ "id", "name", "value", "envs" ], "properties": { "description": { "type": [ "string", "null" ] }, "envs": { "type": "array", "items": { "$ref": "#/components/schemas/VarEnv" } }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "value": { "$ref": "#/components/schemas/VarValue" } } }, "VarEnv": { "type": "object", "required": [ "id", "name", "color" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "VarInput": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/VarType" }, "value": { "type": "string" } } }, "VarType": { "type": "string", "enum": [ "plain", "secret" ] }, "VarValue": { "oneOf": [ { "type": "object", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "plain" ] }, "value": { "type": "string" } } }, { "type": "object", "required": [ "type" ], "properties": { "decrypted": { "type": [ "string", "null" ] }, "preview": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "secret" ] } } } ] }, "WorkforcePreview": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "deleted_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Set when the workforce component has been deleted. Only returned from endpoints that include soft-deleted rows (e.g. runs list)." }, "description": { "type": [ "string", "null" ], "description": "Optional short description." }, "id": { "type": "string", "description": "Identifier of this workforce component within the project." }, "name": { "type": "string", "description": "Display name of the component." }, "type": { "$ref": "#/components/schemas/AppType", "description": "Component category (for example agent or workflow)." }, "uid": { "type": [ "string", "null" ], "description": "Stable identifier from the project manifest (`timbal.yaml`), when defined." }, "url": { "type": [ "string", "null" ], "description": "When present, the authenticated Timbal API URL used to call this component’s **running** deployment (for example from the list-workforce response). Omitted where the response does not expose a callable URL, such as on project detail." } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "description": "Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information." } } }, "tags": [ { "name": "ace", "description": "Action Control Engine (ACE) operations" }, { "name": "analytics", "description": "Project analytics" }, { "name": "billing", "description": "Subscriptions, usage, and payment-related operations" }, { "name": "compose", "description": "Compose — AI coding agent sessions" }, { "name": "files", "description": "File operations" }, { "name": "k2", "description": "Knowledge Bases v2 operations" }, { "name": "orgs", "description": "Organization operations" }, { "name": "preview", "description": "Project dev previews (branch worktree dev servers)" }, { "name": "projects", "description": "Project operations" }, { "name": "runs", "description": "Execution operations" } ] }