Aegis Orchestrator
Reference

REST API Reference

Full HTTP API surface of the AEGIS Orchestrator — all routes, request/response schemas, and authentication.

REST API Reference

The AEGIS Orchestrator exposes an HTTP API on port 8080 (default). All request and response bodies are JSON unless otherwise noted.


Authentication

Route groupMechanism
Most endpointsKeycloak Bearer JWT: Authorization: Bearer <token>
POST /v1/webhooks/{source}HMAC-SHA256 signature: X-Aegis-Signature: sha256=<hex>
POST /v1/dispatch-gatewayInternal — no external auth (agent containers only)
GET /healthNone

Service Account Tenant Delegation

Service accounts (M2M clients using client credentials) may include an X-Tenant-Id: {tenant-slug} request header to scope operations to a specific user tenant. Without this header, service account requests scope to the aegis-system tenant by default.

This header is ignored for all other identity types (consumer users, operator users).


Agents

GET /v1/agents/lookup/{name}

Look up a deployed agent by its unique name. Returns the agent's ID and manifest metadata.

Path parameters:

ParameterDescription
nameThe unique name of the agent (e.g. code-reviewer)

Request headers:

HeaderRequiredDescription
Authorization✓Bearer JWT
X-Tenant-IdNoFor service accounts: scope the lookup to this tenant instead of the default aegis-system tenant

Response 200:

{
  "agent_id": "agt-uuid",
  "name": "code-reviewer",
  "tenant_id": "tenant-slug"
}

Errors:

HTTPBodyCause
404{"error": "Agent not found"}No agent with that name exists in the resolved tenant

GET /v1/agents

List all deployed agents visible to the caller's resolved tenant context.

Request headers:

HeaderRequiredDescription
Authorization✓Bearer JWT
X-Tenant-IdNoFor service accounts: scope the listing to this tenant instead of the default aegis-system tenant

Response 200:

{
  "agents": [
    {
      "agent_id": "agt-uuid",
      "name": "code-reviewer",
      "tenant_id": "tenant-slug"
    }
  ]
}

Executions

POST /v1/executions

Start an agent execution. Returns immediately with the execution_id; use the SSE stream to follow progress.

Request headers:

HeaderRequiredDescription
Authorization✓Bearer JWT
X-Tenant-IdNoFor service accounts: scope the execution to this tenant instead of the default aegis-system tenant

Request body:

{
  "agent_id": "agt-uuid",
  "input": "Write a function that checks if a number is prime."
}
FieldTypeRequiredDescription
agent_idstring (UUID)✓ID of a deployed agent
inputstring✓Task input passed to the agent

Response 200:

{
  "execution_id": "exec-uuid"
}

Errors:

HTTPBodyCause
400{"error": "Invalid agent ID"}agent_id is not a valid UUID
500{"error": "<message>"}Execution failed to start

GET /v1/executions

The caller's agent executions, newest first. Requires the scope execution:list. limit is the most executions answered (default 20, at most the node's max_execution_list_limit, 1000 when unset) and offset the number skipped from the newest (default 0), as GET /v1/workflows/executions pages workflow runs; agent_id keeps one agent's executions, and workflow_name those of the workflow of that name across its versions (a name the tenant does not have answers {"error": "Workflow '<name>' not found"}). The answer is an array of { id, agent_id, status, started_at, ended_at, tenant_id } with no total, so a page shorter than limit is the last. An operator's request with neither filter lists every tenant's executions.

GET /v1/executions/{id}

The status of an agent execution, or of a workflow run. Requires the scope execution:read. A caller reads only executions of the tenant its request resolves to (a service account the tenant it names in X-Tenant-Id); an operator reads any tenant's.

Response 200:

{
  "id": "exec-uuid",
  "agent_id": "agt-uuid",
  "status": "Completed",
  "tenant_id": "tenant-id",
  "final_output": "def is_prime(n): ...",
  "error": null
}

An agent execution answers with "kind": "agent" beside these fields. status is Pending, Running, Completed, Failed or Cancelled. Once the execution has ended (Completed, Failed or Cancelled) the answer also carries final_output, the output of the last iteration that has one, and error, the execution's error, each null when there is none, so a caller that finds the run already over reads what it produced. A Pending or Running execution carries neither key.

