Processes

GET /api/orgs/{org_id}/processes

List Processes

List processes for the organization.

Omit limit to get every process; total is the full count either way.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes
project_id	query	string	no	Filter by project id, or ‘none’ for uncategorized processes.

Responses

Status	Description	Body
200	Successful Response	Page_ProcessResponse_
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/processes

Create Process

Create a process (no revision yet). Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
description	string	no
name	string	yes
title	string	yes

Responses

Status	Description	Body
201	Successful Response	ProcessResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}

Get Process

Get a process, including its current deployed revision (if any).

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes

Responses

Status	Description	Body
200	Successful Response	ProcessResponse
422	Validation Error	HTTPValidationError

PATCH /api/orgs/{org_id}/processes/{process_id}

Update Process

Update a process’s title/description. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes

Request body (required)

Field	Type	Required	Description
description	string	yes
title	string	no

Responses

Status	Description	Body
200	Successful Response	ProcessResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/processes/{process_id}

Delete Process

Soft-delete a process. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/revisions

List Revisions

List a process’s revisions, newest version first.

Not itself in the Phase-1 milestone’s endpoint list, but the CLI’s deploy --revision N (and “deploy latest”) need a way to resolve a version to a revision id, so it’s added here as the minimal completion.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes

Responses

Status	Description	Body
200	Successful Response	ProcessRevisionResponse[]
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/processes/{process_id}/revisions

Push Revision

Push a draft revision from a definition. Requires admin/owner role.

Parse errors return 422 carrying the validator’s plain wording (step id, field, what is wrong, what is valid) rather than the raw pydantic dump. Pushing a definition whose hash matches the latest revision is a no-op — the existing revision is returned (200) instead of creating a duplicate.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes

Request body (required)

Field	Type	Required	Description
definition	object	yes
sop_text	string	no

Responses

Status	Description	Body
201	Successful Response	ProcessRevisionResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/processes/{process_id}/revisions/{revision_id}/deploy

Deploy Revision

Validate + deploy a draft revision. Requires admin/owner role.

Validation errors return 422 with {errors, warnings} in the validator’s plain-language wording, verbatim. On success the revision’s tool snapshot is pinned, the previously-deployed revision is archived, and the process’s stale_reason is cleared (a re-deploy is the re-evaluation).

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes
revision_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	DeployResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs

List Runs

List runs for a process, newest first. Optional status filter.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes
process_id	path	string	yes
status	query	string	no

Responses

Status	Description	Body
200	Successful Response	ProcessRunListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}

Get Run

Get a run’s detail, including its steps ordered by creation time.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessRunDetailResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/agent-calls

List Run Agent Calls

Scalar-only index of a run’s agent block step turns/distill calls.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessAgentCallListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/agent-calls/{call_id}

Get Run Agent Call

Full detail (incl. request/response messages) for one agent-step call.

Parameters

Name	In	Type	Required	Description
call_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessAgentCallDetailResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/cancel

Cancel Run

Cancel a running / human-waiting run.

Tombstones the run row (step children check it at every step boundary) and cancels the durable Hatchet parent plus any in-flight step children. A run already in a terminal state is a no-op (cancelled: false).

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	CancelRunResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/events

List Run Events

A run’s timeline, ordered oldest first.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessRunEventListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/llm-calls

List Run Llm Calls

Scalar-only index of a run’s llm/prompt block exchanges.

The heavy request_messages/response_message JSONB is never loaded — use GET .../llm-calls/{call_id} for the full exchange.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessLlmCallListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/llm-calls/{call_id}

Get Run Llm Call

Full detail (incl. request/response messages) for one LLM call.

Parameters

Name	In	Type	Required	Description
call_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessLlmCallDetailResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/repairs

List Run Repairs

Index of a run’s tool-payload repair verdicts.

The scalar/text fields (tool_slug/error/fixable/reason/ payload_diff) ARE the payload here; the heavy raw exchange is still excluded — use GET .../repairs/{call_id} for that.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessRepairCallListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/repairs/{call_id}

Get Run Repair

Full detail (incl. request/response messages) for one repair call.

Parameters

Name	In	Type	Required	Description
call_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ProcessRepairCallDetailResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/processes/{process_id}/runs/{run_id}/restart

Restart Run

Restart a terminal run as a brand-new run on the process’s current deployed revision.

Only terminal runs (completed / flagged / failed / cancelled) can be restarted — an active run (running / waiting_human) must be cancelled first. The new run replays the old run’s envelope against whatever revision is currently deployed (by design — restart always runs the current revision, not a pinned replay) and does not touch the original run.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
process_id	path	string	yes
run_id	path	string (uuid)	yes

Responses

Status	Description	Body
201	Successful Response	ProcessRunResponse
422	Validation Error	HTTPValidationError