Skip to content

API#

Everything the console does in Anemoi goes through the same REST API as Astraeus, in JSON. Authentication, conventions and the error format are in the Astraeus REST API; this page lists Anemoi's endpoints.

Base URLs#

$ export ASTRA_URL=https://console.astralyx.cloud
$ export ASTRA_TOKEN=ast_pat_…
$ export WS="$ASTRA_URL/api/v1/orgs/acme/workspaces/research/clusters/main/api"
Scope URL
A workspace on a cluster (written $WS) $ASTRA_URL/api/v1/orgs/{org}/workspaces/{ws}/clusters/{cluster}/api
The console $ASTRA_URL/api/v1

Names in paths and bodies are your workspace's own (researcher, not the namespace). Every reference must name an object of the workspace.

Roles#

Role May
viewer Read agents, versions, runs, traces, activity, receipts, costs, approvals (and what a held call would do), guardrails, budgets, prices, suites, eval runs, quality, traffic, flows and executions.
editor Also write agents, versions, runs, suites, eval runs, gates, promotions, traffic, rollbacks, flows, executions, events, retries, cancels; decide approvals they are named for; publish and install templates.
admin Also write guardrails, budgets and retention; evidence packs.
auditor Read the governance record (agents, versions, runs, costs, receipts, traffic, quality, approvals, guardrails, budgets, flows, executions, eval runs, retention, usage) — not workloads, logs, traces, suites' cases or held calls; evidence packs.

Agents#

Method and path Description
POST $WS/agents Create: {metadata, spec} (Agent specification). 201, version 1, current.
GET $WS/agents {items}: each agent with its current version's specification, state and latest runs.
GET $WS/agents/{name} One agent.
PUT $WS/agents/{name} A new version: {spec, current?} (current true by default).
DELETE $WS/agents/{name} Delete it and its versions; runs and receipts stay. 204.
GET $WS/agents/{name}/versions {items}: every version, oldest first.
GET $WS/agents/{name}/versions/{n} One version.
PUT $WS/agents/{name}/current {version}: the version runs use. Ends a traffic split.
GET $WS/agent-templates The kinds, policy templates, the default sandbox, the policy examples (presets), the connections (connectors) and the starters.
POST $WS/agent-policy-checks {tools?, sandbox?, servers?, tests?, sandbox_tests?}: each policy's verdict, and what each tested call or host would get. At most 50 tests of each. Nothing stored.
POST $WS/agent-sandbox-compositions {base?, add, params?} → {sandbox}: a sandbox policy from examples.

Runs, traces and receipts#

Method and path Description
POST $WS/agents/{name}/runs Start a run: {input, version?}. 201 with {agent, version, input, run}.
GET $WS/agents/{name}/runs {items}: its runs, newest first, with waiting_for_approval and spend. Evaluation runs left out.
GET $WS/agents/{name}/runs/{run} One run: {agent, version, input, run, waiting_for_approval, spend}.
GET $WS/tasks/{run}-0/logs?tail= The output.
GET $WS/tasks/{run}-0/trace The trace, from the run's machine: limit (500, at most 2 000); canonical=1 with format=jsonl or json for the receipt's lines.
GET $WS/tasks/{run}-0/activity Everything that left the run, from its machine.
DELETE $WS/jobs/{run} Stop and delete the run.
GET $WS/agents/{name}/runs/{run}/receipt Its receipt (format). 404 AGENT_RECEIPT_NOT_FOUND before it ends.
GET $WS/agents/{name}/receipts?limit= The agent's chain, newest first (50, at most 1 000).
GET $WS/identity/jwks The cluster's public keys (no authentication needed).

Approvals#

Method and path Description
GET $WS/approvals {items}, newest first. Query: state, run, agent.
GET $WS/approvals/{name} One: {metadata, spec: {run, task, agent, version, kind, target, policy, approvers, fingerprint, args_digest, amount_usd, node, created_at, expires_at, execution, step}, status: {state, message, decided_by, decided_at, reason}}.
GET $WS/approvals/{name}/details What the held call would do, read from its machine now.
POST $WS/approvals/{name}/decision {decision: "approve" \| "deny", reason?}: one of its approvers.

Budgets, costs and prices#

Method and path Description
POST $WS/agent-budgets {metadata, spec: {scope, period, max_cost_usd?, max_tokens?, on_exceed?, grant_usd?, grant_tokens?}}. Admins.
GET $WS/agent-budgets {items} with status (Ok, Exhausted) and observed (period_start, spent_usd, spent_tokens, model_calls, stopped_runs).
GET, PUT, DELETE $WS/agent-budgets/{name} One; PUT takes {spec}.
GET $WS/agent-costs?period=day\|month The workspace's spend: total, by agent, and its budgets.
GET $WS/agents/{name}/costs?period= An agent's spend, by run.
GET $WS/model-prices The cluster's prices (prices) and the vendors' list prices beneath (defaults). Read-only.

