Agent Runtime API

Two ways in, both authenticated with an agent api key. Full request and response schemas are in the API Reference; this page is the shape of the thing.

Authenticate with the key as a bearer token (x-api-key also works):

export AGENT_KEY="plak_..."

Orchestrated: give it a goal

curl -X POST "$AUTHORIC_URL/$APP_UID/agent/invoke" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Find order 8817 and refund it if it shipped late." }'

The response is 202 with a runUid, before any work starts:

{ "runUid": "run_01J...", "status": "running", "actions": { "poll": "/{appUid}/agent/runs/run_01J..." } }

For genuinely short calls, ?wait=true holds the connection. That wait has a server-side ceiling; when it is reached you get the async envelope and the run carries on.

Poll it

curl "$AUTHORIC_URL/$APP_UID/agent/runs/$RUN_UID" \
  -H "Authorization: Bearer $AGENT_KEY"

Watch status. A pending_approval means it halted — see Approvals & halts.

Retrying safely

Send an Idempotency-Key header on invoke. A retry carrying the same key joins the run already in flight and reports its current state, rather than starting a second one. It deliberately does not replay a stored response body, which would hand back a stale snapshot of a run that may still be executing.

Direct: call one tool

When you already know what you want done, skip the model.

# What can this key do?
curl "$AUTHORIC_URL/$APP_UID/agent/tools" -H "Authorization: Bearer $AGENT_KEY"

# Do exactly this
curl -X POST "$AUTHORIC_URL/$APP_UID/agent/tools/tickets_create" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Card declined", "priority": "high" }'

The body may be { "input": {...} }, { "arguments": {...} }, or the bare argument object.

Deterministic, no tokens spent, no planning. Governance is unchanged: a high-risk tool returns 202 with a runUid and waits for approval exactly as the orchestrated path does.

The endpoints

Next