Runs - Allternit Docs

Implementation: DESIGN (server) · Exposure: PUBLIC PREVIEW (contract). The Agency API is not live yet. This page describes the published v0.3 contract so you can review and build against it; details may change before alpha.

A Run is one durable execution of a goal. It is persisted before the create call returns and survives process restart. The alpha opens only after a run can survive restart, resume, verify, replay and receipt-backed completion. For the concepts behind this page see The kernel.

Endpoints

Method	Path	Description
`POST`	`/v1/agency`	Create a run
`GET`	`/v1/runs`	List runs
`GET`	`/v1/runs/{run_id}`	Get a run
`POST`	`/v1/runs/{run_id}/input`	Submit input
`POST`	`/v1/runs/{run_id}/pause`	Pause a run
`POST`	`/v1/runs/{run_id}/resume`	Resume a run
`POST`	`/v1/runs/{run_id}/cancel`	Cancel a run
`GET`	`/v1/runs/{run_id}/graph`	Get the compiled graph

Related: events, attention, artifacts and receipts of a run.

The Run object

Run IDs match ^run_[A-Za-z0-9]+$.

Status

Status	Terminal	Meaning
`accepted`	no	Persisted. Stays here until `resolved` is recorded.
`running`	no	At least one node is executing or verifying.
`waiting`	no	Nodes are on a wait gate or a lease reclaim is pending; none is running.
`needs_attention`	no	An attention request is open. Includes `budget_exhausted` after spend is halted.
`paused`	no	Paused by an operator; leases released at a safe boundary.
`cancelling`	no	Cancel receipted; in-flight effects are settling.
`completed`	yes	The completion predicate is true.
`partial`	yes	Closed with unmet criteria, only when `allow_partial` is `true`.
`failed`	yes	Closed after an unrecoverable failure or a budget stop.
`cancelled`	yes	Closed after a cancel.

Precedence when nodes differ: cancelling > paused > needs_attention > running > waiting > accepted.

Resolved defaults

resolved is always present. It holds everything the server resolved before execution. resolved.authority is a ResolvedAuthority: resolved.completion is a ResolvedCompletion:

Nested objects

budget_usage (BudgetUsage): completion (CompletionState). Each result is one of pending, pass, fail, inconclusive, error (VerificationResult). inconclusive is never a pass. output (RunOutput): cancellation (CancellationState): links (RunLinks): debug (RunDebugView), only with view=debug and scope debug:read. Its fields may change without a major version.

Create a run

POST /v1/agency

Compiles the request into explicit internal contracts and returns the Run immediately. It never executes an implicit free-form loop. The run is persisted before 202 is returned. Only goal is required. The server resolves workspace, authority, budget and completion from the agent’s and profile’s versioned defaults and records them on Run.resolved before any execution. There are no hidden permissive defaults: if a default cannot be safely resolved the call fails with 422 ERR_DEFAULTS_UNRESOLVABLE and no run executes. Runs created here always have judge fail-closed and verifier-owned completion enabled; clients cannot disable either.

Parameters

Request body

AgencyRequest Unknown fields are rejected with ERR_INPUT_UNSUPPORTED, including any attempt to disable judge fail-closed or verifier-owned completion. Extension properties named x-<name> are accepted.

workspace

Workspace. resources items are ResourceRef.

context

Array of ContextItem. Supplied context enters as UNTRUSTED unless policy grants a trust class.

authority

Authority. profile is read-only, code-safe or code-write, optionally pinned as name@version. Bypass-style names are rejected with ERR_AUTHORITY_PROFILE_FORBIDDEN. grants items (Grant): network (NetworkPolicy). Private-address, redirect-hop and DNS-rebind defenses are always on. environment (ExecutionEnvironment). Raw environment inheritance is never allowed.

budget

Budget. At least one of max_seconds or max_cost_usd is required when you supply a budget. On exhaustion the platform first hard-stops all billable and effectful execution, then asks or stops.

completion

CompletionCriteria. Items in require are registry IDs (a string, latest version) or pinned {id, version} objects (CriterionRef). Custom criteria items (Criterion):

capabilities (tier B)

CapabilityLimits

models (tier B)

ModelConstraints. Constrain by logical class, locality and trust. Model or vendor names are rejected.

graph (tier C)

GraphSpec. Treated as opaque until the public Graph contract is frozen.

runtime (tier D)

RuntimeHints. Hints never change semantics, eligibility, policy or evidence.

Responses

Example

