Start a Process instance

POST /v1/processes

Property	Value
Operation	`create_process`
Group	Processes
Scope	`processes:write`
Route class	`control`
Idempotency	`Idempotency-Key` required: a retry with the same key replays the first answer
Audit	Audited `processes.process.start` (mutation)
Released in	1.62.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Starts an instance of a published process-scope Workflow version, the active one when the body names none, and answers it running (1.62.0). The inputs are checked against the version's declared inputs and the correlation key is kept as a keyed hash (ProcessIssueCode); a conversation-scope Workflow is validation_failed (workflow_not_process_scope), an archived one workflow_archived, and one with no active version, or a retired version, workflow_version_unavailable. The Idempotency-Key makes a repeated start answer the same instance.

Request

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

curl -X POST "$VOCAL_API/v1/processes" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "workflow_id": "wfl_..." }'

const response = await fetch(`${process.env.VOCAL_API}/v1/processes`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "workflow_id": "wfl_..."
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/processes",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "workflow_id": "wfl_...",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string	yes	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: ProcessCreateRequest.

Field	Type	Required	Description
`correlation`	string	no	The correlation key Process events match on; when omitted, the version's `correlation.key` over the inputs. Content: stored only as a keyed hash.
`inputs`	map of any	no	The start inputs, checked against the version's declared `inputs`; at most 32 KiB (a target). Content.
`version`	integer	no	A published version; the Workflow's active version when omitted.
`workflow_id`	WorkflowId	yes

Responses

Status	Content type	Shape	Error codes
`201`	`application/json`	ProcessInstance
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`workflow_archived`, `workflow_version_unavailable`, `idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `201` answer

The shape is ProcessInstance.

Field	Type	Required	Description
`compliance_profile_version`	integer or null	yes	The Compliance profile version pinned at the start (section 10, rule 3).
`correlated`	boolean	yes	True when the instance has a correlation key, which Process events match on; the key is kept as a keyed hash and never answered.
`current_nodes`	array of WorkflowNodeId	yes	The nodes the instance is at; empty once it ended.
`ended_at`	Timestamp or null	yes
`environment`	Environment	yes
`error_code`	string or null	yes	Why a `failed` instance failed, such as `max_steps_reached`, `max_lifetime_reached` or the failure code of the node that ended it `failed`; null otherwise.
`id`	ProcessInstanceId	yes
`inputs`	object or null	yes	The start inputs. Content; null unless the read names `include=content`.
`interpreter_version`	string	yes	The version of Vocal's interpreter the instance pinned at its start, kept by the runner until the instance ends.
`object`	`"process"`	yes
`organization_id`	OrganizationId	yes
`outputs`	object or null	yes	The declared outputs, once the instance ended on an `end` node. Content; null unless the read names `include=content`.
`project_id`	ProjectId or null	yes	The instance's Project: the default Project until Projects ship.
`started_at`	Timestamp	yes
`started_by`	ProcessStartedBy	yes
`status`	ProcessInstanceStatus	yes
`updated_at`	Timestamp	yes
`vars`	object or null	yes	The working data. Content; null unless the read names `include=content`.
`waiting_on`	ProcessWaitingOn or null	yes
`wake_at`	Timestamp or null	yes	The next timer of a waiting instance, mirrored from the runner; null when none.
`workflow_id`	WorkflowId	yes
`workflow_version`	integer	yes	The process-scope Workflow version the instance runs to its end (section 10).