> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsales.io/llms.txt > Use this file to discover all available pages before exploring further. # Update workflow > Draft-editing verb (partial update). draft_steps is FULL-REPLACE: send the whole array, CARRY the id of every kept step verbatim, OMIT ids on new steps - the response echoes all ids filled. Config edits (sender pool, schedule, on_reply, rotation_strategy, priority) affect FUTURE decisions only; pinned records keep their sender. status = archive family ONLY (archived / paused / draft); anything involving active → 422 - use pause/resume. Archived rows reject other edits. Contract: - MCP tool `update_workflow`, registry package `mcp.playtables/workflows`, mount `playtables.workflows`. - Operation `update`, response envelope `update`. - Flags: none. ## OpenAPI ````yaml /api-reference/playtables/openapi.yaml patch /api/workflows/{sid} openapi: 3.0.3 info: title: 'GetSales public contract: gs.service.playtables' description: >- The data platform and the outreach engine: tables of people and companies, their enrichment columns, cells and runs, the data sources that feed them, sender profiles, the stoplist, the activity feed, the credit ledger, and the multichannel workflows with their per-person journeys and tasks. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gs.service.playtables`, 142 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GetSales url: https://getsales.io email: support@getsales.io license: name: Proprietary url: https://getsales.io/terms servers: - url: https://beta.getsales.io/playtables/v1 description: >- Production (the gateway path on the beta ring; the origin is provisioned per DEPLOY_MAP.md) security: - BearerJwt: [] TeamSid: [] tags: - name: activities description: >- Registry package `mcp.playtables/activities`, served on MCP mount `playtables.journeys`. - name: activity_objects description: >- Registry package `mcp.playtables/activity_objects`, served on MCP mount `playtables.people`. - name: companies description: >- Registry package `mcp.playtables/companies`, served on MCP mount `playtables.people`. - name: credit_ledger_entries description: >- Registry package `mcp.playtables/credit_ledger_entries`, served on MCP mount `id.billing`. - name: data_source_items description: >- Registry package `mcp.playtables/data_source_items`, served on MCP mount `playtables.sources`. - name: data_sources description: >- Registry package `mcp.playtables/data_sources`, served on MCP mount `playtables.sources`. - name: notes description: >- Registry package `mcp.playtables/notes`, served on MCP mount `playtables.pipeline`. - name: people description: >- Registry package `mcp.playtables/people`, served on MCP mount `playtables.people`. - name: pipeline_stages description: >- Registry package `mcp.playtables/pipeline_stages`, served on MCP mount `playtables.pipeline`. - name: plays description: >- Registry package `mcp.playtables/plays`, served on MCP mount `playtables.pipeline`. - name: playtable_field_values description: >- Registry package `mcp.playtables/playtable_field_values`, served on MCP mount `playtables.columns`. - name: playtable_fields description: >- Registry package `mcp.playtables/playtable_fields`, served on MCP mount `playtables.columns`. - name: playtable_runs description: >- Registry package `mcp.playtables/playtable_runs`, served on MCP mount `playtables.columns`. - name: playtable_views description: >- Registry package `mcp.playtables/playtable_views`, served on MCP mount `playtables.tables`. - name: playtables description: >- Registry package `mcp.playtables/playtables`, served on MCP mount `playtables.tables`. - name: result_pages description: >- Registry package `mcp.playtables/result_pages`, served on MCP mount `playtables.tables`. - name: sender_profiles description: >- Registry package `mcp.playtables/sender_profiles`, served on MCP mount `playtables.sources`. - name: stoplist_entries description: >- Registry package `mcp.playtables/stoplist_entries`, served on MCP mount `playtables.stoplist`. - name: tags description: >- Registry package `mcp.playtables/tags`, served on MCP mount `playtables.pipeline`. - name: workflow_attachments description: >- Registry package `mcp.playtables/workflow_attachments`, served on MCP mount `playtables.workflows`. - name: workflow_records description: >- Registry package `mcp.playtables/workflow_records`, served on MCP mount `playtables.journeys`. - name: workflow_sources description: >- Registry package `mcp.playtables/workflow_sources`, served on MCP mount `playtables.workflows`. - name: workflow_tasks description: >- Registry package `mcp.playtables/workflow_tasks`, served on MCP mount `playtables.journeys`. - name: workflow_versions description: >- Registry package `mcp.playtables/workflow_versions`, served on MCP mount `playtables.workflows`. - name: workflows description: >- Registry package `mcp.playtables/workflows`, served on MCP mount `playtables.workflows`. paths: /api/workflows/{sid}: patch: tags: - workflows summary: Update workflow description: >- Draft-editing verb (partial update). draft_steps is FULL-REPLACE: send the whole array, CARRY the id of every kept step verbatim, OMIT ids on new steps - the response echoes all ids filled. Config edits (sender pool, schedule, on_reply, rotation_strategy, priority) affect FUTURE decisions only; pinned records keep their sender. status = archive family ONLY (archived / paused / draft); anything involving active → 422 - use pause/resume. Archived rows reject other edits. Contract: - MCP tool `update_workflow`, registry package `mcp.playtables/workflows`, mount `playtables.workflows`. - Operation `update`, response envelope `update`. - Flags: none. operationId: update_workflow parameters: - name: sid in: path required: true description: Workflow sid (wf_wf_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^wf_wf_ description: Workflow sid (wf_wf_…). requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/UpdateWorkflowRequest' responses: '200': description: '`update` success envelope.' content: application/json: schema: $ref: '#/components/schemas/UpdateWorkflowResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: UpdateWorkflowRequest: type: object description: Request body of `update_workflow`. properties: playtable_sid: type: string minLength: 18 maxLength: 18 pattern: ^pt_tb_ description: >- Move the workflow to another home playtable (draft only; the sources and step references must still resolve at publish). name: type: string minLength: 1 maxLength: 255 description: New campaign name (1..255), unique per team. description: type: string nullable: true maxLength: 2000 description: null resets the description. draft_steps: type: array items: oneOf: - type: object properties: type: type: string enum: - linkedin_send_connection_request id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. message: type: string nullable: true description: >- Invite note - max 300 RENDERED chars (server-checked); null/omitted = blank invite. Template namespaces: {{people.*}} {{company.*}} {{record.}} {{ai.}}; per-variable fallback {{record.slug|text}}. required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_send_message id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. message: type: string minLength: 1 maxLength: 8000 description: Message template (same namespaces as all templates). required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type - message additionalProperties: false - type: object properties: type: type: string enum: - linkedin_send_inmail id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. subject: type: string nullable: true maxLength: 200 message: type: string minLength: 1 maxLength: 8000 required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type - message additionalProperties: false - type: object properties: type: type: string enum: - linkedin_visit_profile id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_endorse_skills id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. skills_count: type: integer minimum: 1 maximum: 10 description: Endorse the person's top N listed skills, 1..10. required: - type - skills_count additionalProperties: false - type: object properties: type: type: string enum: - linkedin_withdraw_connection_request id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_like_latest_post id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_comment_latest_post id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. comment: type: string minLength: 1 maxLength: 1250 description: >- Comment template on the person's latest post, 1..1250 rendered; same namespaces as message templates. required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type - comment additionalProperties: false - type: object properties: type: type: string enum: - email_send id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. subject: type: string minLength: 1 maxLength: 255 body: type: string minLength: 1 maxLength: 100000 description: HTML body template. required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false email_field: type: string nullable: true description: >- Which address the send uses: any | work_email | personal_email; omitted or any = the best one. cc: type: array nullable: true items: type: string maxLength: 320 format: email maxItems: 5 description: Up to 5 literal copy addresses. bcc: type: array nullable: true items: type: string maxLength: 320 format: email maxItems: 5 description: Up to 5 literal blind-copy addresses. attachments: type: array nullable: true items: type: object properties: sid: type: string minLength: 18 maxLength: 18 pattern: ^wf_at_ name: type: string minLength: 1 maxLength: 255 required: - sid - name additionalProperties: false maxItems: 5 description: >- Up to 5 library files ({sid: wf_at_…, name}) sent with the email. reply_in_thread: type: boolean nullable: true track_opens: type: boolean nullable: true track_clicks: type: boolean nullable: true unsubscribe_link: type: boolean nullable: true required: - type - subject - body additionalProperties: false - type: object properties: type: type: string enum: - wait id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. for: type: string pattern: ^[1-9][0-9]*[mhd]$ description: >- Duration string: ^[1-9][0-9]*(m|h|d)$ - e.g. "45m", "12h", "14d". Publish lints the range 1m..365d. required: - type - for additionalProperties: false - type: object properties: type: type: string enum: - wait_for_event id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. event: type: string enum: - linkedin_connection_request_accepted - email_opened - email_link_clicked description: Event observed via the activities ingest. timeout: type: object properties: after: type: string pattern: ^[1-9][0-9]*[mhd]$ description: >- Duration string: ^[1-9][0-9]*(m|h|d)$ - e.g. "45m", "12h", "14d". Publish lints the range 1m..365d. steps: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - after - steps additionalProperties: false description: >- Required since 2026-10-11: a wait always has a time limit. Bundled: a timeout path cannot exist without a duration. required: - type - event - timeout additionalProperties: false - type: object properties: type: type: string enum: - condition id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. branches: type: array items: type: object properties: id: type: integer minimum: 1 description: >- Server-assigned - SAME id-space as step ids; omit on new branches, carry on kept ones. The fired branch id lands on the condition task result. label: type: string nullable: true maxLength: 255 description: Editor caption. when: type: object additionalProperties: {} description: >- NON-nullable filter AST, LOOSE mode (predicate-only, never compiled to ES): leaf paths people.* / company.* / record. / ai. / api..; a path missing from the record's playtable makes the leaf false. steps: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - when - steps additionalProperties: false minItems: 1 maxItems: 9 description: 1..9 branches, evaluated in order, first match wins. else: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - type - branches - else additionalProperties: false - type: object properties: type: type: string enum: - ab_test id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. branches: type: array items: type: object properties: id: type: integer minimum: 1 description: >- Server-assigned - SAME id-space as step ids; omit on new arms, carry on kept ones. The assigned arm id lands on the ab_test task result. label: type: string nullable: true maxLength: 255 description: Editor caption ("Variant A"). weight: type: integer minimum: 1 description: >- Relative weight (int >= 1; need not sum to 100). Record assigned by crc32(record.sid) mod sum(weights) - see workflow_versions.md ab_test algorithm. steps: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - weight - steps additionalProperties: false minItems: 2 maxItems: 9 description: >- 2..9 weighted arms; the record is assigned deterministically by hashing its sid into the weight distribution. No `else`. required: - type - branches additionalProperties: false - type: object properties: type: type: string enum: - end id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - api_call id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. method: type: string enum: - GET - POST - PUT - PATCH - DELETE url: type: string minLength: 1 maxLength: 2048 description: >- https-only (publish check); a template - variables may stand in the path and the query. headers: type: object nullable: true additionalProperties: type: string maxLength: 1024 query: type: object nullable: true additionalProperties: type: string maxLength: 2048 body: type: string nullable: true maxLength: 16000 description: >- JSON body template, variables inside quotes; null = the fixed payload; must be null on GET / DELETE. provider_connection_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^in_cn_ description: >- A `custom` provider connection whose auth the integration platform injects at call time; null = no auth. timeout_secs: type: integer nullable: true minimum: 1 maximum: 120 retry_on_error: type: boolean nullable: true remove_empty_values: type: boolean nullable: true output_key: type: string nullable: true pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- The answer's name for later steps (2026-10-11): a slug, unique within the version with the ask_ai keys; later steps read {{api..}} and condition leaves filter on api..; null = the answer is not kept. required: - type - method - url additionalProperties: false - type: object properties: type: type: string enum: - ask_ai id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. prompt: type: string minLength: 1 maxLength: 8000 description: Same variable namespaces as message templates. output_key: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- Slug, unique within the version (publish check) - later steps read {{ai.}} / condition leaves on ai.. preset_sid: type: string nullable: true description: gtm-api preset for the AI call; null = team default. required: - type - prompt - output_key additionalProperties: false - type: object properties: type: type: string enum: - manual_task id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. title: type: string minLength: 1 maxLength: 255 instructions: type: string nullable: true maxLength: 4000 description: >- Rendered into the human todo; the journey waits until the task is completed. required: - type - title additionalProperties: false - type: object properties: type: type: string enum: - move_to_workflow id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. target_workflow_sid: type: string minLength: 18 maxLength: 18 pattern: ^wf_wf_ description: >- Enroll the person into this campaign (wf_wf_…); reuses the existing record per the re-entry policy. THIS record then completes - terminal-for-this-record. mode: type: string nullable: true enum: - from_start - from_current description: >- Re-entry mode when the person is ALREADY in the target (workflow_records.md, Re-entry): from_start (default; reset to the entry step) | from_current (resume the pinned step, else the entry step). A re-entry is loop-guarded at re_entered_count 10. required: - type - target_workflow_sid additionalProperties: false - type: object properties: type: type: string enum: - add_tag id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. tag_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^cr_tg_ minItems: 1 maxItems: 20 description: >- 1..20 CRM tags (cr_tg_…) attached to the person mid-flow, then falls through. required: - type - tag_sids additionalProperties: false - type: object properties: type: type: string enum: - remove_tag id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. tag_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^cr_tg_ minItems: 1 maxItems: 20 description: >- 1..20 CRM tags (cr_tg_…) detached from the person mid-flow, then falls through. required: - type - tag_sids additionalProperties: false - type: object properties: type: type: string enum: - set_field id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. field_slug: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- Playtable field slug to write (pipeline_stage is a scalar_select field). value: anyOf: - type: string - type: number - type: boolean - {} - {} description: >- Scalar cell value (one cell; no arrays/objects); null clears the field. required: - type - field_slug - value additionalProperties: false - type: object properties: type: type: string enum: - change_sender id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. sender_profile_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^ub_sp_ description: >- Explicit forward-only re-pin (ub_sp_…). Exactly one of sender_profile_sid / rotation (publish check). NOT a restart-from-top. rotation: type: string nullable: true enum: - fair - random - new_sender - prior_engagement description: >- Re-pick the sender from the workflow pool by this strategy instead of a fixed sid. Exactly one of sender_profile_sid / rotation (publish check). required: - type additionalProperties: false description: >- FULL-REPLACE of the working copy. Carry ids of kept steps verbatim; omit ids on new steps (assigned from step_id_seq). Dropping the id of an unchanged step risks a possible_lost_identity warning. schedule: type: object nullable: true properties: timeblocks: type: array items: type: object properties: dow: type: integer minimum: 0 maximum: 6 description: >- Day of week, 0=Sunday … 6=Saturday (legacy Carbon dayOfWeek convention). start_minute: type: integer minimum: 0 maximum: 1439 description: 'Minutes from local midnight (legacy key: min).' end_minute: type: integer minimum: 1 maximum: 1440 description: >- Minutes from local midnight; must be > start_minute (server-validated). Legacy key: max. required: - dow - start_minute - end_minute additionalProperties: false minItems: 1 maxItems: 7 description: >- 1..7 blocks; at most one block per day-of-week in v1 (server-validated). timezone: type: string minLength: 1 maxLength: 64 description: >- IANA tz name, e.g. "Europe/Lisbon" - base timezone for the blocks. use_people_timezone: type: boolean description: >- Default false - resolve blocks in the person's timezone when known, fall back to `timezone` (legacy use_lead_timezone). required: - timeblocks - timezone additionalProperties: false description: Full-replace; null clears the windows (any time). on_reply: type: string enum: - autopilot - copilot - stop - continue description: >- Applies to the next replies and to the threads the workflow acts on from now on; a thread already stamped keeps its automation mode until the next report. agent_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^ub_ag_ description: >- Pick the AI SDR for the threads this workflow starts (ub_ag_…); null = back to its table's pick. Reaches the open threads it started at their next turn. sender_profile_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^ub_sp_ description: >- Full-replace of the pool (existence-checked); already-pinned records keep their sender. rotation_strategy: type: string enum: - fair - random - new_sender - prior_engagement description: Applies to future enrollments only. priority: type: integer minimum: 1 maximum: 3 description: >- New share of a shared sender profile: 1..3 (low / medium / high), never a rank. status: type: string enum: - archived - paused - draft description: >- Archive family only: archived (from draft|paused); paused = unarchive (requires a published version); draft = unarchive (if never published). Transitions involving active → 422 invalid_transition (use pause/resume). UpdateWorkflowResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - update item: type: object properties: sid: type: string team_sid: type: string name: type: string description: type: string nullable: true status: type: string enum: - draft - active - paused - archived published_version_sid: type: string nullable: true description: >- wf_vr_… [ro] - written ONLY by publish; null until first publish. Old versions are never repointed back to (no rollback verb - republish the old steps instead). draft_steps: type: array items: oneOf: - type: object properties: type: type: string enum: - linkedin_send_connection_request id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. message: type: string nullable: true description: >- Invite note - max 300 RENDERED chars (server-checked); null/omitted = blank invite. Template namespaces: {{people.*}} {{company.*}} {{record.}} {{ai.}}; per-variable fallback {{record.slug|text}}. required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_send_message id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. message: type: string minLength: 1 maxLength: 8000 description: Message template (same namespaces as all templates). required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type - message additionalProperties: false - type: object properties: type: type: string enum: - linkedin_send_inmail id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. subject: type: string nullable: true maxLength: 200 message: type: string minLength: 1 maxLength: 8000 required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type - message additionalProperties: false - type: object properties: type: type: string enum: - linkedin_visit_profile id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_endorse_skills id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. skills_count: type: integer minimum: 1 maximum: 10 description: Endorse the person's top N listed skills, 1..10. required: - type - skills_count additionalProperties: false - type: object properties: type: type: string enum: - linkedin_withdraw_connection_request id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_like_latest_post id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - linkedin_comment_latest_post id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. comment: type: string minLength: 1 maxLength: 1250 description: >- Comment template on the person's latest post, 1..1250 rendered; same namespaces as message templates. required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false required: - type - comment additionalProperties: false - type: object properties: type: type: string enum: - email_send id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. subject: type: string minLength: 1 maxLength: 255 body: type: string minLength: 1 maxLength: 100000 description: HTML body template. required_fields: type: object nullable: true properties: refs: type: array items: type: string maxLength: 160 pattern: >- ^(people|company|record|ai|api)\.[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$ maxItems: 20 description: >- 0..20 bare template refs required on top of the text's own variables (people.first_name, company.name, record., company.record., ai.). on_missing: type: string enum: - fail - skip description: >- fail | skip - what to do when a value the text needs is empty at task time; no policy (null) sends the text as it renders. required: - refs - on_missing additionalProperties: false email_field: type: string nullable: true description: >- Which address the send uses: any | work_email | personal_email; omitted or any = the best one. cc: type: array nullable: true items: type: string maxLength: 320 format: email maxItems: 5 description: Up to 5 literal copy addresses. bcc: type: array nullable: true items: type: string maxLength: 320 format: email maxItems: 5 description: Up to 5 literal blind-copy addresses. attachments: type: array nullable: true items: type: object properties: sid: type: string minLength: 18 maxLength: 18 pattern: ^wf_at_ name: type: string minLength: 1 maxLength: 255 required: - sid - name additionalProperties: false maxItems: 5 description: >- Up to 5 library files ({sid: wf_at_…, name}) sent with the email. reply_in_thread: type: boolean nullable: true track_opens: type: boolean nullable: true track_clicks: type: boolean nullable: true unsubscribe_link: type: boolean nullable: true required: - type - subject - body additionalProperties: false - type: object properties: type: type: string enum: - wait id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. for: type: string pattern: ^[1-9][0-9]*[mhd]$ description: >- Duration string: ^[1-9][0-9]*(m|h|d)$ - e.g. "45m", "12h", "14d". Publish lints the range 1m..365d. required: - type - for additionalProperties: false - type: object properties: type: type: string enum: - wait_for_event id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. event: type: string enum: - linkedin_connection_request_accepted - email_opened - email_link_clicked description: Event observed via the activities ingest. timeout: type: object properties: after: type: string pattern: ^[1-9][0-9]*[mhd]$ description: >- Duration string: ^[1-9][0-9]*(m|h|d)$ - e.g. "45m", "12h", "14d". Publish lints the range 1m..365d. steps: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - after - steps additionalProperties: false description: >- Required since 2026-10-11: a wait always has a time limit. Bundled: a timeout path cannot exist without a duration. required: - type - event - timeout additionalProperties: false - type: object properties: type: type: string enum: - condition id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. branches: type: array items: type: object properties: id: type: integer minimum: 1 description: >- Server-assigned - SAME id-space as step ids; omit on new branches, carry on kept ones. The fired branch id lands on the condition task result. label: type: string nullable: true maxLength: 255 description: Editor caption. when: type: object additionalProperties: {} description: >- NON-nullable filter AST, LOOSE mode (predicate-only, never compiled to ES): leaf paths people.* / company.* / record. / ai. / api..; a path missing from the record's playtable makes the leaf false. steps: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - when - steps additionalProperties: false minItems: 1 maxItems: 9 description: 1..9 branches, evaluated in order, first match wins. else: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - type - branches - else additionalProperties: false - type: object properties: type: type: string enum: - ab_test id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. branches: type: array items: type: object properties: id: type: integer minimum: 1 description: >- Server-assigned - SAME id-space as step ids; omit on new arms, carry on kept ones. The assigned arm id lands on the ab_test task result. label: type: string nullable: true maxLength: 255 description: Editor caption ("Variant A"). weight: type: integer minimum: 1 description: >- Relative weight (int >= 1; need not sum to 100). Record assigned by crc32(record.sid) mod sum(weights) - see workflow_versions.md ab_test algorithm. steps: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - weight - steps additionalProperties: false minItems: 2 maxItems: 9 description: >- 2..9 weighted arms; the record is assigned deterministically by hashing its sid into the weight distribution. No `else`. required: - type - branches additionalProperties: false - type: object properties: type: type: string enum: - end id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. required: - type additionalProperties: false - type: object properties: type: type: string enum: - api_call id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. method: type: string enum: - GET - POST - PUT - PATCH - DELETE url: type: string minLength: 1 maxLength: 2048 description: >- https-only (publish check); a template - variables may stand in the path and the query. headers: type: object nullable: true additionalProperties: type: string maxLength: 1024 query: type: object nullable: true additionalProperties: type: string maxLength: 2048 body: type: string nullable: true maxLength: 16000 description: >- JSON body template, variables inside quotes; null = the fixed payload; must be null on GET / DELETE. provider_connection_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^in_cn_ description: >- A `custom` provider connection whose auth the integration platform injects at call time; null = no auth. timeout_secs: type: integer nullable: true minimum: 1 maximum: 120 retry_on_error: type: boolean nullable: true remove_empty_values: type: boolean nullable: true output_key: type: string nullable: true pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- The answer's name for later steps (2026-10-11): a slug, unique within the version with the ask_ai keys; later steps read {{api..}} and condition leaves filter on api..; null = the answer is not kept. required: - type - method - url additionalProperties: false - type: object properties: type: type: string enum: - ask_ai id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. prompt: type: string minLength: 1 maxLength: 8000 description: Same variable namespaces as message templates. output_key: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- Slug, unique within the version (publish check) - later steps read {{ai.}} / condition leaves on ai.. preset_sid: type: string nullable: true description: gtm-api preset for the AI call; null = team default. required: - type - prompt - output_key additionalProperties: false - type: object properties: type: type: string enum: - manual_task id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. title: type: string minLength: 1 maxLength: 255 instructions: type: string nullable: true maxLength: 4000 description: >- Rendered into the human todo; the journey waits until the task is completed. required: - type - title additionalProperties: false - type: object properties: type: type: string enum: - move_to_workflow id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. target_workflow_sid: type: string minLength: 18 maxLength: 18 pattern: ^wf_wf_ description: >- Enroll the person into this campaign (wf_wf_…); reuses the existing record per the re-entry policy. THIS record then completes - terminal-for-this-record. mode: type: string nullable: true enum: - from_start - from_current description: >- Re-entry mode when the person is ALREADY in the target (workflow_records.md, Re-entry): from_start (default; reset to the entry step) | from_current (resume the pinned step, else the entry step). A re-entry is loop-guarded at re_entered_count 10. required: - type - target_workflow_sid additionalProperties: false - type: object properties: type: type: string enum: - add_tag id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. tag_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^cr_tg_ minItems: 1 maxItems: 20 description: >- 1..20 CRM tags (cr_tg_…) attached to the person mid-flow, then falls through. required: - type - tag_sids additionalProperties: false - type: object properties: type: type: string enum: - remove_tag id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. tag_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^cr_tg_ minItems: 1 maxItems: 20 description: >- 1..20 CRM tags (cr_tg_…) detached from the person mid-flow, then falls through. required: - type - tag_sids additionalProperties: false - type: object properties: type: type: string enum: - set_field id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. field_slug: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- Playtable field slug to write (pipeline_stage is a scalar_select field). value: anyOf: - type: string - type: number - type: boolean - {} - {} description: >- Scalar cell value (one cell; no arrays/objects); null clears the field. required: - type - field_slug - value additionalProperties: false - type: object properties: type: type: string enum: - change_sender id: type: integer minimum: 1 description: >- Server-assigned (workflows.step_id_seq). OMIT on new steps, CARRY verbatim on kept steps; always present on read. name: type: string nullable: true maxLength: 255 description: Editor label. sender_profile_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^ub_sp_ description: >- Explicit forward-only re-pin (ub_sp_…). Exactly one of sender_profile_sid / rotation (publish check). NOT a restart-from-top. rotation: type: string nullable: true enum: - fair - random - new_sender - prior_engagement description: >- Re-pick the sender from the workflow pool by this strategy instead of a fixed sid. Exactly one of sender_profile_sid / rotation (publish check). required: - type additionalProperties: false description: >- Working copy of the step document (chain-and-blocks v2); step ids always present on read (server-assigned). Not executable until published. Max 100 steps incl. nested / 512 KB. schedule: type: object nullable: true properties: timeblocks: type: array items: type: object properties: dow: type: integer minimum: 0 maximum: 6 description: >- Day of week, 0=Sunday … 6=Saturday (legacy Carbon dayOfWeek convention). start_minute: type: integer minimum: 0 maximum: 1439 description: 'Minutes from local midnight (legacy key: min).' end_minute: type: integer minimum: 1 maximum: 1440 description: >- Minutes from local midnight; must be > start_minute (server-validated). Legacy key: max. required: - dow - start_minute - end_minute additionalProperties: false timezone: type: string description: IANA tz name - base timezone for the blocks. use_people_timezone: type: boolean description: >- Resolve blocks in the person's timezone when known, falling back to `timezone`. required: - timeblocks - timezone - use_people_timezone description: >- The campaign's sending windows, the one send-window gate: null = any time (gtm-api's per-account limits still pace the sends). A sender profile carries no window of its own (founder 2026-09-22). on_reply: type: string enum: - autopilot - copilot - stop - continue description: >- What a reply does (default copilot): autopilot = the records pause and the AI SDR answers within its caps; copilot = the records pause and the AI SDR drafts for approval; stop = the records pause and the thread is the human's; continue = the records keep sending (nurture), the agent stays out. Reply scope = all the person's live records. Frozen onto each thread the workflow acts on as its automation_ref mode (autopilot | copilot | off). agent_sid: type: string nullable: true description: >- The AI SDR picked for this workflow (ub_ag_…, block 10 step 10.2): the agent that works the threads it starts, every setting on the agent itself (update_agent). Null = its home table's pick, else the team's default. The campaign's own setup of before (ai_sdr_setup, 2026-10-12 to 2026-10-30) became an agent of its own in step 10.3. sender_profile_sids: type: array items: type: string description: >- ub_sp_… each - the sender pool; a record is pinned to ONE sender at enrollment by rotation_strategy. rotation_strategy: type: string enum: - fair - random - new_sender - prior_engagement priority: type: integer description: >- 1..3 (low / medium / high) - the workflow's SHARE of a sender profile it shares with other workflows (three actions of high for one of low), never a rank (see ./workflow_tasks.md). created_by: type: object properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string nullable: true team_sid: type: string actor_name: type: string nullable: true description: >- The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. oauth_client_sid: type: string nullable: true description: The acting OAuth client (id_oc_*); null off the OAuth path. reason: type: string nullable: true description: >- Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. permissions: type: object additionalProperties: {} description: >- Internal audit context: the grant set the actor held at write time. Not a contract. cluster_id: type: integer nullable: true description: 'Internal audit context: the cluster that served the write.' trace_id: type: string nullable: true description: >- Internal audit context: the trace id of the request that wrote the row. required: - actor_type - actor_sid - team_sid - permissions deleted_by: type: object nullable: true properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string nullable: true team_sid: type: string actor_name: type: string nullable: true description: >- The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. oauth_client_sid: type: string nullable: true description: The acting OAuth client (id_oc_*); null off the OAuth path. reason: type: string nullable: true description: >- Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. permissions: type: object additionalProperties: {} description: >- Internal audit context: the grant set the actor held at write time. Not a contract. cluster_id: type: integer nullable: true description: 'Internal audit context: the cluster that served the write.' trace_id: type: string nullable: true description: >- Internal audit context: the trace id of the request that wrote the row. required: - actor_type - actor_sid - team_sid - permissions created_at: type: string updated_at: type: string deleted_at: type: string nullable: true required: - sid - team_sid - name - description - status - published_version_sid - draft_steps - schedule - on_reply - agent_sid - sender_profile_sids - rotation_strategy - priority - created_by - deleted_by - created_at - updated_at - deleted_at updated_fields: type: array items: type: string previous_values: type: object additionalProperties: {} kept_fields: type: array items: type: string description: >- The fields this write did not change because the person's own value stands on them (stamped person); read the item for what landed. meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - item - updated_fields - previous_values - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gs.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.