When no agent execution has the id, a workflow run of the same tenant answers with "kind": "workflow" and the fields GET /v1/workflows/executions/{id} gives: id and execution_id (both the run's id), workflow_id, workflow_name, status in lower case (running, completed, failed, cancelled), current_state, started_at, last_transition_at and tenant_id; once the run has ended it also carries final_output, null when the run produced none.

{
  "kind": "workflow",
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "workflow_id": "wf-uuid",
  "workflow_name": "the-forge",
  "status": "running",
  "current_state": "AWAIT_REQUIREMENTS_APPROVAL",
  "started_at": "2026-10-13T07:25:09Z",
  "last_transition_at": "2026-10-13T07:31:40Z",
  "tenant_id": "tenant-id"
}

Errors:

HTTPBodyCause
404{"error": "Execution not found"}No agent execution and no workflow run of that id in the caller's tenant

GET /v1/executions/{id}/files/{path}

The bytes of one file of a completed execution's workspace volume, with its Content-Type and Content-Length. Requires the scope execution:read. A leading /workspace/ of the path is stripped. This is the route an aegis.execution.file answer's download_url names.

With ?volume_id=<id> the file is read from that volume of the caller's tenant instead, and the execution id in the path is not read: the volume and path an aegis.image.generate answer names, for example /v1/executions/<volume_id>/files/generated/<batch>/1.jpg?volume_id=<volume_id>. A volume that does not exist, another tenant's volume and a missing file answer alike, 404 with {"error": "not found: no file <path> in volume <id>"}, so the answer never tells that another tenant's volume exists. An invalid path answers 422.


GET /v1/executions/{id}/stream

Stream execution events as Server-Sent Events (SSE). Returns Content-Type: text/event-stream.

Each data: line is a JSON-encoded ExecutionEvent object. Events match the types defined in the gRPC API reference.

With ?follow=false the route answers the execution's history and ends. The history carries the execution's repository rows (repository_prepared and the rows of a commit, a push or a landing) with the orchestrator's line, for example "Prepared repository app at /workspace/app: branch aegis/1234abcd created from <sha>".

Example stream:

data: {"execution_started":{"execution_id":"exec-uuid","agent_id":"agt-uuid","started_at":"2026-03-05T14:00:00Z"}}

data: {"iteration_started":{"execution_id":"exec-uuid","iteration_number":1,"action":"Write a primality check","started_at":"2026-03-05T14:00:01Z"}}

data: {"iteration_completed":{"execution_id":"exec-uuid","iteration_number":1,"output":"def is_prime(n): ...","completed_at":"2026-03-05T14:00:15Z"}}

data: {"execution_completed":{"execution_id":"exec-uuid","final_output":"def is_prime(n): ...","total_iterations":1,"completed_at":"2026-03-05T14:00:15Z"}}

Example (JavaScript EventSource):

const es = new EventSource(
  `https://your-aegis-node/v1/executions/${executionId}/stream`,
  { headers: { Authorization: `Bearer ${token}` } },
);

es.onmessage = (e) => {
  const event = JSON.parse(e.data);
  if (event.execution_completed) {
    console.log("Output:", event.execution_completed.final_output);
    es.close();
  }
};

Volumes

Your volumes and your storage quota; both routes need the scope volume:read. A volume's used bytes are summed from the sizes of the files storage lists under it, read again at each request, so a file written a moment ago is counted.

RouteWhat it answers
GET /v1/volumesYour volumes, each {"id", "name", "status", "size_limit_bytes", "used_bytes", "usage_incomplete", "created_at"}.
GET /v1/volumes/quota{"volume_count", "total_bytes_used", "usage_incomplete", "max_volumes", "total_storage_bytes", "max_file_size_bytes"}.

When usage cannot be read. When storage cannot be listed for a volume, or the volume holds more than 100,000 entries or folders nested deeper than 64, its usage is reported as unread, never as a smaller number: on GET /v1/volumes that volume has used_bytes: null and usage_incomplete: true, and GET /v1/volumes/quota answers total_bytes_used for the volumes it could read with usage_incomplete: true. A new volume reads 0.


Volume Files

The files of one of your volumes, as the dashboard's file browser reads and changes them. Each route takes the volume's id in the path and the file or folder's path in the volume as ?path=; the reading routes need the scope volume:read, the others volume:write.

RouteWhat it does
GET /v1/volumes/{id}/files?path=Lists a folder.
GET /v1/volumes/{id}/files/stat?path=Describes one file or folder.
GET /v1/volumes/{id}/files/download?path=Answers a file's bytes.
POST /v1/volumes/{id}/files/upload?path=Writes a file from the request body.
POST /v1/volumes/{id}/files/mkdir?path=Creates a folder.
POST /v1/volumes/{id}/files/moveMoves a file or folder, body {"from": "<path>", "to": "<path>"}.
DELETE /v1/volumes/{id}/files?path=Deletes a file or folder.

Errors. Every error body is {"error": "<sentence>"}, and a sentence names only the path you sent, never where the volume is stored. A path is read for what it is before anything is fetched, so a file is never listed as a folder and a folder is never answered as a file's content.

HTTPBodyCause
404{"error": "not found: <path>"}Nothing is at that path in the volume.
422{"error": "not a directory: <path>"}A file was given where a folder is needed, for example a listing of a file.
422{"error": "is a directory: <path>"}A folder was given where a file is needed, for example a download of a folder.
422{"error": "invalid path: …"} or {"error": "file size exceeds limit"}The path is not valid in a volume, or the file is over your size limit.
403{"error": "unauthorized"}The volume belongs to another tenant, or storage refused the access.
503{"error": "The volume's usage could not be read; try again."}A write held to your quota was refused because the volume's usage could not be read (Volumes).
500{"error": "[AEGIS] the file operation failed; the server logged the cause."}Storage failed; the cause is written only to the orchestrator's log, with the route and the volume's id.

Human Approvals

A workflow's kind: Human gate is not posted to this queue: list gates with GET /v1/workflow-gates and answer one with POST /v1/workflows/executions/{id}/signal.

GET /v1/human-approvals

List all pending human approval requests.

Response 200:

{
  "pending_requests": [
    {
      "id": "req-uuid",
      "execution_id": "exec-uuid",
      "prompt": "Review the draft and approve or reject.",
      "created_at": "2026-03-05T14:00:00Z",
      "timeout_seconds": 86400
    }
  ]
}

GET /v1/human-approvals/{id}

Get a specific pending approval request.

Response 200:

{
  "request": {
    "id": "req-uuid",
    "execution_id": "exec-uuid",
    "prompt": "Review the draft and approve or reject.",
    "created_at": "2026-03-05T14:00:00Z",
    "timeout_seconds": 86400
  }
}

Errors:

HTTPBodyCause
400{"error": "Invalid request ID"}Not a valid UUID
200{"error": "Request not found or already completed"}Request expired or already resolved

POST /v1/human-approvals/{id}/approve

Approve a pending request and resume the workflow.

Request:

{
  "feedback": "Looks good, approved for production.",
  "approved_by": "alice@example.com"
}

Both fields are optional.

Response 200:

{ "status": "approved" }

POST /v1/human-approvals/{id}/reject

Reject a pending request and transition the workflow to the rejection path.

Request:

{
  "reason": "Needs more citations.",
  "rejected_by": "bob@example.com"
}

reason is required. rejected_by is optional.

Response 200:

{ "status": "rejected" }

Schedules

A person's schedules: an agent or workflow started as its owner, once (at) or on a recurrence (cron, timezone, jitter_seconds). The routes need the scopes schedule:read and schedule:write; every change is the owner's, and an operator only reads the tenant's.

MethodPathDescription
POST/v1/schedulesMake a schedule. 201 with {"schedule": {...}}.
GET/v1/schedulesYour schedules, {count, schedules}.
GET/v1/schedules/{id}One schedule, with state, next_run_at and last_run.
PATCH/v1/schedules/{id}Change the fields given; a new at or recurrence replaces the timing.
POST/v1/schedules/{id}/pausePause.
POST/v1/schedules/{id}/resumeResume.
POST/v1/schedules/{id}/runStart one run now, active or paused, as a fire starts it; {"run": {...}}, the run as runs lists it, with scheduled_time null.
DELETE/v1/schedules/{id}Delete; its runs are kept. {"deleted": "<id>"}.
GET/v1/schedules/{id}/runs?limit=Its fires, newest first, limit 1 to 100 (default 20).
GET/v1/schedules/defaults?target_kind=&target=The target manifest's spec.default_schedule, or null.

A refusal is {"error": "<sentence>"}: 400 for a request refused before anything was stored, or a run that could not start, 403 for a caller who may not do it, 404 for a schedule that is not yours, 409 with "Skipped: the last run was still running" for a run asked for now while the last run is still running, and 503 when nothing could be saved.


Rate Limits

The orchestrator limits agent executions, workflow executions, model calls and model tokens over several windows at once: hourly, daily, weekly and monthly windows kept in its database, and a per-minute window counted in memory where the work runs. Each stored window is fixed: it opens at the first charge after the previous window's close and closes one window length later, and its close does not move with later charges. Every charge made while it is open counts against its limit, so a charge that would take any window's count past its limit is refused and stored in no window. At the close the count returns to zero, and the next charge opens the next window. When an hourly, daily, weekly or monthly window refuses, the refusal's retry_after_seconds (the Retry-After header of a refused tool call) is the seconds until that window closes; a per-minute refusal carries 60.

The limits a caller is held to are, in order: an override set for the person, an override set for their tenant, then their plan's defaults. For a Zaru consumer the plan is the effective tier their own subscription and active team memberships give them, read from the orchestrator's store each time a limit is checked, so a scheduled or dispatched run is held to its person's plan; the zaru_tier claim of the token stands only when the store holds no subscription and no active membership for the person, or cannot be read. A run on the person's own model key is not limited on model calls or tokens.

Your Usage

MethodPathDescription
GET/v1/user/rate-limits/usageYour usage of every resource and stored window your limits name: {"usage": [...], "count": n}.
POST/v1/user/rate-limits/usageRecord model usage a client made for you, then answer your usage.

Both take the caller's own access token and count under the key every writer charges: the caller's own tenant and subject. Each item of usage is one resource in one window:

FieldDescription
resource_typeagent_execution, workflow_execution, llm_call, llm_token, or seal_tool:<pattern> for a tool limit.
buckethourly, daily, weekly or monthly. The per-minute window is counted only in memory and has no item.
current_countThe sum of the charges made while the open window has been open; 0 when the bucket has no open window.
limit_valueThe window's limit.
window_secondsThe window's length.
resets_atThe open window's close, fixed from the moment it opened; null when the bucket has no open window.

POST takes {"llm_calls": <n>, "llm_tokens": <m>}, each a non-negative integer, at most 1,000 calls and 50,000,000 tokens per request, and no other field. It charges the calls as llm_call and the tokens as llm_token, in the stored windows only, under the limits the writers resolve for you; a zero is not charged. A charge that a window refuses is stored in no window of its resource and is named in refused as {"resource_type", "bucket"}, the window that refused it; the answer is still 200, {"usage": [...], "count": n, "refused": [...]}, the usage read after the write.

StatusWhen
400 {"error": "usage over the request bound"}More than 1,000 calls or 50,000,000 tokens in one request.
401 {"error": "Authentication required"}No identity, or one with an empty subject.
503The node has no database for rate limits.

A body that is not that object is refused before anything is charged.

Administration

MethodPathDescription
GET/v1/admin/rate-limits/overrides?tenant_id=&user_id=The overrides, {"overrides": [...], "count": n}.
POST/v1/admin/rate-limits/overridesSet an override: tenant_id or user_id (exactly one), resource_type, bucket, limit_value and, optionally, burst_value.
DELETE/v1/admin/rate-limits/overrides/{id}Remove an override; 404 {"error": "Override not found"} when there is none.
GET/v1/admin/rate-limits/usage?scope_type=&scope_id=The counter rows stored for one scope, {"usage": [...], "count": n}.

These routes reach every tenant and user, so they serve operators only. Any operator role (aegis:admin, aegis:operator, aegis:readonly) may read; only aegis:admin and aegis:operator may set or remove an override, and aegis:readonly is refused 403 {"error": "Operator or Admin role required"}. Every other identity is refused 403 with {"error": "operator_required", ...}, and a request with no identity 401, before anything is read or written. An override naming both or neither of tenant_id and user_id is refused 400 with "Exactly one of tenant_id or user_id must be provided".


Profiles

A person's profiles: a named set of their connections and the tools they may use. The routes need the scopes profile:read and profile:write, and serve only the profile's owner.

MethodPathDescription
POST/v1/profilesMake a profile.
GET/v1/profilesYour profiles, {count, profiles}.
GET/v1/profiles/{id}One profile.
PATCH/v1/profiles/{id}Change the fields given.
DELETE/v1/profiles/{id}Delete it and revoke the standing choices made in it. 204.
POST/v1/profiles/available-toolsThe tools your security context admits for {"bindings": [<ids>]}, {count, tools}.

API Keys

Your aegis_ API keys. Each key carries the profile whose connections it reaches, or none; a key with none reaches none of your connections.

MethodPathScopeDescription
GET/v1/api-keyskey:listYour keys, {api_keys}: each its id, name, scopes, expires_at, last_used_at, created_at, status, profile (an id or null) and profile_name (the profile's name while it is still yours). Never a key's value.
POST/v1/api-keyskey:createMake a key from name, scopes, expires_at and an optional profile, one of your profiles' ids; absent or null chooses none.
PATCH/v1/api-keys/{id}key:createSet or clear an active key's profile with {"profile": <profile id or null>}, answered as GET /v1/api-keys lists the key.
DELETE/v1/api-keys/{id}Revoke the key.

A profile that is not one of your profiles' ids, or a PATCH body that names no profile or names anything but an id or null, is refused 400 "'profile' must be the id of one of your profiles, or null." with nothing stored. A key of another person's, a revoked key or none answers 404 "API key not found or already revoked".


Vault API

The vault is where AEGIS keeps credentials: the connections you store for your agents' tools, and the platform's own secret paths. These routes are how the web client, the CLI and an SDK manage it. Only the orchestrator reaches the secret store behind them, and only one route answers a stored value: your own key, read from your own signed-in session. In the tables below, the Scope column names who a route serves. Every route takes a Keycloak session; an aegis_ API key is refused 401.

Connections

MethodPathScopeDescription
GET/v1/credentialsYouYour connections, {"credentials": [...], "count": n}: metadata only, never a value.
POST/v1/credentials/api-keysYouStore a key for yourself. The value goes to the vault before the connection is saved.
POST/v1/credentials/mailboxesYouConnect a mailbox.
POST/v1/credentials/calendarsYouConnect a calendar account.
GET/v1/credentials/oauth/providersYouThe OAuth providers you can connect.
POST/v1/credentials/oauth/initiateYouStart an OAuth connection.
GET/v1/credentials/oauth/callbackYouWhere the provider returns after you approve.
POST/v1/credentials/oauth/device/pollYouPoll a device-code connection.
GET/v1/credentials/{id}Owner, team, operatorOne connection's metadata.
POST/v1/credentials/{id}/rotateOwner, team manager, operatorReplace the stored value.
DELETE/v1/credentials/{id}Owner, team manager, operatorRevoke the connection: its value and its record are deleted in one act. A revoked connection is not listed, and its id answers 404 afterwards.
POST/v1/credentials/{id}/introspectOwner, team manager, operatorCheck a remote tool server's token again and record what it reaches.
GET/v1/credentials/{id}/grantsOwner, team, operatorWho the connection is granted to.
POST/v1/credentials/{id}/grantsOwner, team manager, operatorGrant the connection.
DELETE/v1/credentials/{id}/grants/{grant_id}Owner, team manager, operatorRemove a grant.

A connection that does not exist, or one you may not reach, answers 404 {"error": "Credential binding not found"}, the same for both, so an id cannot be probed. An operator is refused the list and the writes with 403 {"error": "Consumer or tenant user identity required"}.

Reading a value

MethodPathScopeDescription
POST/v1/credentials/{id}/valueOwnerYour own key's value, for a named purpose.

Send {"purpose": "<purpose>"}, where the purpose is 1 to 64 characters of lowercase letters, digits and dashes saying why you read the value, such as chat-turn or models-fetch. The answer is 200 {"id": "<connection id>", "provider": "<provider>", "value": "<the value>"} with the header Cache-Control: no-store, and only when all of these hold: the session is yours, as a person, not an operator's or a service account's; the connection is yours; it is a personal key (type secret), not a team connection; it is active; and it is not a remote tool server's token, which only the platform presents.

Every refusal carries {"error": "<code>", "message": "<sentence>"}, or the not-found answer, and never a value:

  • 404 {"error": "Credential binding not found"}: the connection does not exist, is another person's, or is a team connection you are a member of.
  • 403 vault_value_owner_only: "A key's value is answered only to the person who owns it." An operator's session, a service account, or any identity that is not a person.
  • 422 vault_value_not_readable: "This connection's value is not answered by the vault; it is used only inside the platform." Your own connection of another type (OAuth, mailbox, calendar), a team connection, a remote tool server's token, or a connection that is not active.
  • 400 vault_purpose_required: "Name the purpose of this read: lowercase letters, digits and dashes, at most 64 characters." The purpose is missing or outside that rule.
  • 503 vault_unavailable: "The vault could not be read right now. Try again in a moment." The vault could not be read, or the read's audit record could not be written.

No route answers the value of a mailbox, a calendar account, an OAuth token, a team connection, a remote tool server's token or a platform secret path. A run, an agent or a container is never answered a value: a tool call inside a run uses the value within the platform.

Platform secret paths

MethodPathScopeDescription
GET/v1/secretsOperatorNot answered yet: 501 {"error": "Secret listing is not supported via this endpoint"}.
GET/v1/secrets/{path}OperatorA secret path's field names, {"path", "fields"}. Never its values.
PUT/v1/secrets/{path}OperatorWrite a secret path.
DELETE/v1/secrets/{path}OperatorDelete a secret path.

These routes serve aegis:admin and aegis:operator; every other identity is refused 403 {"error": "Operator or Admin role required"}.

Client secrets

A confidential client declared in the node configuration's spec.vault.client_secret_clients keeps the tokens of its own users' sessions in the vault instead of its own database.

MethodPathScopeDescription
PUT/v1/vault/client-secrets/{kind}/{id}Declared clientWrite {"owner_sub": "<the person's sub>", "value": {<token fields>}}.
POST/v1/vault/client-secrets/{kind}/{id}/valueDeclared clientRead it, with {"purpose": "<purpose>"} under the same purpose rule: {"owner_sub", "value"} with Cache-Control: no-store.
DELETE/v1/vault/client-secrets/{kind}/{id}Declared clientDelete it.

{kind} is session or revocation, and {id} is the client's own row id, a UUID. Only the declared client's service account, with a token from its client-credentials grant, may call these routes, and it reaches only the secrets it wrote: another client's secret answers 404 {"error": "Client secret not found"}, as one that does not exist. Every other caller is refused 403 vault_client_not_declared, "This client may not keep secrets in the vault.", and an aegis_ API key 401. A missing purpose is refused 400 vault_purpose_required, and a vault that cannot be read 503 vault_unavailable, as for a key's value.

Who may call each operation

OperationYour own sessionTeam memberOperator's sessionaegis_ API keyA run, an agent, a container
List connectionsyour own, metadata onlyyour own onlyrefused 403refused 401never
Store a connectionfor yourselffor yourselfrefused 403refused 401never
Read a connection's metadatayour owna team connectionevery operator rolerefused 401never
Rotate, revoke, grantsyour owna team manageraegis:admin, aegis:operatorrefused 401never
Read a valueyour own personal key onlyrefused 404refused 403refused 401never; a tool call inside a run uses it within the platform
Secret paths: field names, write, deleterefused 403refused 403aegis:admin, aegis:operatorrefused 401never
A secret path's valueno route, for anyone
Client secretsrefused 403refused 403refused 403refused 401never; only a declared client's service account, for its own secrets

A service account is refused every row but the last.

The audit record

Each of these acts appends one row to the orchestrator's audit log: a value read or its refusal; storing a key, a mailbox or a calendar account; a rotation; a revoke; a grant added or removed; a secret path written or deleted; and a client secret written, read or deleted. No row carries a value or anything derived from one. A row names the caller's sub, the action (vault.value_read, vault.value_refused, vault.binding_stored, vault.binding_rotated, vault.binding_revoked, vault.grant_added, vault.grant_revoked, vault.secret_written, vault.secret_deleted, vault.client_secret_written, vault.client_secret_read or vault.client_secret_deleted) and the target (credential:<id>, secret:<engine>/<path> or client-secret:<client_id>/<kind>/<id>). For a connection or a secret path it also records the caller kind (session, operator or other), the tenant, the provider, the connection type, a read's purpose and the outcome; for a client secret, the client, the kind, the person it is kept for, a read's purpose and the outcome. The outcome is answered, or the refusal's code. A value is never answered without its row: a read writes its row first, and a row that cannot be written refuses the read with 503 vault_unavailable. For every other act the row is written after the act, and a row that cannot be written is logged without undoing the act.


SEAL Endpoints

POST /v1/seal/attest

Attestation handshake — used by bootstrap.py at the start of each agent execution to establish an SEAL session.

Request:

{
  "agent_id": "agt-uuid",
  "execution_id": "exec-uuid",
  "container_id": "container-hash",
  "agent_public_key": "<base64-encoded Ed25519 public key>"
}

A caller outside an agent container, such as an MCP server attesting for its user, authenticates the request with its own bearer, an aegis_ API key or a Keycloak token. The session's user is always that credential's own subject: the key's owner, or the token's sub. The body cannot name the user: a user_id field is ignored. The session records the credential that attested it: the person's own sign-in token, or an aegis_ key with the profile stored for that key, and reaches the person's connections as that credential does (What a key reaches).

Response 200:

{
  "security_token": "<JWT>",
  "session_id": "session-uuid",
  "expires_at": "2026-03-05T15:00:00Z"
}

See SEAL Protocol for the full attestation flow.


POST /v1/seal/invoke

SEAL-wrapped tool invocation. Called by bootstrap.py to invoke a tool through the orchestrator proxy. The body is a SealEnvelope containing a signed MCP tool call.

The orchestrator registers this path only; it has no /v1/invoke alias. (The standalone SEAL Gateway serves both /v1/invoke and /v1/seal/invoke on its own port.)

A refused or failed call is answered with a status other than 2xx and a body {"protocol":"seal/v1","request_id":"<uuid>","status":"policy_violation|error","error":{"code","message","context","tool"}}; a refusal for a connection you lack or a tool your chosen profile does not admit also carries error.needs, {"family", "page"}, the Zaru Web page that resolves it. Every code, its HTTP status, what it means and what to do about it are listed in Built-in Tools: Refusals and Errors. A 429 also carries Retry-After and the X-RateLimit-* headers.

See Tool Routing for the three routing paths and wire format.


Dispatch Gateway

POST /v1/dispatch-gateway

The inner-loop communication endpoint between bootstrap.py and the orchestrator. Handles the full LLM → tool call → LLM cycle.

This endpoint is called by bootstrap.py inside agent containers. It is bound to the internal Docker network and is not exposed externally.

Request — initial generate:

{
  "type": "generate",
  "agent_id": "agt-uuid",
  "execution_id": "exec-uuid",
  "iteration_number": 1,
  "model_alias": "default",
  "prompt": "Task: Write a primality check\n\nInput: in Python",
  "messages": []
}

Request — dispatch result:

{
  "type": "dispatch_result",
  "execution_id": "exec-uuid",
  "dispatch_id": "dispatch-uuid",
  "exit_code": 0,
  "stdout": "All tests passed.\n",
  "stderr": "",
  "duration_ms": 1243,
  "truncated": false
}

Response — final:

{
  "type": "final",
  "content": "def is_prime(n): ...",
  "tool_calls_executed": 2,
  "conversation": [...]
}

Response — dispatch a command:

{
  "type": "dispatch",
  "dispatch_id": "dispatch-uuid",
  "action": "exec",
  "command": "python",
  "args": ["-m", "pytest", "test_prime.py"],
  "cwd": "/workspace",
  "env_additions": {},
  "timeout_secs": 60,
  "max_output_bytes": 524288
}

Stimulus Ingestion

POST /v1/stimuli

Ingest a stimulus from an internal service or operator. Authenticated by Keycloak Bearer JWT.

Request:

{
  "source": "http_api",
  "content": "Deploy release v2.1.0 to production.",
  "idempotency_key": "deploy-v2.1.0"
}
FieldTypeRequiredDescription
sourcestring✓Source identifier. Use "http_api" or a custom source name.
contentstring✓Stimulus payload — natural language or JSON string.
idempotency_keystring—Deduplication key. Scoped to (source, key) with 24-hour TTL.

Response 200:

{
  "stimulus_id": "stim-uuid",
  "workflow_execution_id": "wfex-uuid"
}

Errors:

HTTPCodeCause
409idempotent_duplicateAlready processed within TTL window
422classification_failedRouterAgent confidence below threshold
422no_router_configuredNo direct route and no RouterAgent
500workflow_errorWorkflow execution failed to start

POST /v1/webhooks/{source}

Ingest a webhook from an external system. Authenticated by HMAC-SHA256.

Required headers:

HeaderFormatDescription
X-Aegis-Signaturesha256=<hex>HMAC-SHA256 of the raw body using the source's shared secret
X-Idempotency-Keyany stringOptional — enables duplicate delivery detection

Body: Any content type. The raw body bytes are used for HMAC verification and forwarded as the stimulus content.

Response 200:

{
  "stimulus_id": "stim-uuid",
  "workflow_execution_id": "wfex-uuid"
}

Errors:

HTTPCodeCause
401missing_signatureX-Aegis-Signature header absent
401invalid_signatureHMAC digest mismatch
401secret_not_foundAEGIS_WEBHOOK_SECRET_<SOURCE> not set
400malformed_signatureHeader not in sha256=<hex> format
409idempotent_duplicateSame delivery already processed
422classification_failedRouterAgent confidence below threshold

Workflow Definitions and Executions

Workflow definition and execution management endpoints are available under /v1/workflows. The key response fields related to output schemas are documented below.

Workflow Definition Response Fields

When retrieving a workflow definition, the response includes the full manifest metadata:

FieldTypeDescription
metadata.output_schemaobjectJSON Schema declaring the workflow's output shape (if declared).
metadata.output_templatemap[string, string]Handlebars expressions for extracting final output (if declared).

These fields appear alongside existing metadata fields (name, version, input_schema, etc.).

Workflow Execution Response Fields

When retrieving a workflow execution (e.g. GET /v1/workflows/executions/{id}), the response includes:

FieldTypeDescription
final_outputobjectStructured output produced at workflow completion, if the workflow declares output_template. null when the workflow has no output template or has not yet completed.

The final_output value is the rendered and type-coerced result of evaluating the workflow's output_template against the final Blackboard. It is also returned as last_output in aegis.workflow.wait tool responses.

POST /v1/workflows/executions/{id}/signal

Answers the Human gate a workflow execution waits at. Scope workflow:signal; the execution must be in the caller's tenant.

{ "response": "yes", "feedback": "Keep the flag name short." }

response is required; feedback, optional, is read by the workflow as {{human.feedback}}. Answers 202 with {"status": "signal_sent", "execution_id": "<id>"}; 404 with {"error": "workflow execution not found"} for an id that is not a workflow execution of the caller's tenant; 503 while the orchestrator has no Temporal connection.

GET /v1/workflow-gates

Lists the Human gates of your own workflow executions. Scope workflow:read. Within the caller's tenant only executions the caller started are listed, so in a tenant several people share another member's run is not listed; a service account is refused 403. status is one of:

statusLists
pending (the default)The gates your running executions wait at. An execution is listed while its latest workflow event is the gate's HumanInputRequested, once, with that event's sequence; a run past its gate, or ended, is not listed.
answeredThe gates of your executions, running or ended, that closed: answered, or closed on the gate's timeout. A gate the run left with no answer recorded (it was cancelled with the gate open, for example) is not listed.
anyBoth, each in its own listing's shape.

Any other status answers 400 "Unknown status '<status>': the status is pending, answered or any". Gates are listed newest first: a pending gate by its post, an answered gate by its answer. The answered and any listings are paged by limit (default 50, from 1 to 200; any other answers 400 "limit must be from 1 to 200") and offset (default 0); the pending listing is not paged.

{
  "count": 1,
  "gates": [
    {
      "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "workflow_name": "the-forge",
      "state_name": "AWAIT_REQUIREMENTS_APPROVAL",
      "prompt": "Approve these requirements? …",
      "responses": ["yes", "no"],
      "default_response": null,
      "expires_at": "2026-10-13T05:38:34+00:00",
      "sequence": 7,
      "requested_at": "2026-10-13T04:38:34+00:00"
    }
  ]
}

responses are the words the gate takes, [] for a gate that takes any answer; expires_at is when the gate stops waiting. Answer a gate with POST /v1/workflows/executions/{id}/signal.

An answered gate carries execution_id, workflow_name, state_name, prompt (its latest post's), responses and sequence as a pending one does, with requested_at, and in place of the deadline:

{
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "workflow_name": "the-forge",
  "state_name": "AWAIT_REQUIREMENTS_APPROVAL",
  "prompt": "Approve these requirements? …",
  "responses": ["yes", "no"],
  "response": "yes",
  "feedback": "Keep the flag name short.",
  "answered_at": "2026-10-13T04:52:10+00:00",
  "answered_by": null,
  "sequence": 7,
  "requested_at": "2026-10-13T04:38:34+00:00",
  "outcome": "went_on"
}
FieldMeaning
responseThe word chosen; null for a gate that closed on its timeout.
feedbackThe feedback sent with the answer, or null.
answered_atWhen the gate closed.
answered_byAlways null: the run's events do not record who answered.
outcomewent_on when the run entered another state after the answer, ended when the run ended on it, timed_out when the gate closed on its timeout.

GET /v1/workflows/executions/{id}/logs

A page of a workflow run's events, in sequence order. Scope workflow:read; the run must be in the caller's tenant, else 404 with {"error": "workflow execution not found"}. limit is the most events answered (default 50, at most 200; a larger value answers 200) and offset the number of events skipped from the run's first (default 0).

{
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "events": [ … ],
  "count": 50,
  "total": 73,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

count is the page's length, total the run's number of events, and has_more whether events follow the page; limit and offset are the values applied.

A run's repository rows are among its events: the repository_prepared row of each repository the run prepared, also when an agent state prepared it, with event_type repository_prepared, the orchestrator's line as message, for example "Prepared repository aegis-examples at /workspace/aegis-examples: branch aegis/6ba7b810 created from <sha>; removed 1 paths (test/)", and the stored row as details.

An answered gate carries execution_id, workflow_name, state_name, prompt (its latest post's), responses and sequence as a pending one does, with requested_at, and in place of the deadline:

{
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "workflow_name": "the-forge",
  "state_name": "AWAIT_REQUIREMENTS_APPROVAL",
  "prompt": "Approve these requirements? …",
  "responses": ["yes", "no"],
  "response": "yes",
  "feedback": "Keep the flag name short.",
  "answered_at": "2026-10-13T04:52:10+00:00",
  "answered_by": null,
  "sequence": 7,
  "requested_at": "2026-10-13T04:38:34+00:00",
  "outcome": "went_on"
}
FieldMeaning
responseThe word chosen; null for a gate that closed on its timeout.
feedbackThe feedback sent with the answer, or null.
answered_atWhen the gate closed.
answered_byAlways null: the run's events do not record who answered.
outcomewent_on when the run entered another state after the answer, ended when the run ended on it, timed_out when the gate closed on its timeout.

GET /v1/workflows/executions/{id}/logs

A page of a workflow run's events, in sequence order. Scope workflow:read; the run must be in the caller's tenant, else 404 with {"error": "workflow execution not found"}. limit is the most events answered (default 50, at most 200; a larger value answers 200) and offset the number of events skipped from the run's first (default 0).

{
  "execution_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "events": [ … ],
  "count": 50,
  "total": 73,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

count is the page's length, total the run's number of events, and has_more whether events follow the page; limit and offset are the values applied.

A run's repository rows are among its events: the repository_prepared row of each repository the run prepared, also when an agent state prepared it, with event_type repository_prepared, the orchestrator's line as message, for example "Prepared repository aegis-examples at /workspace/aegis-examples: branch aegis/6ba7b810 created from <sha>; removed 1 paths (test/)", and the stored row as details.


Billing

All billing endpoints require a valid Keycloak Bearer JWT (Authorization: Bearer <token>). They return 501 Not Implemented if STRIPE_SECRET_KEY is not configured on the orchestrator.

GET /v1/billing/prices

List all available pricing tiers with their Stripe price IDs.

Response 200:

{
  "tiers": [
    {
      "tier": "pro",
      "product_id": "prod_xxx",
      "name": "Pro",
      "description": "For professionals and small teams",
      "included_seats": 1,
      "monthly": { "price_id": "price_xxx", "amount": 2900, "currency": "usd" },
      "annual": { "price_id": "price_yyy", "amount": 29000, "currency": "usd" },
      "seat_monthly": {
        "price_id": "price_seat_m",
        "amount": 1500,
        "currency": "usd"
      },
      "seat_annual": {
        "price_id": "price_seat_a",
        "amount": 15000,
        "currency": "usd"
      }
    }
  ]
}
FieldTypeDescription
tiers[].tierstringTier slug (pro, business, enterprise)
tiers[].product_idstringStripe Product ID
tiers[].namestringHuman-readable tier name
tiers[].descriptionstringTier description
tiers[].included_seatsintegerNumber of seats included in the base price
tiers[].monthlyobject or nullMonthly price (price_id, amount in cents, currency)
tiers[].annualobject or nullAnnual price
tiers[].seat_monthlyobject or nullMonthly per-seat price
tiers[].seat_annualobject or nullAnnual per-seat price

POST /v1/billing/checkout

Create a Stripe Checkout Session for subscribing to a plan.

Request body:

{
  "price_id": "price_xxx",
  "seat_price_id": "price_seat_xxx",
  "seats": 5
}
FieldTypeRequiredDescription
price_idstringYesStripe Price ID from GET /v1/billing/prices
seat_price_idstringNoStripe Price ID for per-seat billing
seatsintegerNoNumber of additional seats

Response 200:

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Redirect the user's browser to the returned url to complete payment.


POST /v1/billing/portal

Create a Stripe Customer Portal session for managing payment methods, viewing invoices, and cancelling subscriptions.

Response 200:

{
  "url": "https://billing.stripe.com/p/session/..."
}

GET /v1/billing/subscription

Get the current user's subscription details.

Response 200:

{
  "tier": "pro",
  "status": "active",
  "current_period_end": "2026-05-15T00:00:00Z",
  "cancel_at_period_end": false,
  "stripe_customer_id": "cus_..."
}
FieldTypeDescription
tierstringCurrent subscription tier (free, pro, business, enterprise)
statusstringStripe subscription status (active, past_due, canceled, trialing, etc.)
current_period_endstring (ISO 8601)End of the current billing period
cancel_at_period_endbooleanWhether the subscription will cancel at period end
stripe_customer_idstringThe Stripe Customer ID associated with this user

GET /v1/billing/invoices

List invoices for the current user.

Response 200:

{
  "invoices": [
    {
      "id": "in_...",
      "amount": 2900,
      "currency": "usd",
      "status": "paid",
      "created": "2026-04-01T00:00:00Z",
      "pdf_url": "https://pay.stripe.com/invoice/..."
    }
  ]
}
FieldTypeDescription
idstringStripe Invoice ID
amountintegerInvoice amount in the smallest currency unit (e.g., cents)
currencystringThree-letter ISO currency code
statusstringInvoice status (draft, open, paid, void, uncollectible)
createdstring (ISO 8601)Invoice creation timestamp
pdf_urlstringURL to download the invoice PDF

Operator Escalation

The routes behind an operator escalation. A refusal is { "error": <code>, "message": <text> }; a node without the escalation service answers 503 unavailable, and so does a redemption on a node that cannot read operator roles, one without spec.iam.keycloak_admin or without a realm of kind: system, where every escalated call is refused as well.

RouteCallerAnswer
POST /v1/admin/operator-escalation-codesZaru Web's stepped-up operator session: an aegis-system operator token whose azp is zaru-client-system and whose role is aegis:admin or aegis:operator201 { "code", "expires_at" } with Cache-Control: no-store; the code is never returned again
GET /v1/admin/operator-escalationsthe same session200 { "escalations": [{ "id", "api_key_id", "aegis_role", "started_at", "expires_at" }] }, the caller's active escalations
DELETE /v1/admin/operator-escalations/{id}the same session200 { "ended_at" }; 404 escalation_not_found when the id is not one of the caller's active escalations
POST /v1/admin/operator-escalations/end-for-operatorthe same session, role aegis:adminbody { "system_sub" }: ends every active escalation of that operator; 200 { "ended": <count> }
POST /v1/operator-escalationsan aegis_ API keybody { "code" }; 200 { "aegis_role", "expires_at" }
DELETE /v1/operator-escalations/currentthe escalated aegis_ API key200 { "ended_at" }; 404 escalation_not_found when the key holds none

On the session's routes an API key is refused 403 forbidden, a token that is not such a session 403, aegis:readonly included, and no token 401. On the two API-key routes any other bearer is refused 403 escalation_requires_api_key, and a missing or invalid key 401. A redemption is refused 400 invalid_code when no live code of the key's user matches or the key was created with an operator role of its own, and 400 code_expired when the code matched after its validity ended. A redemption is also refused 400 invalid_code when the operator's account in the system realm no longer holds the code's role, is disabled or is gone, and that code is invalidated; it answers 500 internal_error when the account cannot be read, the code neither used nor counted as a failure. While a key holds an active escalation, POST /v1/api-keys/validate answers the escalation's role as aegis_role, with operator_escalation: { "expires_at" }.


Model Aliases

GET /v1/llm/aliases/{alias}

Returns the model a call on a model alias is sent to, read from the node's provider registry, the one every agent's model call is routed through. A caller outside the orchestrator uses it to select the same model the node's alias table names. The answer carries no endpoint, header or key.

The route accepts an aegis_* API key as well as a signed-in user's JWT, and answers both the same.

Path parameters:

ParameterDescription
aliasA model alias from spec.llm_providers[].models

Request headers:

HeaderRequiredDescription
Authorization✓Bearer JWT, or an aegis_* API key

Response 200:

{ "alias": "default", "model": "@cf/zai-org/glm-5.3-flash" }

Errors:

HTTPBodyCause
401{"error": "Authentication required"}No valid JWT or API key, or a revoked or expired key, including a node configured without spec.iam and no key
404{"error": "Model alias not configured"}The node maps no model to that alias

Health

GET /health

Liveness probe. Returns 200 OK when the orchestrator is running.

Response 200:

{ "status": "ok" }

See Also


Edge Mode (/v1/edge/*)

The /v1/edge/* namespace covers enrollment, host management, groups, and fleet operations for user-installed edge daemons. Every endpoint is filtered through effective_tenant; cross-tenant access is impossible at the router boundary.

MethodPathPurpose
POST/v1/edge/enrollment-tokensIssue a one-time enrollment token.
GET/v1/edge/hostsList hosts in the tenant (filterable by tag, label, connected).
GET/v1/edge/hosts/:idSingle host detail with recent command history.
PATCH/v1/edge/hosts/:idUpdate display name and/or tags.
POST/v1/edge/hosts/:id/tagsAtomic add/remove on the tags array.
DELETE/v1/edge/hosts/:idRevoke an edge host.
GET/v1/edge/groupsList groups.
POST/v1/edge/groupsCreate a group.
GET/v1/edge/groups/:idSingle group with resolved members.
PATCH/v1/edge/groups/:idUpdate name, selector, pinned members.
DELETE/v1/edge/groups/:idDelete a group.
POST/v1/edge/fleet/previewResolve a target without dispatching.
POST/v1/edge/fleet/invokeDispatch a tool against a target with a fleet policy. Server-streamed.
POST/v1/edge/fleet/:fleet_command_id/cancelBroadcast Cancel to in-flight per-node commands.
GET/v1/edge/fleet/runsFleet run history.
GET/v1/edge/fleet/runs/:idSingle run with per-node detail.

Required scopes (mapped from Keycloak roles): aegis.edge.enroll, aegis.edge.hosts.{read,write}, aegis.edge.groups.write, aegis.edge.fleet.{read,manage}.

For the full reference, see edge REST API.

On this page