POST /api/v1/processes

Create Process

Create a new tracked process with defined steps.

Request

curl -X POST https://your-instance/api/v1/processes \
  -H "Authorization: Bearer htk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "deployments",
    "name": "Deploy v2.1.0 to production",
    "steps": [
      { "key": "build", "label": "Build artifacts" },
      { "key": "test", "label": "Run test suite" },
      { "key": "review", "label": "Code review", "human": true },
      { "key": "deploy", "label": "Deploy to production" },
      { "key": "verify", "label": "Verify deployment", "human": true }
    ]
  }'

Required scope: processes:write or tasks:create

Request Body

Field	Type	Required	Description
`namespace`	string	Yes	Namespace for grouping (1-100 chars, alphanumeric/dots/hyphens)
`name`	string	Yes	Process display name (1-200 chars)
`description`	string	No	Optional description
`process_id`	string	No	Custom UUID (auto-generated if omitted)
`steps`	array	Yes	Step definitions (min 1)

Step Definition

Field	Type	Required	Description
`key`	string	Yes	Unique step identifier
`label`	string	Yes	Display label
`human`	boolean	No	Whether the step requires human input

Response

{
	"process_id": "uuid",
	"namespace": "orgId.deployments",
	"name": "Deploy v2.1.0 to production",
	"started_at": "2026-02-24T12:00:00Z"
}

Note: The namespace is automatically prefixed with your organization ID.

Errors

Status	Meaning
`400`	Invalid request body
`401`	Missing or invalid token
`403`	Token lacks required scope