Run Governance API
Every endpoint uses the Gateway listener and Authorization: Bearer gw_.... POST requests require Content-Type: application/json, a body no larger than 16 KiB, and Idempotency-Key.
Scopes and endpoints
Section titled “Scopes and endpoints”| Scope | Methods and paths |
|---|---|
work_unit:create | POST /halro/v1/work-units, POST /halro/v1/work-units/{id}/close |
run:create | POST /halro/v1/runs, POST /halro/v1/runs/{id}/close |
run:attach | Accept X-Halro-Run-ID on model calls; also requires inference |
governance:read | GET /halro/v1/work-units/{id}, GET /halro/v1/runs/{id} |
outcome:write | POST /halro/v1/work-units/{id}/outcomes |
Every resource is scoped to the Gateway Key’s Project. Cross-Project reads and attachments do not reveal resource existence.
Create a Work Unit
Section titled “Create a Work Unit”POST /halro/v1/work-units{"outcome_definition_ids":["odef_xxx"]}outcome_definition_ids is optional, accepts at most eight IDs, and every ID must belong to the same Project and currently be enabled. Creation freezes the Definition ID and version. The first success returns 201; replaying the same Idempotency-Key and body returns 200 with the same resource.
Read and close a Work Unit
Section titled “Read and close a Work Unit”GET /halro/v1/work-units/{id}POST /halro/v1/work-units/{id}/closeGET returns work_unit, its runs, and its outcomes. The close body must be {}. No new Run can be created after closing; repeating close is an idempotent replay.
Create a Run
Section titled “Create a Run”POST /halro/v1/runs{ "work_unit_id": "wku_xxx", "budget_micros_usd": 500000, "ttl_seconds": 3600}An omitted or zero budget/TTL uses the Project default; an explicit value cannot exceed the Project ceiling. One Work Unit accepts at most 32 Runs. budget_state is available, fully_reserved, or depleted; remaining_micros_usd already subtracts committed, reserved, and in-process pending cost.
Read and close a Run
Section titled “Read and close a Run”GET /halro/v1/runs/{id}POST /halro/v1/runs/{id}/closeClose can send {"reason":"completed"}; omission defaults to completed, and the value must be 1–64 characters. Expiry is derived from the read clock. A closed or expired Run rejects new attached calls.
Report an Outcome
Section titled “Report an Outcome”POST /halro/v1/work-units/{id}/outcomes| Field | Required | Constraint |
|---|---|---|
definition_id | Yes | Must be a Definition frozen when the Work Unit was created |
value | Yes | Must be within the BOOLEAN/CATEGORICAL allowed values |
observed_at | Yes | RFC 3339 business observation time |
evidence_ref | No | Opaque reference up to 128 characters; URLs, control characters, and credential-shaped values are rejected |
evidence_sha256 | No | 64-character lowercase hexadecimal SHA-256 |
supersedes_outcome_id | For a revision | Must identify the current Outcome for this Work Unit/Definition |
The first report returns 201; an idempotent replay returns 200. A revision creates a new out_... and retains the old record. Each head accepts at most 20 revisions, and the write window remains open for 30 days after Work Unit close.
Main errors
Section titled “Main errors”| HTTP | code | Caller action |
|---|---|---|
| 400 | invalid_request / invalid_outcome | Repair fields, value domain, or Content-Type; do not retry unchanged |
| 400 | invalid_idempotency_key | Supply a legal stable Key for this logical operation |
| 403 | gateway_key_scope_denied | Use an authorized Key; do not retry blindly |
| 403 | run_budget_exceeded | Stop this Run, or change policy and create a new compliant Run |
| 404 | work_unit_not_found / run_not_found | Verify Project and resource ID |
| 409 | idempotency_conflict | Same Key was used for a different request; investigate before creating a new operation |
| 409 | run_not_active / work_unit_closed | Stop writing to or attaching requests to a terminal resource |
| 409 | outcome_revision_conflict | Read the current Outcome and resubmit using its ID |
| 409 | outcome_write_closed | Revision count or post-close write window was exceeded |
| 429 | governance_rate_limited / governance_resource_limit | Honor Retry-After or reduce resource creation rate |
| 503 | run_governance_unavailable / governance_unavailable | Authority cannot be verified; do not interpret failure as empty data or success |
See Integrate Run Governance for the complete business flow.