{ "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": "Get a single ACE job by id.", "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 ACE job.", "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": "Retry a failed, cancelled, or errored ACE job.", "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 for an 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 for an 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 endpoint for an 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 for temporary staging.", "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.", "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/photo": { "put": { "tags": [ "users" ], "description": "Upload and set the authenticated user's profile picture.", "operationId": "handler", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Multipart form schema for the OpenAPI doc only (the handler reads the raw\n`file` part directly).", "required": [ "file" ], "properties": { "file": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Profile picture bytes. Must be an image; the type is detected from the\nfile content, not the filename or declared content type.", "contentMediaType": "application/octet-stream" } } } } }, "required": true }, "responses": { "200": { "description": "Profile picture updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhotoResBody" } } } }, "400": { "description": "Missing file or unsupported image type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "413": { "description": "Image too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "users" ], "description": "Clear the authenticated user's profile picture.", "operationId": "delete", "responses": { "204": { "description": "Profile picture cleared", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } } }, "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": { "post": { "tags": [ "orgs" ], "description": "Create a new organization.", "operationId": "handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgReqBody" } } }, "required": true }, "responses": { "204": { "description": "Organization created successfully", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "429": { "description": "Org limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "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.", "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.", "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 partial credit budget changes for the organization.", "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": { "get": { "tags": [ "billing" ], "description": "Get overage credit usage for the current billing period.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Overage usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageSummary" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "billing" ], "description": "Update overage billing settings 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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Unprocessable entity", "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}/connectors": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors`", "description": "List connectors for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connectors listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResBody" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/enrollment-tokens": { "post": { "tags": [ "connectors" ], "summary": "`POST /orgs/{org_id}/connectors/enrollment-tokens`", "description": "Create a connector enrollment token.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReqBody" } } }, "required": true }, "responses": { "201": { "description": "Token minted (raw value shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResBody" } } } }, "400": { "description": "Invalid TTL" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/jobs": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/jobs`", "description": "List connector jobs for the organization.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "query", "description": "Filter to a single connector.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Jobs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsRes" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/syncs": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/syncs`", "description": "List connector syncs for the organization.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "query", "description": "Filter to a single connector.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Syncs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSyncsRes" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/{connector_id}`", "description": "Get a connector by id.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connector details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResBody" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Connector not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/browse/columns": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/{connector_id}/browse/columns`", "description": "List columns for a remote table.", "operationId": "columns", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_ref", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "schema", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "table", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Columns listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnsRes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Connector not found" }, "422": { "description": "Connector offline / refused / timed out" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/browse/connections": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/{connector_id}/browse/connections`", "description": "List remote connections available to a connector.", "operationId": "connections", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection refs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionsRes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Connector not found" }, "422": { "description": "Connector offline / refused / timed out" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/browse/tables": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/{connector_id}/browse/tables`", "description": "List remote tables available to a connector.", "operationId": "tables", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_ref", "in": "query", "description": "Connection ref on the node (from `/browse/connections`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tables listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TablesRes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Connector not found" }, "422": { "description": "Connector offline / refused / timed out" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/jobs": { "post": { "tags": [ "connectors" ], "summary": "`POST /orgs/{org_id}/connectors/{connector_id}/jobs`", "description": "Dispatch a job to a connector.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchReq" } } }, "required": true }, "responses": { "202": { "description": "Job accepted and dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchRes" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Forbidden" }, "404": { "description": "Connector or KB not found" }, "422": { "description": "Unprocessable entity" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/rebind": { "post": { "tags": [ "connectors" ], "summary": "`POST /orgs/{org_id}/connectors/{connector_id}/rebind`", "description": "Rebind a connector to a different knowledge base.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebindReq" } } }, "required": true }, "responses": { "202": { "description": "Rebind dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebindRes" } } } }, "400": { "description": "Invalid URL" }, "403": { "description": "Forbidden" }, "404": { "description": "Connector not found" }, "422": { "description": "Connector offline (`code: connector_offline`)" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/syncs": { "post": { "tags": [ "connectors" ], "summary": "`POST /orgs/{org_id}/connectors/{connector_id}/syncs`", "description": "Create a connector sync configuration.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSyncReq" } } }, "required": true }, "responses": { "201": { "description": "Sync created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSyncRes" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Forbidden" }, "404": { "description": "Connector or KB not found" }, "422": { "description": "Source unsupported by connector" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/syncs/{sync_id}": { "get": { "tags": [ "connectors" ], "summary": "`GET /orgs/{org_id}/connectors/{connector_id}/syncs/{sync_id}`", "description": "Get a connector sync by id.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncDetailRes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Sync not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "connectors" ], "summary": "`DELETE /orgs/{org_id}/connectors/{connector_id}/syncs/{sync_id}`", "description": "Delete a connector sync.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sync deleted" }, "403": { "description": "Forbidden" }, "404": { "description": "Sync not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "connectors" ], "summary": "`PATCH /orgs/{org_id}/connectors/{connector_id}/syncs/{sync_id}`", "description": "Update a connector sync.", "operationId": "update", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSyncReq" } } }, "required": true }, "responses": { "204": { "description": "Sync updated" }, "400": { "description": "Invalid request" }, "403": { "description": "Forbidden" }, "404": { "description": "Sync not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/connectors/{connector_id}/update": { "post": { "tags": [ "connectors" ], "summary": "`POST /orgs/{org_id}/connectors/{connector_id}/update`", "description": "Trigger a connector software update.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReq" } } }, "required": true }, "responses": { "200": { "description": "Connector already on the target version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRes" } } } }, "202": { "description": "Update dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Connector or release version not found" }, "422": { "description": "Connector offline or too old to update remotely" } }, "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}/content/sign": { "post": { "tags": [ "content" ], "description": "Refresh a signed URL for stored content.", "operationId": "sign", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignContentRequest" } } }, "required": true }, "responses": { "200": { "description": "Freshly-signed content URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignContentResponse" } } } }, "400": { "description": "Malformed request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "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 custom domain with current DNS and 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 grantable IAM actions for the organization.", "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": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/check": { "post": { "tags": [ "iam" ], "description": "Simulate authorization checks against a user's effective grants.", "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" }, "422": { "description": "Invalid request" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/roles": { "get": { "tags": [ "iam" ], "description": "List system and custom roles for the organization.", "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": "Unprocessable entity" } }, "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 organization role.", "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": "Unprocessable entity" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "iam" ], "description": "Partially update a custom organization role.", "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": "Unprocessable entity" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/users": { "get": { "tags": [ "iam" ], "description": "List members of an organization.", "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 one or more members 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": "Member(s) removed successfully", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/users/roles": { "put": { "tags": [ "iam" ], "description": "Replace role attachments for multiple members in one request.", "operationId": "bulk_handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkReplaceRolesReqBody" } } }, "required": true }, "responses": { "204": { "description": "Attachments updated", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Insufficient permissions" }, "422": { "description": "Invalid request" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/users/{user_id}/effective-grants": { "get": { "tags": [ "iam" ], "description": "List a member's effective IAM grants in the organization.", "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" }, "422": { "description": "Target user is not a member" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/iam/users/{user_id}/roles": { "put": { "tags": [ "iam" ], "description": "Replace a member's role attachments.", "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}/identity-providers": { "get": { "tags": [ "orgs" ], "description": "List SSO identity connections for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connections listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIdentityProvidersResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Create an SSO or directory identity connection for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdentityProviderReqBody" } } }, "required": true }, "responses": { "201": { "description": "Connection created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "409": { "description": "provider_key already in use" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/identity-providers/{provider_id}": { "get": { "tags": [ "orgs" ], "description": "Get an SSO identity connection by id.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "orgs" ], "description": "Delete an SSO identity connection.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "orgs" ], "description": "Update an SSO identity connection.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdentityProviderReqBody" } } }, "required": true }, "responses": { "200": { "description": "Updated connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/identity-providers/{provider_id}/default-role": { "put": { "tags": [ "orgs" ], "description": "Set or clear the SSO connection's default just-in-time role.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultRoleReqBody" } } }, "required": true }, "responses": { "200": { "description": "Updated connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/identity-providers/{provider_id}/group-mappings": { "get": { "tags": [ "orgs" ], "description": "List external-group to role mappings for a connection", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mappings listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGroupRoleMappingsResBody" } } } }, "404": { "description": "Connection not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Map an external IdP group to a role for this connection", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupRoleMappingReqBody" } } }, "required": true }, "responses": { "201": { "description": "Mapping created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupRoleMappingView" } } } }, "404": { "description": "Connection not found" }, "409": { "description": "Group already mapped for this connection" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/identity-providers/{provider_id}/group-mappings/{mapping_id}": { "delete": { "tags": [ "orgs" ], "description": "Delete a group-to-role mapping", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mapping_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "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.", "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", "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": "Conflict", "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 directory.", "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 the immediate contents of one folder, like a file browser:\nthe files directly in it plus a folder entry per immediate subfolder (one\nlevel only). Use `\"/\"` for the KB root. Omit to get a flat dump of every\nfile in the knowledge base at all depths. Otherwise a normalized path such\nas `docs/reports`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Case-insensitive substring filter on entry name. When set, results are a\nflat recursive search: `directory` scopes the search to that folder's\nsubtree (omit or use `\"/\"` to search the whole knowledge base) and no\nfolder entries are synthesized.", "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 by upload or URL.", "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` (multipart bytes) or `url` (http/https). Exactly one is required.", "required": [ "metadata" ], "properties": { "directory": { "type": [ "string", "null" ], "description": "Optional subdirectory path 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": "When set, overrides whether the file is parsed and embedded on upload." }, "url": { "type": [ "string", "null" ], "description": "Public http/https URL for the server to fetch and ingest. 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": "Conflict", "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.", "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 into a knowledge base file.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Chunk" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict", "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 from a knowledge base file.", "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": "Precondition failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "k2" ], "description": "Edit a chunk's content, embedding, or page range.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2Chunk" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "Precondition failed", "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/governance-mode": { "put": { "tags": [ "k2" ], "description": "Set query-time governance mode for a knowledge base.", "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/SetK2GovernanceModeRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated governance mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2GovernanceModeResponse" } } } } }, "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 on 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": "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": "Precondition failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "k2" ], "description": "Update an access-shaping rule on a knowledge base.", "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": "Precondition failed", "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.", "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 on an access-shaping rule.", "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}/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 completed backup.", "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", "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", "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 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": { "description": "Multipart form with a file upload or a remote URL.", "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": "List notification channels for the organization.", "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": "Forbidden", "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 created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationChannelOut" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "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": "Delete a notification channel for the organization.", "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 force-delete flag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteChannelBody" } } }, "required": true }, "responses": { "204": { "description": "Channel deleted" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict", "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": "Forbidden", "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": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "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": "Delete an org-wide notification rule.", "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/photo": { "put": { "tags": [ "orgs" ], "description": "Upload and set the organization's logo.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Multipart form schema for the OpenAPI doc only (the handler reads the raw\n`file` part directly).", "required": [ "file" ], "properties": { "file": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Org logo bytes. Must be an image; the type is detected from the file\ncontent, not the filename or declared content type.", "contentMediaType": "application/octet-stream" } } } } }, "required": true }, "responses": { "200": { "description": "Org logo updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgPhotoResBody" } } } }, "400": { "description": "Missing file or unsupported image type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "413": { "description": "Image too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "orgs" ], "description": "Clear the organization's logo.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Org logo cleared", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects": { "get": { "tags": [ "projects" ], "description": "List projects in an organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "Response detail level: \"list\" (default) returns a lightweight preview, \"full\" returns all project details", "required": false, "schema": { "type": "string", "enum": [ "list", "full" ] } } ], "responses": { "200": { "description": "Projects listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectsResBody" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectReqBody" } } }, "required": true }, "responses": { "200": { "description": "Project created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}": { "get": { "tags": [ "projects" ], "description": "Get a project by ID.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDetail" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Project deleted" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Edit project metadata.", "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}/auth": { "get": { "tags": [ "projects" ], "description": "Get app sign-in settings for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "App auth settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAuthSettings" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Toggle app sign-in 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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAuthSettingsReqBody" } } }, "required": true }, "responses": { "204": { "description": "Settings updated", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/auth/providers/{provider}": { "put": { "tags": [ "projects" ], "description": "Enable, disable, or configure an app sign-in provider.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "path", "description": "Sign-in method key (for example `email`, `google`, `microsoft`, `github`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAuthProviderReqBody" } } }, "required": true }, "responses": { "204": { "description": "Provider updated", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "400": { "description": "Unknown provider key" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/duplicate": { "post": { "tags": [ "projects" ], "description": "Duplicate a project, copying its code and knowledge base structure.", "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/DuplicateProjectReqBody" } } }, "required": true }, "responses": { "200": { "description": "Project duplicated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs": { "get": { "tags": [ "projects" ], "description": "List environments for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Environments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvsResBody" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new environment 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" } } ], "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.", "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 source branch for an environment.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnvBranchReqBody" } } }, "required": true }, "responses": { "200": { "description": "Branch updated successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/config": { "patch": { "tags": [ "projects" ], "description": "Update deploy configuration for an environment.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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 to a revision.", "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.", "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 a custom domain for an environment.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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 a deployed project component.", "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": "Bad request" }, "403": { "description": "Forbidden" } }, "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.", "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 a running environment.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Stop initiated" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/k2": { "put": { "tags": [ "projects" ], "description": "Link a knowledge base to a project.", "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 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": "List notification rules scoped to a project.", "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": "Forbidden" } }, "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": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/notifications/rules/{rule_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete a project-scoped notification rule", "description": "Delete a project-scoped notification rule.", "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": "Forbidden" }, "404": { "description": "Not found", "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.", "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": "roots", "in": "query", "description": "When `true`, return only thread roots (runs that start a conversation, i.e.\nhave no parent). For a root run, `group_id` equals its own `id`.", "required": false, "schema": { "type": "boolean" } }, { "name": "sort_by", "in": "query", "description": "Sort field (`id`, `created_at`, `duration_ms`, `cost_usd`, `cost_credits`)", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunSortBy" } ] } }, { "name": "sort_order", "in": "query", "description": "Sort direction (`asc` or `desc`; default `desc`)", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SortOrder" } ] } }, { "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 project run by id or idempotency key.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetail" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs/{run_id}/reactions": { "get": { "tags": [ "runs" ], "description": "List reactions on a project run.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } }, { "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.", "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.", "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 project variable.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVarReqBody" } } }, "required": true }, "responses": { "201": { "description": "Variable created successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/batch": { "post": { "tags": [ "projects" ], "description": "Batch create project variables.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateVarsReqBody" } } }, "required": true }, "responses": { "201": { "description": "Variables created successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/{var_id}": { "get": { "tags": [ "projects" ], "description": "Get a project variable by ID.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Variable details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Var" } } } }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a project variable.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Variable deleted successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a project variable.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVarReqBody" } } }, "required": true }, "responses": { "204": { "description": "Variable updated successfully" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce": { "get": { "tags": [ "projects" ], "description": "List workforce components on a branch revision.", "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 on a branch revision.", "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 a branch revision.", "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.", "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 an ACE for a workforce component and enqueue its initial generation job.", "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 linked to a workforce component.", "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 requests to a deployed workforce component.", "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": "Sub-path on the deployment server.", "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": "Bad gateway" }, "504": { "description": "Gateway timeout" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "projects" ], "description": "Proxy HTTP requests to a deployed workforce component.", "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": "Sub-path on the deployment server.", "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": "Bad gateway" }, "504": { "description": "Gateway timeout" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Proxy HTTP requests to a deployed workforce component.", "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": "Sub-path on the deployment server.", "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": "Bad gateway" }, "504": { "description": "Gateway timeout" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Proxy HTTP requests to a deployed workforce component.", "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": "Sub-path on the deployment server.", "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": "Bad gateway" }, "504": { "description": "Gateway timeout" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Proxy HTTP requests to a deployed workforce component.", "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": "Sub-path on the deployment server.", "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": "Bad gateway" }, "504": { "description": "Gateway timeout" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/scim-tokens": { "get": { "tags": [ "orgs" ], "description": "List SCIM tokens for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SCIM tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScimTokensResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Create a SCIM bearer token for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimTokenReqBody" } } }, "required": true }, "responses": { "201": { "description": "Token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimTokenResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/scim-tokens/{token_id}": { "delete": { "tags": [ "orgs" ], "description": "Revoke a SCIM token", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Token revoked" }, "404": { "description": "Token not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/templates": { "get": { "tags": [ "templates" ], "description": "Public project template catalog available to this organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published public project templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResBody" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AceJobView": { "type": "object", "description": "Public view of a background job against an ACE.", "required": [ "uid", "kind", "status", "iteration_count", "tool_call_count", "queued_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "error_message": { "type": [ "string", "null" ], "description": "Present when the job terminated unsuccessfully (`failed`, `error`, `cancelled`)." }, "iteration_count": { "type": "integer", "format": "int32" }, "kind": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "tool_call_count": { "type": "integer", "format": "int32" }, "uid": { "type": "string", "format": "uuid" } } }, "AcePolicy": { "type": "object", "description": "A single policy entry.\n\n- `id` is the human-readable stable key (e.g. `\"ev_subsidy\"`).\n- `requires` / `provides` / `tool_action` are kept as raw JSON because\n their shape is still evolving.", "required": [ "id", "condition", "action" ], "properties": { "action": { "type": "string" }, "condition": { "type": "string" }, "id": { "type": "string" }, "provides": { "type": "array", "items": { "type": "string" } }, "requires": { }, "tool_action": { } } }, "AceVar": { "type": "object", "description": "A single variable declaration.\n\n- `id` is the human-readable stable key (e.g. `\"flow\"`, `\"presupuesto_max\"`).\n- `choices`, when present, restricts the variable to an enum of string values.\n- `match_mode` tweaks how the matcher compares extracted vs expected values\n (e.g. `\"semantic\"`).", "required": [ "id" ], "properties": { "choices": { "type": [ "array", "null" ], "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "match_mode": { "type": [ "string", "null" ] } } }, "ActionInfo": { "type": "object", "required": [ "key", "label", "description" ], "properties": { "description": { "type": "string", "description": "One-sentence description of what the action allows." }, "key": { "type": "string", "description": "Action key to grant on a role." }, "label": { "type": "string", "description": "Short label for display." }, "resource": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActionResourceInfo", "description": "Resource shape for typed actions, or null when the action is org-wide." } ] } } }, "ActionResourceInfo": { "type": "object", "required": [ "kind", "segments", "template" ], "properties": { "kind": { "type": "string", "description": "Stable wire name for the resource kind (for example `project` or `project_env`)." }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Ordered segment names that make up the resource path template." }, "template": { "type": "string", "description": "Example resource path with `{id}` placeholders." } } }, "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" ] } } }, "AuthProviderState": { "type": "object", "description": "State of a single sign-in method on the settings screen.", "required": [ "provider", "enabled", "configured" ], "properties": { "configured": { "type": "boolean", "description": "Whether provider-specific settings (e.g. a bring-your-own OAuth app) have\nbeen supplied. `false` means the method runs on Timbal's defaults." }, "enabled": { "type": "boolean", "description": "Whether end users can sign in with this method." }, "provider": { "type": "string", "description": "Provider key (for example `email`, `google`, `microsoft`, `github`)." } } }, "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": [ "string", "null" ] }, "limit_credits": { "type": "string" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "project_id": { "type": [ "string", "null" ] }, "project_name": { "type": [ "string", "null" ] }, "role_id": { "type": [ "string", "null" ] }, "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": [ "string", "null" ], "description": "When null, removes the budget for this target. When set, must be \u003E 0." }, "project_id": { "type": [ "string", "null" ] }, "role_id": { "type": [ "string", "null" ] } } }, "BulkReplaceRolesReqBody": { "type": "object", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserRolesReq" }, "description": "Per-member desired attachment sets. Applied atomically: if any entry\nis rejected the whole request fails and nothing is written. A member\nmay not appear twice and may not be the caller." } } }, "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": "IAM action key (for example `projects.envs.deploy`)." }, "resource": { "type": [ "string", "null" ], "description": "Concrete resource path for typed actions, or omit for org-wide actions." } } }, "CheckReqBody": { "type": "object", "required": [ "checks" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckInput" }, "description": "Authorization checks to evaluate. Up to 50 per request." }, "user_id": { "type": [ "string", "null" ], "description": "Target user to evaluate. Defaults to the caller." } } }, "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." } } }, "ColumnView": { "type": "object", "required": [ "name", "data_type", "nullable", "cursor_candidate" ], "properties": { "cursor_candidate": { "type": "boolean", "description": "Usable as the extract job's `cursor_column`." }, "data_type": { "type": "string" }, "name": { "type": "string" }, "nullable": { "type": "boolean" } } }, "ColumnsRes": { "type": "object", "required": [ "columns" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnView" } } } }, "ConnectionsRes": { "type": "object", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "type": "string" }, "description": "Connection refs configured on the node (names only; DSNs stay local)." } } }, "ConnectorView": { "type": "object", "required": [ "id", "capabilities", "connected", "online", "enrolled_at" ], "properties": { "arch": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "connected": { "type": "boolean", "description": "Last known DB-side connected flag (survives monolith restarts)." }, "enrolled_at": { "type": "string", "format": "date-time" }, "hostname": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "online": { "type": "boolean", "description": "Live socket on *this* monolith instance right now." }, "os": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] } } }, "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" } } }, "CreateGroupRoleMappingReqBody": { "type": "object", "description": "Add an external-group → role mapping to a connection.", "required": [ "external_group", "role_id" ], "properties": { "external_group": { "type": "string", "description": "External group identifier exactly as the IdP emits it." }, "role_id": { "type": "integer", "format": "int64", "description": "Target Timbal role id. Accepts a number or a stringified id." } } }, "CreateIdentityProviderReqBody": { "type": "object", "description": "Create an OIDC identity-provider connection for an org.", "required": [ "provider_key" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "Email domains eligible for JIT auto-provisioning. Empty = no JIT." }, "client_id": { "type": [ "string", "null" ], "description": "OAuth client id registered with the IdP. Required for `oidc`." }, "client_secret": { "type": [ "string", "null" ], "description": "OAuth client secret. Sealed at rest with the org DEK; never returned.\nRequired for `oidc`." }, "default_role_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional catch-all role for JIT members whose group claim matched no\nmapping. When omitted, such members are added with no role (a bare\nmember, pending an admin grant) rather than an implicit default.\nAccepts a number or a stringified id (`2227` or `\"2227\"`)." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable label for the login button / admin UI." }, "enabled": { "type": [ "boolean", "null" ], "description": "Whether the connection is active. Defaults to true." }, "groups_claim": { "type": [ "string", "null" ], "description": "Claim carrying group membership. Defaults to `groups`." }, "issuer": { "type": [ "string", "null" ], "description": "IdP issuer / discovery base; `/.well-known/openid-configuration` is\nfetched from here. **Required for `oidc`; ignored for `directory`.**", "example": "https://acme.okta.com" }, "kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IdentityProviderKind", "description": "Connection kind. Defaults to `oidc` (backward-compatible). Use\n`directory` for a login-less SCIM connection: no issuer/client creds\nrequired, it only anchors SCIM group→role mappings + the catch-all role." } ] }, "provider_key": { "type": "string", "description": "Stable, URL-safe handle used in the login URL\n(`/auth/sso/{provider_key}`) and the signed OAuth state. Lowercase\nletters/digits/hyphens; must not collide with the built-in social\nproviders. Globally unique.", "example": "acme" }, "scopes": { "type": [ "string", "null" ], "description": "Space-separated scopes. Defaults to `openid email profile`." } } }, "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" } } }, "CreateOrgReqBody": { "type": "object", "required": [ "name" ], "properties": { "livemode": { "type": [ "boolean", "null" ], "description": "Stripe live mode for billing. Superadmin-only; ignored for other callers." }, "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." } } }, "CreateScimTokenReqBody": { "type": "object", "description": "Create a SCIM token for an org.", "properties": { "label": { "type": [ "string", "null" ], "description": "Human label for the admin UI (e.g. \"Entra prod\")." }, "provider_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional IdP connection to bind this token to. When set, SCIM group\npushes resolve roles through that connection's group→role mappings;\nwhen omitted the token does membership-only SCIM (auto add/remove)." } } }, "CreateScimTokenResBody": { "allOf": [ { "$ref": "#/components/schemas/ScimTokenView" }, { "type": "object", "required": [ "token", "base_url" ], "properties": { "base_url": { "type": "string", "description": "The base URL the IdP should target, e.g. `https://api.timbal.ai/scim/v2`." }, "token": { "type": "string", "description": "The bearer token to paste into the IdP's SCIM config. Shown once." } } } ], "description": "Create response: the only time the plaintext token is ever returned. The\ncaller (IdP admin) must copy `token` now — it can't be retrieved later." }, "CreateSyncReq": { "type": "object", "required": [ "kb_id", "dest_table", "source", "interval_secs" ], "properties": { "dest_table": { "type": "string", "description": "Destination table inside the KB. Must not pre-exist: the first run\ncreates it, later runs append." }, "interval_secs": { "type": "integer", "format": "int64", "description": "Seconds between run *starts*. The scheduler ticks every 30s, so smaller\nvalues effectively mean \"every tick\"." }, "kb_id": { "type": "integer", "format": "int64", "description": "Target KB (numeric id, same as the `/k2` routes)." }, "name": { "type": [ "string", "null" ], "description": "Operator label." }, "source": { "$ref": "#/components/schemas/SourceBody" } } }, "CreateSyncRes": { "type": "object", "required": [ "sync_id" ], "properties": { "sync_id": { "type": "string" } } }, "CreateVarReqBody": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "description": { "type": [ "string", "null" ] }, "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/VarType" }, "value": { "type": "string" } } }, "CreateWorkforceReqBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Optional display name for the new component. If omitted, a unique name is generated." }, "type": { "type": "string", "description": "Either `agent` or `workflow`. Defaults to `agent`." } } }, "CreateWorkforceResponse": { "type": "object", "description": "Response returned when a new workforce component is created.", "required": [ "id", "uid", "type", "name", "path" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string", "description": "Path to the new component inside the repository worktree (for example `workforce/my-agent`)." }, "type": { "type": "string" }, "uid": { "type": "string", "description": "Identifier assigned in the project manifest for this component." } } }, "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" } } }, "DispatchReq": { "type": "object", "required": [ "kb_id", "dest_table", "source" ], "properties": { "batch_rows": { "type": [ "integer", "null" ], "format": "int32", "description": "Target rows per batch. Defaults to 5000.", "minimum": 0 }, "cursor": { "type": [ "object", "null" ], "description": "Resume checkpoint; omit for a full initial extract." }, "dest_table": { "type": "string", "description": "Destination table inside the KB." }, "kb_id": { "type": "integer", "format": "int64", "description": "Target KB (numeric id, same as the `/k2` routes)." }, "mode": { "type": [ "string", "null" ], "description": "`create` | `append` | `replace`. Defaults to `create`." }, "pacing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PacingBody", "description": "Optional load-shaping for gentle extraction against busy source systems.\nOmit for no throttle." } ] }, "placement": { "type": [ "string", "null" ], "description": "Where the KB's data lives: `hosted` (control-plane KB, the default) or\n`local` (a KB runtime inside the connector's environment — requires the\nconnector to advertise the `kb:local` capability)." }, "source": { "$ref": "#/components/schemas/SourceBody" } } }, "DispatchRes": { "type": "object", "required": [ "job_id" ], "properties": { "job_id": { "type": "string" } } }, "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" } } }, "DuplicateProjectReqBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Name for the new project. Defaults to the source name with a \" copy\"\nsuffix, de-duplicated within the organization." } } }, "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" } } }, "EditProjectReqBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "is_public_template": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "search_text": { "type": [ "string", "null" ] }, "template_description": { "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 pattern for this grant." }, "via": { "$ref": "#/components/schemas/GrantAttribution", "description": "Role that contributed this grant." } } }, "EffectiveGrantsResBody": { "type": "object", "required": [ "user_id", "is_superadmin", "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/EffectiveGrant" }, "description": "Effective grants for the user, with role attribution." }, "is_superadmin": { "type": "boolean", "description": "Whether the target user is a platform superadmin." }, "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." } } }, "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" ] }, "GroupRoleMappingView": { "type": "object", "description": "View of a group→role mapping.", "required": [ "id", "provider_id", "external_group", "role_id", "created_at", "updated_at" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "external_group": { "type": "string" }, "id": { "type": "string" }, "provider_id": { "type": "string" }, "role_id": { "type": "string" }, "updated_at": { "type": "integer", "format": "int64" } } }, "HashAlg": { "type": "string", "description": "Hash family for `hash` / `pseudonymize` masks.", "enum": [ "sha256", "sha512" ] }, "IdentityProviderKind": { "type": "string", "description": "Which provider implementation drives a connection's login flow. Mirrors the\n`kind` CHECK in `db/init.sql`; widened additively as kinds ship (`oidc`\nfirst, `saml` later).", "enum": [ "oidc", "saml", "directory" ] }, "IdentityProviderView": { "type": "object", "description": "Masked view of a connection. Never includes the client secret.", "required": [ "id", "org_id", "kind", "provider_key", "allowed_domains", "client_secret_set", "enabled", "enforced", "created_at", "updated_at" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" } }, "client_id": { "type": [ "string", "null" ], "description": "OIDC client id. `null` for non-OIDC kinds." }, "client_secret_set": { "type": "boolean", "description": "Whether a client secret is configured. The secret itself is never\nreturned." }, "created_at": { "type": "integer", "format": "int64" }, "default_role_id": { "type": [ "string", "null" ], "description": "Catch-all role granted to JIT members with no matching group mapping.\n`null` = no catch-all role." }, "display_name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "enforced": { "type": "boolean", "description": "Read-only here: SSO enforcement isn't configurable via the API yet." }, "groups_claim": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "issuer": { "type": [ "string", "null" ], "description": "OIDC issuer. `null` for non-OIDC kinds (e.g. SAML), whose connection\ndetails live in kind-specific fields added when those kinds ship." }, "kind": { "type": "string" }, "org_id": { "type": "string" }, "provider_key": { "type": "string" }, "scopes": { "type": [ "string", "null" ] }, "updated_at": { "type": "integer", "format": "int64" } } }, "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", "properties": { "email": { "type": [ "string", "null" ], "description": "Single email address to invite. Legacy shape — prefer `emails`.\nMerged with `emails` when both are provided." }, "emails": { "type": [ "array", "null" ], "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`." } } }, "JobView": { "type": "object", "required": [ "id", "connector_id", "kb_uid", "dest_table", "mode", "state", "rows_emitted", "created_at", "updated_at" ], "properties": { "connector_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "dest_table": { "type": "string" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Run duration in ms — to `finished_at`, or to \"now\" for a live run." }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the run reached a terminal state; `null` while still active." }, "id": { "type": "string" }, "kb_uid": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "rows_emitted": { "type": "integer", "format": "int64" }, "rows_per_sec": { "type": [ "number", "null" ], "format": "double", "description": "Average landed throughput over the run window; `null` until measurable." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the run first reported progress (excludes time queued)." }, "state": { "type": "string" }, "sync_id": { "type": [ "string", "null" ], "description": "Parent sync this run belongs to; `null` for one-off manual dispatches." }, "updated_at": { "type": "string", "format": "date-time" } } }, "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 for search (`pending`, `indexing`, `indexed`, or `failed`)." }, "indexed_at": { "type": [ "string", "null" ], "format": "date-time" }, "kb_file_id": { "type": "string" }, "ordinal": { "type": "string", "description": "Ordering key within the file." }, "page_end": { "type": [ "integer", "null" ], "format": "int32" }, "page_start": { "type": [ "integer", "null" ], "format": "int32" }, "revision": { "type": "string", "description": "Revision token for optimistic concurrency on update and 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_mode", "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_mode": { "$ref": "#/components/schemas/K2GovernanceMode", "description": "Query-time governance mode. Toggle via `PUT …/k2/{kb_id}/policies/governance-mode` (`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." }, "signed_url": { "type": [ "string", "null" ], "description": "CloudFront signed URL on the new CDN for private content. Omitted when\nsigning is unavailable or the object is public." }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "**Deprecated (API):** use `signed_url` when present. Legacy unsigned CDN URL\n(`content.timbal.ai` during migration). Still populated server-side for old clients.", "deprecated": true } } }, "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" } } }, "K2GovernanceMode": { "type": "string", "description": "Per-KB query governance mode.", "enum": [ "off", "shadow", "enforce" ] }, "K2GovernanceModeResponse": { "type": "object", "required": [ "governance_mode" ], "properties": { "governance_mode": { "$ref": "#/components/schemas/K2GovernanceMode" } } }, "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": "Revision token for optimistic concurrency on update and delete." }, "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": "Grantable actions for the organization." } } }, "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" } } } }, "ListGroupRoleMappingsResBody": { "type": "object", "required": [ "group_role_mappings" ], "properties": { "group_role_mappings": { "type": "array", "items": { "$ref": "#/components/schemas/GroupRoleMappingView" } } } }, "ListIdentityProvidersResBody": { "type": "object", "required": [ "identity_providers" ], "properties": { "identity_providers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "ListJobsRes": { "type": "object", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/JobView" } } } }, "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" } } } }, "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" } } }, "ListScimTokensResBody": { "type": "object", "required": [ "scim_tokens" ], "properties": { "scim_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ScimTokenView" } } } }, "ListSyncsRes": { "type": "object", "required": [ "syncs" ], "properties": { "syncs": { "type": "array", "items": { "$ref": "#/components/schemas/SyncView" } } } }, "ListTemplatesResBody": { "type": "object", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTemplate" } } } }, "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" } } } }, "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" }, "overage_rate_cents_per_1k": { "type": [ "integer", "null" ], "format": "int64", "description": "Metered-overage rate in cents per 1,000 credits. Self-serve plans return\nthe fixed tier default; enterprise returns the negotiated rate when\nconfigured; `null` on free or when overage is unavailable." }, "overage_threshold_usd": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum outstanding overage (whole USD dollars) allowed before an\ninterim invoice is issued. Self-serve plans return the fixed tier\ndefault (1× monthly subscription); enterprise returns the negotiated\nvalue when configured; `null` when no interim threshold applies." }, "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": { }, "plan_period": { "type": [ "string", "null" ], "description": "Billing cadence of the active plan: `\"month\"` or `\"year\"`. `null` on the\nfree plan (no active subscription)." }, "plan_renews_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix timestamp (seconds) when the current billing period ends and the\nplan renews. `null` on the free plan (no active subscription). When\n`plan_cancel_at_period_end` is `true`, the plan ends at this time instead\nof renewing." }, "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", "pending" ], "properties": { "email": { "type": "string", "description": "User's email address" }, "id": { "type": [ "string", "null" ], "description": "Unique user identifier. Null only for legacy pending invites created\nbefore invites allocated a user up front; use `pending` to detect\nnot-yet-registered members." }, "name": { "type": [ "string", "null" ], "description": "User's display name" }, "pending": { "type": "boolean", "description": "True when the member was invited but hasn't completed signup yet. Such\nmembers can still have roles assigned ahead of their first login." }, "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 members with no\nrole attachments (including freshly invited users)." } } }, "OverageSummary": { "type": "object", "description": "Customer-facing overage usage summary for the current credits period.\n\n`used_credits = invoiced_credits + pending_credits`. `invoiced_credits` is\nthe real metered overage billed on finalized invoices this period (see\n[`overage_summary`]); `pending_credits` is the headline \"extra usage you'll\nbe billed for\" number, and a non-zero `invoiced_credits` means an interim\n(threshold-driven) invoice has already billed part of this period.", "required": [ "enabled", "used_credits", "invoiced_credits", "pending_credits" ], "properties": { "cap_credits": { "type": [ "integer", "null" ], "format": "int64", "description": "Org-configured ceiling on overage credits for the period. `null` means\nunlimited (or no cap configured); only meaningful when `enabled`." }, "enabled": { "type": "boolean", "description": "Whether usage-based overage billing is currently enabled for the org." }, "invoiced_credits": { "type": "integer", "format": "int64", "description": "Overage credits already included on a finalized invoice this period." }, "pending_credits": { "type": "integer", "format": "int64", "description": "Overage credits accrued this period that have not been invoiced yet." }, "period_end": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the current credits period — when pending overage bills if no\ninterim invoice fires first. `null` when there is no metered window." }, "period_start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the current credits period. `null` when the org has no metered\nbilling window (e.g. free plan with no period anchor)." }, "rate_cents_per_1k": { "type": [ "integer", "null" ], "format": "int64", "description": "Metered overage rate in cents per 1,000 credits. `null` when overage\npricing is unavailable for the plan." }, "threshold_usd": { "type": [ "integer", "null" ], "format": "int64", "description": "Outstanding overage value (whole USD) that triggers an interim invoice.\n`null` means overage bills only at the end of the period." }, "used_credits": { "type": "integer", "format": "int64", "description": "Total overage credits consumed this period (`invoiced` + `pending`)." } } }, "PacingBody": { "type": "object", "description": "Request mirror of [`Pacing`]. All fields optional; absent == unthrottled.", "properties": { "batch_delay_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Sleep (ms) between batches. `0`/omitted = none.", "minimum": 0 }, "max_dop": { "type": [ "integer", "null" ], "format": "int32", "description": "SQL Server only: `OPTION (MAXDOP n)` to cap server-side query\nparallelism. `1` pins single-threaded. Ignored by other sources.", "minimum": 0 }, "max_rows_per_sec": { "type": [ "integer", "null" ], "format": "int32", "description": "Cap on sustained rows/sec across the job. Omit = unlimited.", "minimum": 0 }, "read_uncommitted": { "type": [ "boolean", "null" ], "description": "SQL Server only: read with `READ UNCOMMITTED` (no shared locks, never\nblocks the source's OLTP; dirty reads OK for snapshots). No-op elsewhere." } } }, "PatchAuthSettingsReqBody": { "type": "object", "description": "Body for `PATCH …/auth` — flip the master sign-in switch for the app.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the deployed app requires end-user sign-in." } } }, "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`). Cannot be set to null." }, "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." } } }, "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" } } } }, "ProjectAuthSettings": { "type": "object", "description": "Full app-auth configuration for a project. Drives the settings UI.", "required": [ "enabled", "providers" ], "properties": { "enabled": { "type": "boolean", "description": "Master switch: whether the deployed app requires end-user sign-in at all.\nWhen false the app is public and `providers` is moot until it's turned on." }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AuthProviderState" }, "description": "Every known sign-in method with its current state, in a stable order." } } }, "ProjectDetail": { "type": "object", "required": [ "id", "name", "has_ui", "role", "use_platform_iam", "is_public_template", "template_uses", "publishable_api_key", "environments", "knowledge_bases", "integrations", "auth_enabled", "auth_providers", "created_at", "updated_at" ], "properties": { "auth_enabled": { "type": "boolean", "description": "Master sign-in switch for the deployed app: when false the app is public,\nwhen true it requires end-user sign-in via `auth_providers`." }, "auth_providers": { "type": "array", "items": { "type": "string" }, "description": "Enabled end-user sign-in methods for the project's deployed app login\nscreen (for example `email`, `google`, `microsoft`, `github`). Empty when\nno sign-in method has been turned on." }, "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": "**Deprecated — will be removed.** Always `\"admin\"` for backwards-compatible\nresponse shape. Caller permissions are determined by v2 IAM grants, not\nthis field. Use `/orgs/{org_id}/iam/check` or effective-grants instead." }, "screenshot_signed_url": { "type": [ "string", "null" ], "description": "CloudFront-signed screenshot URL, minted per response (TTL-bound).\nPresent only when the banner is a Timbal-hosted screenshot (private\n`orgs/{}/projects/{}/screenshots/*` prefix) and signing is configured.\n\nNOTE: screenshots live under a *private* prefix, so this URL is signed\nand short-lived. If a banner ever needs to live on a public / cacheable\nsurface (timbal.ai landing pages, OG/meta image tags, emails — anywhere\nthe URL is cached or can't be re-minted per request), copy the object to\na public prefix (e.g. `orgs/{org_id}/assets/...`) and serve that\nunsigned instead of signing this one." }, "screenshot_url": { "type": [ "string", "null" ], "description": "**Legacy** unsigned screenshot URL (`content.timbal.ai`). Prefer\n`screenshot_signed_url` when present.", "deprecated": true }, "search_text": { "type": [ "string", "null" ], "description": "Text corpus used for semantic similarity matching when recommending templates." }, "template_description": { "type": [ "string", "null" ], "description": "Public-facing description shown when the project is listed as a template." }, "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/`." } } } ] }, "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": "**Deprecated — will be removed.** Always `\"admin\"` for backwards-compatible\nresponse shape. Caller permissions are determined by v2 IAM grants, not\nthis field. Use `/orgs/{org_id}/iam/check` or effective-grants instead." }, "screenshot_signed_url": { "type": [ "string", "null" ], "description": "CloudFront-signed screenshot URL, minted per response (TTL-bound).\nPresent only for Timbal-hosted screenshots (private prefix) when signing\nis configured. To use a banner on a public/cacheable surface, copy the\nobject to a public prefix (`orgs/{org_id}/assets/...`) and serve unsigned." }, "screenshot_url": { "type": [ "string", "null" ], "description": "**Legacy** unsigned screenshot URL (`content.timbal.ai`). Prefer\n`screenshot_signed_url` when present.", "deprecated": true }, "template_uses": { "type": "integer", "format": "int64", "description": "Number of times this template has been used" } } }, "ProjectTemplate": { "type": "object", "description": "A published public project template. Instantiate it via\n`POST /orgs/{org_id}/projects` with\n`{ \"origin\": { \"type\": \"Template\", \"project_id\": \u003Cid\u003E } }`.", "required": [ "id", "name", "has_ui", "template_uses", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds." }, "description": { "type": [ "string", "null" ], "description": "Short description of what the template provides." }, "has_ui": { "type": "boolean", "description": "Whether the template includes a web UI." }, "id": { "type": "string", "description": "Project id to pass as `project_id` when creating from this template." }, "name": { "type": "string", "description": "Template display name." }, "screenshot_signed_url": { "type": [ "string", "null" ], "description": "CloudFront-signed screenshot URL, minted per response (TTL-bound).\nPresent only for Timbal-hosted screenshots (private prefix) when signing\nis configured. To put a template banner on a public/cacheable surface\n(e.g. the timbal.ai marketing site), copy the object to a public prefix\n(`orgs/{org_id}/assets/...`) and serve that unsigned instead." }, "screenshot_url": { "type": [ "string", "null" ], "description": "**Legacy** unsigned screenshot URL (`content.timbal.ai`). Prefer\n`screenshot_signed_url` when present.", "deprecated": true }, "search_text": { "type": [ "string", "null" ], "description": "Text corpus used for semantic similarity matching when recommending templates." }, "template_description": { "type": [ "string", "null" ], "description": "Public-facing description shown in the template catalog." }, "template_uses": { "type": "integer", "format": "int64", "description": "Number of times this template has been instantiated." } } }, "PutAuthProviderReqBody": { "type": "object", "description": "Body for `PUT …/auth/providers/{provider}` — upsert one sign-in method.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Turn the sign-in method on or off." } } }, "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 query parameters bound to SQL placeholders ($1, $2, …)." }, "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" } } }, "RebindReq": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "New channel URL to dial, e.g. `wss://api.timbal.ai/v1/connect/channel`." } } }, "RebindRes": { "type": "object", "required": [ "url", "dispatched" ], "properties": { "dispatched": { "type": "boolean", "description": "Always true on a 202 — the connector acks/reverts asynchronously over\nthe channel; watch the fleet listing for it to reconnect." }, "url": { "type": "string" } } }, "RelationalSourceBody": { "type": "object", "description": "Shared shape for the relational sources (Postgres, SQL Server). `schema`\ndefaults per-source (`public` / `dbo`).", "required": [ "connection_ref", "table", "cursor_column" ], "properties": { "columns": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Projection; omit for all columns." }, "connection_ref": { "type": "string", "description": "Name of a connection in the connector's local `connections.json`.\nThe DSN itself never leaves the connector box." }, "cursor_column": { "type": "string", "description": "Monotonic column for incremental extraction (`id`, `updated_at`, ...)." }, "schema": { "type": [ "string", "null" ], "description": "Source schema; defaults to `public` (Postgres) / `dbo` (SQL Server)." }, "table": { "type": "string", "description": "Source table to extract." } } }, "RemoveOrgUserReqBody": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "description": "Email address of the user to remove from the organization. Merged with\n`emails` when both are provided." }, "emails": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Email addresses to remove in one request. When non-empty, batch\nremoval is used and not-found addresses are skipped." } } }, "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", "properties": { "name": { "type": [ "string", "null" ], "description": "Operator label (\"warehouse-pg box\")." }, "ttl_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Token lifetime in seconds. Default 86400 (24h), max 30 days." } } }, "ResBody": { "type": "object", "required": [ "token_id", "token", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "token": { "type": "string", "description": "Raw enrollment token, shown once in the response." }, "token_id": { "type": "string" } } }, "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" } } }, "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" } } }, "ScimTokenView": { "type": "object", "description": "Masked view of a SCIM token. Never includes the secret.", "required": [ "id", "org_id", "enabled", "created_at", "updated_at" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "integer", "null" ], "format": "int64" }, "org_id": { "type": "string" }, "provider_id": { "type": [ "string", "null" ] }, "updated_at": { "type": "integer", "format": "int64" } } }, "SetDefaultRoleReqBody": { "type": "object", "description": "Body for the dedicated default-role endpoint. The field is required but may\nbe `null` to clear the catch-all role (no separate \"unset\" verb needed).", "properties": { "role_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Target role id, or `null` to remove the catch-all (group-mapping-only).\nAccepts a number or a stringified id." } } }, "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" } } }, "SetK2GovernanceModeRequest": { "type": "object", "required": [ "governance_mode" ], "properties": { "governance_mode": { "$ref": "#/components/schemas/K2GovernanceMode" } } }, "SignContentRequest": { "type": "object", "description": "Request to mint a fresh CDN URL for a stored content object.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "A content URL previously returned by the API (signed or unsigned), or a\nbare object key. The server resolves it back to a known object it owns,\nre-checks your access, and mints a fresh URL — useful when a cached\nsigned URL has expired and you want a new one without re-fetching the\nwhole parent resource." } } }, "SignContentResponse": { "type": "object", "description": "A freshly-minted CDN URL pair for a stored content object.", "required": [ "url" ], "properties": { "signed_url": { "type": [ "string", "null" ], "description": "CloudFront signed URL for private content. Omitted when the object is\npublic or signing is unavailable." }, "url": { "type": "string", "description": "Legacy unsigned CDN URL. Populated for backwards compatibility; prefer\n`signed_url` when present." } } }, "SourceBody": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RelationalSourceBody" }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "postgres" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/RelationalSourceBody" }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "sql_server" ] } } } ] } ], "description": "The source half of a dispatch, tagged by `kind`. Each variant maps to a\n`SourceSpec` and gates on the connector advertising the matching\n`source:\u003Ckind\u003E` capability. Request shape:\n`\"source\": { \"kind\": \"sql_server\", \"connection_ref\": \"...\", \"table\": \"...\", \"cursor_column\": \"...\" }`." }, "SyncDetailRes": { "type": "object", "required": [ "sync", "stats", "recent_runs" ], "properties": { "recent_runs": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRunView" } }, "stats": { "$ref": "#/components/schemas/SyncStatsView" }, "sync": { "$ref": "#/components/schemas/SyncView" } } }, "SyncRunView": { "type": "object", "description": "One historical run of a sync, with derived timing.", "required": [ "job_id", "state", "rows_emitted", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "job_id": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "rows_emitted": { "type": "integer", "format": "int64" }, "rows_per_sec": { "type": [ "number", "null" ], "format": "double" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "type": "string" } } }, "SyncStatsView": { "type": "object", "description": "Rollup of a sync's run history (from its `ConnectorJobs`).", "required": [ "runs_total", "runs_completed", "runs_failed", "rows_total" ], "properties": { "rows_total": { "type": "integer", "format": "int64" }, "runs_completed": { "type": "integer", "format": "int64" }, "runs_failed": { "type": "integer", "format": "int64" }, "runs_total": { "type": "integer", "format": "int64" } } }, "SyncView": { "type": "object", "required": [ "id", "connector_id", "source_kind", "connection_ref", "source_schema", "source_table", "cursor_column", "kb_uid", "dest_table", "interval_secs", "enabled", "has_cursor", "created_at", "updated_at" ], "properties": { "connection_ref": { "type": "string" }, "connector_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "cursor_column": { "type": "string" }, "dest_table": { "type": "string" }, "enabled": { "type": "boolean" }, "has_cursor": { "type": "boolean", "description": "Whether a cursor checkpoint has been committed (i.e. the sync has pulled\nat least one batch). The raw cursor is intentionally not exposed." }, "id": { "type": "string" }, "interval_secs": { "type": "integer", "format": "int32" }, "kb_uid": { "type": "string" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_state": { "type": [ "string", "null" ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last time a run reached `completed`; `null` if it has never succeeded." }, "name": { "type": [ "string", "null" ] }, "seconds_since_success": { "type": [ "integer", "null" ], "format": "int64", "description": "Freshness/lag: seconds since the last successful run. `null` if never\nsucceeded. Compare against `interval_secs` to spot a stalling sync." }, "source_kind": { "type": "string" }, "source_schema": { "type": "string" }, "source_table": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TableView": { "type": "object", "required": [ "schema", "name", "approx_rows" ], "properties": { "approx_rows": { "type": "integer", "format": "int64", "description": "Planner estimate; `-1` when the table was never analyzed." }, "name": { "type": "string" }, "schema": { "type": "string" } } }, "TablesRes": { "type": "object", "required": [ "tables" ], "properties": { "tables": { "type": "array", "items": { "$ref": "#/components/schemas/TableView" } } } }, "TempFile": { "type": "object", "description": "Short-lived upload metadata returned by POST /files.", "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": "When the download URL is expected to stop working (~24h after upload)." }, "name": { "type": "string", "description": "Original filename (sanitized — slashes / control characters replaced)." }, "url": { "type": "string", "description": "Download URL. Anyone with this URL can fetch the file until it expires." } } }, "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" } } }, "UpdateIdentityProviderReqBody": { "type": "object", "description": "Update a connection. All fields optional; absent = unchanged. `client_secret`\nis write-only — supply it only to rotate.", "properties": { "allowed_domains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "client_id": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "groups_claim": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "scopes": { "type": [ "string", "null" ] } } }, "UpdateOrgPhotoResBody": { "type": "object", "required": [ "photo_url" ], "properties": { "photo_url": { "type": "string", "description": "Public URL of the newly stored org logo." } } }, "UpdatePhotoResBody": { "type": "object", "required": [ "photo_url" ], "properties": { "photo_url": { "type": "string", "description": "Public URL of the newly stored profile picture." } } }, "UpdateReq": { "type": "object", "properties": { "version": { "type": [ "string", "null" ], "description": "Target version (`0.1.3` or `v0.1.3`). Omit for the published `latest`." } } }, "UpdateRes": { "type": "object", "required": [ "target_version", "artifact", "dispatched" ], "properties": { "artifact": { "type": "string", "description": "Release artifact selected for the connector's platform." }, "dispatched": { "type": "boolean", "description": "`false` when the connector already reports the target version (no-op)." }, "target_version": { "type": "string", "description": "Bare semver the connector was told to move to." } } }, "UpdateSyncReq": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Pause (`false`) / resume (`true`). Pausing preserves the cursor." }, "interval_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "New interval in seconds." } } }, "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" ] } } }, "UserRolesReq": { "type": "object", "description": "One member's desired attachment set in a bulk request.", "required": [ "user_id", "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentReq" }, "description": "Desired attachment set for this member. Same semantics as the\nsingle-member endpoint: a full replace, an empty list detaches\neverything, duplicate `(role_id, scope)` pairs are ignored." }, "user_id": { "type": "integer", "format": "int64" } } }, "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": "content", "description": "Re-sign stored content URLs" }, { "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": "projects", "description": "Project operations" }, { "name": "runs", "description": "Execution operations" }, { "name": "templates", "description": "Public project template catalog" }, { "name": "users", "description": "Authenticated user profile" } ] }