{ "openapi": "3.1.0", "info": { "title": "Timbal Platform API", "description": "Public API documentation for the Timbal platform", "license": { "name": "" }, "version": "1.3.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}/apps/{app_id}/runs": { "get": { "tags": [ "runs" ], "description": "List runs for a specific application", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "user_id", "in": "query", "description": "Filter runs by user ID", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "version_id", "in": "query", "description": "Filter runs by version ID", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "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": [ "integer", "null" ], "format": "int64" } }, { "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": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Runs listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/apps/{app_id}/runs/{run_id}": { "patch": { "tags": [ "runs" ], "description": "Update an existing platform run or link a local run with the platform", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "run_id", "in": "path", "description": "This can be a platform-defined id or a custom id.\nThe platform will map the custom id to an internal one afterwards.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRunReqBody" } } }, "required": true }, "responses": { "200": { "description": "Run updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPreview" } } } } }, "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}/files": { "get": { "tags": [ "k2" ], "description": "List files 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" ] } } ], "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": { "description": "File upload with optional metadata JSON field", "content": { "multipart/form-data": {} } }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/K2File" } } } } }, "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}/kbs/{kb_id}/embeddings": { "get": { "tags": [ "embeddings" ], "description": "List embeddings", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "table_name", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Embeddings listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmbeddingsResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "embeddings" ], "description": "Create a new embedding", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbeddingReqBody" } } }, "required": true }, "responses": { "204": { "description": "Embedding created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/kbs/{kb_id}/embeddings/{embedding_name}": { "delete": { "tags": [ "embeddings" ], "description": "Delete an embedding", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "embedding_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Embedding deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/kbs/{kb_id}/indexes": { "get": { "tags": [ "indexes" ], "description": "List indexes for a KB", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "table_name", "in": "query", "description": "Table name to filter indexes by", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Array of indexes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIndexesResBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "indexes" ], "description": "Create a new index on a table", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIndexReqBody" } } }, "required": true }, "responses": { "204": { "description": "Index created successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/kbs/{kb_id}/indexes/{index_name}": { "delete": { "tags": [ "indexes" ], "description": "Delete an index", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Index deleted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/kbs/{kb_id}/tables/{table_name}/csv": { "post": { "tags": [ "tables" ], "description": "Insert or update rows into a table from a CSV file", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/csv": {} } }, "responses": { "204": { "description": "Rows inserted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/kbs/{kb_id}/tables/{table_name}/records": { "post": { "tags": [ "tables" ], "description": "Insert or update records into a table", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertRecordsReqBody" } } }, "required": true }, "responses": { "204": { "description": "Records upserted successfully" } }, "security": [ { "bearer_auth": [] } ] } }, "/orgs/{org_id}/kbs/{kb_id}/tables/{table_name}/search": { "post": { "tags": [ "tables" ], "description": "Search for records in a table", "operationId": "handler", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTableReqBody" } } }, "required": true }, "responses": { "200": { "description": "Array of records matching the search query. Structure depends on the table schema and selected columns.", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [ { "id": 1, "name": "Alice Johnson", "email": "alice@example.com" }, { "id": 2, "name": null, "email": "bob@example.com" }, { "id": 3, "name": "Carol", "email": "carol@example.com" } ] } } } }, "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}/compose": { "post": { "tags": [ "compose" ], "description": "Send a prompt and stream the response as Server-Sent Events", "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" } } }, "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}/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}/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" ] }, "BatchCreateVarsReqBody": { "type": "object", "required": [ "vars" ], "properties": { "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "vars": { "type": "array", "items": { "$ref": "#/components/schemas/VarInput" } } } }, "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": { "type": "string", "description": "The prompt to send to Claude", "example": "Add error handling to the upload endpoint" }, "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" ] } } } ] }, "CreateDomainReqBody": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Custom domain name", "example": "custom.timbal.ai" } } }, "CreateEmbeddingReqBody": { "type": "object", "required": [ "name", "table_name", "column_name", "model", "with_gin_index" ], "properties": { "column_name": { "type": "string", "description": "Name of the source column" }, "model": { "$ref": "#/components/schemas/EmbeddingModel", "description": "Embedding model to use. See the list embedding models endpoint for available options." }, "name": { "type": "string", "description": "Name of the embedding" }, "table_name": { "type": "string", "description": "Name of the source table" }, "with_gin_index": { "type": "boolean", "description": "Whether to create a GIN index for the source column for faster hybrid search" } } }, "CreateEnvReqBody": { "type": "object", "required": [ "name", "color" ], "properties": { "color": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "CreateIndexReqBody": { "type": "object", "required": [ "table_name", "name", "column_names", "type", "is_unique" ], "properties": { "column_names": { "type": "array", "items": { "type": "string" }, "description": "List of column names to index. At least one column is required. Multiple columns will create a composite index" }, "is_unique": { "type": "boolean", "description": "Whether the index should enforce uniqueness" }, "name": { "type": "string", "description": "Index name. This must be unique in the entire Knowledge Base" }, "table_name": { "type": "string", "description": "Table name" }, "type": { "$ref": "#/components/schemas/IndexType", "description": "Index type" } } }, "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" } } }, "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" } } }, "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" } } }, "Embedding": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingStatus" }, { "type": "object", "required": [ "id", "name", "table_name", "column_name", "model", "created_at", "updated_at" ], "properties": { "column_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int64" }, "model": { "$ref": "#/components/schemas/EmbeddingModel" }, "name": { "type": "string" }, "table_name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "EmbeddingModel": { "type": "string" }, "EmbeddingStatus": { "oneOf": [ { "type": "object", "required": [ "details", "status" ], "properties": { "details": { "type": "object" }, "status": { "type": "string", "enum": [ "pending" ] } } }, { "type": "object", "required": [ "details", "status" ], "properties": { "details": { "type": "object", "properties": { "processed_rows": { "type": [ "integer", "null" ], "format": "int64" }, "total_rows": { "type": [ "integer", "null" ], "format": "int64" } } }, "status": { "type": "string", "enum": [ "processing" ] } } }, { "type": "object", "required": [ "details", "status" ], "properties": { "details": { "type": "object" }, "status": { "type": "string", "enum": [ "success" ] } } }, { "type": "object", "required": [ "details", "status" ], "properties": { "details": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "status": { "type": "string", "enum": [ "error" ] } } } ] }, "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" } } }, "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" } } }, "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" } } }, "Index": { "type": "object", "required": [ "table", "name", "columns", "type", "is_unique", "definition" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "string" }, "is_unique": { "type": "boolean" }, "name": { "type": "string" }, "table": { "type": "string" }, "type": { "$ref": "#/components/schemas/IndexType" } } }, "IndexType": { "type": "string", "enum": [ "btree", "hash", "gin", "gist", "brin", "hnsw" ] }, "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" }, "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" } } }, "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" } } } }, "ListEmbeddingsResBody": { "type": "object", "required": [ "embeddings" ], "properties": { "embeddings": { "type": "array", "items": { "$ref": "#/components/schemas/Embedding" } } } }, "ListEnvsResBody": { "type": "object", "required": [ "envs" ], "properties": { "envs": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEnv" } } } }, "ListIndexesResBody": { "type": "object", "required": [ "indexes" ], "properties": { "indexes": { "type": "array", "items": { "$ref": "#/components/schemas/Index" } } } }, "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" ] } } }, "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" } } }, "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" } } } } ] }, "ListRunsResBody": { "type": "object", "required": [ "runs" ], "properties": { "group_id": { "type": [ "integer", "null" ], "format": "int64", "description": "The `group_id` filter applied to the query" }, "next_page_token": { "type": [ "integer", "null" ], "format": "int64", "description": "Cursor for the next page" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunPreview" }, "description": "List of runs" }, "user_id": { "type": [ "integer", "null" ], "format": "int64", "description": "The `user_id` filter applied to the query" } } }, "ListVarsResBody": { "type": "object", "required": [ "vars" ], "properties": { "vars": { "type": "array", "items": { "$ref": "#/components/schemas/Var" } } } }, "Org": { "type": "object", "required": [ "id", "name", "plan", "plan_metadata", "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" }, "photo_url": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "plan_metadata": {}, "role": { "type": "string" }, "stripe_customer_id": { "type": [ "string", "null" ] } } }, "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" } } }, "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": "List of workforce items in this project" } } }, "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." } } }, "RemoveOrgUserReqBody": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the user to remove from the organization" } } }, "RunPreview": { "type": "object", "required": [ "id", "user", "version", "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": [ "integer", "null" ], "format": "int64" }, "id": { "type": "integer", "format": "int64" }, "idempotency_key": { "type": "string" }, "last_reaction_sentiment": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "integer", "null" ], "format": "int64" }, "status": { "type": "string" }, "status_detail": {}, "trace": {}, "user": { "$ref": "#/components/schemas/UserRef" }, "version": { "$ref": "#/components/schemas/VersionRef" } }, "additionalProperties": {} }, "SearchTableReqBody": { "type": "object", "required": [ "query", "embedding_names" ], "properties": { "embedding_names": { "type": "array", "items": { "type": "string" }, "description": "List of embedding names to use for semantic search. Only a single column is supported at the moment." }, "fts_columns": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List of column names to use for full-text search. When specified together with embedding_names, search will be hybrid (both semantic and full-text)." }, "limit": { "type": "integer", "format": "int64", "description": "Maximum number of results to return.", "default": 10 }, "offset": { "type": "integer", "format": "int64", "description": "Number of results to skip before returning.", "default": 0 }, "query": { "type": "string", "description": "Semantic search query." }, "select_columns": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List of column names to return in the search results. When not specified, all columns will be returned." }, "where": { "type": [ "string", "null" ], "description": "SQL WHERE expression to apply to the search. This feature is _experimental_ and may be removed or changed in the future." } } }, "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" } } }, "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" } } }, "UpdateRunReqBody": { "type": "object", "properties": { "metadata": { "description": "Custom metadata" }, "parent_id": { "type": [ "string", "null" ], "description": "This can be a platform-defined id or a custom id.\nThe platform will map the custom id to an internal one afterwards." }, "trace": { "description": "Trace data" }, "version_id": { "type": [ "string", "null" ], "description": "Version identifier (if any)" } } }, "UpdateVarReqBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "env_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" } }, "value": { "type": [ "string", "null" ] } } }, "UpsertRecordsReqBody": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "description": "Array of records to insert or update (at least one record is required)" } } }, "UserRef": { "type": "object", "required": [ "id", "name", "email" ], "properties": { "email": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "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" ] } } } ] }, "VersionRef": { "type": "object", "required": [ "id", "name", "is_prod" ], "properties": { "deployment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Deployment" } ] }, "id": { "type": "integer", "format": "int64" }, "is_prod": { "type": "boolean" }, "name": { "type": "string" } } }, "WorkforcePreview": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Workforce item description" }, "id": { "type": "string", "description": "Unique workforce item identifier" }, "name": { "type": "string", "description": "Workforce item name" }, "type": { "$ref": "#/components/schemas/AppType", "description": "Workforce item type" }, "uid": { "type": [ "string", "null" ], "description": "Unique identifier from the project manifest (timbal.yaml)" } } } }, "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": "k2", "description": "Knowledge Bases v2 operations" }, { "name": "orgs", "description": "Organization operations" }, { "name": "embeddings", "description": "KB Embeddings operations" }, { "name": "files", "description": "File operations" }, { "name": "indexes", "description": "KB Indexes operations" }, { "name": "projects", "description": "Project operations" }, { "name": "runs", "description": "Execution operations" }, { "name": "compose", "description": "Compose — AI coding agent sessions" }, { "name": "tables", "description": "KB Tables operations" } ] }