curl -X POST https://api.allternit.com/v1/agency \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: 3f1c2a9e-7b1d-4c55-9a0e-1d2b3c4d5e6f" \
  -H "Allternit-Version: 2026-09-29" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "allternit-code",
    "goal": "Fix the failing checkout tests and verify the repair",
    "workspace": {"repo": "repo://acme/store"},
    "authority": {"profile": "code-safe"},
    "budget": {"max_seconds": 900, "max_cost_usd": 2.0},
    "completion": {"require": ["tests_pass", "no_new_regressions"]},
    "stream": true
  }'

The 202 response body is a Run with status: "accepted". A full response, including resolved, is shown in the overview. Error example, when defaults cannot be resolved:

{
  "error": {
    "family": "INPUT",
    "code": "ERR_DEFAULTS_UNRESOLVABLE",
    "message": "No default workspace can be resolved for agent allternit-code. Supply workspace.",
    "retryable": false,
    "request_id": "req_8f2c1d",
    "param": "workspace"
  }
}

List runs

GET /v1/runs

Returns a page of runs, newest first.

Parameters

status takes a comma-separated list, for example ?status=running,needs_attention.

Responses

RunPage:

Example

curl "https://api.allternit.com/v1/runs?status=running,needs_attention&limit=20" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "run_01JB2K4Y7MQ8",
      "object": "run",
      "status": "needs_attention",
      "agent": "allternit-code@v1",
      "thread_id": "thr_01JB2K4Y7N",
      "created_at": "2026-09-29T17:00:00Z",
      "updated_at": "2026-09-29T17:02:10Z",
      "version": 9,
      "open_attention_count": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The example item is shortened. Each item is a full Run.

Get a run

GET /v1/runs/{run_id}

Returns the current run state. The default view hides kernel internals.

Parameters

Responses

Example

curl https://api.allternit.com/v1/runs/run_01JB2K4Y7MQ8 \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

A completed run (shortened; resolved and links omitted):

{
  "id": "run_01JB2K4Y7MQ8",
  "object": "run",
  "status": "completed",
  "terminal": true,
  "agent": "allternit-code@v1",
  "thread_id": "thr_01JB2K4Y7N",
  "created_at": "2026-09-29T17:00:00Z",
  "updated_at": "2026-09-29T17:09:42Z",
  "finished_at": "2026-09-29T17:09:42Z",
  "version": 31,
  "budget": { "max_seconds": 900, "max_cost_usd": 2.0, "on_exhaustion": "request_attention" },
  "budget_usage": { "seconds": 581.4, "cost_usd": 0.62, "steps": 14, "spend_halted": false },
  "attention": null,
  "open_attention_count": 0,
  "completion": {
    "status": "satisfied",
    "criteria": [
      { "criterion": "tests_pass", "result": "pass", "receipt_ids": ["rcpt_01JB2K9A01"] },
      { "criterion": "no_new_regressions", "result": "pass", "receipt_ids": ["rcpt_01JB2K9A02"] }
    ]
  },
  "output": {
    "summary": "Fixed a rounding error in cart totals; 3 failing tests now pass.",
    "artifact_ids": ["art_01JB2K8Z11"],
    "run_receipt_id": "rcpt_01JB2K9A03"
  },
  "effect_receipt_ids": ["rcpt_01JB2K7Q05"]
}

Submit input

POST /v1/runs/{run_id}/input

Answer an attention request, steer the run, or add data. approval and rejection must carry attention_id. An approval only resolves a policy ask; it can never override a hard policy deny (403 ERR_POLICY_DENIED). Input is recorded as a receipt before it takes effect.

Parameters

Request body

RunInput

`type`	Use
`message`	Send a message to the run.
`approval`	Approve an attention request. Requires `attention_id`.
`rejection`	Reject an attention request. Requires `attention_id`.
`steer`	Redirect the run with free text.
`data`	Supply a typed payload in `value`.

Responses

InputAccepted:

Example

curl -X POST https://api.allternit.com/v1/runs/run_01JB2K4Y7MQ8/input \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: 7a0e2b51-52c1-4a41-8d0b-2d3f7c1b9e10" \
  -H "Content-Type: application/json" \
  -d '{"type": "approval", "attention_id": "att_01JB2K61QF", "comment": "Approved."}'

{
  "run_id": "run_01JB2K4Y7MQ8",
  "receipt_id": "rcpt_01JB2K7Q04",
  "attention_id": "att_01JB2K61QF",
  "status": "running"
}

Pause a run

POST /v1/runs/{run_id}/pause

Asynchronous and idempotent. Nodes stop at the next safe boundary; in-flight effects finish and are receipted; leases are released. Status goes to paused. Pausing a paused run is a no-op (202, same Run).

Parameters

Request body

Optional. ControlRequest

Responses

Example

