# Add workflow group (/api-reference/tables/addTableWorkflowGroup) `POST /api/v2/tables/{tableId}/groups` Bind a workflow or enrichment to the table and create the columns populated by its outputs. An output whose column the table already has attaches that column to the group instead of creating it, so `outputColumns` may be omitted when every output lands in an existing column. OAuth scope: `api:write`. ## Authentication ```json { "requirements": [ { "apiKey": [] }, { "oauthBearer": [ "api:write" ] } ], "schemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description." }, "oauthBearer": { "type": "oauth2", "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).", "flows": { "authorizationCode": { "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize", "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token", "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token", "scopes": { "api:read": "Read your workspaces, workflows, files, tables, and logs", "api:write": "Read, create, change, run, and delete resources in your workspaces", "offline_access": "Stay signed in without asking again" } } } } } } ``` Required OAuth scope: `api:write`. ## Request examples ### cURL ```bash curl --request POST 'https://www.sim.ai/api/v2/tables/string/groups' \ --header 'X-API-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "group": { "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Enrich company", "outputs": [ { "blockId": "block_lookup", "path": "output.revenue", "columnName": "revenue" } ] }, "outputColumns": [ { "name": "revenue", "type": "number" } ] }' ``` ### JavaScript ```javascript const response = await fetch("https://www.sim.ai/api/v2/tables/string/groups", { "method": "POST", "headers": { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" }, "body": "{\n \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n \"group\": {\n \"workflowId\": \"3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36\",\n \"name\": \"Enrich company\",\n \"outputs\": [\n {\n \"blockId\": \"block_lookup\",\n \"path\": \"output.revenue\",\n \"columnName\": \"revenue\"\n }\n ]\n },\n \"outputColumns\": [\n {\n \"name\": \"revenue\",\n \"type\": \"number\"\n }\n ]\n}" }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const result = await response.json(); ``` ### Python ```python import requests response = requests.request( "POST", "https://www.sim.ai/api/v2/tables/string/groups", headers={ "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" }, data="{\n \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n \"group\": {\n \"workflowId\": \"3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36\",\n \"name\": \"Enrich company\",\n \"outputs\": [\n {\n \"blockId\": \"block_lookup\",\n \"path\": \"output.revenue\",\n \"columnName\": \"revenue\"\n }\n ]\n },\n \"outputColumns\": [\n {\n \"name\": \"revenue\",\n \"type\": \"number\"\n }\n ]\n}", ) response.raise_for_status() result = response.json() ``` ### Go ```go package main import ( "io" "net/http" "os" "strings" ) func check(err error) { if err != nil { panic(err) } } func must[T any](value T, err error) T { check(err) return value } func main() { request := must(http.NewRequest("POST", "https://www.sim.ai/api/v2/tables/string/groups", strings.NewReader("{\n \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n \"group\": {\n \"workflowId\": \"3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36\",\n \"name\": \"Enrich company\",\n \"outputs\": [\n {\n \"blockId\": \"block_lookup\",\n \"path\": \"output.revenue\",\n \"columnName\": \"revenue\"\n }\n ]\n },\n \"outputColumns\": [\n {\n \"name\": \"revenue\",\n \"type\": \"number\"\n }\n ]\n}"))) request.Header.Set("X-API-Key", "YOUR_API_KEY") request.Header.Set("Content-Type", "application/json") response := must(http.DefaultClient.Do(request)) defer response.Body.Close() if response.StatusCode >= 400 { panic(response.Status) } must(io.Copy(os.Stdout, response.Body)) } ``` ### Java ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Example { public static void main(String[] args) throws Exception { var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/tables/string/groups")); builder.header("X-API-Key", "YOUR_API_KEY"); builder.header("Content-Type", "application/json"); var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n \"group\": {\n \"workflowId\": \"3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36\",\n \"name\": \"Enrich company\",\n \"outputs\": [\n {\n \"blockId\": \"block_lookup\",\n \"path\": \"output.revenue\",\n \"columnName\": \"revenue\"\n }\n ]\n },\n \"outputColumns\": [\n {\n \"name\": \"revenue\",\n \"type\": \"number\"\n }\n ]\n}")).build(); var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream()); try (var body = response.body()) { if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode()); body.transferTo(System.out); } } } ``` ### C# ```csharp using System; using System.IO; using System.Net.Http; using System.Text; using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.sim.ai/api/v2/tables/string/groups"); request.Content = new StringContent("{\n \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n \"group\": {\n \"workflowId\": \"3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36\",\n \"name\": \"Enrich company\",\n \"outputs\": [\n {\n \"blockId\": \"block_lookup\",\n \"path\": \"output.revenue\",\n \"columnName\": \"revenue\"\n }\n ]\n },\n \"outputColumns\": [\n {\n \"name\": \"revenue\",\n \"type\": \"number\"\n }\n ]\n}", Encoding.UTF8); request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY"); request.Content!.Headers.ContentType = System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json"); using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); response.EnsureSuccessStatusCode(); await response.Content.CopyToAsync(Console.OpenStandardOutput()); ``` ## Parameters ```json [ { "name": "tableId", "in": "path", "required": true, "description": "Unique table identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique table identifier." } } ] ``` ## Request body ```json { "required": true, "description": "Workspace scope, producer definition, and output columns.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique workspace identifier." }, "group": { "type": "object", "properties": { "id": { "description": "Optional client-provided workflow-group identifier.", "type": "string", "minLength": 1 }, "workflowId": { "description": "Backing workflow identifier. Required when `type` is `manual` (which is also the default when `type` is omitted); omit it for an `enrichment` group.", "type": "string", "minLength": 1 }, "enrichmentId": { "description": "Registry enrichment identifier.", "type": "string", "minLength": 1 }, "name": { "description": "Workflow-group display name.", "type": "string" }, "type": { "description": "Workflow-group producer type.", "type": "string", "enum": [ "manual", "enrichment" ] }, "dependencies": { "description": "Producer input dependencies.", "type": "object", "properties": { "columns": { "description": "Columns required as producer inputs.", "type": "array", "items": { "type": "string" } } } }, "outputs": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "blockId": { "default": "", "description": "Workflow block producing this output.", "type": "string" }, "path": { "default": "", "description": "Path to the value in the workflow block output.", "type": "string" }, "outputId": { "description": "Registry enrichment output identifier.", "type": "string" }, "columnName": { "type": "string", "minLength": 1, "description": "Table column receiving the output." } }, "required": [ "columnName" ] }, "description": "Producer outputs mapped to columns." }, "inputMappings": { "description": "Workflow inputs mapped from table columns.", "type": "array", "items": { "type": "object", "properties": { "inputName": { "type": "string", "minLength": 1, "description": "Workflow input name." }, "columnName": { "type": "string", "minLength": 1, "description": "Source table column name." } }, "required": [ "inputName", "columnName" ] } }, "deploymentMode": { "description": "Workflow state used for cell runs.", "type": "string", "enum": [ "live", "deployed" ] }, "autoRun": { "description": "Whether this group automatically runs for new rows.", "type": "boolean" } }, "required": [ "outputs" ], "description": "Workflow or enrichment producer definition." }, "outputColumns": { "default": [], "description": "Columns to create for producer outputs. An entry naming a column the table already has attaches that column to the group instead of creating it (its `type` must match), and an output whose column already exists may omit its entry entirely — so `[]` attaches existing columns only.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name." }, "type": { "type": "string", "enum": [ "string", "number", "currency", "boolean", "date", "json", "select" ], "description": "Output column data type." }, "required": { "description": "Whether the output column is required.", "type": "boolean" }, "unique": { "description": "Whether the output column must be unique.", "type": "boolean" } }, "required": [ "name", "type" ], "additionalProperties": false } }, "autoRun": { "default": false, "description": "Whether to schedule existing rows after group creation.", "type": "boolean" } }, "required": [ "workspaceId", "group" ], "additionalProperties": false, "title": "Add table workflow group request", "description": "Workspace scope, producer definition, and output columns.", "examples": [ { "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "group": { "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Enrich company", "outputs": [ { "blockId": "block_lookup", "path": "output.revenue", "columnName": "revenue" } ] }, "outputColumns": [ { "name": "revenue", "type": "number" } ] } ] }, "examples": { "example1": { "summary": "Request example 1", "value": { "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "group": { "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Enrich company", "outputs": [ { "blockId": "block_lookup", "path": "output.revenue", "columnName": "revenue" } ] }, "outputColumns": [ { "name": "revenue", "type": "number" } ] } } } } } } ``` ## Responses ### 201 ```json { "description": "The created workflow group and resulting columns.", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow-group identifier." }, "workflowId": { "type": "string", "description": "Backing workflow identifier for a manual group." }, "enrichmentId": { "description": "Registry enrichment identifier.", "type": "string" }, "name": { "description": "Workflow-group display name.", "type": "string" }, "type": { "description": "Producer type.", "type": "string", "enum": [ "manual", "enrichment" ] }, "dependencies": { "description": "Input column dependencies.", "type": "object", "properties": { "columns": { "description": "Columns required as producer inputs.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Workflow block producing this output." }, "path": { "type": "string", "description": "Path to the value in the workflow block output." }, "outputId": { "description": "Registry enrichment output identifier.", "type": "string" }, "columnName": { "type": "string", "description": "Name of the table column receiving the output." } }, "required": [ "blockId", "path", "columnName" ], "additionalProperties": false }, "description": "Workflow outputs mapped to table columns." }, "inputMappings": { "description": "Workflow inputs mapped from table columns.", "type": "array", "items": { "type": "object", "properties": { "inputName": { "type": "string", "description": "Workflow input name." }, "columnName": { "type": "string", "description": "Name of the source table column." } }, "required": [ "inputName", "columnName" ], "additionalProperties": false } }, "deploymentMode": { "type": "string", "enum": [ "live", "deployed" ], "description": "Which workflow state per-cell runs execute against. `deployed` (the default when a group was created without one) runs the latest active deployment and refuses to run while the workflow is undeployed; `live` runs the editable draft." }, "autoRun": { "description": "Whether the group automatically runs for new rows.", "type": "boolean" } }, "required": [ "id", "workflowId", "outputs", "deploymentMode" ], "additionalProperties": false, "title": "Table workflow group", "description": "The created or updated workflow group." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable server-assigned column identifier.", "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Column name used as the public row-data key." }, "type": { "type": "string", "enum": [ "string", "number", "currency", "boolean", "date", "json", "select" ], "description": "Data type of values stored in the column." }, "required": { "default": false, "description": "Whether inserts require a value for this column.", "type": "boolean" }, "unique": { "default": false, "description": "Whether values must be unique across table rows.", "type": "boolean" }, "workflowGroupId": { "description": "Workflow group whose output populates this column.", "type": "string" }, "options": { "description": "Options declared for a select column.", "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable select-option identifier." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name of the select option." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "multiple": { "description": "Whether a select column accepts multiple options.", "type": "boolean" }, "currencyCode": { "description": "ISO 4217 code for a currency column, normalized to uppercase.", "type": "string", "pattern": "^[A-Za-z]{3}$" } }, "required": [ "name", "type", "required", "unique" ], "additionalProperties": false, "description": "A typed column in a table schema." }, "description": "Current table columns after the mutation." } }, "required": [ "group", "columns" ], "additionalProperties": false, "title": "Workflow group data", "description": "Response data." } }, "required": [ "data" ], "additionalProperties": false, "title": "Add table workflow group response", "description": "The workflow group and complete resulting table columns." } } } } ``` ### 400 ```json { "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } } ``` ### 401 ```json { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } } ``` ### 403 ```json { "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } } ``` ### 404 ```json { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } } ``` ### 413 ```json { "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "Request body is too large" } } } } } ``` ### 415 ```json { "description": "The request uses an unsupported media type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Request body must be sent as application/json" } } } } } ``` ### 423 ```json { "description": "The resource is temporarily locked or unavailable; retry the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "LOCKED", "message": "A table lock prevents this operation.", "details": { "lock": "insert" } } } } } } ``` ### 429 ```json { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } } ``` ### 500 ```json { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } ``` ### 503 ```json { "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } ``` ## Referenced schemas The following definitions preserve recursive references and composition exactly. ```json { "#/components/schemas/AddTableWorkflowGroupRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique workspace identifier." }, "group": { "type": "object", "properties": { "id": { "description": "Optional client-provided workflow-group identifier.", "type": "string", "minLength": 1 }, "workflowId": { "description": "Backing workflow identifier. Required when `type` is `manual` (which is also the default when `type` is omitted); omit it for an `enrichment` group.", "type": "string", "minLength": 1 }, "enrichmentId": { "description": "Registry enrichment identifier.", "type": "string", "minLength": 1 }, "name": { "description": "Workflow-group display name.", "type": "string" }, "type": { "description": "Workflow-group producer type.", "type": "string", "enum": [ "manual", "enrichment" ] }, "dependencies": { "description": "Producer input dependencies.", "type": "object", "properties": { "columns": { "description": "Columns required as producer inputs.", "type": "array", "items": { "type": "string" } } } }, "outputs": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "blockId": { "default": "", "description": "Workflow block producing this output.", "type": "string" }, "path": { "default": "", "description": "Path to the value in the workflow block output.", "type": "string" }, "outputId": { "description": "Registry enrichment output identifier.", "type": "string" }, "columnName": { "type": "string", "minLength": 1, "description": "Table column receiving the output." } }, "required": [ "columnName" ] }, "description": "Producer outputs mapped to columns." }, "inputMappings": { "description": "Workflow inputs mapped from table columns.", "type": "array", "items": { "type": "object", "properties": { "inputName": { "type": "string", "minLength": 1, "description": "Workflow input name." }, "columnName": { "type": "string", "minLength": 1, "description": "Source table column name." } }, "required": [ "inputName", "columnName" ] } }, "deploymentMode": { "description": "Workflow state used for cell runs.", "type": "string", "enum": [ "live", "deployed" ] }, "autoRun": { "description": "Whether this group automatically runs for new rows.", "type": "boolean" } }, "required": [ "outputs" ], "description": "Workflow or enrichment producer definition." }, "outputColumns": { "default": [], "description": "Columns to create for producer outputs. An entry naming a column the table already has attaches that column to the group instead of creating it (its `type` must match), and an output whose column already exists may omit its entry entirely — so `[]` attaches existing columns only.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Output column name." }, "type": { "type": "string", "enum": [ "string", "number", "currency", "boolean", "date", "json", "select" ], "description": "Output column data type." }, "required": { "description": "Whether the output column is required.", "type": "boolean" }, "unique": { "description": "Whether the output column must be unique.", "type": "boolean" } }, "required": [ "name", "type" ], "additionalProperties": false } }, "autoRun": { "default": false, "description": "Whether to schedule existing rows after group creation.", "type": "boolean" } }, "required": [ "workspaceId", "group" ], "additionalProperties": false, "title": "Add table workflow group request", "description": "Workspace scope, producer definition, and output columns.", "examples": [ { "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "group": { "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Enrich company", "outputs": [ { "blockId": "block_lookup", "path": "output.revenue", "columnName": "revenue" } ] }, "outputColumns": [ { "name": "revenue", "type": "number" } ] } ] }, "#/components/headers/X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "#/components/headers/X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "#/components/headers/X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } }, "#/components/schemas/V2AddTableWorkflowGroupResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/V2WorkflowGroupData" } }, "required": [ "data" ], "additionalProperties": false, "title": "Add table workflow group response", "description": "The workflow group and complete resulting table columns." }, "#/components/schemas/V2WorkflowGroupData": { "type": "object", "properties": { "group": { "description": "The created or updated workflow group.", "$ref": "#/components/schemas/V2TableWorkflowGroup" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable server-assigned column identifier.", "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Column name used as the public row-data key." }, "type": { "type": "string", "enum": [ "string", "number", "currency", "boolean", "date", "json", "select" ], "description": "Data type of values stored in the column." }, "required": { "default": false, "description": "Whether inserts require a value for this column.", "type": "boolean" }, "unique": { "default": false, "description": "Whether values must be unique across table rows.", "type": "boolean" }, "workflowGroupId": { "description": "Workflow group whose output populates this column.", "type": "string" }, "options": { "description": "Options declared for a select column.", "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable select-option identifier." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name of the select option." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "multiple": { "description": "Whether a select column accepts multiple options.", "type": "boolean" }, "currencyCode": { "description": "ISO 4217 code for a currency column, normalized to uppercase.", "type": "string", "pattern": "^[A-Za-z]{3}$" } }, "required": [ "name", "type", "required", "unique" ], "additionalProperties": false, "description": "A typed column in a table schema." }, "description": "Current table columns after the mutation." } }, "required": [ "group", "columns" ], "additionalProperties": false, "title": "Workflow group data", "description": "Response data." }, "#/components/schemas/V2TableWorkflowGroup": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow-group identifier." }, "workflowId": { "type": "string", "description": "Backing workflow identifier for a manual group." }, "enrichmentId": { "description": "Registry enrichment identifier.", "type": "string" }, "name": { "description": "Workflow-group display name.", "type": "string" }, "type": { "description": "Producer type.", "type": "string", "enum": [ "manual", "enrichment" ] }, "dependencies": { "description": "Input column dependencies.", "type": "object", "properties": { "columns": { "description": "Columns required as producer inputs.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Workflow block producing this output." }, "path": { "type": "string", "description": "Path to the value in the workflow block output." }, "outputId": { "description": "Registry enrichment output identifier.", "type": "string" }, "columnName": { "type": "string", "description": "Name of the table column receiving the output." } }, "required": [ "blockId", "path", "columnName" ], "additionalProperties": false }, "description": "Workflow outputs mapped to table columns." }, "inputMappings": { "description": "Workflow inputs mapped from table columns.", "type": "array", "items": { "type": "object", "properties": { "inputName": { "type": "string", "description": "Workflow input name." }, "columnName": { "type": "string", "description": "Name of the source table column." } }, "required": [ "inputName", "columnName" ], "additionalProperties": false } }, "deploymentMode": { "type": "string", "enum": [ "live", "deployed" ], "description": "Which workflow state per-cell runs execute against. `deployed` (the default when a group was created without one) runs the latest active deployment and refuses to run while the workflow is undeployed; `live` runs the editable draft." }, "autoRun": { "description": "Whether the group automatically runs for new rows.", "type": "boolean" } }, "required": [ "id", "workflowId", "outputs", "deploymentMode" ], "additionalProperties": false, "title": "Table workflow group", "description": "The created or updated workflow group." }, "#/components/responses/BadRequest": { "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "#/components/schemas/V2Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "$ref": "#/components/schemas/V2ActionableForbiddenDetails" }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "#/components/schemas/V2ActionableForbiddenDetails": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/V2ForbiddenDetailCode" } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, "#/components/schemas/V2ForbiddenDetailCode": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." }, "#/components/responses/Unauthorized": { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } }, "#/components/responses/Forbidden": { "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } }, "#/components/responses/NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } }, "#/components/responses/PayloadTooLarge": { "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "Request body is too large" } } } } }, "#/components/responses/UnsupportedMediaType": { "description": "The request uses an unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Request body must be sent as application/json" } } } } }, "#/components/responses/Locked": { "description": "The resource is temporarily locked or unavailable; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "LOCKED", "message": "A table lock prevents this operation.", "details": { "lock": "insert" } } } } } }, "#/components/responses/RateLimited": { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } }, "#/components/headers/Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } }, "#/components/responses/InternalError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } }, "#/components/responses/ServiceUnavailable": { "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } } ``` [Download OpenAPI specification](/openapi.json) Source: `openapi-v2-tables.json`, operation `addTableWorkflowGroup`.