Update Process

Push state changes to a process — step transitions, progress updates, and completion events.

Request

curl -X POST https://your-instance/api/v1/processes/proc-uuid/update \
  -H "Authorization: Bearer htk_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "step_started", "step": "build" }'

Required scope: processes:write or tasks:create

Update Types

step_started

Mark a step as in progress.

{
	"type": "step_started",
	"step": "build",
	"detail": "Building Docker image..."
}

step_completed

Mark a step as complete.

{
	"type": "step_completed",
	"step": "build",
	"detail": "Build successful",
	"data": { "image_tag": "v2.1.0-abc123" }
}

step_failed

Mark a step as failed.

{
	"type": "step_failed",
	"step": "test",
	"error": "3 tests failed in auth module"
}

progress

Report progress on a running step (for long-running operations).

{
	"type": "progress",
	"step": "deploy",
	"message": "Deploying to 3/10 instances...",
	"percent": 30
}

completed

Mark the entire process as complete.

{
	"type": "completed",
	"summary": "Successfully deployed v2.1.0"
}

failed

Mark the entire process as failed.

{
	"type": "failed",
	"error": "Deployment failed: timeout waiting for health check"
}

Response

{
	"process_id": "proc-uuid",
	"update_type": "step_started",
	"timestamp": "2026-02-24T12:01:00Z"
}

Errors

Typical Workflow

# Start the build step
curl -X POST .../processes/proc-uuid/update \
  -d '{"type":"step_started","step":"build"}'

# Report progress
curl -X POST .../processes/proc-uuid/update \
  -d '{"type":"progress","step":"build","message":"Compiling...","percent":50}'

# Complete the build step
curl -X POST .../processes/proc-uuid/update \
  -d '{"type":"step_completed","step":"build"}'

# Start the next step
curl -X POST .../processes/proc-uuid/update \
  -d '{"type":"step_started","step":"test"}'

# ...continue until all steps complete

# Mark process as complete
curl -X POST .../processes/proc-uuid/update \
  -d '{"type":"completed","summary":"All done!"}'