curl -X POST https://api.allternit.com/v1/runs/run_01JB2K4Y7MQ8/pause \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: 0c6d2f7e-3b1a-4f0e-9a55-7e1d2c3b4a59" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Holding until the release branch is cut"}'

The response is the Run. Its status becomes paused once nodes reach a safe boundary.

Resume a run

POST /v1/runs/{run_id}/resume

Asynchronous and idempotent. Resumes from durable state and receipts, never from a transcript. A node interrupted in the middle of an effect is not blindly re-run: it resumes only if its effect is idempotency-keyed and receipted. Otherwise the run raises an attention request (reason unsafe_resume).

Parameters

Request body

Optional. ControlRequest (reason).

Responses

Example

curl -X POST https://api.allternit.com/v1/runs/run_01JB2K4Y7MQ8/resume \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: 5b9f1c22-0d4e-4c7a-b1f3-8a6e9d0c2b17"

Cancel a run

POST /v1/runs/{run_id}/cancel

Asynchronous and idempotent. Status goes cancelling, then cancelled.

No new node is admitted or leased after the request is receipted.
Effects already dispatched are not silently abandoned. Each one completes, times out, or is rolled back where the node declares a rollback, and its outcome is receipted. Run.cancellation.effects_in_flight lists them until settled.
Open attention requests are withdrawn.
Repeating cancel on a cancelling or cancelled run returns 202 with the current Run.
Cancelling a run already completed, partial or failed returns 409 ERR_RUN_TERMINAL.

Parameters

Request body

Optional. CancelRequest

Responses

Example

curl -X POST https://api.allternit.com/v1/runs/run_01JB2K4Y7MQ8/cancel \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: 9d3e7a10-6f2b-4b8c-a4d1-1c5e0f7b3a66" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Superseded by a newer request", "rollback_reversible_effects": true}'

{
  "id": "run_01JB2K4Y7MQ8",
  "object": "run",
  "status": "cancelling",
  "terminal": false,
  "cancellation": {
    "requested_at": "2026-09-29T17:05:00Z",
    "reason": "Superseded by a newer request",
    "receipt_id": "rcpt_01JB2K7Q09",
    "effects_in_flight": [
      {
        "description": "Patch applied to checkout/cart.ts",
        "effect_class": "reversible",
        "state": "settling",
        "receipt_id": null
      }
    ]
  }
}

The example is shortened to the fields that change.

Get the compiled graph

GET /v1/runs/{run_id}/graph

Disclosure tier C. Requires scope graph:read. This is not part of the Goal API. It shows the graph the request compiled into, and each node’s lifecycle position.

Parameters

Responses

GraphView:

Example

curl https://api.allternit.com/v1/runs/run_01JB2K4Y7MQ8/graph \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

{
  "graph_id": "graph_01JB2K4Y80",
  "version": 1,
  "template_id": null,
  "nodes": [
    { "node_id": "n1", "primitive_id": "obs.read_file", "lifecycle": "CLOSE", "wait_gate": null, "output_ids": ["art_01JB2K5A01"] },
    { "node_id": "n2", "primitive_id": "ver.run_tests", "lifecycle": "RUN", "wait_gate": null, "output_ids": [] }
  ],
  "edges": [
    { "from": "n1", "to": "n2", "when": null }
  ]
}

​Endpoints

​The Run object

​Status

​Resolved defaults

​Nested objects

​Create a run

​Parameters

​Request body

​workspace

​context

​authority

​budget

​completion

​capabilities (tier B)

​models (tier B)

​graph (tier C)

​runtime (tier D)

​Responses

​Example

​List runs

​Parameters

​Responses

​Example

​Get a run

​Parameters

​Responses

​Example

​Submit input

​Parameters

​Request body

​Responses

​Example

​Pause a run

​Parameters

​Request body

​Responses

​Example

​Resume a run

​Parameters

​Request body

​Responses

​Example

​Cancel a run

​Parameters

​Request body

​Responses

​Example

​Get the compiled graph

​Parameters

​Responses

​Example

Endpoints

The Run object

Status

Resolved defaults

Nested objects

Create a run

Parameters

Request body

workspace

context

authority

budget

completion

capabilities (tier B)

models (tier B)

graph (tier C)

runtime (tier D)

Responses

Example

List runs

Parameters

Responses

Example

Get a run

Parameters

Responses

Example

Submit input

Parameters

Request body

Responses

Example

Pause a run

Parameters

Request body

Responses

Example

Resume a run

Parameters

Request body

Responses

Example

Cancel a run

Parameters

Request body

Responses

Example

Get the compiled graph

Parameters

Responses

Example