{ "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": { "patch": { "tags": [ "users" ], "description": "Patch the authenticated user's profile. Omitted fields are left untouched; null clears nullable fields.", "operationId": "handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchMeReqBody" } } }, "required": true }, "responses": { "204": { "description": "Profile updated", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "400": { "description": "Validation failed or non-nullable field set to null", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Internal server error", "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": [] } ] } }, "/me/tokens": { "get": { "tags": [ "users" ], "description": "List the authenticated user's API credentials.", "operationId": "handler", "responses": { "200": { "description": "Credentials listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "users" ], "description": "Create an API credential for the authenticated user.", "operationId": "handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReqBody" } } }, "required": true }, "responses": { "201": { "description": "Credential created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResBody" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/me/tokens/{token_id}": { "delete": { "tags": [ "users" ], "description": "Revoke an API credential owned by the authenticated user.", "operationId": "handler", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Credential revoked", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } } }, "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/budgets": { "get": { "tags": [ "billing" ], "description": "Read credit budgets for the organization. Filter with `project_id` or `role_id` to fetch a single target without listing the full org config.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "description": "When set, return at most the project budget for this project (0 or 1 rows).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "role_id", "in": "query", "description": "When set, return at most the role budget for this role (0 or 1 rows).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Budgets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetListBody" } } } }, "400": { "description": "Invalid query" }, "403": { "description": "Forbidden" }, "404": { "description": "Filtered project or role not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "billing" ], "description": "Replace the organization's full credit budget configuration. Omitted targets are removed.", "operationId": "put", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetListBody" } } }, "required": true }, "responses": { "200": { "description": "Budgets saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetListBody" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Forbidden" }, "404": { "description": "Project or role not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "billing" ], "description": "Merge credit budget changes. Each row upserts when `limit_credits` is set, or removes the budget when `limit_credits` is null. Other configured targets are left unchanged.", "operationId": "patch", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetPatchBody" } } }, "required": true }, "responses": { "200": { "description": "Budgets saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetListBody" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Forbidden" }, "404": { "description": "Project or role not found" } }, "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 cannot manage billing for this organization", "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}/composer/{*path}": { "get": { "tags": [ "composer" ], "description": "Proxy HTTP to the composer Python sidecar. Injects session platform_config on `/stream` and `/run`.", "operationId": "composer_proxy_get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Sidecar path (for example `stream` or `healthcheck`). Leave empty for the sidecar root.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the composer sidecar" }, "503": { "description": "Composer sidecar unavailable" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "composer" ], "description": "Proxy HTTP to the composer Python sidecar. Injects session platform_config on `/stream` and `/run`.", "operationId": "composer_proxy_put", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Sidecar path (for example `stream` or `healthcheck`). Leave empty for the sidecar root.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the composer sidecar" }, "503": { "description": "Composer sidecar unavailable" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "composer" ], "description": "Proxy HTTP to the composer Python sidecar. Injects session platform_config on `/stream` and `/run`.", "operationId": "composer_proxy_post", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Sidecar path (for example `stream` or `healthcheck`). Leave empty for the sidecar root.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the composer sidecar" }, "503": { "description": "Composer sidecar unavailable" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "composer" ], "description": "Proxy HTTP to the composer Python sidecar. Injects session platform_config on `/stream` and `/run`.", "operationId": "composer_proxy_delete", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Sidecar path (for example `stream` or `healthcheck`). Leave empty for the sidecar root.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the composer sidecar" }, "503": { "description": "Composer sidecar unavailable" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "composer" ], "description": "Proxy HTTP to the composer Python sidecar. Injects session platform_config on `/stream` and `/run`.", "operationId": "composer_proxy_patch", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Sidecar path (for example `stream` or `healthcheck`). Leave empty for the sidecar root.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the composer sidecar" }, "503": { "description": "Composer sidecar unavailable" } }, "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}/credit-grants": { "get": { "tags": [ "billing" ], "description": "Credit grants awarded to an organization, most recent first.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credit grants for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreditGrantsResBody" } } } }, "403": { "description": "Forbidden" } }, "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}/iam/actions": { "get": { "tags": [ "iam" ], "description": "Catalog of every action this organization may grant on a role. Org-scoped so future plans / feature flags can enable subsets per-org; today every org sees the full catalog. Use to drive the custom-role builder UI: render a checkbox per action, and a resource picker keyed on `resource.kind` for typed actions. Cacheable per `(org_id, version)`.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Action catalog visible to this org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListActionsResBody" } } } }, "403": { "description": "Caller is not a member of this org" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/check": { "post": { "tags": [ "iam" ], "description": "Forward authorization simulator. Evaluates one or more `(action, resource?)` checks against a user's effective grants and returns a decision per check, including the matched allow/deny grants that explain it. Mirrors the live evaluator exactly — same scope intersection, expiry filtering, and deny-beats-allow precedence. \n\nDefaults `user_id` to the caller; passing another user requires `users.read`. Cap is 50 checks per request.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckReqBody" } } }, "required": true }, "responses": { "200": { "description": "Per-check decisions + matched grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResBody" } } } }, "403": { "description": "Forbidden (not a member, or asking about another user without `users.read`)" }, "422": { "description": "Invalid request (empty/too many checks, unknown action key, malformed or wildcarded resource, target user is not a member)" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/roles": { "get": { "tags": [ "iam" ], "description": "List roles available to an organization. Returns built-in system roles + any custom roles defined by the org.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Roles for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgRolesResBody" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "iam" ], "description": "Create a custom role for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleReqBody" } } }, "required": true }, "responses": { "201": { "description": "Role created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDetail" } } } }, "403": { "description": "Forbidden" }, "409": { "description": "A role with that name already exists in the organization" }, "422": { "description": "Invalid request body (unknown action, bad resource shape, reserved name, duplicate grant), or plan does not allow custom roles (`code: PLAN_REQUIRED`)" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/roles/{role_id}": { "get": { "tags": [ "iam" ], "description": "Retrieve a role and the full set of grants it carries.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Role for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDetail" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Role not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "iam" ], "description": "Delete a custom role. System roles cannot be deleted. Roles still attached to members return 409 with the assignee list — reassign first, then retry.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Role deleted" }, "403": { "description": "Forbidden or system role (immutable)" }, "404": { "description": "Role not found" }, "409": { "description": "Role is still attached to one or more members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleInUseConflict" } } } }, "422": { "description": "Deleting this role would lock the caller out of roles.manage, or plan does not allow custom roles (`code: PLAN_REQUIRED`)" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "iam" ], "description": "Partially update a custom role. System roles are immutable.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditRoleReqBody" } } }, "required": true }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDetail" } } } }, "403": { "description": "Forbidden or system role (immutable)" }, "404": { "description": "Role not found" }, "409": { "description": "A role with that name already exists" }, "422": { "description": "Invalid body, would lock the caller out of roles.manage, or plan does not allow custom roles (`code: PLAN_REQUIRED`)" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/users": { "get": { "tags": [ "iam" ], "description": "List members of an organization. Requires `users.read`.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Optional case-insensitive substring filter on user name or email.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Page token for pagination. Pass back the `next_page_token` from the\nprevious response.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Organization members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgUsersResBody" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "iam" ], "description": "Invite one or more users 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": [ "iam" ], "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": [] } ] } }, "/orgs/{org_id}/iam/users/{user_id}/effective-grants": { "get": { "tags": [ "iam" ], "description": "Dump the grants a user actually carries in this org, post-scope-intersection and expiry-filtered, with role attribution. Asking about yourself only requires membership; asking about another user requires `users.read`. Same effective grant contributed by N roles produces N rows.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Effective grants for the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectiveGrantsResBody" } } } }, "403": { "description": "Forbidden (not a member, or asking about another user without `users.read`)" }, "422": { "description": "Target user is not a member of this organization" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/users/{user_id}/roles": { "put": { "tags": [ "iam" ], "description": "Replace a member's role attachments with the provided set. Each attachment is a `(role_id, scope?)` pair — the same role may appear multiple times scoped to different resources. Requires `users.edit`.", "operationId": "handler", "parameters": [ { "name": "org_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/ReplaceRolesReqBody" } } }, "required": true }, "responses": { "204": { "description": "Attachments updated" }, "403": { "description": "Insufficient permissions" }, "422": { "description": "Invalid attachment" } }, "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 folders in a knowledge base (use directory=/ for root)", "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": "Scope listing to one folder. Use `\"/\"` for KB root (entries with no parent path).\nOmit to list every file in the knowledge base. Otherwise a normalized path such as `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": "Add a file to a knowledge base via direct upload or remote URL fetch. Provide exactly one of `file` (raw bytes) or `url` (http/https; the server fetches it with an SSRF-hardened client).", "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 adding a file to a knowledge base.\n\nProvide **either** `file` (raw bytes via multipart) **or** `url` (http/https URL\nthe server fetches directly). Exactly one is required.", "required": [ "metadata" ], "properties": { "directory": { "type": [ "string", "null" ], "description": "Optional subdirectory path to organize the file within the knowledge base." }, "file": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "File bytes (multipart `file` field). Mutually exclusive with `url`.", "contentMediaType": "application/octet-stream" }, "metadata": { "type": "object", "description": "Optional JSON metadata to attach to the file." }, "parse": { "type": [ "boolean", "null" ], "description": "Per-upload override for the parse/chunk/embed pipeline. Accepts\n`\"true\"`/`\"false\"` (or `\"1\"`/`\"0\"`). When omitted, the knowledge base's\nauto-processing setting and the file extension decide. `true` forces\nparsing even when the KB has auto-processing off (still credit-gated;\nunsupported extensions silently fall back to stored-as-is). `false`\nstores the file as-is and never runs the pipeline." }, "url": { "type": [ "string", "null" ], "description": "Public http/https URL the server fetches and ingests directly.\nSSRF-hardened (internal hosts blocked). Mutually exclusive with `file`." } } } } }, "required": true }, "responses": { "201": { "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/K2File" } } } }, "409": { "description": "A file with the same name already exists in this directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "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": [] } ] } }, "/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}/policies": { "get": { "tags": [ "k2" ], "description": "List access-shaping rules authored on 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": "table_name", "in": "query", "description": "Restrict to policies that target this exact table.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "enabled", "in": "query", "description": "Restrict to enabled or disabled rules. Omit for both.", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "include_deleted", "in": "query", "description": "When true, also return soft-deleted rules. Defaults to false.", "required": false, "schema": { "type": "boolean" } }, { "name": "page_token", "in": "query", "description": "Pagination cursor. Pass the previous response's `next_page_token`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Policies listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListK2PoliciesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Author a new access-shaping rule on a 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/CreateK2PolicyRequest" } } }, "required": true }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Policy" } } } }, "400": { "description": "Invalid policy body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/policies/enforcement": { "put": { "tags": [ "k2" ], "description": "Enable or disable enforcement of data-governance policies on K2 queries. Requires `k2.policies.manage`. When enabled, queries are rewritten to satisfy active policies or rejected if they cannot be safely constrained. Read the current value from `GET /orgs/{org_id}/k2/{kb_id}` (`governance_enforced` on the KB detail).", "operationId": "put", "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/SetK2GovernanceEnforcementRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated enforcement status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2GovernanceEnforcementResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/policies/{policy_id}": { "get": { "tags": [ "k2" ], "description": "Fetch a single access-shaping rule by id.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Policy" } } } }, "404": { "description": "Policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "k2" ], "description": "Soft-delete an access-shaping rule. Requires `If-Match: \u003Crevision\u003E` from the prior GET. Assignments remain for audit; the rule no longer applies.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Policy deleted" }, "404": { "description": "Policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "`If-Match` revision mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "k2" ], "description": "Update an access-shaping rule. 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": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchK2PolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Policy" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "`If-Match` revision mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/policies/{policy_id}/assignments": { "get": { "tags": [ "k2" ], "description": "List role bindings for an access-shaping rule.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "query", "description": "Restrict to bindings for this role.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "enabled", "in": "query", "description": "Restrict to enabled or disabled bindings. Omit for both.", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "include_revoked", "in": "query", "description": "When true, include revoked bindings. Defaults to false.", "required": false, "schema": { "type": "boolean" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Assignments listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListK2PolicyAssignmentsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Bind an access-shaping rule to a role. Re-attaches if the binding was previously revoked.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2PolicyAssignmentRequest" } } }, "required": true }, "responses": { "201": { "description": "Assignment created or re-attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2PolicyAssignment" } } } }, "400": { "description": "Invalid binding body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Policy or role not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/policies/{policy_id}/assignments/{assignment_id}": { "get": { "tags": [ "k2" ], "description": "Fetch a single role binding for an access-shaping rule.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assignment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Assignment found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2PolicyAssignment" } } } }, "404": { "description": "Assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "k2" ], "description": "Revoke a role binding (soft). Clears active access without deleting the row.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assignment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Assignment revoked" }, "404": { "description": "Assignment not found or already revoked", "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. Requires `k2.manage`.", "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 lacks `k2.manage` or KB not in org", "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 into the knowledge base via direct upload or remote URL fetch", "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": "Multipart form with either a `file` field (raw bytes) OR a `url` field (http/https; the server fetches it). Optional `table_name` overrides the auto-derived table name; optional `mode` is `create` (default), `replace`, or `append`.", "content": { "multipart/form-data": { } } }, "responses": { "200": { "description": "Upload result", "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": { } } }, "429": { "description": "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": [] } ] } }, "/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 in an organization, filtered to those the caller has `projects.read` on. Org admins (with `projects.read` on `projects:*`) see everything; scoped users see only the projects covered by their attachments.", "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" } } } }, "403": { "description": "Caller is not a member of the organization" } }, "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. Requires `projects.read` on `projects:{project_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" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a project. Requires `projects.delete` on `projects:{project_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": { "204": { "description": "Project deleted" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Edit project metadata. Requires `projects.edit` on `projects:{project_id}`.", "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" }, "400": { "description": "Validation failed" }, "403": { "description": "Insufficient permissions" }, "422": { "description": "Name conflicts with an existing project" } }, "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": [ "composer" ], "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. File blocks (`base64` or `url` source) are staged server-side under the session inbox and replaced with a path-reference text block before reaching the model — bytes never enter the conversation context. The agent can then either `Read` the staged file for inspection, `import_kb_table` it to create queryable DuckDB tables (csv/xlsx/parquet/json), or `add_kb_file` to parse + embed it for semantic/keyword search (pdf/docx/md/txt/audio). Legacy `.xls` is not accepted for tabular ingest; save as `.xlsx` first.", "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": { "CSV for KB ingestion": { "value": { "rev": "main", "prompt": [ "Load this into the knowledge base as table 'sales' (append mode)", { "type": "file", "file": { "name": "sales.csv", "source": { "type": "base64", "data": "Y3VzdG9tZXIsYW1vdW50CkFsaWNlLDEwMAo=" } } } ] } }, "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 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": [ "composer" ], "description": "List plan files produced by Composer 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": [ "composer" ], "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": [ "composer" ], "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": "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": [ "composer" ], "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": [ "composer" ], "description": "Stop a running Composer 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}/envs": { "get": { "tags": [ "projects" ], "description": "List environments for a project. Requires `projects.envs.read` on `projects:{project_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": "Environments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvsResBody" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new environment and a matching git branch from the repo default branch. Requires `projects.envs.create` on `projects:{project_id}`.", "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" }, "400": { "description": "Invalid branch name or project has no repository" }, "403": { "description": "Insufficient permissions" }, "409": { "description": "Environment with that name already exists" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}": { "delete": { "tags": [ "projects" ], "description": "Delete an environment. Requires `projects.envs.delete` on `projects:{project_id}:envs:{env_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": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Environment deleted successfully" }, "403": { "description": "Insufficient permissions" } }, "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. Requires `projects.envs.branch` on `projects:{project_id}:envs:{env_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": "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/config": { "patch": { "tags": [ "projects" ], "description": "Update environment deploy config (CPU, memory, ephemeral storage, replica count). Requires `projects.envs.deploy_config` on `projects:{project_id}:envs:{env_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": "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/deploy": { "post": { "tags": [ "projects" ], "description": "Deploy an environment (idempotent on the same rev). Requires `projects.envs.deploy` on `projects:{project_id}:envs:{env_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": "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" }, "400": { "description": "Rev does not exist in the project repo" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/deployments": { "get": { "tags": [ "projects" ], "description": "List deployments for an environment. Requires `projects.envs.read` on `projects:{project_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": "env_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "component_id", "in": "query", "description": "Filter to a single workforce component by its numeric app id\n(the value the SDK reads from `TIMBAL_APP_ID`, also returned\nas `id` on each deployment in the response). Combines with\n`component_uid`: when both are set, rows must match both.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "component_uid", "in": "query", "description": "Filter to a single workforce component by its manifest uid\n(the `_id` field in `timbal.yaml`, also returned as `uid` on\neach deployment in the response). Display name is\ndeliberately not accepted as a filter — it's user-editable\nand not guaranteed unique within a project.", "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\n trigger for this env; falls back to the latest row per\n component when the env has no trigger history.\n * a UUID — return every row produced by that trigger.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Deployments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeploymentsResBody" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/domain": { "patch": { "tags": [ "projects" ], "description": "Attach, replace, or detach the custom domain mapped to an env. Set `domain_id` to assign or reassign; omit (or send null) to unassign. Requires `projects.envs.domain` on `projects:{project_id}:envs:{env_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": "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/logs": { "get": { "tags": [ "projects" ], "description": "Fetch runtime logs for the active deployment of a specific component within an env. `component` selects the component kind (`ui` / `api` / `workforce`); when `component=workforce`, supply exactly one of `component_id` or `component_uid` to identify which one. `workforce` covers agent and workflow components interchangeably. Requires `projects.envs.logs` on `projects:{project_id}:envs:{env_id}`. Always returns the active deployment's logs — a per-deployment override is not exposed yet, as logs from superseded deployments are not retained.", "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": "component", "in": "query", "description": "Which component's logs to fetch. Shared vocabulary with\n`GET /preview/logs` (which 501s on `workforce`). `workforce`\nhere covers agent and workflow components interchangeably.", "required": true, "schema": { "type": "string", "description": "Routing selector for the deployable units a Timbal project owns:\nthe project-level frontend (`Ui`), the project-level backend (`Api`),\nand the N workforce components (`Workforce`, keyed on\n`manifest_id`).\n\nUsed as a `?component=` query parameter on every surface that acts\non one component at a time (`GET /preview/logs`,\n`GET /envs/{env}/logs`, etc.). Wire values are lowercase\n(`ui`/`api`/`workforce`). Surfaces that don't apply to a given\nvariant (e.g. previews don't run workforce components today) reject\nwith `501 NotImplemented` instead of forking the schema — clients\nrely on a single shared vocabulary.\n\nDistinct from [`AppType`], which is a **type discriminator** on\nworkforce rows (`Agent` vs `Workflow`) carried in response payloads.\n`ProjectComponent` collapses both into `Workforce` because every\nsurface that *selects* a workforce component keys on `manifest_id`,\nnot on the Agent-vs-Workflow distinction (the underlying log\npipeline, deployment shape, etc. are identical for both). Use\n[`From\u003CAppType\u003E`] to bridge: any workforce type — including the\nforward-compat `AppType::Unknown` catch-all — maps to\n`ProjectComponent::Workforce`.", "enum": [ "ui", "api", "workforce" ] } }, { "name": "component_id", "in": "query", "description": "Numeric workforce app id (the value the SDK reads from\n`TIMBAL_APP_ID`, also returned as `id` on each deployment in\nthe deployments-list response). XOR with `component_uid`\nwhen `component=workforce`; forbidden for `ui` / `api`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "component_uid", "in": "query", "description": "Workforce manifest uid (the `_id` field in `timbal.yaml`,\nalso returned as `uid` on each deployment in the\ndeployments-list response). XOR with `component_id`.\nDisplay name is deliberately not accepted as a selector —\nit's user-editable and not guaranteed unique within a\nproject.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "start_time", "in": "query", "description": "ms since epoch. Defaults to `end_time - 1h`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "end_time", "in": "query", "description": "ms since epoch. Defaults to now.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "limit", "in": "query", "description": "Defaults to 50.", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page_token", "in": "query", "description": "Pagination cursor from a prior response. Returned only when\ncursor-based pagination is available for the component's\nruntime; ignored otherwise.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Logs fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid query (workforce without exactly one of component_id/component_uid, or ui/api with either set)" }, "403": { "description": "Insufficient permissions, or no deployment found for the requested component" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/metrics/{metric_type}": { "get": { "tags": [ "projects" ], "description": "Query runtime metrics for an environment. Requires `projects.envs.metrics` on `projects:{project_id}:envs:{env_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": "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/stop": { "post": { "tags": [ "projects" ], "description": "Stop an environment. Destructive. Requires `projects.envs.stop` on `projects:{project_id}:envs:{env_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": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Stop initiated" }, "403": { "description": "Insufficient permissions" } }, "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. Requires `projects.notification_rules.read` on `projects:{project_id}`.", "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": "Insufficient permissions" } }, "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": "Insufficient permissions" } }, "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. Requires `projects.notification_rules.manage` on `projects:{project_id}`.", "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": "Insufficient permissions" }, "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. Preview only runs `ui` and `api`\ntoday; passing `workforce` deserializes successfully but the handler\nreturns `501 NotImplemented` (the wire vocabulary is shared with\n`GET /envs/{env}/logs` so clients can use a single\n[`crate::models::ProjectComponent`] across surfaces).", "required": true, "schema": { "type": "string", "description": "Routing selector for the deployable units a Timbal project owns:\nthe project-level frontend (`Ui`), the project-level backend (`Api`),\nand the N workforce components (`Workforce`, keyed on\n`manifest_id`).\n\nUsed as a `?component=` query parameter on every surface that acts\non one component at a time (`GET /preview/logs`,\n`GET /envs/{env}/logs`, etc.). Wire values are lowercase\n(`ui`/`api`/`workforce`). Surfaces that don't apply to a given\nvariant (e.g. previews don't run workforce components today) reject\nwith `501 NotImplemented` instead of forking the schema — clients\nrely on a single shared vocabulary.\n\nDistinct from [`AppType`], which is a **type discriminator** on\nworkforce rows (`Agent` vs `Workflow`) carried in response payloads.\n`ProjectComponent` collapses both into `Workforce` because every\nsurface that *selects* a workforce component keys on `manifest_id`,\nnot on the Agent-vs-Workflow distinction (the underlying log\npipeline, deployment shape, etc. are identical for both). Use\n[`From\u003CAppType\u003E`] to bridge: any workforce type — including the\nforward-compat `AppType::Unknown` catch-all — maps to\n`ProjectComponent::Workforce`.", "enum": [ "ui", "api", "workforce" ] } }, { "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" } } } }, "501": { "description": "`component=workforce` not supported on previews yet", "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 project. Org members see their own runs; `projects.runs.list` is required to list all runs or filter by another user.", "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" } } } }, "403": { "description": "Insufficient permissions" } }, "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). Returned when you initiated the run, or when you hold `projects.runs.list` for the 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": "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" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs/{run_id}/reactions": { "get": { "tags": [ "runs" ], "description": "List reactions for a project run. Returned when you initiated the run, or when you hold `projects.runs.list` for the 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": "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" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "runs" ], "description": "Add a reaction to a project run. Allowed when the caller initiated the run, or when the caller holds `projects.runs.react` for the 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": "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars": { "get": { "tags": [ "projects" ], "description": "List variables for a project. Requires `projects.vars.read` on `projects:{project_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": "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" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new variable. Requires `projects.vars.manage` on `projects:{project_id}`.", "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/batch": { "post": { "tags": [ "projects" ], "description": "Batch create variables. Requires `projects.vars.manage` on `projects:{project_id}`.", "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" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/{var_id}": { "get": { "tags": [ "projects" ], "description": "Get a variable by ID. Requires `projects.vars.read` on `projects:{project_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" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a variable. Requires `projects.vars.manage` on `projects:{project_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": { "204": { "description": "Variable deleted successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a variable. Requires `projects.vars.manage` on `projects:{project_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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVarReqBody" } } }, "required": true }, "responses": { "204": { "description": "Variable updated successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce": { "get": { "tags": [ "projects" ], "description": "List workforce components 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" } } ], "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" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "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" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "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 HTTP to a **running** workforce deployment (agent or workflow). Non-serverless: method and headers pass through; JSON on `/run` or `/stream` may get `context.platform_config` merged for SDK auth-back. Serverless: no upstream URL — the platform runs the workforce for this request. Pass `workforce` as id, manifest UUID, or name; `rev` is the git branch. Response header `X-Timbal-Workforce-Deployment-Type` is `serverless`, `ecs`, or `on-premise`. WebSocket upgrades are not supported.", "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 was unreachable, dropped the connection, or returned an invalid response" }, "504": { "description": "The deployment did not respond within the proxy timeout" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "projects" ], "description": "Proxy HTTP to a **running** workforce deployment (agent or workflow). Non-serverless: method and headers pass through; JSON on `/run` or `/stream` may get `context.platform_config` merged for SDK auth-back. Serverless: no upstream URL — the platform runs the workforce for this request. Pass `workforce` as id, manifest UUID, or name; `rev` is the git branch. Response header `X-Timbal-Workforce-Deployment-Type` is `serverless`, `ecs`, or `on-premise`. WebSocket upgrades are not supported.", "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 was unreachable, dropped the connection, or returned an invalid response" }, "504": { "description": "The deployment did not respond within the proxy timeout" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Proxy HTTP to a **running** workforce deployment (agent or workflow). Non-serverless: method and headers pass through; JSON on `/run` or `/stream` may get `context.platform_config` merged for SDK auth-back. Serverless: no upstream URL — the platform runs the workforce for this request. Pass `workforce` as id, manifest UUID, or name; `rev` is the git branch. Response header `X-Timbal-Workforce-Deployment-Type` is `serverless`, `ecs`, or `on-premise`. WebSocket upgrades are not supported.", "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 was unreachable, dropped the connection, or returned an invalid response" }, "504": { "description": "The deployment did not respond within the proxy timeout" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Proxy HTTP to a **running** workforce deployment (agent or workflow). Non-serverless: method and headers pass through; JSON on `/run` or `/stream` may get `context.platform_config` merged for SDK auth-back. Serverless: no upstream URL — the platform runs the workforce for this request. Pass `workforce` as id, manifest UUID, or name; `rev` is the git branch. Response header `X-Timbal-Workforce-Deployment-Type` is `serverless`, `ecs`, or `on-premise`. WebSocket upgrades are not supported.", "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 was unreachable, dropped the connection, or returned an invalid response" }, "504": { "description": "The deployment did not respond within the proxy timeout" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Proxy HTTP to a **running** workforce deployment (agent or workflow). Non-serverless: method and headers pass through; JSON on `/run` or `/stream` may get `context.platform_config` merged for SDK auth-back. Serverless: no upstream URL — the platform runs the workforce for this request. Pass `workforce` as id, manifest UUID, or name; `rev` is the git branch. Response header `X-Timbal-Workforce-Deployment-Type` is `serverless`, `ecs`, or `on-premise`. WebSocket upgrades are not supported.", "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 was unreachable, dropped the connection, or returned an invalid response" }, "504": { "description": "The deployment did not respond within the proxy timeout" } }, "security": [ { "bearer_auth": [] } ] } }, "/templates": { "get": { "tags": [ "templates" ], "description": "Platform starter catalog for the CLI and create flows.", "operationId": "handler", "parameters": [ { "name": "type", "in": "query", "description": "Filter by template type (`ui`, `api`, `agent`, `workflow`, `project`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "slug", "in": "query", "description": "Filter by slug (e.g. `ui-simple-chat`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Active platform templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResBody" } } } } } } } }, "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" ] } } }, "ActionInfo": { "type": "object", "required": [ "key", "label", "description" ], "properties": { "description": { "type": "string", "description": "One-sentence description for tooltips / role-builder copy." }, "key": { "type": "string", "description": "Stable action key — pass as `RoleGrants.action` when authoring a\ncustom role." }, "label": { "type": "string", "description": "Short, human-readable name for UI display." }, "resource": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActionResourceInfo", "description": "`null` for actions that don't target a sub-resource (e.g.\n`users.read`, `billing.manage`); `RoleGrants.resource` MUST be\n`null` for these. Otherwise the resource shape spec." } ] } } }, "ActionResourceInfo": { "type": "object", "required": [ "kind", "segments", "template" ], "properties": { "kind": { "type": "string", "description": "Stable wire name: `project`, `project_env`, `integration`, etc.\n`integration`. Discriminator the UI may key off when it wants a\nspecific picker variant." }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of segment-kind names (e.g. `[\"projects\", \"envs\"]`).\n`segments.len()` is the number of `{id}` slots in `template`." }, "template": { "type": "string", "description": "Canonical example path with `{id}` placeholders (e.g.\n`\"projects:{id}:envs:{id}\"`). Per-segment `*` wildcards are\naccepted by the evaluator." } } }, "AppType": { "type": "string", "description": "Read/output enum for a workforce component's type.\n\nTolerant on deserialization (`#[serde(other)]`) because this type is reconstructed\nfrom DB rows via two paths that both must not fail on unknown values:\n 1. [`AppType::try_from`] — used by `FromRow` impls reading `OrgsApps.type` directly.\n 2. `serde_json::from_value` — used by handlers that build workforce JSON via\n `json_build_object('type', oa.type, ...)` (runs list, deployments, etc.) and\n then deserialize into `WorkforcePreview` / `RunPreview`.\n\nNew workforce types written by `on_push` (or older ones removed from this enum) must\nnot break list/get endpoints, hence `Unknown` as a catch-all.\n\n**Do not use this for API request bodies** — see [`AppTypeInput`] for the strict\ninput variant that rejects unknowns at the deserialization boundary.", "enum": [ "agent", "workflow", "unknown" ] }, "AttachmentReq": { "type": "object", "description": "A single (role, scope) attachment in the desired state.\n\n`scope` is an optional hierarchical resource path (`projects:42`,\n`projects:42:envs:5`). `null` / omitted = unscoped (the role's grants\napply as-written). The same role may appear multiple times with\ndifferent scopes — the unique key on `OrgUserRoles` is\n`(org, user, role, scope) NULLS NOT DISTINCT`.", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "format": "int64" }, "scope": { "type": [ "string", "null" ] } } }, "BTreeMap": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Replace the column value with a SQL literal expression (e.g. `'***'`).", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "redact" ] }, "value": { "type": "string" } } }, { "type": "object", "description": "Non-keyed hash. Use `pseudonymize` for stronger guarantees.", "required": [ "algorithm", "type" ], "properties": { "algorithm": { "$ref": "#/components/schemas/HashAlg" }, "type": { "type": "string", "enum": [ "hash" ] } } }, { "type": "object", "description": "HMAC-keyed deterministic pseudonym. Stable across queries that share `key_ref`.", "required": [ "key_ref", "algorithm", "type" ], "properties": { "algorithm": { "$ref": "#/components/schemas/HashAlg" }, "key_ref": { "type": "string" }, "type": { "type": "string", "enum": [ "pseudonymize" ] } } }, { "type": "object", "description": "Truncate a string column to `length` characters, optionally pad-suffixed.", "required": [ "length", "type" ], "properties": { "length": { "type": "integer", "format": "int32", "minimum": 0 }, "pad": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "truncate" ] } } }, { "type": "object", "description": "Format-preserving redaction of a payment account number.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "pan_last4" ] } } }, { "type": "object", "description": "Email with the local part hidden (`***@example.com`).", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "email_domain_only" ] } } }, { "type": "object", "description": "Generalize a date or timestamp to the start of the given unit.", "required": [ "unit", "type" ], "properties": { "type": { "type": "string", "enum": [ "date_trunc" ] }, "unit": { "$ref": "#/components/schemas/DateTruncUnit" } } }, { "type": "object", "description": "Cap a numeric column at a maximum value.", "required": [ "max", "type" ], "properties": { "max": { "type": "number", "format": "double" }, "type": { "type": "string", "enum": [ "cap" ] } } }, { "type": "object", "description": "Power-user pattern replacement.", "required": [ "pattern", "replacement", "type" ], "properties": { "pattern": { "type": "string" }, "replacement": { "type": "string" }, "type": { "type": "string", "enum": [ "regexp_replace" ] } } } ], "description": "Per-column transformation applied to query results when this rule matches.\n\nThe full vocabulary is reserved at the API boundary so future deployments\ncan add masks without breaking existing clients. Only `redact`, `hash`,\nand `truncate` are accepted by the current release; the others return\n`400` until enforcement ships." }, "propertyNames": { "type": "string" } }, "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" ] }, "Budget": { "type": "object", "description": "Credit budget on a project (shared pool) or role (per attached user).", "required": [ "budget_type", "limit_credits" ], "properties": { "budget_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_credits": { "type": [ "number", "null" ], "format": "double" }, "id": { "type": [ "integer", "null" ], "format": "int64" }, "limit_credits": { "type": "integer", "format": "int64" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "project_id": { "type": [ "integer", "null" ], "format": "int64" }, "project_name": { "type": [ "string", "null" ] }, "role_id": { "type": [ "integer", "null" ], "format": "int64" }, "role_name": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BudgetListBody": { "type": "object", "required": [ "budgets" ], "properties": { "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } } } }, "BudgetPatchBody": { "type": "object", "description": "Partial budget update — merge rows without touching other configured targets.", "properties": { "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetPatchInput" } } } }, "BudgetPatchInput": { "type": "object", "description": "One budget change in a PATCH merge. `limit_credits: null` removes the budget.", "required": [ "budget_type" ], "properties": { "budget_type": { "type": "string", "description": "`project` or `role`." }, "limit_credits": { "type": [ "integer", "null" ], "format": "int64", "description": "When null, removes the budget for this target. When set, must be \u003E 0." }, "project_id": { "type": [ "integer", "null" ], "format": "int64" }, "role_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "ChannelAction": { "type": "string", "description": "How the rule was wired to `NotificationChannels` for this create call.", "enum": [ "linked", "reused", "created" ] }, "CheckInput": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "Action key (e.g. `projects.envs.deploy`). Discover keys via\n`GET /orgs/{org_id}/iam/actions`. Unknown keys → 422." }, "resource": { "type": [ "string", "null" ], "description": "Concrete resource path for actions whose `resource.kind != \"none\"`\n(e.g. `projects:7:envs:3`). MUST be omitted / null for `none`-kind\nactions. Wildcards (`*`) are rejected — the simulator answers for\na concrete target, not a pattern." } } }, "CheckReqBody": { "type": "object", "required": [ "checks" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckInput" }, "description": "`(action, resource?)` tuples to evaluate. Capped at 50. An empty\nlist is rejected — almost always a client bug." }, "user_id": { "type": [ "string", "null" ], "description": "Target user to evaluate. Defaults to the caller. Passing another\nuser's id requires the `users.read` grant on this org." } } }, "CheckResBody": { "type": "object", "required": [ "user_id", "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CheckResult" }, "description": "One result per input check, in input order." }, "user_id": { "type": "string", "description": "Echoes the evaluated user id (input or caller)." } } }, "CheckResult": { "type": "object", "required": [ "action", "decision", "matched_allows", "matched_denies" ], "properties": { "action": { "type": "string" }, "decision": { "$ref": "#/components/schemas/Decision" }, "matched_allows": { "type": "array", "items": { "$ref": "#/components/schemas/GrantAttribution" }, "description": "Grants that matched as `allow`. Empty for `no_allow` / `superadmin`." }, "matched_denies": { "type": "array", "items": { "$ref": "#/components/schemas/GrantAttribution" }, "description": "Grants that matched as `deny`. Non-empty only for `deny_overrides`." }, "resource": { "type": [ "string", "null" ] } } }, "CloudWatchLogEvent": { "type": "object", "description": "A single log event from CloudWatch Logs.", "required": [ "timestamp", "message", "log_stream" ], "properties": { "log_stream": { "type": "string", "description": "The log stream name this event came from." }, "message": { "type": "string", "description": "The log message content." }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds since epoch." } } }, "ComposeEffort": { "type": "string", "description": "Reasoning effort level for the session.", "enum": [ "low", "medium", "high", "max" ] }, "ComposeMode": { "type": "string", "description": "Composer 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." } } }, "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" } } }, "CreateK2PolicyAssignmentRequest": { "type": "object", "required": [ "role_id" ], "properties": { "combine_mode": { "$ref": "#/components/schemas/K2PolicyCombineMode" }, "enabled": { "type": "boolean" }, "priority": { "type": "integer", "format": "int32" }, "role_id": { "type": "string" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "CreateK2PolicyRequest": { "type": "object", "required": [ "name", "row_filter_dsl" ], "properties": { "audit_level": { "$ref": "#/components/schemas/K2PolicyAuditLevel" }, "break_glass_allowed": { "type": "boolean" }, "column_masks": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BTreeMap" } ] }, "compliance_tags": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean", "description": "Defaults to true; set false to author the rule in a draft state." }, "external_id": { "type": [ "string", "null" ] }, "labels": { "type": "object", "description": "Free-form key/value labels." }, "name": { "type": "string", "description": "Operator-facing label." }, "purpose_tags": { "type": "array", "items": { "type": "string" } }, "row_filter_dsl": { "type": "object", "description": "Row predicate JSON. Stored opaquely in this release." }, "source": { "$ref": "#/components/schemas/K2PolicySource" }, "table_name": { "type": [ "string", "null" ], "description": "Target table within the knowledge base. Omit to apply to every table." } } }, "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" } } }, "CreateRoleReqBody": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/RoleGrant" }, "description": "Grants this role carries. Empty list is allowed (creates a no-op\nrole; admin can extend it later)." }, "name": { "type": "string", "description": "Role name. Must be unique within the org. Reserved system names\n(`admin`, `developer`, `billing`, `member`, `user`) are rejected." } } }, "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." } } }, "CreditGrant": { "type": "object", "description": "A single credit grant on an organization.", "required": [ "uid", "source", "source_metadata", "amount_credits", "consumed_credits", "starts_at", "created_at" ], "properties": { "amount_credits": { "type": "integer", "format": "int64", "description": "Credits awarded by this grant. Always positive; corrections ship as a\nseparate grant rather than a negative amount." }, "consumed_credits": { "type": "integer", "format": "int64", "description": "Credits already drawn from this grant by attributed costs. Bounded by\n`amount_credits`; remaining headroom is `amount_credits - consumed_credits`." }, "created_at": { "type": "string", "format": "date-time", "description": "Grant creation timestamp." }, "exhausted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set once the grant has been fully consumed by usage; `null` while\nthe grant still has unspent credits or hasn't been reconciled yet." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the grant stops being spendable. `null` = never expires." }, "granted_by_user_id": { "type": [ "integer", "null" ], "format": "int64", "description": "User who triggered the grant. `null` for system-issued grants." }, "source": { "type": "string", "description": "Where the grant came from (e.g. `onboarding`, `promo`, `support`,\n`referral`, `refund`)." }, "source_metadata": { "description": "Source-specific payload. Shape depends on `source`." }, "starts_at": { "type": "string", "format": "date-time", "description": "When the grant became (or will become) spendable." }, "uid": { "type": "string", "format": "uuid", "description": "Stable public identifier for this grant." } } }, "DateTruncUnit": { "type": "string", "description": "Granularity for the `date_trunc` mask.", "enum": [ "year", "quarter", "month", "week", "day" ] }, "Decision": { "type": "string", "enum": [ "allow", "deny_overrides", "no_allow", "superadmin" ] }, "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" ] } } }, "DeploymentDetail": { "type": "object", "description": "Public-API representation of a single deployment row, returned by the\nenv-scoped deployments list endpoint. Flattens the runtime config\n(cpu/memory/...) inline rather than nesting under `config` — frontend\nconsumes the fields directly.", "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/DeploymentTarget" }, "type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DeploymentTarget": { "type": "object", "description": "Image/version pointer embedded in [`DeploymentDetail::target`]. Distinct\nfrom [`crate::deployments::models::DeployTarget`] (the domain-layer spec\ncarrying image URIs / platform). This shape is the public-API view of\nwhat a deployment is *of*.", "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" } } }, "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": { "auto_processing_enabled": { "type": [ "boolean", "null" ], "description": "Toggle the automatic parsing, chunking, and embedding pipeline for new file uploads. When false, uploads are stored as-is. Existing files are not affected." }, "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" } } }, "EditProjectReqBody": { "type": "object", "properties": { "banner_url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_public_template": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "use_platform_iam": { "type": [ "boolean", "null" ] } } }, "EditRoleReqBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Pass `null` to clear." }, "grants": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RoleGrant" }, "description": "Full replacement of the role's grant set." }, "name": { "type": [ "string", "null" ], "description": "New role name. Reserved system names rejected." } } }, "EffectiveGrant": { "type": "object", "required": [ "effect", "action", "via" ], "properties": { "action": { "type": "string" }, "effect": { "$ref": "#/components/schemas/GrantEffect" }, "resource": { "type": [ "string", "null" ], "description": "Scope-intersected resource — the pattern the live evaluator would\nmatch against. `null` for `none`-kind actions." }, "via": { "$ref": "#/components/schemas/GrantAttribution", "description": "Attribution: which role + which attachment scope + the original\ngrant resource (pre-intersection)." } } }, "EffectiveGrantsResBody": { "type": "object", "required": [ "user_id", "is_superadmin", "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/EffectiveGrant" }, "description": "One row per `(attachment × grant)` pair, ordered for stable\nrendering. May contain duplicates on `(effect, action, resource)`\nwhen multiple roles contribute the same grant — `via` distinguishes\nthem." }, "is_superadmin": { "type": "boolean", "description": "`true` if the target is a platform superadmin. RBAC is bypassed\nfor every action regardless of `grants[]` (which will be empty\nunless a superadmin happens to also have org role attachments)." }, "user_id": { "type": "string", "description": "Echoes the target user id." } } }, "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 the staged file name on disk\nand for media-type inference. Optional — when omitted, `media_type` must\nbe provided explicitly and a generic name is generated." }, "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": "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" } } }, "GrantAttribution": { "type": "object", "description": "Attribution for a single grant: which role contributed it, what\nattachment-level scope was in effect, and the resource pattern as\nauthored on the role (pre-scope-intersection).\n\nShared by `POST /iam/check` (matched_allows / matched_denies) and\n`GET /iam/users/{id}/effective-grants` (the `via` field on each row).\n\nTo derive the effective resource a grant matched against, compute\n`resource_pattern_intersect(grant_resource, attachment_scope)`. When\n`attachment_scope` is `null`, the effective resource equals\n`grant_resource`.", "required": [ "role_id", "role_name" ], "properties": { "attachment_scope": { "type": [ "string", "null" ] }, "grant_resource": { "type": [ "string", "null" ] }, "role_id": { "type": "string" }, "role_name": { "type": "string" } } }, "GrantEffect": { "type": "string", "description": "Effect of a [`RoleGrant`]. `deny` wins at eval time.", "enum": [ "allow", "deny" ] }, "HashAlg": { "type": "string", "description": "Hash family for `hash` / `pseudonymize` masks.", "enum": [ "sha256", "sha512" ] }, "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": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses to invite to the organization." }, "send_email": { "type": "boolean", "description": "Whether to send an invitation email to each invitee. Defaults to `true`." } } }, "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", "auto_processing_enabled", "governance_enforced", "backup_enabled", "created_at", "updated_at" ], "properties": { "auto_processing_enabled": { "type": "boolean", "description": "When false, file uploads to this knowledge base are stored as-is and skipped by the automatic parsing, chunking, and embedding pipeline." }, "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" ] }, "governance_enforced": { "type": "boolean", "description": "When true, K2 queries are enforced against active governance policies (rewritten or rejected). When false, governance is audit-only. Toggle via `PUT …/k2/{kb_id}/policies/enforcement` (`k2.policies.manage`)." }, "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" } } }, "K2GovernanceEnforcementResponse": { "type": "object", "description": "Whether governance policies are enforced on queries (vs audit-only).", "required": [ "governance_enforced" ], "properties": { "governance_enforced": { "type": "boolean" } } }, "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" } } }, "K2Policy": { "type": "object", "required": [ "id", "kb_id", "name", "enabled", "row_filter_dsl", "compliance_tags", "purpose_tags", "audit_level", "break_glass_allowed", "source", "labels", "revision", "created_at", "updated_at" ], "properties": { "audit_level": { "$ref": "#/components/schemas/K2PolicyAuditLevel" }, "break_glass_allowed": { "type": "boolean", "description": "Whether sessions may bypass the rule via a logged escalation." }, "column_masks": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BTreeMap", "description": "Per-column transformation map. Null means no masks.\n`{\"col\": {\"type\":\"redact\"}}` is the canonical \"hide this column\"." } ] }, "compliance_tags": { "type": "array", "items": { "type": "string" }, "description": "Compliance classifications (e.g. `hipaa.phi`, `pci.pan`)." }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean", "description": "When false, the rule body is inactive everywhere it is bound." }, "external_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "kb_id": { "type": "string" }, "labels": { "type": "object", "description": "Free-form key/value labels." }, "name": { "type": "string", "description": "Operator-facing label." }, "purpose_tags": { "type": "array", "items": { "type": "string" }, "description": "Purpose-of-use bindings (e.g. `treatment`, `research`)." }, "revision": { "type": "integer", "format": "int32", "description": "Optimistic-concurrency token. Echo back via `If-Match` on mutations." }, "row_filter_dsl": { "type": "object", "description": "Row predicate authored as JSON. Stored opaquely in this release." }, "source": { "$ref": "#/components/schemas/K2PolicySource" }, "table_name": { "type": [ "string", "null" ], "description": "Target table within the knowledge base. Null applies to every table." }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2PolicyAssignment": { "type": "object", "required": [ "id", "policy_id", "role_id", "enabled", "priority", "combine_mode", "granted_at", "created_at", "updated_at" ], "properties": { "combine_mode": { "$ref": "#/components/schemas/K2PolicyCombineMode" }, "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "granted_at": { "type": "string", "format": "date-time" }, "granted_by": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "policy_id": { "type": "string" }, "priority": { "type": "integer", "format": "int32" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_by": { "type": [ "string", "null" ] }, "role_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "K2PolicyAuditLevel": { "type": "string", "description": "Audit verbosity for matches against this rule.", "enum": [ "none", "normal", "verbose" ] }, "K2PolicyCombineMode": { "type": "string", "description": "Postgres-RLS-style combination semantic for a policy binding.", "enum": [ "restrictive", "permissive" ] }, "K2PolicySource": { "type": "string", "description": "Provenance of the rule.", "enum": [ "manual", "imported", "derived" ] }, "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" } } }, "ListActionsResBody": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionInfo" }, "description": "Every action this org may grant on a role, in catalog order. Group\non the client by the first dot-segment of `key` (e.g. `users.*` →\n\"Users\", `notification_channels.*` → \"Notification channels\")." } } }, "ListBackupsResponse": { "type": "object", "required": [ "backups" ], "properties": { "backups": { "type": "array", "items": { "$ref": "#/components/schemas/KbBackupResponse" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "ListCreditGrantsResBody": { "type": "object", "required": [ "credit_grants" ], "properties": { "credit_grants": { "type": "array", "items": { "$ref": "#/components/schemas/CreditGrant" } } } }, "ListDeploymentsResBody": { "type": "object", "required": [ "deployments" ], "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentDetail" } } } }, "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" ] } } }, "ListK2PoliciesResponse": { "type": "object", "required": [ "policies" ], "properties": { "next_page_token": { "type": [ "string", "null" ] }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/K2Policy" } } } }, "ListK2PolicyAssignmentsResponse": { "type": "object", "required": [ "assignments" ], "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/K2PolicyAssignment" } }, "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" } } } }, "ListOrgRolesResBody": { "type": "object", "required": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RolePreview" }, "description": "Roles available to this organization — system rows first, then\ncustom rows alphabetically by name." } } }, "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" } } } }, "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" } } }, "ListTemplatesResBody": { "type": "object", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } }, "ListVarsResBody": { "type": "object", "required": [ "vars" ], "properties": { "vars": { "type": "array", "items": { "$ref": "#/components/schemas/Var" } } } }, "ListWorkforceResBody": { "type": "object", "description": "Workforce components on the git branch given by `rev`. The `url` field is set only when the component has a **running** deployment for that branch.", "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", "billing_suspended", "plan_cancel_at_period_end", "created_at", "role" ], "properties": { "banner_url": { "type": [ "string", "null" ] }, "billing_suspended": { "type": "boolean", "description": "`true` when billing is suspended because a finalized invoice charge\nfailed and is still unpaid. While suspended, credit-consuming requests\nare blocked until the outstanding invoice is paid." }, "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" }, "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_cancel_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix timestamp (seconds) of the scheduled plan cancellation; `null` when\nno cancellation is pending." }, "plan_cancel_at_period_end": { "type": "boolean", "description": "`true` between the moment a user schedules a plan cancellation in the\nBilling Portal and the final cancellation taking effect." }, "plan_metadata": { }, "role": { "type": "string" } } }, "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", "roles" ], "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": "Legacy single-role text. Kept for backward compatibility; new\nintegrations should rely on `roles`." }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RolePreview" }, "description": "Roles currently attached to this membership. Empty for pending\ninvites and for members with no role attachments." } } }, "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." } } }, "PatchK2PolicyRequest": { "type": "object", "properties": { "audit_level": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/K2PolicyAuditLevel" } ] }, "break_glass_allowed": { "type": [ "boolean", "null" ] }, "column_masks": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BTreeMap", "description": "Omit to leave unchanged; send `null` to clear all masks." } ] }, "compliance_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "description": { "type": [ "string", "null" ], "description": "Omit to leave unchanged; send `null` to clear." }, "enabled": { "type": [ "boolean", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "labels": { }, "name": { "type": [ "string", "null" ] }, "purpose_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "row_filter_dsl": { "description": "Omit to leave unchanged; send `null` to clear the row filter." }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/K2PolicySource" } ] }, "table_name": { "type": [ "string", "null" ], "description": "Omit to leave unchanged; send `null` to apply to every table." } } }, "PatchMeReqBody": { "type": "object", "properties": { "access_request_data": { "description": "Free-form access-request metadata. Merged (shallow) into the existing\nstored object server-side." }, "lang": { "type": [ "string", "null" ], "description": "Preferred language (ISO 639-1, e.g. `en`)." }, "name": { "type": [ "string", "null" ], "description": "Display name. 1–64 characters. Cannot be set to null." }, "phone": { "type": [ "string", "null" ], "description": "Phone number. Pass null to clear." }, "photo_url": { "type": [ "string", "null" ], "description": "Profile photo URL. Pass null to clear." } } }, "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" } } } }, "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": [ "type" ], "properties": { "agents": { "type": "array", "items": { "type": "string" }, "description": "Agent directory names to scaffold under `workforce/`. Omit for an\nempty workforce directory." }, "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" ] }, "with_ui": { "type": "boolean", "description": "Include the default web UI scaffold. Requires at least one entry in\n`agents` (workflows alone do not use the web UI)." }, "workflows": { "type": "array", "items": { "type": "string" }, "description": "Workflow directory names to scaffold under `workforce/`." } } } ] }, "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" } } }, "ReplaceRolesReqBody": { "type": "object", "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentReq" }, "description": "Desired attachment set for this member. Attachments present today\nbut not in the list are detached; new ones are attached. An empty\nlist detaches everything. Duplicate `(role_id, scope)` pairs are\nignored." } } }, "ReqBody": { "type": "object", "required": [ "name" ], "properties": { "kind": { "type": "string", "description": "Credential kind. Defaults to `api_key`." }, "name": { "type": "string", "description": "Display name (max 64 characters, unique per user)." }, "org_id": { "type": [ "string", "null" ], "description": "Organization to bind the credential to. Set alone for an org-only key\n(full access within that org); required when `scope` is set. Omit with\n`scope` for a full-access key across all your orgs." }, "scope": { "type": [ "string", "null" ], "description": "IAM scope path (e.g. `projects:42`) restricting the credential to one\nresource subtree. Requires `org_id`. Omit for an org-only or full-access key." } } }, "ResBody": { "type": "object", "required": [ "token" ], "properties": { "token": { "$ref": "#/components/schemas/Token" } } }, "Response": { "type": "object", "description": "Resolved window echoed back so the client can paginate / refresh\nwithout re-deriving the defaults the server applied.", "required": [ "events", "start_time", "end_time", "limit" ], "properties": { "end_time": { "type": "integer", "format": "int64" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CloudWatchLogEvent" } }, "limit": { "type": "integer", "minimum": 0 }, "next_page_token": { "type": [ "string", "null" ] }, "start_time": { "type": "integer", "format": "int64" } } }, "Role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "RoleDetail": { "type": "object", "description": "A role with its full grant set.", "required": [ "id", "name", "source", "grants", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/RoleGrant" }, "description": "Domain grants this role carries. May be empty." }, "id": { "type": "string" }, "name": { "type": "string" }, "source": { "$ref": "#/components/schemas/RoleSource" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RoleGrant": { "type": "object", "description": "A single grant on a role — `(effect, action, resource?, condition?)`.\n\n`resource` is `None` for `ResourceKind::None` actions (`users.read`),\nor a hierarchical path like `projects:42:envs:5` (or `projects:42:envs:*`)\nfor typed actions.\n\n`condition` is opaque JSON reserved for future ABAC; ignored by the\nevaluator in v1, accepted and stored as-is by writes.", "required": [ "effect", "action" ], "properties": { "action": { "type": "string" }, "condition": { }, "effect": { "$ref": "#/components/schemas/GrantEffect" }, "resource": { "type": [ "string", "null" ] } } }, "RoleInUseConflict": { "type": "object", "description": "Returned when `DELETE /orgs/{org_id}/iam/roles/{role_id}` is called while\nthe role is still attached to one or more members.", "required": [ "code", "message", "user_ids" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Members currently holding this role via `OrgUserRoles`." } } }, "RolePreview": { "type": "object", "description": "Compact role record returned by listing endpoints. Fetch a single\nrole to retrieve the full grant set.", "required": [ "id", "name", "source", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string", "description": "Role name. Unique per `(org_id)` for custom roles, globally unique\nfor system roles." }, "source": { "$ref": "#/components/schemas/RoleSource" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RoleSource": { "type": "string", "description": "Whether a role is a built-in preset or defined by the organization.\n`system` roles are read-only; `custom` roles can be edited or deleted\nby an organization admin.", "enum": [ "system", "custom" ] }, "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" } } }, "SetK2GovernanceEnforcementRequest": { "type": "object", "required": [ "governance_enforced" ], "properties": { "governance_enforced": { "type": "boolean", "description": "When true, queries are rewritten to satisfy active policies or rejected\nif they cannot be safely constrained. When false, governance is audit-only." } } }, "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`)." } } }, "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." } } }, "Template": { "type": "object", "required": [ "id", "slug", "type", "name", "github_ref", "target_path", "is_default" ], "properties": { "banner_url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "github_ref": { "type": "string", "description": "Git branch or tag name used when building `tarball_url`." }, "github_repo_full_name": { "type": [ "string", "null" ], "description": "GitHub `owner/repo` for blueprint templates. Omitted for embedded scaffolds." }, "id": { "type": "integer", "format": "int64" }, "is_default": { "type": "boolean", "description": "When true, this row is the default pick for its `type` within the catalog scope." }, "name": { "type": "string" }, "slug": { "type": "string", "description": "Stable identifier for CLI and UI selection (e.g. `ui-simple-chat`)." }, "tarball_url": { "type": [ "string", "null" ], "description": "GitHub archive tarball URL derived from `github_repo_full_name` and `github_ref`." }, "target_path": { "type": "string", "description": "Project-relative directory to extract into (e.g. `ui`, `api`, `.`)." }, "type": { "type": "string", "description": "Starter category: `ui`, `api`, `agent`, `workflow`, or `project`." } } }, "Token": { "type": "object", "description": "User credential (API key or future kinds).", "required": [ "id", "kind", "name", "hint", "createdAt" ], "properties": { "createdAt": { "type": "integer", "format": "int64", "description": "Creation time as epoch milliseconds." }, "hint": { "type": "string", "description": "Masked secret for display (prefix and suffix only)." }, "id": { "type": "string", "description": "Credential identifier." }, "kind": { "type": "string", "description": "Credential kind (currently `api_key`)." }, "name": { "type": "string", "description": "Display name chosen at creation." }, "org_id": { "type": [ "string", "null" ], "description": "Organization the credential is scoped to. Omitted for legacy full-access keys." }, "scope": { "type": [ "string", "null" ], "description": "IAM scope path (e.g. `projects:42`). Omitted for legacy full-access keys." }, "secret": { "type": [ "string", "null" ], "description": "Full secret value. Present only in the create response; omitted on list." } } }, "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" ] } } }, "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": "composer", "description": "Composer — AI coding agent sessions" }, { "name": "files", "description": "File operations" }, { "name": "iam", "description": "IAM — actions, roles, users, and authorization introspection" }, { "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" }, { "name": "templates", "description": "Platform starter catalog" }, { "name": "users", "description": "Authenticated user profile" } ] }