{ "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": { "/me/orgs": { "get": { "tags": [ "orgs" ], "description": "List organizations the authenticated user belongs to", "operationId": "handler", "parameters": [ { "name": "q", "in": "query", "description": "Optional search query to filter orgs by name", "required": false, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Page token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organizations listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgsResult" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}": { "get": { "tags": [ "orgs" ], "description": "Get an organization by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "orgs" ], "description": "Partially update an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOrgReqBody" } } }, "required": true }, "responses": { "204": { "description": "Organization updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/billing/overage": { "post": { "tags": [ "billing" ], "description": "Enable or disable usage-based overage billing and set an optional credit cap for the organization.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingOverageReqBody" } } }, "required": true }, "responses": { "204": { "description": "Overage settings updated", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Cannot apply overage (plan, payments, or subscription state)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/domains": { "get": { "tags": [ "orgs" ], "description": "List connected domains for an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domains listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Add a custom domain to an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainReqBody" } } }, "required": true }, "responses": { "204": { "description": "Domain created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/domains/{domain_id}": { "get": { "tags": [ "orgs" ], "description": "Get a domain by ID. This endpoint triggers DNS validation and returns the live certificate status.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "orgs" ], "description": "Delete a domain", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Domain deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/embedding-models": { "get": { "tags": [ "embeddings" ], "description": "List all available embedding models for the organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Array of embedding models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmbeddingModelsResBody" }, "example": { "embedding_models": [ "text-embedding-ada-002", "text-embedding-3-small", "text-embedding-3-large" ] } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/files": { "post": { "tags": [ "files" ], "description": "Upload a file to an org", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "contentMediaType": "application/octet-stream" } } } } }, "required": true }, "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } }, "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": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/directories": { "post": { "tags": [ "k2" ], "description": "Create a virtual directory in the knowledge base", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2VirtualDirectoryRequest" } } }, "required": true }, "responses": { "200": { "description": "Folder already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2VirtualDirectoryResponse" } } } }, "201": { "description": "Folder created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateK2VirtualDirectoryResponse" } } } }, "409": { "description": "A file with the same name already exists at this path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/files": { "get": { "tags": [ "k2" ], "description": "List files and directories in a knowledge base", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "directory", "in": "query", "description": "Filter files by directory path (e.g. \"docs/reports\")", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Files listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListK2FilesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "k2" ], "description": "Upload a file to a knowledge base for parsing and embedding", "operationId": "add", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Request body for uploading a file to a knowledge base.", "required": [ "file", "metadata" ], "properties": { "directory": { "type": [ "string", "null" ], "description": "Optional subdirectory path to organize the file within the knowledge base." }, "file": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "The file to upload.", "contentMediaType": "application/octet-stream" }, "metadata": { "type": "object", "description": "Optional JSON metadata to attach to the file." } } } } }, "required": true }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2File" } } } }, "409": { "description": "A file with the same name already exists in this directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/files/{file_id}": { "get": { "tags": [ "k2" ], "description": "Get a file with its parsings and embeddings metadata", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File details with parsings and embeddings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetK2FileResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "k2" ], "description": "Delete a file from a knowledge base", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "File deleted" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/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}/schema": { "get": { "tags": [ "k2" ], "description": "Get the schema for a knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format: \"structured\" (default) or \"sql\"", "required": false, "schema": { "type": "string", "enum": [ "structured", "sql" ] } } ], "responses": { "200": { "description": "Schema (structured by default, or SQL DDL statements when ?format=sql)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/K2Schema", "description": "Structured schema with tables, columns, indexes, and constraints (default)" }, { "$ref": "#/components/schemas/K2SchemaSql", "description": "SQL DDL statements (CREATE TABLE, CREATE INDEX, etc.)" } ], "description": "Response for the schema endpoint — structured (default) or SQL DDL." } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/k2/{kb_id}/upload": { "post": { "tags": [ "k2" ], "description": "Upload a data file (CSV, Parquet, JSON) into the knowledge base", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "File upload with optional table_name and mode fields", "content": { "multipart/form-data": { } } }, "responses": { "200": { "description": "Upload result", "content": { "application/json": { } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/channels": { "get": { "tags": [ "notifications" ], "summary": "List notification channels for the org", "description": "Returns all `NotificationChannels` rows for this organization (email and future types). Any org member may call.", "operationId": "list_org_notification_channels", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channels for the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgNotificationChannelsResBody" } } } }, "403": { "description": "Caller is not a member of this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "notifications" ], "summary": "Create a notification channel", "description": "Creates or **reuses** an email channel for this org (same dedupe as rule creation: `type` + `config`). **Org admin** only.", "operationId": "create_org_notification_channel", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Email channel: `type: \"email\"` and `config.to`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationChannelReq" } } }, "required": true }, "responses": { "201": { "description": "Channel id and whether it was created or reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationChannelOut" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/channels/{channel_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete a notification channel", "description": "Removes the channel for this org; rule–channel links are removed automatically. Rules may remain with no channels. **Org admin** only.", "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" } } ], "responses": { "204": { "description": "Channel deleted" }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Channel not found for this org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/rules": { "get": { "tags": [ "notifications" ], "summary": "List org-wide notification rules", "description": "Returns notification rules that apply at the **organization** level (e.g. credits low, billing payment failed). Each rule includes linked **channels** (typically one email channel). Any authenticated org member may call this; use **POST** `/orgs/{org_id}/notifications/rules` to create rules (org **admin** only).", "operationId": "list_org_notification_rules", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of rules with channels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgNotificationRulesResBody" } } } }, "403": { "description": "Caller is not a member of this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "notifications" ], "summary": "Create an org-wide notification rule", "description": "Creates a rule with `project_id` unset (org-wide). Exactly one **channel** per request: inline `type: \"email\"` + `config.to`, or `channel.id` pointing at an existing email channel in this org. Allowed `event_type` values: `org.credits.low`, `org.billing.payment_failed`. Response includes `channel_action` (`linked` | `reused` | `created`). **Org admin** role required.", "operationId": "create_org_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Rule name, allowlisted org `event_type`, optional `condition`, cooldown, and a single channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleReq" } } }, "required": true }, "responses": { "201": { "description": "Rule and channel link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleOut" } } } }, "400": { "description": "Validation error (unknown event type, bad email, empty name, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/notifications/rules/{rule_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete an org-wide notification rule", "description": "Deletes a rule with `project_id` unset only. **Org admin** only.", "operationId": "delete_org_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Rule deleted" }, "403": { "description": "Caller is not an org admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Rule not found or not org-scoped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/previews": { "get": { "tags": [ "preview" ], "description": "List project previews for the organization", "operationId": "list_previews", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "preview_status", "in": "query", "description": "Return only previews in this lifecycle state. Omit to include every active preview (`starting` or `running`).", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PreviewStatus" } ] } } ], "responses": { "200": { "description": "Previews listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPreviewsResponse" } } } }, "403": { "description": "Caller is not a member of the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects": { "get": { "tags": [ "projects" ], "description": "List projects for an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "Response detail level: \"list\" (default) returns a lightweight preview, \"full\" returns all project details", "required": false, "schema": { "type": "string", "enum": [ "list", "full" ] } } ], "responses": { "200": { "description": "Projects listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectReqBody" } } }, "required": true }, "responses": { "200": { "description": "Project created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}": { "get": { "tags": [ "projects" ], "description": "Get a project by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDetail" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Project deleted successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditProjectReqBody" } } }, "required": true }, "responses": { "204": { "description": "Project updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/analytics/credits": { "get": { "tags": [ "analytics" ], "description": "Time-binned credits and USD cost breakdown for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "Bucket size for aggregation (`minute`, `hour`, or `day`).", "required": false, "schema": { "$ref": "#/components/schemas/BinSize" } }, { "name": "from", "in": "query", "description": "Inclusive range start (epoch milliseconds). Defaults: 1h / 1d / 30d before `to` by `group_by`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Exclusive range end (epoch milliseconds). Defaults to now.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "user_id", "in": "query", "description": "Restrict to a specific user’s runs.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Credits analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAnalyticsCreditsBody" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "500": { "description": "Error" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/analytics/usage": { "get": { "tags": [ "analytics" ], "description": "Time-binned run counts, user counts, and duration percentiles for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "Bucket size for aggregation (`minute`, `hour`, or `day`).", "required": false, "schema": { "$ref": "#/components/schemas/BinSize" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Usage analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAnalyticsUsageBody" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden" }, "500": { "description": "Error" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/analytics/users": { "get": { "tags": [ "analytics" ], "description": "Per-user run and spend aggregates for a project.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Inclusive range start (epoch milliseconds).", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "description": "Exclusive range end (epoch milliseconds).", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Opaque offset for the next page (from the previous response’s `next_page_token`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "User analytics page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAnalyticsUsersBody" } } } }, "403": { "description": "Forbidden" }, "500": { "description": "Error" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose": { "post": { "tags": [ "compose" ], "description": "Send a prompt to the Timbal Composer agent. The `prompt` field accepts a plain string, an array of content blocks, or a full Message object. Content blocks can be text or files (base64, URL, or server-side path). Supported file types: images (png/jpg/gif/webp/svg), PDFs, and text-readable formats (json, csv, md, yaml, py, rs, etc.).", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeRequest" }, "examples": { "File from URL": { "value": { "rev": "main", "prompt": [ "Review this config file", { "type": "file", "file": { "name": "config.json", "source": { "type": "url", "url": "https://example.com/config.json" } } } ] } }, "File from server path": { "value": { "rev": "main", "prompt": [ "Analyze this log file", { "type": "file", "file": { "name": "app.log", "source": { "type": "path", "path": "/mnt/efs/uploads/app.log" } } } ] } }, "File without name (media_type required)": { "value": { "rev": "main", "prompt": [ "What is in this image?", { "type": "file", "file": { "media_type": "image/png", "source": { "type": "base64", "data": "iVBORw0KGgo..." } } } ] } }, "Full Message object": { "value": { "rev": "main", "prompt": { "role": "user", "content": [ { "type": "text", "text": "Refactor this to use async/await" } ] } } }, "Plain string": { "value": { "rev": "main", "prompt": "Add error handling to the upload endpoint" } }, "Text with inline image (base64)": { "value": { "rev": "main", "prompt": [ "Describe what you see in this screenshot and fix the layout", { "type": "file", "file": { "name": "screenshot.png", "source": { "type": "base64", "data": "iVBORw0KGgo..." } } } ] } } } } }, "required": true }, "responses": { "200": { "description": "SSE stream of Claude responses", "content": { "text/event-stream": { } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/sessions": { "get": { "tags": [ "compose" ], "description": "List sessions for a project, most recent first", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Filter sessions by user ID", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Sessions listed successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSession" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/sessions/{session_id}": { "get": { "tags": [ "compose" ], "description": "Get session details including token usage, cost, and message history", "operationId": "single", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session UUID (e.g. \"019d1bbe-2f61-7393-afa7-6bb770878c9b\")", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019d1bbe-2f61-7393-afa7-6bb770878c9b" } ], "responses": { "200": { "description": "Session details with messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetail" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/compose/sessions/{session_id}/stop": { "post": { "tags": [ "compose" ], "description": "Stop a running compose session by sending SIGTERM to the Claude process", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session UUID (e.g. \"019d1bbe-2f61-7393-afa7-6bb770878c9b\")", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019d1bbe-2f61-7393-afa7-6bb770878c9b" } ], "responses": { "204": { "description": "Session stopped" }, "404": { "description": "No active process for this session" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/connections": { "get": { "tags": [ "projects" ], "description": "List connections for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connections listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectionsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Connect a resource (KB or integration) to a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectToProject" } } }, "required": true }, "responses": { "201": { "description": "Connection created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/connections/{connection_id}": { "delete": { "tags": [ "projects" ], "description": "Delete a project connection", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connection deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/deployments": { "get": { "tags": [ "projects" ], "description": "List deployments for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_env_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "manifest_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Deployments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeploymentsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/deployments/{deployment_id}": { "get": { "tags": [ "projects" ], "description": "Get a deployment by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deployment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs": { "get": { "tags": [ "projects" ], "description": "List environments for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Environments listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvReqBody" } } }, "required": true }, "responses": { "201": { "description": "Environment created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}": { "delete": { "tags": [ "projects" ], "description": "Delete an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Environment deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/branch": { "patch": { "tags": [ "projects" ], "description": "Set or clear the branch for an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnvBranchReqBody" } } }, "required": true }, "responses": { "200": { "description": "Branch updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/config": { "patch": { "tags": [ "projects" ], "description": "Update environment configuration (CPU, memory, etc.)", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvConfigReqBody" } } }, "required": true }, "responses": { "200": { "description": "Configuration updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/deploy": { "post": { "tags": [ "projects" ], "description": "Deploy an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployEnvReqBody" } } }, "required": true }, "responses": { "202": { "description": "Deployment initiated" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/domain": { "patch": { "tags": [ "projects" ], "description": "Associate or disassociate a custom domain with an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnvDomainReqBody" } } }, "required": true }, "responses": { "200": { "description": "Domain updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/metrics/{metric_type}": { "get": { "tags": [ "projects" ], "description": "Query environment metrics", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metric_type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MetricType" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Metrics data" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/envs/{env_id}/stop": { "post": { "tags": [ "projects" ], "description": "Stop an environment", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Stop initiated" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/k2": { "put": { "tags": [ "projects" ], "description": "Link a K2 knowledge base to a project. Replaces any previously linked KB.", "operationId": "put", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkKbRequest" } } }, "required": true }, "responses": { "200": { "description": "Knowledge base linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbPreview" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Knowledge base not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Unlink the K2 knowledge base from a project.", "operationId": "delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Knowledge base unlinked" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/notifications/rules": { "get": { "tags": [ "notifications" ], "summary": "List project notification rules", "description": "Returns rules scoped to a single **project** (e.g. deployment lifecycle emails). Each rule includes linked channels. Any authenticated project member may call; **POST** on the same path requires **project admin**.", "operationId": "list_project_notification_rules", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of rules with channels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectNotificationRulesResBody" } } } }, "403": { "description": "Caller is not a member of this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "notifications" ], "summary": "Create a project-scoped notification rule", "description": "Creates a rule tied to this **project** (all environments in that project for deployment-style events). Same channel semantics as org rules: inline email or `channel.id`. Allowed `event_type` values: `project.deployment.failed`, `project.deployment.running`. Response includes `channel_action`. **Project admin** role required.", "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": { "description": "Rule name, allowlisted project `event_type`, optional `condition`, cooldown, and a single channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleReq" } } }, "required": true }, "responses": { "201": { "description": "Rule and channel link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRuleOut" } } } }, "400": { "description": "Validation error (unknown event type, bad email, empty name, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/notifications/rules/{rule_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete a project-scoped notification rule", "description": "Deletes a rule tied to this project. **Project admin** only.", "operationId": "delete_project_notification_rule", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Rule deleted" }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Rule not found for this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/preview": { "get": { "tags": [ "preview" ], "description": "Get preview status (starting or running) and health when running", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name of the preview to inspect (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewInfo" } } } }, "403": { "description": "Caller has no access to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No preview or start in progress for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "preview" ], "description": "Start dev preview servers (API/UI) for a branch worktree; returns starting immediately, then ready after health checks", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "Preview starting or already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewInfo" } } } }, "400": { "description": "Invalid branch, worktree not ready, or preview already starting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "Org preview concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/preview/stop": { "post": { "tags": [ "preview" ], "description": "Stop preview dev servers for a branch", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopPreviewRequest" } } }, "required": true }, "responses": { "204": { "description": "Preview stopped", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } }, "403": { "description": "Caller is not a project admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No preview running for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs": { "get": { "tags": [ "runs" ], "description": "List runs for a specific project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Filter runs by user ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "description": "Filter runs by status", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "sentiment", "in": "query", "description": "Filter runs by sentiment", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "group_id", "in": "query", "description": "Filter runs by group ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "description": "Filter runs by start time (epoch timestamp in milliseconds)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" }, "example": 1729540800000 }, { "name": "to", "in": "query", "description": "Filter runs by end time (epoch timestamp in milliseconds)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" }, "example": 1729627200000 }, { "name": "metadata", "in": "query", "description": "Filter runs by metadata", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Page token", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Runs listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs/{run_id}": { "get": { "tags": [ "runs" ], "description": "Get a single run for a project (by run id or idempotency key)", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetail" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/runs/{run_id}/reactions": { "get": { "tags": [ "runs" ], "description": "List reactions for a project run (admin only)", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Reactions listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReactionsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "runs" ], "description": "Add a reaction to a project run", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Platform run id or idempotency key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewReactionReqBody" } } }, "required": true }, "responses": { "204": { "description": "Reaction created" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/users": { "get": { "tags": [ "projects" ], "description": "List users for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectUsersResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Add a user to a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProjectUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User added successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/users/{user_id}": { "delete": { "tags": [ "projects" ], "description": "Remove a user from a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "User removed successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a user's role in a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditProjectUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User role updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars": { "get": { "tags": [ "projects" ], "description": "List variables for a project", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "env_ids", "in": "query", "description": "Comma-separated list of environment IDs to filter by", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Variables listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVarsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a new variable", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVarReqBody" } } }, "required": true }, "responses": { "201": { "description": "Variable created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/batch": { "post": { "tags": [ "projects" ], "description": "Batch create variables", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateVarsReqBody" } } }, "required": true }, "responses": { "201": { "description": "Variables created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/vars/{var_id}": { "get": { "tags": [ "projects" ], "description": "Get a variable by ID", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Variable details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Var" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a variable", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Variable deleted successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Update a variable", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVarReqBody" } } }, "required": true }, "responses": { "204": { "description": "Variable updated successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce": { "get": { "tags": [ "projects" ], "description": "List workforce components for the project. When `rev` is provided the response is scoped to that git branch and includes deployment URLs; when omitted all registered components are returned.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`). When omitted, all registered (non-deleted) workforce components are returned without deployment status.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of workforce items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkforceResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Create a workforce component (agent or workflow) on the git **branch** given by `rev`.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkforceReqBody" } } }, "required": true }, "responses": { "201": { "description": "Workforce component created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkforceResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Delete a workforce component on the git **branch** given by `rev`.", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkforceReqBody" } } }, "required": true }, "responses": { "204": { "description": "Workforce component deleted", "content": { "application/json": { "schema": { "type": "null", "description": "Successful responses use HTTP 204 and do not include a body." } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/projects/{project_id}/workforce/{workforce}/{*path}": { "get": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). The HTTP method and body are forwarded unchanged. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). The HTTP method and body are forwarded unchanged. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_put", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). The HTTP method and body are forwarded unchanged. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_post", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). The HTTP method and body are forwarded unchanged. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_delete", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "projects" ], "description": "Proxy an HTTP request to a **running** workforce deployment (agent or workflow). The HTTP method and body are forwarded unchanged. Identify the component with `workforce` (numeric id, manifest UUID, or name) and the git **branch** with `rev`. WebSocket upgrades are not supported on this route.", "operationId": "workforce_proxy_patch", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "workforce", "in": "path", "description": "Workforce component: numeric id, manifest UUID, or name", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path on the deployment server after the component segment (for example `run` or `healthcheck`). Leave empty to call the deployment root.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "query", "description": "Git branch name (for example `main`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response from the workforce deployment" }, "404": { "description": "No running deployment found for this component on this branch" }, "502": { "description": "The deployment did not return a successful HTTP response" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/users": { "get": { "tags": [ "orgs" ], "description": "List users in an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Optional search query to filter users by name", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page_token", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Users listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgUsersResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "orgs" ], "description": "Invite a user to an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteOrgUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User invited successfully" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "orgs" ], "description": "Remove a user from an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveOrgUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User removed successfully" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "orgs" ], "description": "Update a user's role in an organization", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOrgUserReqBody" } } }, "required": true }, "responses": { "204": { "description": "User role updated successfully" } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AddProjectUserReqBody": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "format": "int64" } } }, "AppType": { "type": "string", "enum": [ "agent", "workflow", "unknown" ] }, "BatchCreateVarsReqBody": { "type": "object", "required": [ "vars" ], "properties": { "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "vars": { "type": "array", "items": { "$ref": "#/components/schemas/VarInput" } } } }, "BillingOverageReqBody": { "type": "object", "required": [ "enabled" ], "properties": { "cap_credits": { "type": [ "integer", "null" ], "format": "int64", "description": "Max overage **credits** the user allows (null = unlimited)." }, "enabled": { "type": "boolean" } } }, "BinSize": { "type": "string", "enum": [ "minute", "hour", "day" ] }, "ChannelAction": { "type": "string", "description": "How the rule was wired to `NotificationChannels` for this create call.", "enum": [ "linked", "reused", "created" ] }, "ComposeRequest": { "type": "object", "required": [ "rev", "prompt" ], "properties": { "effort": { "type": [ "string", "null" ], "description": "Effort level: low, medium, high, max", "example": "high" }, "model": { "type": [ "string", "null" ], "description": "Model alias or full name (e.g. \"sonnet\", \"opus\", \"claude-sonnet-4-6\")", "example": "sonnet" }, "prompt": { "$ref": "#/components/schemas/Message", "description": "The prompt: a plain string, an array of content blocks, or a full Message object." }, "rev": { "type": "string", "description": "Branch to run against (worktree is checked out at this rev)", "example": "main" }, "session_id": { "type": [ "string", "null" ], "description": "Existing session ID to continue a conversation. Omit to start a new session." } } }, "ConnectToProject": { "oneOf": [ { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "kb" ] } } }, { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "integration" ] } } } ] }, "Content": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "file", "type" ], "properties": { "file": { "$ref": "#/components/schemas/FileRef" }, "type": { "type": "string", "enum": [ "file" ] } } } ] }, "Cost": { "type": "object", "required": [ "id", "name", "unit", "usd", "credits" ], "properties": { "credits": { "type": "number", "format": "double" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "unit": { "type": "string" }, "usd": { "type": "number", "format": "double" } } }, "CostBin": { "type": "object", "required": [ "interval_starts_at", "interval_ends_at", "costs" ], "properties": { "costs": { "type": "array", "items": { "$ref": "#/components/schemas/Cost" } }, "interval_ends_at": { "type": "integer", "format": "int64" }, "interval_starts_at": { "type": "integer", "format": "int64" } } }, "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": { "type": "string" } } }, "CreateDomainReqBody": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Custom domain name", "example": "custom.timbal.ai" } } }, "CreateEnvReqBody": { "type": "object", "required": [ "name", "color" ], "properties": { "color": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "CreateK2Request": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Name for the new knowledge base" } } }, "CreateK2Response": { "type": "object", "required": [ "id", "uid", "name", "path" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "uid": { "type": "string" } } }, "CreateK2VirtualDirectoryRequest": { "type": "object", "required": [ "directory" ], "properties": { "directory": { "type": "string", "description": "Folder path, same format as the `directory` field on file upload (e.g. `docs/reports`)." } } }, "CreateK2VirtualDirectoryResponse": { "type": "object", "required": [ "directory", "placeholder_file_id", "created" ], "properties": { "created": { "type": "boolean", "description": "`true` if this call created the folder, `false` if it already existed." }, "directory": { "type": "string" }, "placeholder_file_id": { "type": "string", "description": "Listing id for this folder; remove it with `DELETE /orgs/{org_id}/k2/{kb_id}/files/{file_id}`." } } }, "CreateNotificationChannelOut": { "type": "object", "required": [ "id", "channel_action" ], "properties": { "channel_action": { "$ref": "#/components/schemas/ChannelAction" }, "id": { "type": "integer", "format": "int64" } } }, "CreateNotificationChannelReq": { "type": "object", "description": "Body for **POST** `/orgs/{org_id}/notifications/channels` (standalone channel; same validation as inline rule channel, no `id`).", "properties": { "config": { "type": "object" }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" } } }, "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": { "type": "string" }, "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" } } }, "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." } } }, "DeleteWorkforceReqBody": { "type": "object", "required": [ "workforce" ], "properties": { "workforce": { "type": "string", "description": "Component to delete: numeric id, manifest UUID (`uid`), or configured name." } } }, "DeployEnvReqBody": { "type": "object", "properties": { "rev": { "type": [ "string", "null" ] } } }, "Deployment": { "type": "object", "required": [ "id", "type", "project_env_id", "target", "status", "created_at", "updated_at" ], "properties": { "build_finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "build_logs": { "type": [ "string", "null" ] }, "build_started_at": { "type": [ "string", "null" ], "format": "date-time" }, "cpu": { "type": [ "integer", "null" ], "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "desired_count": { "type": [ "integer", "null" ], "format": "int32" }, "domain": { "type": [ "string", "null" ] }, "ephemeral_storage": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "integer", "format": "int64" }, "memory": { "type": [ "integer", "null" ], "format": "int32" }, "project_env_id": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "status_detail": { "type": [ "string", "null" ] }, "target": { "$ref": "#/components/schemas/Target" }, "type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Domain": { "type": "object", "required": [ "id", "domain", "validation_records", "validation_status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "domain": { "type": "string", "description": "Custom domain name" }, "id": { "type": "string", "description": "Unique domain identifier" }, "project_env": { "description": "Project environment this domain is linked to, if any" }, "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp in epoch milliseconds" }, "validation_records": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationRecord" }, "description": "DNS records required for SSL certificate validation" }, "validation_status": { "$ref": "#/components/schemas/ValidationStatus", "description": "Current SSL certificate validation status" } } }, "EditOrgReqBody": { "type": "object", "properties": { "banner_url": { "type": [ "string", "null" ], "description": "URL of the organization's banner image", "deprecated": true }, "contact_email": { "type": [ "string", "null" ], "description": "Contact email address" }, "contact_name": { "type": [ "string", "null" ], "description": "Contact person's name" }, "contact_phone": { "type": [ "string", "null" ], "description": "Contact phone number" }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code" }, "description": { "type": [ "string", "null" ], "description": "Organization description" }, "name": { "type": [ "string", "null" ], "description": "Organization name" }, "photo_url": { "type": [ "string", "null" ], "description": "URL of the organization's profile photo" } } }, "EditOrgUserReqBody": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "description": "User's email address" }, "role": { "type": "string", "description": "User's role in the organization. Standard values are `admin` and `user`. Custom roles are available — contact sales for more information", "example": "user" } } }, "EditProjectReqBody": { "type": "object", "properties": { "banner_url": { "type": [ "string", "null" ] }, "default_role": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_public_template": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "use_platform_iam": { "type": [ "boolean", "null" ] } } }, "EditProjectUserReqBody": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string" } } }, "EmbeddingModel": { "type": "string" }, "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." } } }, "File": { "type": "object", "required": [ "content_length", "content_type", "created_at", "name", "id", "url" ], "properties": { "content_length": { "type": "integer", "format": "int64", "description": "The content length of the file in bytes" }, "content_type": { "type": "string", "description": "The content type of the file" }, "created_at": { "type": "string", "format": "date-time", "description": "The time the file was created" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time the file expires at" }, "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the file" }, "name": { "type": "string", "description": "The name of the file" }, "url": { "type": "string", "description": "The URL where the file can be accessed" } } }, "FileRef": { "type": "object", "required": [ "source" ], "properties": { "media_type": { "type": [ "string", "null" ], "description": "MIME type. Inferred from `name` extension when omitted." }, "name": { "type": [ "string", "null" ], "description": "Filename (e.g. \"screenshot.png\"). Used for display and media-type inference.\nOptional — when omitted, `media_type` must be provided explicitly." }, "source": { "$ref": "#/components/schemas/FileSource", "description": "How to obtain the file bytes." } } }, "FileSource": { "oneOf": [ { "type": "object", "description": "Inline base64-encoded content.", "required": [ "data", "type" ], "properties": { "data": { "type": "string" }, "type": { "type": "string", "enum": [ "base64" ] } } }, { "type": "object", "description": "Local filesystem path (server-side).", "required": [ "path", "type" ], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "path" ] } } }, { "type": "object", "description": "Remote URL to fetch.", "required": [ "url", "type" ], "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } } } ] }, "GetK2FileResponse": { "allOf": [ { "$ref": "#/components/schemas/K2File" }, { "type": "object", "required": [ "parsings", "embeddings" ], "properties": { "embeddings": { "type": "array", "items": { "$ref": "#/components/schemas/K2FileEmbedding" } }, "parsings": { "type": "array", "items": { "$ref": "#/components/schemas/K2FileParsing" } } } } ] }, "GetOrgResBody": { "type": "object", "required": [ "org" ], "properties": { "org": { "$ref": "#/components/schemas/Org" } } }, "IntegrationPreview": { "type": "object", "required": [ "id", "provider", "name" ], "properties": { "id": { "type": "string", "description": "Integration identifier" }, "logo_url": { "type": [ "string", "null" ], "description": "Integration logo URL" }, "name": { "type": "string", "description": "Integration display name" }, "provider": { "type": "string", "description": "Integration provider key" } } }, "InviteOrgUserReqBody": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } }, "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", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "data_size_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "index_count": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string" }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "table_count": { "type": "integer", "format": "int64", "minimum": 0 }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "vector_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "K2File": { "type": "object", "required": [ "id", "uid", "kb_id", "name", "content_type", "content_length", "metadata", "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" }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } }, "K2FileEmbedding": { "type": "object", "required": [ "id", "kb_file_id", "provider", "model", "status", "created_at", "updated_at" ], "properties": { "chunk_count": { "type": [ "integer", "null" ], "format": "int32" }, "cost_usd": { "type": [ "number", "null" ], "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "kb_file_id": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "parsing_id": { "type": [ "integer", "null" ], "format": "int64" }, "provider": { "type": "string" }, "status": { "type": "string" }, "token_count": { "type": [ "integer", "null" ], "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2FileParsing": { "type": "object", "required": [ "id", "kb_file_id", "provider", "status", "created_at", "updated_at" ], "properties": { "chunk_count": { "type": [ "integer", "null" ], "format": "int32" }, "cost_usd": { "type": [ "number", "null" ], "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "kb_file_id": { "type": "integer", "format": "int64" }, "num_pages": { "type": [ "integer", "null" ], "format": "int32" }, "provider": { "type": "string" }, "provider_job_id": { "type": [ "string", "null" ] }, "s3_bucket": { "type": [ "string", "null" ] }, "s3_key": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2ForeignKey": { "type": "object", "required": [ "column", "ref_table", "ref_column" ], "properties": { "column": { "type": "string" }, "ref_column": { "type": "string" }, "ref_table": { "type": "string" } } }, "K2Index": { "type": "object", "required": [ "name", "table_name", "columns", "is_unique" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "is_unique": { "type": "boolean" }, "name": { "type": "string" }, "table_name": { "type": "string" } } }, "K2Preview": { "type": "object", "required": [ "id", "uid", "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "data_size_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "uid": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "K2Schema": { "type": "object", "required": [ "tables" ], "properties": { "tables": { "type": "array", "items": { "$ref": "#/components/schemas/K2Table" } } } }, "K2SchemaSql": { "type": "object", "required": [ "statements" ], "properties": { "statements": { "type": "array", "items": { "type": "string" }, "description": "DDL statements (CREATE TABLE, CREATE INDEX, etc.)" } } }, "K2Table": { "type": "object", "required": [ "name", "source", "columns", "indexes", "constraints", "estimated_row_count" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/K2Column" } }, "constraints": { "type": "array", "items": { "$ref": "#/components/schemas/K2Constraint" } }, "estimated_row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "indexes": { "type": "array", "items": { "$ref": "#/components/schemas/K2Index" } }, "name": { "type": "string" }, "schema": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/K2TableSource" } } }, "K2TableSource": { "type": "string", "enum": [ "primary", "vectors" ] }, "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" } } }, "LinkKbRequest": { "type": "object", "required": [ "kb_id" ], "properties": { "kb_id": { "type": "string", "description": "ID of the K2 knowledge base to link to this project" } } }, "ListConnectionsResBody": { "type": "object", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectConnection" } } } }, "ListDeploymentsResBody": { "type": "object", "required": [ "deployments" ], "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } } } }, "ListDomainsResBody": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } }, "ListEmbeddingModelsResBody": { "type": "object", "required": [ "embedding_models" ], "properties": { "embedding_models": { "type": "array", "items": { "$ref": "#/components/schemas/EmbeddingModel" } } } }, "ListEnvsResBody": { "type": "object", "required": [ "envs" ], "properties": { "envs": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEnv" } } } }, "ListK2FilesResponse": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/K2File" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "ListK2Response": { "type": "object", "required": [ "k2" ], "properties": { "k2": { "type": "array", "items": { "$ref": "#/components/schemas/K2Preview" } }, "next_page_token": { "type": [ "string", "null" ] } } }, "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/OrgNotificationRuleOut" } } } }, "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" } } }, "ListPreviewsResponse": { "type": "object", "description": "Previews currently visible for the organization.", "required": [ "previews" ], "properties": { "previews": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewInfo" } } } }, "ListProjectNotificationRulesResBody": { "type": "object", "title": "ListProjectNotificationRulesResponse", "description": "Wrapper for **GET** `/orgs/{org_id}/projects/{project_id}/notifications/rules`.", "required": [ "rules" ], "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/OrgNotificationRuleOut" } } } }, "ListProjectUsersResBody": { "type": "object", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserWithRole" } } } }, "ListProjectsResBody": { "oneOf": [ { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectPreview" } } } }, { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDetail" } } } } ] }, "ListReactionsResBody": { "type": "object", "required": [ "reactions" ], "properties": { "next_page_token": { "type": [ "string", "null" ] }, "reactions": { "type": "array", "items": { "$ref": "#/components/schemas/Reaction" } } } }, "ListRunsResBody": { "type": "object", "required": [ "runs" ], "properties": { "next_page_token": { "type": [ "string", "null" ], "description": "Cursor for the next page" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunPreview" }, "description": "List of runs" } } }, "ListVarsResBody": { "type": "object", "required": [ "vars" ], "properties": { "vars": { "type": "array", "items": { "$ref": "#/components/schemas/Var" } } } }, "ListWorkforceResBody": { "type": "object", "description": "Workforce components registered for the project. The `url` field is set only when the component has a **running** deployment for the git **branch** you queried (`rev`).", "required": [ "workforce" ], "properties": { "workforce": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforcePreview" } } } }, "Message": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/Content" } }, "role": { "$ref": "#/components/schemas/Role" } } }, "NewReactionReqBody": { "type": "object", "required": [ "sentiment" ], "properties": { "feedback": { "type": [ "string", "null" ] }, "sentiment": { "type": "string" } } }, "NotificationChannelOut": { "type": "object", "required": [ "id", "type", "config" ], "properties": { "config": { "type": "object" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" } } }, "Org": { "type": "object", "required": [ "id", "name", "plan", "plan_metadata", "overage_enabled", "credits_per_usd", "created_at", "role" ], "properties": { "banner_url": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "credits_per_usd": { "type": "number", "format": "double" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "overage_cap_credits": { "type": [ "integer", "null" ], "format": "int64" }, "overage_enabled": { "type": "boolean" }, "photo_url": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "plan_metadata": { }, "role": { "type": "string" }, "stripe_customer_id": { "type": [ "string", "null" ] } } }, "OrgNotificationRuleOut": { "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": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "OrgPreview": { "type": "object", "required": [ "id", "name", "plan", "n_projects", "role", "created_at" ], "properties": { "banner_url": { "type": [ "string", "null" ], "description": "URL of the organization's banner image", "deprecated": true }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "description": { "type": [ "string", "null" ], "description": "Organization description" }, "id": { "type": "string", "description": "Unique organization identifier" }, "n_projects": { "type": "integer", "format": "int64", "description": "Number of projects in the organization" }, "name": { "type": "string", "description": "Organization name" }, "photo_url": { "type": [ "string", "null" ], "description": "URL of the organization's profile photo" }, "plan": { "type": "string", "description": "Subscription plan" }, "role": { "type": "string", "description": "Authenticated user's role in the organization" } } }, "OrgUser": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "description": "User's email address" }, "id": { "type": [ "string", "null" ], "description": "Unique user identifier. Null for pending invites that haven't been accepted yet" }, "name": { "type": [ "string", "null" ], "description": "User's display name" }, "photo_url": { "type": [ "string", "null" ], "description": "URL of the user's profile photo" }, "role": { "type": "string", "description": "User's role in the organization" } } }, "PreviewComponent": { "type": "object", "required": [ "component" ], "properties": { "component": { "type": "string", "description": "Which part of the preview this row describes: `api` (backend dev server) or `ui` (frontend dev server)." }, "healthy": { "type": [ "boolean", "null" ], "description": "Whether the dev server answered a health check on its port. Absent when no check was performed." } } }, "PreviewInfo": { "type": "object", "required": [ "slug", "started_at", "rev", "components" ], "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/PreviewComponent" } }, "project_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Included on organization-wide preview listings so you can tell which project a row belongs to." }, "rev": { "type": "string", "description": "Git branch name this preview is tied to." }, "slug": { "type": "string", "description": "Opaque token used with your organization’s preview hostname." }, "started_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when acceptance of the preview start was recorded." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PreviewStatus" } ] }, "url": { "type": [ "string", "null" ], "description": "Public HTTPS URL for the running preview, when preview hosting is configured for your organization." } } }, "PreviewStatus": { "type": "string", "enum": [ "starting", "running" ] }, "ProjectAnalyticsCreditsBody": { "type": "object", "required": [ "group_by", "from", "to", "bins" ], "properties": { "bins": { "type": "array", "items": { "$ref": "#/components/schemas/CostBin" } }, "from": { "type": "integer", "format": "int64" }, "group_by": { "$ref": "#/components/schemas/BinSize" }, "to": { "type": "integer", "format": "int64" } } }, "ProjectAnalyticsUsageBody": { "type": "object", "required": [ "group_by", "from", "to", "bins" ], "properties": { "bins": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBin" } }, "from": { "type": "integer", "format": "int64" }, "group_by": { "$ref": "#/components/schemas/BinSize" }, "to": { "type": "integer", "format": "int64" } } }, "ProjectAnalyticsUsersBody": { "type": "object", "required": [ "from", "to", "users" ], "properties": { "from": { "type": "integer", "format": "int64" }, "next_page_token": { "type": [ "string", "null" ] }, "to": { "type": "integer", "format": "int64" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserRow" } } } }, "ProjectConnection": { "type": "object", "required": [ "id", "type", "resource_id", "resource_data", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int64" }, "resource_data": { }, "resource_id": { "type": "integer", "format": "int64" }, "resource_name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectDetail": { "type": "object", "required": [ "id", "name", "has_ui", "workforce", "role", "use_platform_iam", "is_public_template", "template_uses", "publishable_api_key", "environments", "knowledge_bases", "integrations", "created_at", "updated_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "default_role": { "type": [ "string", "null" ], "description": "Project's default role. All organization members will be assigned this role by default for this project" }, "description": { "type": [ "string", "null" ], "description": "Project description" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/EnvPreview" }, "description": "Project environments with their latest deployment status" }, "has_ui": { "type": "boolean", "description": "Whether the project has a UI interface" }, "id": { "type": "string", "description": "Unique project identifier" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationPreview" }, "description": "Integrations active in this project" }, "is_public_template": { "type": "boolean", "description": "Whether the project is a public template" }, "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KbPreview" }, "description": "Knowledge bases connected to this project (new KB system only)" }, "name": { "type": "string", "description": "Project name" }, "publishable_api_key": { "type": "string", "description": "Publishable API key for this project" }, "repository_url": { "type": [ "string", "null" ], "description": "URL of the project's source code repository. When null, the project does not have source code available" }, "role": { "type": "string", "description": "Authenticated user's role in the project" }, "screenshot_url": { "type": [ "string", "null" ], "description": "URL of the project's screenshot image" }, "template_uses": { "type": "integer", "format": "int64", "description": "Number of times this template has been used" }, "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp in epoch milliseconds" }, "use_platform_iam": { "type": "boolean", "description": "Whether the project uses the platform's IAM system for access control" }, "workforce": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforcePreview" }, "description": "Workforce components (agents and workflows) defined for this project in the manifest." } } }, "ProjectEnv": { "type": "object", "required": [ "id", "name", "color", "subdomain", "created_at", "updated_at" ], "properties": { "branch": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "cpu": { "type": [ "integer", "null" ], "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "custom_domain": { }, "description": { "type": [ "string", "null" ] }, "desired_count": { "type": [ "integer", "null" ], "format": "int32" }, "ephemeral_storage": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "integer", "format": "int64" }, "memory": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "subdomain": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectOrigin": { "oneOf": [ { "type": "object", "required": [ "project_id", "type" ], "properties": { "project_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "Template" ] } } }, { "type": "object", "required": [ "has_ui", "app_type", "type" ], "properties": { "app_type": { "$ref": "#/components/schemas/AppType" }, "has_ui": { "type": "boolean" }, "type": { "type": "string", "enum": [ "Scratch" ] } } } ] }, "ProjectPreview": { "type": "object", "required": [ "id", "name", "role", "created_at", "is_public_template", "template_uses" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "default_role": { "type": [ "string", "null" ], "description": "Project's default role. All organization members will be assigned this role by default for this project" }, "description": { "type": [ "string", "null" ], "description": "Project description" }, "id": { "type": "string", "description": "Unique project identifier" }, "is_public_template": { "type": "boolean", "description": "Whether the project is a public template" }, "name": { "type": "string", "description": "Project name" }, "role": { "type": "string", "description": "Authenticated user's role in the project" }, "screenshot_url": { "type": [ "string", "null" ], "description": "URL of the project's screenshot image" }, "template_uses": { "type": "integer", "format": "int64", "description": "Number of times this template has been used" } } }, "ProjectSession": { "type": "object", "required": [ "id", "uid", "project_id", "user_id", "rev", "status", "turn_count", "iteration_count", "tool_call_count", "input_tokens", "output_tokens", "cache_creation_tokens", "cache_read_tokens", "cost_usd", "model_usage", "created_at", "last_active_at" ], "properties": { "cache_creation_tokens": { "type": "integer", "format": "int64", "description": "Total cache creation tokens" }, "cache_read_tokens": { "type": "integer", "format": "int64", "description": "Total cache read tokens" }, "cost_usd": { "type": "number", "format": "double", "description": "Accumulated cost in USD" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "input_tokens": { "type": "integer", "format": "int64", "description": "Total input tokens across all turns" }, "iteration_count": { "type": "integer", "format": "int32", "description": "Total LLM calls (including mid-turn iterations)" }, "last_active_at": { "type": "string", "format": "date-time" }, "model": { "type": [ "string", "null" ], "description": "Model used in this session" }, "model_usage": { "description": "Per-model token and cost breakdown" }, "output_tokens": { "type": "integer", "format": "int64", "description": "Total output tokens across all turns" }, "project_id": { "type": "string" }, "rev": { "type": "string", "description": "Git branch the session is scoped to" }, "status": { "type": "string", "description": "Session status: \"active\" or \"idle\"" }, "tool_call_count": { "type": "integer", "format": "int32", "description": "Total tool_use blocks across all calls" }, "turn_count": { "type": "integer", "format": "int32", "description": "Number of user prompts sent" }, "uid": { "type": "string" }, "user_id": { "type": "string" } } }, "QueryK2Request": { "type": "object", "required": [ "sql" ], "properties": { "explain": { "type": "boolean", "description": "When true, runs EXPLAIN ANALYZE and includes the query plan in the response." }, "params": { "type": "array", "items": { }, "description": "Optional parameters for the query. Parameters used inside Lance vector\nsearch functions (lance_vector_search, lance_hybrid_search) are\nautomatically embedded into vectors." }, "sql": { "type": "string", "description": "SQL query to execute against the knowledge base.\nUse $1, $2, etc. for parameter placeholders." } } }, "Reaction": { "type": "object", "required": [ "id", "user", "sentiment", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "feedback": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "sentiment": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserRef" } } }, "RemoveOrgUserReqBody": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the user to remove from the organization" } } }, "Role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "RunDetail": { "type": "object", "required": [ "id", "user", "status", "cost_usd", "cost_credits", "created_at", "idempotency_key" ], "properties": { "cost_credits": { "type": "number", "format": "double" }, "cost_usd": { "type": "number", "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "group_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "last_reaction_sentiment": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_detail": { }, "trace": { }, "user": { "$ref": "#/components/schemas/UserRef" } }, "additionalProperties": { } }, "RunPreview": { "type": "object", "required": [ "id", "user", "workforce", "status", "cost_usd", "cost_credits", "created_at", "idempotency_key" ], "properties": { "cost_credits": { "type": "number", "format": "double" }, "cost_usd": { "type": "number", "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "group_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "last_reaction_sentiment": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserRef" }, "workforce": { "$ref": "#/components/schemas/WorkforcePreview" } } }, "SessionDetail": { "allOf": [ { "$ref": "#/components/schemas/ProjectSession" }, { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { }, "description": "Message history from the Claude session file (same format as compose stream events)" } } } ] }, "SetEnvBranchReqBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "When null, the branch will be cleared" } } }, "SetEnvDomainReqBody": { "type": "object", "properties": { "domain_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "StartPreviewRequest": { "type": "object", "required": [ "rev" ], "properties": { "rev": { "type": "string", "description": "Git branch name to run the preview for (for example `main`)." } } }, "StopPreviewRequest": { "type": "object", "required": [ "rev" ], "properties": { "rev": { "type": "string", "description": "Git branch name you used when starting the preview (for example `main`)." } } }, "Target": { "type": "object", "required": [ "type", "id" ], "properties": { "commit": { }, "id": { "type": "integer", "format": "int64" }, "manifest_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "version_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "UpdateEnvConfigReqBody": { "type": "object", "properties": { "cpu": { "type": [ "integer", "null" ], "format": "int32" }, "desired_count": { "type": [ "integer", "null" ], "format": "int32" }, "ephemeral_storage": { "type": [ "integer", "null" ], "format": "int32" }, "memory": { "type": [ "integer", "null" ], "format": "int32" } } }, "UpdateVarReqBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "value": { "type": [ "string", "null" ] } } }, "UsageBin": { "type": "object", "required": [ "interval_starts_at", "interval_ends_at", "n_success", "n_error", "n_running", "n_timeout", "n_users" ], "properties": { "interval_ends_at": { "type": "integer", "format": "int64" }, "interval_starts_at": { "type": "integer", "format": "int64" }, "n_error": { "type": "integer", "format": "int64" }, "n_running": { "type": "integer", "format": "int64" }, "n_success": { "type": "integer", "format": "int64" }, "n_timeout": { "type": "integer", "format": "int64" }, "n_users": { "type": "integer", "format": "int64" }, "p50": { "type": [ "number", "null" ], "format": "double" }, "p90": { "type": [ "number", "null" ], "format": "double" }, "p95": { "type": [ "number", "null" ], "format": "double" }, "p99": { "type": [ "number", "null" ], "format": "double" } } }, "UserRef": { "type": "object", "required": [ "id", "name", "email" ], "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "photo_url": { "type": [ "string", "null" ] } } }, "UserRow": { "type": "object", "required": [ "user_id", "user_name", "user_email", "n_success", "n_error", "n_running", "n_timeout", "usd", "credits" ], "properties": { "credits": { "type": "number", "format": "double" }, "n_error": { "type": "integer", "format": "int64" }, "n_running": { "type": "integer", "format": "int64" }, "n_success": { "type": "integer", "format": "int64" }, "n_timeout": { "type": "integer", "format": "int64" }, "usd": { "type": "number", "format": "double" }, "user_email": { "type": "string" }, "user_id": { "type": "integer", "format": "int64" }, "user_name": { "type": "string" }, "user_photo_url": { "type": [ "string", "null" ] } } }, "UserWithRole": { "type": "object", "required": [ "id", "email", "name", "role" ], "properties": { "email": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "photo_url": { "type": [ "string", "null" ] }, "role": { "type": "string" } } }, "ValidationRecord": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "name": { "type": "string", "description": "DNS record name" }, "type": { "type": "string", "description": "DNS record type (e.g. `CNAME`)" }, "value": { "type": "string", "description": "DNS record value" } } }, "ValidationStatus": { "type": "string", "description": "SSL certificate validation status", "enum": [ "pending", "issued", "inactive", "expired", "revoked", "failed", "validationtimedout" ] }, "Var": { "type": "object", "required": [ "id", "name", "value", "envs" ], "properties": { "description": { "type": [ "string", "null" ] }, "envs": { "type": "array", "items": { "$ref": "#/components/schemas/VarEnv" } }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "value": { "$ref": "#/components/schemas/VarValue" } } }, "VarEnv": { "type": "object", "required": [ "id", "name", "color" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "VarInput": { "type": "object", "required": [ "type", "name", "value" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/VarType" }, "value": { "type": "string" } } }, "VarType": { "type": "string", "enum": [ "plain", "secret" ] }, "VarValue": { "oneOf": [ { "type": "object", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "plain" ] }, "value": { "type": "string" } } }, { "type": "object", "required": [ "type" ], "properties": { "decrypted": { "type": [ "string", "null" ] }, "preview": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "secret" ] } } } ] }, "WorkforcePreview": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "deleted_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Set when the workforce component has been deleted. Only returned from endpoints that include soft-deleted rows (e.g. runs list)." }, "description": { "type": [ "string", "null" ], "description": "Optional short description." }, "id": { "type": "string", "description": "Identifier of this workforce component within the project." }, "name": { "type": "string", "description": "Display name of the component." }, "type": { "$ref": "#/components/schemas/AppType", "description": "Component category (for example agent or workflow)." }, "uid": { "type": [ "string", "null" ], "description": "Stable identifier from the project manifest (`timbal.yaml`), when defined." }, "url": { "type": [ "string", "null" ], "description": "When present, the authenticated Timbal API URL used to call this component’s **running** deployment (for example from the list-workforce response). Omitted where the response does not expose a callable URL, such as on project detail." } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "description": "Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information." } } }, "tags": [ { "name": "analytics", "description": "Project analytics" }, { "name": "billing", "description": "Subscriptions, usage, and payment-related operations" }, { "name": "compose", "description": "Compose — AI coding agent sessions" }, { "name": "files", "description": "File operations" }, { "name": "k2", "description": "Knowledge Bases v2 operations" }, { "name": "orgs", "description": "Organization operations" }, { "name": "preview", "description": "Project dev previews (branch worktree dev servers)" }, { "name": "projects", "description": "Project operations" }, { "name": "runs", "description": "Execution operations" } ] }