Guardrails and retention#

Method and path Description
GET $WS/agent-guardrails {items}: the workspace's and the organisation's (org-<name>, read-only).
POST $WS/agent-guardrails {metadata, spec: {text, description?}}. Admins.
GET, PUT, DELETE $WS/agent-guardrails/{name} One; PUT creates or replaces ({spec}).
GET $WS/agent-guardrail-presets The examples.
GET $WS/retention-policies/default The workspace's retention, with its effective values.
PUT, DELETE $WS/retention-policies/default {spec}; DELETE goes back to the defaults. Admins.

Evaluations, gate and traffic#

Method and path Description
POST $WS/eval-suites {metadata, spec}.
GET $WS/eval-suites?agent= {items}.
GET, PUT, DELETE $WS/eval-suites/{name} One; PUT takes {spec}. DELETE is refused while a gate names it.
POST $WS/eval-suites/{name}/cases/from-run {agent, run, id?, criteria?, tags?, expected_from_answer?} → {suite, case}.
POST $WS/eval-runs {spec: {suite, agent?, version?, promote?}}. 201.
GET $WS/eval-runs?suite=&agent=&version=&state= {items}, newest first.
GET, DELETE $WS/eval-runs/{name} One, with its cases' results, totals, verdict and baseline.
POST $WS/eval-runs/{name}/cancel Stop it.
PUT $WS/agents/{name}/gate {suite, required}.
DELETE $WS/agents/{name}/gate Remove the gate.
POST $WS/agents/{name}/promote {version, suite?}: 200 promoted, or 202 with the eval run started.
GET $WS/agents/{name}/quality Gate, traffic, verdicts per suite and version, suites, eval runs (at most 50).
GET $WS/agents/{name}/traffic The split and each version's runs, success rate, cost and evaluation.
PUT $WS/agents/{name}/traffic {traffic: [{version, weight}]} (or the list alone).
POST $WS/agents/{name}/rollback {version?}: end the split, or make the previous version current.

Flows#

Method and path Description
POST $WS/flows {metadata, spec} (Flow specification): version 1.
GET $WS/flows {items} with current and latest.
GET, DELETE $WS/flows/{name} One.
PUT $WS/flows/{name} A new version: {spec, current}.
GET $WS/flows/{name}/versions[/{n}] Versions.
PUT $WS/flows/{name}/current {version}.
POST $WS/flow-checks {name?, spec} → {ok, errors: [{path, message}], warnings}. Nothing stored.
POST $WS/flows/{name}/executions {inputs, version?}: start an execution.
GET $WS/flows/{name}/executions, GET $WS/flow-executions?flow=&state= Executions.
GET, DELETE $WS/flow-executions/{name} One; DELETE an execution that ended, with its own drive.
POST $WS/flow-executions/{name}/cancel Cancel it.
POST $WS/flow-executions/{name}/steps/{step}/retry Run a failed step again.
POST $WS/flow-executions/{name}/events/{event} {data: {k: v}}, at most 4 KiB.

Evidence packs#

Method and path Description
POST $WS/evidence-packs {metadata: {name}, spec: {scope, from, to, include?}}. 201, Pending. Admins and auditors.
GET $WS/evidence-packs {items}.
GET, DELETE $WS/evidence-packs/{name} One, with its signed manifest once Ready.
GET $WS/evidence-packs/{name}/download The ZIP. 409 EVIDENCE_PACK_NOT_READY before.

Console endpoints#

Method and path Description
GET /orgs/{org}/workspaces/{ws}/marketplace?q=&kind=&tag=&cluster= The built-in starters and the organisation's templates visible to the workspace.
POST /orgs/{org}/workspaces/{ws}/marketplace/publish {cluster, kind, name, version?, template?, slug?, title?, description?, tags?, icon?, notes?, visibility?, workspaces?}. Editors.
POST /orgs/{org}/workspaces/{ws}/marketplace/{slug}/install {cluster, name?, version?, bindings, update?, current?}. Editors.
GET /orgs/{org}/workspaces/{ws}/marketplace/installs What was installed, with update_available.
GET /orgs/{org}/marketplace/templates, …/settings, approval and withdrawal See Agent governance.
GET, PUT, DELETE /orgs/{org}/guardrails[/{name}], POST …/sync Organisation guardrails: see Agent governance.
GET /mcp The MCP server's description; the server itself is POST https://console.astralyx.cloud/mcp (how-to).
GET /oauth/redirect-uri The redirect URI to register with an OAuth client.
POST /me/tokens A personal API token: {name, expires_in_days}.