Agent Runtime API

The Agent Runtime API is how your own code drives an agent: start a conversation and follow it, or skip the model and call one tool. Every route is authenticated with an agent API key, and the key decides which agent runs. Full request and response schemas are in the API reference; this page is the shape of the thing.

export AUTHORIC_URL="https://api.authoric.ai"   # your API's address
export APP_UID="<your app uid>"
export AGENT_KEY="plak_..."

Send the key as a bearer token: Authorization: Bearer plak_…. The x-api-key header works too.

The endpoints

There is no route to approve or continue a run with an API key, by design. See Approvals & halts.

Conversations: give it a goal

curl -X POST "$AUTHORIC_URL/$APP_UID/agent/invoke" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-2291-late-refund" \
  -d '{ "message": "Find the order on invoice INV-2291 and refund it if it shipped late." }'

The answer is 202, with the run's handle, before any work starts:

{
  "ok": true,
  "status": "running",
  "runUid": "0199f1d2-4b6a-7c3e-8a1f-2d9e6b0c4a77",
  "message": "",
  "resumable": false,
  "pendingSteps": [],
  "steps": [],
  "actions": {
    "poll": { "method": "GET", "href": "/{appUid}/agent/runs/0199f1d2-4b6a-7c3e-8a1f-2d9e6b0c4a77" },
    "cancel": { "method": "POST", "href": "/{appUid}/agent/runs/0199f1d2-4b6a-7c3e-8a1f-2d9e6b0c4a77/abort" },
    "message": { "method": "POST", "href": "/{appUid}/agent/runs/0199f1d2-4b6a-7c3e-8a1f-2d9e6b0c4a77/messages", "body": { "message": "" } }
  }
}

The body takes:

There is no agent field: the key implies the agent, and an agent named in the body is ignored. An autoApprove field is ignored too. See Approvals & halts.

Waiting for short calls

?wait=true holds the connection until the run ends, up to a ceiling the server sets. Within it you get 200 with the agent's message and the conversation's sessionUid. Past it you get the ordinary 202 envelope and the run carries on, so waiting can turn into polling but never into a lost run.

Retrying safely

Send an Idempotency-Key header on invoke. A retry with the same key and the same request joins the run already started and reports its current state; it does not start a second one or replay an old response. The same key with a different request is 409. Keys are remembered for 24 hours.

Following it

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

The statuses, progress, activity and assets are explained on Runs.

Listing runs

GET /{appUid}/agent/runs answers "what is my agent doing?" without already holding a handle. It returns a summary per run, newest first, with each run's actions.

paging.count is the size of this page, not a total: keep asking until a short page comes back.

Steering and stopping

POST …/runs/{runUid}/messages with { "message": "…" } delivers a new instruction into a run that is still going, and POST …/runs/{runUid}/abort stops one. Both are your key's to use on its own runs; neither can approve anything. See Runs.

Direct: call one tool

When you already know what you want done, skip the model. List the key's tools, then call one by name:

# 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/invoices_create" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "invoice_number": "INV-1042", "amount": 1200 } }'

The body is the tool's arguments, matching its inputSchema. It may also be wrapped as { "input": { … } } or { "arguments": { … } }. Tool names and schemas are explained on Tools.

No model, no planning, no tokens spent, and the same governance: a tool rated above low does not run here either. The HTTP status says what happened:

{
  "ok": true,
  "name": "invoices_delete",
  "status": "pending_approval",
  "runUid": "0199f1d4-0a2e-7d61-9b3c-6f8e1a2d5c90",
  "risk": "high",
  "output": null,
  "error": null
}

An Idempotency-Key header makes a retried call run at most once; a duplicate gets the stored response back. ?mode= chooses how tables are presented as tools (see MCP server).

Errors

Every key is also rate limited, separately from the run limit; over it you get 429. The full list of codes is in Error codes.

What's next