# Get block (/api-reference/catalog/getBlock) `GET /api/v2/blocks/{blockId}` Get a block's fields, conditions, operations, tool schemas, and triggers. Unversioned types resolve to the newest visible version; the returned `id` identifies that version. Hidden or missing blocks return `404`. OAuth scope: `api:read`. ## Authentication ```json { "requirements": [ { "apiKey": [] }, { "oauthBearer": [ "api:read" ] } ], "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:read`. ## Request examples ### cURL ```bash curl --request GET 'https://www.sim.ai/api/v2/blocks/string?workspaceId=string' \ --header 'X-API-Key: YOUR_API_KEY' ``` ### JavaScript ```javascript const response = await fetch("https://www.sim.ai/api/v2/blocks/string?workspaceId=string", { "method": "GET", "headers": { "X-API-Key": "YOUR_API_KEY" } }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const result = await response.json(); ``` ### Python ```python import requests response = requests.request( "GET", "https://www.sim.ai/api/v2/blocks/string?workspaceId=string", headers={ "X-API-Key": "YOUR_API_KEY" }, ) response.raise_for_status() result = response.json() ``` ### Go ```go package main import ( "io" "net/http" "os" ) 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("GET", "https://www.sim.ai/api/v2/blocks/string?workspaceId=string", nil)) request.Header.Set("X-API-Key", "YOUR_API_KEY") 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/blocks/string?workspaceId=string")); builder.header("X-API-Key", "YOUR_API_KEY"); var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).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("GET"), "https://www.sim.ai/api/v2/blocks/string?workspaceId=string"); request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY"); using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); response.EnsureSuccessStatusCode(); await response.Content.CopyToAsync(Console.OpenStandardOutput()); ``` ## Parameters ```json [ { "name": "blockId", "in": "path", "required": true, "description": "Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID." } }, { "name": "workspaceId", "in": "query", "required": true, "description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains." } } ] ``` ## Responses ### 200 ```json { "description": "The block.", "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": { "id": { "type": "string", "description": "Block type identifier, used as a workflow block’s `type`." }, "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "One-line summary of what the block does." }, "longDescription": { "description": "Extended explanation, when the block has one.", "type": "string" }, "category": { "type": "string", "description": "Toolbar category: `blocks`, `tools`, or `triggers`." }, "integrationType": { "description": "Integration category, e.g. `communication`, `databases`.", "type": "string" }, "source": { "type": "string", "enum": [ "builtin", "custom" ], "description": "Block source: `builtin` for built-in blocks, or `custom` for workflows this workspace deployed as blocks." }, "authMode": { "description": "How the block authenticates: `oauth`, `api_key`, or `bot_token`.", "type": "string" }, "triggerAllowed": { "type": "boolean", "description": "Whether the block declares itself usable as a trigger." }, "triggerCapable": { "type": "boolean", "description": "Whether the block can start a workflow — a trigger-category block, one declaring `triggerAllowed`, or one with trigger-mode fields." }, "triggerIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the triggers this block supports." }, "toolIds": { "type": "array", "items": { "type": "string" }, "description": "Built-in tools this block can run. Read a tool by its id for the full definition." }, "operationIds": { "type": "array", "items": { "type": "string" }, "description": "Operations this block exposes. Their fields and tools are on the block read." }, "preview": { "type": "boolean", "description": "Whether the block is unreleased and revealed only to this caller." }, "sunset": { "description": "Post-release lifecycle state. Absent for a block in normal support.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "legacy", "deprecated" ], "description": "`legacy` is superseded but supported; `deprecated` is slated for removal." }, "replacedBy": { "description": "Block type to migrate to, when one exists.", "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "docsLink": { "description": "Sim documentation page for the integration.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Catalog tags, e.g. `messaging`, `version-control`." }, "bestPractices": { "description": "Authored guidance on using the block correctly.", "type": "string" }, "inputSchema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Field identifier, and the key its value is stored under." }, "type": { "type": "string", "description": "Editor control the field renders as, e.g. `short-input`." }, "title": { "description": "Human-readable label.", "type": "string" }, "required": { "description": "Whether a value must always be supplied. A field required only under some configuration reports `false` and carries `requiredWhen`.", "type": "boolean" }, "requiredWhen": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field is required." }, "description": { "description": "Authored explanation of the field.", "type": "string" }, "placeholder": { "description": "Placeholder shown in the editor.", "type": "string" }, "mode": { "description": "Where the field renders: `basic`, `advanced`, `both`, `trigger`, or `trigger-advanced`.", "type": "string" }, "hidden": { "description": "Whether the field is hidden in the editor.", "type": "boolean" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "condition": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field applies at all." }, "options": { "description": "Selectable options. Absent on fields whose options are fetched per workspace at edit time. A `model` field always carries its options, with `hosted` marking the models a hosted deployment runs without an author-supplied key.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value stored when this option is selected." }, "label": { "description": "Human-readable option label.", "type": "string" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "hasIcon": { "description": "Whether the option renders with an icon. The icon itself is not published.", "type": "boolean" }, "hosted": { "description": "Model options only: whether Sim runs the model with its own key on a hosted deployment, so no provider API key is needed for it.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } }, "min": { "description": "Minimum accepted numeric value.", "type": "number" }, "max": { "description": "Maximum accepted numeric value.", "type": "number" }, "step": { "description": "Increment for numeric controls.", "type": "number" }, "integer": { "description": "Whether the numeric value must be a whole number.", "type": "boolean" }, "rows": { "description": "Visible row count for multi-line text.", "type": "number" }, "password": { "description": "Whether the stored value is masked in the editor.", "type": "boolean" }, "multiSelect": { "description": "Whether more than one option may be selected.", "type": "boolean" }, "language": { "description": "Language of a code field.", "type": "string" }, "generationType": { "description": "Kind of content AI assistance generates here.", "type": "string" }, "serviceId": { "description": "OAuth service this credential field authenticates.", "type": "string" }, "requiredScopes": { "description": "OAuth scopes the credential selected here must carry.", "type": "array", "items": { "type": "string" } }, "mimeType": { "description": "MIME type filter applied to a file picker.", "type": "string" }, "acceptedTypes": { "description": "Accepted file extensions for an upload field.", "type": "string" }, "multiple": { "description": "Whether more than one file may be supplied.", "type": "boolean" }, "maxSize": { "description": "Maximum upload size in megabytes.", "type": "number" }, "connectionDroppable": { "description": "Whether another block’s output can be dropped onto this field.", "type": "boolean" }, "columns": { "description": "Column headings for a table field.", "type": "array", "items": { "type": "string" } }, "dependsOn": { "description": "Sibling fields this field is cleared by when they change.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "all": { "description": "Every listed field must hold a value.", "type": "array", "items": { "type": "string" } }, "any": { "description": "At least one listed field must hold a value.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ] }, "canonicalParamId": { "description": "Shared key for a picker/manual-entry pair. Both fields write the same value, so supply exactly one of the pair.", "type": "string" }, "defaultValue": { "description": "Value used when the field is left unset.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Member of an object-valued default. Shape varies by field type." } }, { "type": "array", "items": { "description": "Element of an array-valued default. Shape varies by field type." } } ] }, "hasComputedDefault": { "description": "Whether the field derives its value from the block’s other values. The deriving function is not published.", "type": "boolean" } }, "required": [ "id", "type" ], "additionalProperties": false, "title": "Block field", "description": "One configuration field on a block." }, "description": "Configuration fields that apply regardless of the selected operation." }, "operationInputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Field identifier, and the key its value is stored under." }, "type": { "type": "string", "description": "Editor control the field renders as, e.g. `short-input`." }, "title": { "description": "Human-readable label.", "type": "string" }, "required": { "description": "Whether a value must always be supplied. A field required only under some configuration reports `false` and carries `requiredWhen`.", "type": "boolean" }, "requiredWhen": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field is required." }, "description": { "description": "Authored explanation of the field.", "type": "string" }, "placeholder": { "description": "Placeholder shown in the editor.", "type": "string" }, "mode": { "description": "Where the field renders: `basic`, `advanced`, `both`, `trigger`, or `trigger-advanced`.", "type": "string" }, "hidden": { "description": "Whether the field is hidden in the editor.", "type": "boolean" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "condition": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field applies at all." }, "options": { "description": "Selectable options. Absent on fields whose options are fetched per workspace at edit time. A `model` field always carries its options, with `hosted` marking the models a hosted deployment runs without an author-supplied key.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value stored when this option is selected." }, "label": { "description": "Human-readable option label.", "type": "string" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "hasIcon": { "description": "Whether the option renders with an icon. The icon itself is not published.", "type": "boolean" }, "hosted": { "description": "Model options only: whether Sim runs the model with its own key on a hosted deployment, so no provider API key is needed for it.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } }, "min": { "description": "Minimum accepted numeric value.", "type": "number" }, "max": { "description": "Maximum accepted numeric value.", "type": "number" }, "step": { "description": "Increment for numeric controls.", "type": "number" }, "integer": { "description": "Whether the numeric value must be a whole number.", "type": "boolean" }, "rows": { "description": "Visible row count for multi-line text.", "type": "number" }, "password": { "description": "Whether the stored value is masked in the editor.", "type": "boolean" }, "multiSelect": { "description": "Whether more than one option may be selected.", "type": "boolean" }, "language": { "description": "Language of a code field.", "type": "string" }, "generationType": { "description": "Kind of content AI assistance generates here.", "type": "string" }, "serviceId": { "description": "OAuth service this credential field authenticates.", "type": "string" }, "requiredScopes": { "description": "OAuth scopes the credential selected here must carry.", "type": "array", "items": { "type": "string" } }, "mimeType": { "description": "MIME type filter applied to a file picker.", "type": "string" }, "acceptedTypes": { "description": "Accepted file extensions for an upload field.", "type": "string" }, "multiple": { "description": "Whether more than one file may be supplied.", "type": "boolean" }, "maxSize": { "description": "Maximum upload size in megabytes.", "type": "number" }, "connectionDroppable": { "description": "Whether another block’s output can be dropped onto this field.", "type": "boolean" }, "columns": { "description": "Column headings for a table field.", "type": "array", "items": { "type": "string" } }, "dependsOn": { "description": "Sibling fields this field is cleared by when they change.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "all": { "description": "Every listed field must hold a value.", "type": "array", "items": { "type": "string" } }, "any": { "description": "At least one listed field must hold a value.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ] }, "canonicalParamId": { "description": "Shared key for a picker/manual-entry pair. Both fields write the same value, so supply exactly one of the pair.", "type": "string" }, "defaultValue": { "description": "Value used when the field is left unset.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Member of an object-valued default. Shape varies by field type." } }, { "type": "array", "items": { "description": "Element of an array-valued default. Shape varies by field type." } } ] }, "hasComputedDefault": { "description": "Whether the field derives its value from the block’s other values. The deriving function is not published.", "type": "boolean" } }, "required": [ "id", "type" ], "additionalProperties": false, "title": "Block field", "description": "One configuration field on a block." } }, "description": "Configuration fields keyed by the operation that reveals them." }, "inputDefinitions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type: `string`, `number`, `boolean`, `json`, `array`, or `file`." }, "description": { "description": "What the input means.", "type": "string" }, "schema": { "description": "JSON-Schema-shaped structure for object and array inputs." } }, "required": [ "type" ], "additionalProperties": false }, "description": "Block-level input definitions, keyed by parameter name." }, "operations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "toolId": { "description": "Built-in tool that performs this operation.", "type": "string" }, "toolName": { "description": "Display name of that tool.", "type": "string" }, "description": { "description": "What the operation does.", "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type." }, "required": { "description": "Whether the value must be supplied.", "type": "boolean" }, "visibility": { "description": "Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.", "type": "string" }, "description": { "description": "What the value means.", "type": "string" }, "default": { "description": "Value used when this input is omitted." }, "items": { "description": "JSON-Schema-shaped constraints declared by the tool parameter." }, "schema": { "description": "JSON-Schema-shaped structure declared by the block input." } }, "required": [ "type" ], "additionalProperties": false, "title": "Operation input", "description": "One value a block operation needs, from its tool or its block-level inputs." }, "description": "Values this operation needs, excluding the ones the block supplies from its own block-level inputs." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output field." }, "description": { "description": "What the field holds.", "type": "string" }, "optional": { "description": "Whether the field may be absent.", "type": "boolean" }, "nullable": { "description": "Whether the field may be null.", "type": "boolean" }, "properties": { "description": "Members of an object-typed output, keyed by field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Nested output field, in this same shape." } }, "items": { "description": "Element shape of an array-typed output.", "type": "object", "properties": { "type": { "type": "string", "description": "Element value type." }, "description": { "description": "What an element holds.", "type": "string" }, "properties": { "description": "Members of an object-typed element, keyed by field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Nested output field, in this same shape." } } }, "required": [ "type" ], "additionalProperties": false }, "fileConfig": { "description": "File metadata for a file-typed output.", "type": "object", "properties": { "mimeType": { "description": "MIME type of the produced file.", "type": "string" }, "extension": { "description": "File extension of the produced file.", "type": "string" } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false, "title": "Tool output", "description": "One declared output field of a built-in tool." }, "description": "Fields the operation produces." }, "inputSchema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Field identifier, and the key its value is stored under." }, "type": { "type": "string", "description": "Editor control the field renders as, e.g. `short-input`." }, "title": { "description": "Human-readable label.", "type": "string" }, "required": { "description": "Whether a value must always be supplied. A field required only under some configuration reports `false` and carries `requiredWhen`.", "type": "boolean" }, "requiredWhen": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field is required." }, "description": { "description": "Authored explanation of the field.", "type": "string" }, "placeholder": { "description": "Placeholder shown in the editor.", "type": "string" }, "mode": { "description": "Where the field renders: `basic`, `advanced`, `both`, `trigger`, or `trigger-advanced`.", "type": "string" }, "hidden": { "description": "Whether the field is hidden in the editor.", "type": "boolean" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "condition": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field applies at all." }, "options": { "description": "Selectable options. Absent on fields whose options are fetched per workspace at edit time. A `model` field always carries its options, with `hosted` marking the models a hosted deployment runs without an author-supplied key.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value stored when this option is selected." }, "label": { "description": "Human-readable option label.", "type": "string" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "hasIcon": { "description": "Whether the option renders with an icon. The icon itself is not published.", "type": "boolean" }, "hosted": { "description": "Model options only: whether Sim runs the model with its own key on a hosted deployment, so no provider API key is needed for it.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } }, "min": { "description": "Minimum accepted numeric value.", "type": "number" }, "max": { "description": "Maximum accepted numeric value.", "type": "number" }, "step": { "description": "Increment for numeric controls.", "type": "number" }, "integer": { "description": "Whether the numeric value must be a whole number.", "type": "boolean" }, "rows": { "description": "Visible row count for multi-line text.", "type": "number" }, "password": { "description": "Whether the stored value is masked in the editor.", "type": "boolean" }, "multiSelect": { "description": "Whether more than one option may be selected.", "type": "boolean" }, "language": { "description": "Language of a code field.", "type": "string" }, "generationType": { "description": "Kind of content AI assistance generates here.", "type": "string" }, "serviceId": { "description": "OAuth service this credential field authenticates.", "type": "string" }, "requiredScopes": { "description": "OAuth scopes the credential selected here must carry.", "type": "array", "items": { "type": "string" } }, "mimeType": { "description": "MIME type filter applied to a file picker.", "type": "string" }, "acceptedTypes": { "description": "Accepted file extensions for an upload field.", "type": "string" }, "multiple": { "description": "Whether more than one file may be supplied.", "type": "boolean" }, "maxSize": { "description": "Maximum upload size in megabytes.", "type": "number" }, "connectionDroppable": { "description": "Whether another block’s output can be dropped onto this field.", "type": "boolean" }, "columns": { "description": "Column headings for a table field.", "type": "array", "items": { "type": "string" } }, "dependsOn": { "description": "Sibling fields this field is cleared by when they change.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "all": { "description": "Every listed field must hold a value.", "type": "array", "items": { "type": "string" } }, "any": { "description": "At least one listed field must hold a value.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ] }, "canonicalParamId": { "description": "Shared key for a picker/manual-entry pair. Both fields write the same value, so supply exactly one of the pair.", "type": "string" }, "defaultValue": { "description": "Value used when the field is left unset.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Member of an object-valued default. Shape varies by field type." } }, { "type": "array", "items": { "description": "Element of an array-valued default. Shape varies by field type." } } ] }, "hasComputedDefault": { "description": "Whether the field derives its value from the block’s other values. The deriving function is not published.", "type": "boolean" } }, "required": [ "id", "type" ], "additionalProperties": false, "title": "Block field", "description": "One configuration field on a block." }, "description": "Configuration fields that appear when this operation is selected." } }, "required": [ "inputs", "outputs", "inputSchema" ], "additionalProperties": false }, "description": "Operations the block exposes, keyed by operation id." }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Registered tool identifier, including its version suffix." }, "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "What the tool does." }, "version": { "description": "Tool version.", "type": "string" }, "hostedApiKey": { "type": "string", "enum": [ "always", "conditional", "none" ], "description": "API-key hosting on this deployment: `always`, `conditional` for some parameter combinations, or `none` when Sim does not supply a key. Supply your own key only if the tool requires one. Self-hosted deployments report `none` for every tool." }, "oauth": { "description": "OAuth requirement, when the tool has one.", "type": "object", "properties": { "required": { "type": "boolean", "description": "Whether the tool cannot run without an OAuth credential." }, "provider": { "type": "string", "description": "OAuth service the credential must authenticate." }, "requiredScopes": { "description": "Scopes the credential must carry.", "type": "array", "items": { "type": "string" } } }, "required": [ "required", "provider" ], "additionalProperties": false }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Parameter value type." }, "required": { "description": "Whether the parameter must be supplied.", "type": "boolean" }, "visibility": { "description": "Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.", "type": "string" }, "description": { "description": "What the parameter means.", "type": "string" }, "default": { "description": "Value used when the parameter is omitted." }, "items": { "description": "JSON-Schema-shaped constraints for structured params." } }, "required": [ "type" ], "additionalProperties": false, "title": "Tool parameter", "description": "One declared parameter of a built-in tool." }, "description": "Parameters the tool accepts." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output field." }, "description": { "description": "What the field holds.", "type": "string" }, "optional": { "description": "Whether the field may be absent.", "type": "boolean" }, "nullable": { "description": "Whether the field may be null.", "type": "boolean" }, "properties": { "description": "Members of an object-typed output, keyed by field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Nested output field, in this same shape." } }, "items": { "description": "Element shape of an array-typed output.", "type": "object", "properties": { "type": { "type": "string", "description": "Element value type." }, "description": { "description": "What an element holds.", "type": "string" }, "properties": { "description": "Members of an object-typed element, keyed by field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Nested output field, in this same shape." } } }, "required": [ "type" ], "additionalProperties": false }, "fileConfig": { "description": "File metadata for a file-typed output.", "type": "object", "properties": { "mimeType": { "description": "MIME type of the produced file.", "type": "string" }, "extension": { "description": "File extension of the produced file.", "type": "string" } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false, "title": "Tool output", "description": "One declared output field of a built-in tool." }, "description": "Fields the tool produces." } }, "required": [ "id", "name", "description", "hostedApiKey", "params", "outputs" ], "additionalProperties": false, "title": "Tool", "description": "A built-in tool with its declared parameters and outputs." }, "description": "Every built-in tool the block can run, with parameters and outputs." }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Trigger identifier." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output." }, "description": { "description": "What the output holds.", "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "description": "Top-level fields the trigger event delivers." }, "configFields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Editor control the field renders as." }, "required": { "type": "boolean", "description": "Whether a value must be supplied." }, "title": { "description": "Human-readable label.", "type": "string" }, "description": { "description": "Authored explanation of the field.", "type": "string" }, "placeholder": { "description": "Placeholder shown in the editor.", "type": "string" }, "default": { "description": "Value used when the field is left unset." }, "options": { "description": "Selectable options.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value stored when this option is selected." }, "label": { "type": "string", "description": "Human-readable option label." }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false } }, "required": [ "id", "label" ], "additionalProperties": false } }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "condition": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field applies." } }, "required": [ "type", "required" ], "additionalProperties": false }, "description": "Fields that configure the trigger, keyed by field id." } }, "required": [ "id", "outputs", "configFields" ], "additionalProperties": false }, "description": "Triggers the block can run on." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output." }, "description": { "description": "What the output holds.", "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "description": "Fields the block produces." } }, "required": [ "id", "name", "description", "category", "source", "triggerAllowed", "triggerCapable", "triggerIds", "toolIds", "operationIds", "preview", "tags", "inputSchema", "operationInputSchema", "inputDefinitions", "operations", "tools", "triggers", "outputs" ], "additionalProperties": false, "title": "Block", "description": "Response data." } }, "required": [ "data" ], "additionalProperties": false, "title": "Get block response", "description": "One block with its fields, operations, tools, and triggers.", "examples": [ { "data": { "id": "slack", "name": "Slack", "description": "Send messages and read channels in Slack.", "category": "tools", "integrationType": "communication", "source": "builtin", "authMode": "oauth", "triggerAllowed": true, "triggerCapable": true, "triggerIds": [ "slack_webhook" ], "toolIds": [ "slack_message", "slack_canvas_read" ], "operationIds": [ "send", "read" ], "preview": false, "docsLink": "https://docs.sim.ai/tools/slack", "tags": [ "messaging" ], "inputSchema": [ { "id": "operation", "type": "dropdown", "title": "Operation", "required": true, "options": [ { "id": "send", "label": "Send message" }, { "id": "read", "label": "Read messages" } ] } ], "operationInputSchema": { "send": [ { "id": "text", "type": "long-input", "title": "Message", "required": true } ] }, "inputDefinitions": { "channel": { "type": "string", "description": "Channel to post into." } }, "operations": { "send": { "toolId": "slack_message", "toolName": "Slack Send Message", "description": "Send a message to a Slack channel.", "inputs": { "text": { "type": "string", "required": true, "description": "Message body." } }, "outputs": { "ts": { "type": "string", "description": "Message timestamp." } }, "inputSchema": [ { "id": "text", "type": "long-input", "title": "Message", "required": true } ] } }, "tools": [ { "id": "slack_message", "name": "Slack Send Message", "description": "Send a message to a Slack channel.", "version": "1.0.0", "hostedApiKey": "none", "oauth": { "required": true, "provider": "slack", "requiredScopes": [ "chat:write" ] }, "params": { "text": { "type": "string", "required": true, "description": "Message body." } }, "outputs": { "ts": { "type": "string", "description": "Message timestamp." } } } ], "triggers": [ { "id": "slack_webhook", "outputs": { "text": { "type": "string", "description": "Message text." } }, "configFields": { "channels": { "type": "short-input", "required": false, "title": "Channels" } } } ], "outputs": { "ts": { "type": "string", "description": "Message timestamp." } } } } ] }, "examples": { "example1": { "summary": "Response example 1", "value": { "data": { "id": "slack", "name": "Slack", "description": "Send messages and read channels in Slack.", "category": "tools", "integrationType": "communication", "source": "builtin", "authMode": "oauth", "triggerAllowed": true, "triggerCapable": true, "triggerIds": [ "slack_webhook" ], "toolIds": [ "slack_message", "slack_canvas_read" ], "operationIds": [ "send", "read" ], "preview": false, "docsLink": "https://docs.sim.ai/tools/slack", "tags": [ "messaging" ], "inputSchema": [ { "id": "operation", "type": "dropdown", "title": "Operation", "required": true, "options": [ { "id": "send", "label": "Send message" }, { "id": "read", "label": "Read messages" } ] } ], "operationInputSchema": { "send": [ { "id": "text", "type": "long-input", "title": "Message", "required": true } ] }, "inputDefinitions": { "channel": { "type": "string", "description": "Channel to post into." } }, "operations": { "send": { "toolId": "slack_message", "toolName": "Slack Send Message", "description": "Send a message to a Slack channel.", "inputs": { "text": { "type": "string", "required": true, "description": "Message body." } }, "outputs": { "ts": { "type": "string", "description": "Message timestamp." } }, "inputSchema": [ { "id": "text", "type": "long-input", "title": "Message", "required": true } ] } }, "tools": [ { "id": "slack_message", "name": "Slack Send Message", "description": "Send a message to a Slack channel.", "version": "1.0.0", "hostedApiKey": "none", "oauth": { "required": true, "provider": "slack", "requiredScopes": [ "chat:write" ] }, "params": { "text": { "type": "string", "required": true, "description": "Message body." } }, "outputs": { "ts": { "type": "string", "description": "Message timestamp." } } } ], "triggers": [ { "id": "slack_webhook", "outputs": { "text": { "type": "string", "description": "Message text." } }, "configFields": { "channels": { "type": "short-input", "required": false, "title": "Channels" } } } ], "outputs": { "ts": { "type": "string", "description": "Message timestamp." } } } } } } } } } ``` ### 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" } } } } } ``` ### 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/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/GetBlockResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/V2BlockDetail" } }, "required": [ "data" ], "additionalProperties": false, "title": "Get block response", "description": "One block with its fields, operations, tools, and triggers.", "examples": [ { "data": { "id": "slack", "name": "Slack", "description": "Send messages and read channels in Slack.", "category": "tools", "integrationType": "communication", "source": "builtin", "authMode": "oauth", "triggerAllowed": true, "triggerCapable": true, "triggerIds": [ "slack_webhook" ], "toolIds": [ "slack_message", "slack_canvas_read" ], "operationIds": [ "send", "read" ], "preview": false, "docsLink": "https://docs.sim.ai/tools/slack", "tags": [ "messaging" ], "inputSchema": [ { "id": "operation", "type": "dropdown", "title": "Operation", "required": true, "options": [ { "id": "send", "label": "Send message" }, { "id": "read", "label": "Read messages" } ] } ], "operationInputSchema": { "send": [ { "id": "text", "type": "long-input", "title": "Message", "required": true } ] }, "inputDefinitions": { "channel": { "type": "string", "description": "Channel to post into." } }, "operations": { "send": { "toolId": "slack_message", "toolName": "Slack Send Message", "description": "Send a message to a Slack channel.", "inputs": { "text": { "type": "string", "required": true, "description": "Message body." } }, "outputs": { "ts": { "type": "string", "description": "Message timestamp." } }, "inputSchema": [ { "id": "text", "type": "long-input", "title": "Message", "required": true } ] } }, "tools": [ { "id": "slack_message", "name": "Slack Send Message", "description": "Send a message to a Slack channel.", "version": "1.0.0", "hostedApiKey": "none", "oauth": { "required": true, "provider": "slack", "requiredScopes": [ "chat:write" ] }, "params": { "text": { "type": "string", "required": true, "description": "Message body." } }, "outputs": { "ts": { "type": "string", "description": "Message timestamp." } } } ], "triggers": [ { "id": "slack_webhook", "outputs": { "text": { "type": "string", "description": "Message text." } }, "configFields": { "channels": { "type": "short-input", "required": false, "title": "Channels" } } } ], "outputs": { "ts": { "type": "string", "description": "Message timestamp." } } } } ] }, "#/components/schemas/V2BlockDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Block type identifier, used as a workflow block’s `type`." }, "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "One-line summary of what the block does." }, "longDescription": { "description": "Extended explanation, when the block has one.", "type": "string" }, "category": { "type": "string", "description": "Toolbar category: `blocks`, `tools`, or `triggers`." }, "integrationType": { "description": "Integration category, e.g. `communication`, `databases`.", "type": "string" }, "source": { "type": "string", "enum": [ "builtin", "custom" ], "description": "Block source: `builtin` for built-in blocks, or `custom` for workflows this workspace deployed as blocks." }, "authMode": { "description": "How the block authenticates: `oauth`, `api_key`, or `bot_token`.", "type": "string" }, "triggerAllowed": { "type": "boolean", "description": "Whether the block declares itself usable as a trigger." }, "triggerCapable": { "type": "boolean", "description": "Whether the block can start a workflow — a trigger-category block, one declaring `triggerAllowed`, or one with trigger-mode fields." }, "triggerIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the triggers this block supports." }, "toolIds": { "type": "array", "items": { "type": "string" }, "description": "Built-in tools this block can run. Read a tool by its id for the full definition." }, "operationIds": { "type": "array", "items": { "type": "string" }, "description": "Operations this block exposes. Their fields and tools are on the block read." }, "preview": { "type": "boolean", "description": "Whether the block is unreleased and revealed only to this caller." }, "sunset": { "description": "Post-release lifecycle state. Absent for a block in normal support.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "legacy", "deprecated" ], "description": "`legacy` is superseded but supported; `deprecated` is slated for removal." }, "replacedBy": { "description": "Block type to migrate to, when one exists.", "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "docsLink": { "description": "Sim documentation page for the integration.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Catalog tags, e.g. `messaging`, `version-control`." }, "bestPractices": { "description": "Authored guidance on using the block correctly.", "type": "string" }, "inputSchema": { "type": "array", "items": { "$ref": "#/components/schemas/V2BlockField" }, "description": "Configuration fields that apply regardless of the selected operation." }, "operationInputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/V2BlockField" } }, "description": "Configuration fields keyed by the operation that reveals them." }, "inputDefinitions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type: `string`, `number`, `boolean`, `json`, `array`, or `file`." }, "description": { "description": "What the input means.", "type": "string" }, "schema": { "description": "JSON-Schema-shaped structure for object and array inputs." } }, "required": [ "type" ], "additionalProperties": false }, "description": "Block-level input definitions, keyed by parameter name." }, "operations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "toolId": { "description": "Built-in tool that performs this operation.", "type": "string" }, "toolName": { "description": "Display name of that tool.", "type": "string" }, "description": { "description": "What the operation does.", "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/V2OperationInput" }, "description": "Values this operation needs, excluding the ones the block supplies from its own block-level inputs." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/V2ToolOutput" }, "description": "Fields the operation produces." }, "inputSchema": { "type": "array", "items": { "$ref": "#/components/schemas/V2BlockField" }, "description": "Configuration fields that appear when this operation is selected." } }, "required": [ "inputs", "outputs", "inputSchema" ], "additionalProperties": false }, "description": "Operations the block exposes, keyed by operation id." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/V2ToolDetail" }, "description": "Every built-in tool the block can run, with parameters and outputs." }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Trigger identifier." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output." }, "description": { "description": "What the output holds.", "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "description": "Top-level fields the trigger event delivers." }, "configFields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Editor control the field renders as." }, "required": { "type": "boolean", "description": "Whether a value must be supplied." }, "title": { "description": "Human-readable label.", "type": "string" }, "description": { "description": "Authored explanation of the field.", "type": "string" }, "placeholder": { "description": "Placeholder shown in the editor.", "type": "string" }, "default": { "description": "Value used when the field is left unset." }, "options": { "description": "Selectable options.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value stored when this option is selected." }, "label": { "type": "string", "description": "Human-readable option label." }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false } }, "required": [ "id", "label" ], "additionalProperties": false } }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "condition": { "description": "Condition under which the field applies.", "$ref": "#/components/schemas/V2CatalogCondition" } }, "required": [ "type", "required" ], "additionalProperties": false }, "description": "Fields that configure the trigger, keyed by field id." } }, "required": [ "id", "outputs", "configFields" ], "additionalProperties": false }, "description": "Triggers the block can run on." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output." }, "description": { "description": "What the output holds.", "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "description": "Fields the block produces." } }, "required": [ "id", "name", "description", "category", "source", "triggerAllowed", "triggerCapable", "triggerIds", "toolIds", "operationIds", "preview", "tags", "inputSchema", "operationInputSchema", "inputDefinitions", "operations", "tools", "triggers", "outputs" ], "additionalProperties": false, "title": "Block", "description": "Response data." }, "#/components/schemas/V2BlockField": { "type": "object", "properties": { "id": { "type": "string", "description": "Field identifier, and the key its value is stored under." }, "type": { "type": "string", "description": "Editor control the field renders as, e.g. `short-input`." }, "title": { "description": "Human-readable label.", "type": "string" }, "required": { "description": "Whether a value must always be supplied. A field required only under some configuration reports `false` and carries `requiredWhen`.", "type": "boolean" }, "requiredWhen": { "description": "Condition under which the field is required.", "$ref": "#/components/schemas/V2CatalogCondition" }, "description": { "description": "Authored explanation of the field.", "type": "string" }, "placeholder": { "description": "Placeholder shown in the editor.", "type": "string" }, "mode": { "description": "Where the field renders: `basic`, `advanced`, `both`, `trigger`, or `trigger-advanced`.", "type": "string" }, "hidden": { "description": "Whether the field is hidden in the editor.", "type": "boolean" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "condition": { "description": "Condition under which the field applies at all.", "$ref": "#/components/schemas/V2CatalogCondition" }, "options": { "description": "Selectable options. Absent on fields whose options are fetched per workspace at edit time. A `model` field always carries its options, with `hosted` marking the models a hosted deployment runs without an author-supplied key.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value stored when this option is selected." }, "label": { "description": "Human-readable option label.", "type": "string" }, "reactiveCondition": { "description": "Credential-kind requirement for this field or option; inspect the selected credential before using it.", "type": "object", "properties": { "watchFields": { "type": "array", "items": { "type": "string" }, "description": "Credential selector fields; the first populated value identifies the credential." }, "requiredType": { "type": "string", "enum": [ "oauth", "service_account" ], "description": "Credential kind required for this field or option to apply." } }, "required": [ "watchFields", "requiredType" ], "additionalProperties": false }, "hasIcon": { "description": "Whether the option renders with an icon. The icon itself is not published.", "type": "boolean" }, "hosted": { "description": "Model options only: whether Sim runs the model with its own key on a hosted deployment, so no provider API key is needed for it.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } }, "min": { "description": "Minimum accepted numeric value.", "type": "number" }, "max": { "description": "Maximum accepted numeric value.", "type": "number" }, "step": { "description": "Increment for numeric controls.", "type": "number" }, "integer": { "description": "Whether the numeric value must be a whole number.", "type": "boolean" }, "rows": { "description": "Visible row count for multi-line text.", "type": "number" }, "password": { "description": "Whether the stored value is masked in the editor.", "type": "boolean" }, "multiSelect": { "description": "Whether more than one option may be selected.", "type": "boolean" }, "language": { "description": "Language of a code field.", "type": "string" }, "generationType": { "description": "Kind of content AI assistance generates here.", "type": "string" }, "serviceId": { "description": "OAuth service this credential field authenticates.", "type": "string" }, "requiredScopes": { "description": "OAuth scopes the credential selected here must carry.", "type": "array", "items": { "type": "string" } }, "mimeType": { "description": "MIME type filter applied to a file picker.", "type": "string" }, "acceptedTypes": { "description": "Accepted file extensions for an upload field.", "type": "string" }, "multiple": { "description": "Whether more than one file may be supplied.", "type": "boolean" }, "maxSize": { "description": "Maximum upload size in megabytes.", "type": "number" }, "connectionDroppable": { "description": "Whether another block’s output can be dropped onto this field.", "type": "boolean" }, "columns": { "description": "Column headings for a table field.", "type": "array", "items": { "type": "string" } }, "dependsOn": { "description": "Sibling fields this field is cleared by when they change.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "all": { "description": "Every listed field must hold a value.", "type": "array", "items": { "type": "string" } }, "any": { "description": "At least one listed field must hold a value.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ] }, "canonicalParamId": { "description": "Shared key for a picker/manual-entry pair. Both fields write the same value, so supply exactly one of the pair.", "type": "string" }, "defaultValue": { "description": "Value used when the field is left unset.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Member of an object-valued default. Shape varies by field type." } }, { "type": "array", "items": { "description": "Element of an array-valued default. Shape varies by field type." } } ] }, "hasComputedDefault": { "description": "Whether the field derives its value from the block’s other values. The deriving function is not published.", "type": "boolean" } }, "required": [ "id", "type" ], "additionalProperties": false, "title": "Block field", "description": "One configuration field on a block." }, "#/components/schemas/V2CatalogCondition": { "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id whose value decides this condition." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Value, or set of accepted values, the named field must hold." }, "not": { "description": "Invert the match: every value EXCEPT `value`.", "type": "boolean" }, "and": { "description": "A second clause that must hold as well.", "type": "object", "properties": { "field": { "type": "string", "description": "Sibling field id for the second clause." }, "value": { "description": "Value the second clause matches. Absent means \"holds any value\".", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] }, "not": { "description": "Invert the second clause.", "type": "boolean" } }, "required": [ "field" ], "additionalProperties": false } }, "required": [ "field", "value" ], "additionalProperties": false, "title": "Catalog condition", "description": "Condition under which the field is required." }, "#/components/schemas/V2OperationInput": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type." }, "required": { "description": "Whether the value must be supplied.", "type": "boolean" }, "visibility": { "description": "Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.", "type": "string" }, "description": { "description": "What the value means.", "type": "string" }, "default": { "description": "Value used when this input is omitted." }, "items": { "description": "JSON-Schema-shaped constraints declared by the tool parameter." }, "schema": { "description": "JSON-Schema-shaped structure declared by the block input." } }, "required": [ "type" ], "additionalProperties": false, "title": "Operation input", "description": "One value a block operation needs, from its tool or its block-level inputs." }, "#/components/schemas/V2ToolOutput": { "type": "object", "properties": { "type": { "type": "string", "description": "Value type of the output field." }, "description": { "description": "What the field holds.", "type": "string" }, "optional": { "description": "Whether the field may be absent.", "type": "boolean" }, "nullable": { "description": "Whether the field may be null.", "type": "boolean" }, "properties": { "description": "Members of an object-typed output, keyed by field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Nested output field, in this same shape." } }, "items": { "description": "Element shape of an array-typed output.", "type": "object", "properties": { "type": { "type": "string", "description": "Element value type." }, "description": { "description": "What an element holds.", "type": "string" }, "properties": { "description": "Members of an object-typed element, keyed by field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Nested output field, in this same shape." } } }, "required": [ "type" ], "additionalProperties": false }, "fileConfig": { "description": "File metadata for a file-typed output.", "type": "object", "properties": { "mimeType": { "description": "MIME type of the produced file.", "type": "string" }, "extension": { "description": "File extension of the produced file.", "type": "string" } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false, "title": "Tool output", "description": "One declared output field of a built-in tool." }, "#/components/schemas/V2ToolDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Registered tool identifier, including its version suffix." }, "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "What the tool does." }, "version": { "description": "Tool version.", "type": "string" }, "hostedApiKey": { "type": "string", "enum": [ "always", "conditional", "none" ], "description": "API-key hosting on this deployment: `always`, `conditional` for some parameter combinations, or `none` when Sim does not supply a key. Supply your own key only if the tool requires one. Self-hosted deployments report `none` for every tool." }, "oauth": { "description": "OAuth requirement, when the tool has one.", "type": "object", "properties": { "required": { "type": "boolean", "description": "Whether the tool cannot run without an OAuth credential." }, "provider": { "type": "string", "description": "OAuth service the credential must authenticate." }, "requiredScopes": { "description": "Scopes the credential must carry.", "type": "array", "items": { "type": "string" } } }, "required": [ "required", "provider" ], "additionalProperties": false }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/V2ToolParam" }, "description": "Parameters the tool accepts." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/V2ToolOutput" }, "description": "Fields the tool produces." } }, "required": [ "id", "name", "description", "hostedApiKey", "params", "outputs" ], "additionalProperties": false, "title": "Tool", "description": "A built-in tool with its declared parameters and outputs." }, "#/components/schemas/V2ToolParam": { "type": "object", "properties": { "type": { "type": "string", "description": "Parameter value type." }, "required": { "description": "Whether the parameter must be supplied.", "type": "boolean" }, "visibility": { "description": "Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.", "type": "string" }, "description": { "description": "What the parameter means.", "type": "string" }, "default": { "description": "Value used when the parameter is omitted." }, "items": { "description": "JSON-Schema-shaped constraints for structured params." } }, "required": [ "type" ], "additionalProperties": false, "title": "Tool parameter", "description": "One declared parameter of a built-in tool." }, "#/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/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-resources.json`, operation `getBlock`.