VocalDocscontracts 1.65.0

Create a Workflow draft

POST /v1/workflows

PropertyValue
Operationcreate_workflow
GroupWorkflows
Scopeworkflows:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited workflow.create (mutation)
Released in1.59.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Creates a Workflow draft at revision 1 (1.59.0). The definition is checked as a publish checks it: a process-scope Workflow, a node type or field the release does not build and a decision that names a Ruleset are refused with capability_not_available (WorkflowCapabilityCode); every issue of workflows-and-processes.md section 5.3 and of conversation scope with validation_failed (WorkflowIssueCode), each naming the node; an agent_id that names no Agent of the Organization is workflow_agent_unknown.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the workflows:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/workflows" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name>",
    "scope": "conversation",
    "entry": "<entry>",
    "limits": {
      "max_steps": 1
    },
    "nodes": [
      {
        "id": "<id>",
        "type": "say"
      }
    ]
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: WorkflowCreateRequest.

FieldTypeRequiredDescription
agent_idAgentIdnoConversation scope only, and required there: the default Agent, which supplies voice, transcriber, model, Policies, Tools and destinations.
correlationWorkflowCorrelationInputno
descriptionstringnoFor reviewers; never spoken or sent to a model.
entryWorkflowNodeIdyes
inputsmap of WorkflowFieldInputnoCall variables (conversation) or start inputs (process).
limitsWorkflowLimitsInputyes
namestringyesKebab-case, unique per Organization.
nodesarray of WorkflowNodeInputyesExactly one entry node; at most 200 nodes, loop bodies included (target).
outputsmap of WorkflowFieldInputnoThe typed result returned to a parent or a starting Process.
scopeWorkflowScopeyes
settingsmap of WorkflowSettingnoProcess scope: named thresholds and constants that evaluate nodes read.
slotsmap of WorkflowFieldInputnoConversation scope: the Session's typed slots.
varsmap of WorkflowFieldInputnoProcess scope: the instance's working data.

Responses

StatusContent typeShapeError codes
201application/jsonWorkflow
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed, capability_not_available
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is Workflow.

FieldTypeRequiredDescription
active_versioninteger or nullyesThe version the next Agent version publish pins, or null when none is active.
agent_idAgentIdnoConversation scope only, and required there: the default Agent, which supplies voice, transcriber, model, Policies, Tools and destinations.
archived_atTimestamp or nullyesWhen DELETE archived the Workflow, or null. An archived Workflow takes no write, publish or activation (409 workflow_archived); its pinned versions keep running.
correlationWorkflowCorrelationno
created_atTimestampyes
descriptionstring or nullyesFor reviewers; never spoken or sent to a model.
entryWorkflowNodeIdyes
idWorkflowIdyes
inputsmap of WorkflowFieldnoCall variables (conversation) or start inputs (process).
latest_versioninteger or nullyesThe highest published version, or null before the first publish.
limitsWorkflowLimitsyes
namestringyesKebab-case, unique per Organization.
nodesarray of WorkflowNodeyesExactly one entry node; at most 200 nodes, loop bodies included (target).
object"workflow"yes
organization_idOrganizationIdyes
outputsmap of WorkflowFieldnoThe typed result returned to a parent or a starting Process.
revisionintegeryesCounts writes to the draft; returned as the ETag and required in If-Match.
scopeWorkflowScopeyes
settingsmap of WorkflowSettingnoProcess scope: named thresholds and constants that evaluate nodes read.
slotsmap of WorkflowFieldnoConversation scope: the Session's typed slots.
updated_atTimestampyes
varsmap of WorkflowFieldnoProcess scope: the instance's working data.