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 group | Mechanism |
|---|---|
| Most endpoints | Keycloak Bearer JWT: Authorization: Bearer <token> |
POST /v1/webhooks/{source} | HMAC-SHA256 signature: X-Aegis-Signature: sha256=<hex> |
POST /v1/dispatch-gateway | Internal — no external auth (agent containers only) |
GET /health | None |
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:
| Parameter | Description |
|---|---|
name | The unique name of the agent (e.g. code-reviewer) |
Request headers:
| Header | Required | Description |
|---|---|---|
Authorization | ✓ | Bearer JWT |
X-Tenant-Id | No | For 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:
| HTTP | Body | Cause |
|---|---|---|
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:
| Header | Required | Description |
|---|---|---|
Authorization | ✓ | Bearer JWT |
X-Tenant-Id | No | For 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:
| Header | Required | Description |
|---|---|---|
Authorization | ✓ | Bearer JWT |
X-Tenant-Id | No | For 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."
}| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string (UUID) | ✓ | ID of a deployed agent |
input | string | ✓ | Task input passed to the agent |
Response 200:
{
"execution_id": "exec-uuid"
}Errors:
| HTTP | Body | Cause |
|---|---|---|
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:
| HTTP | Body | Cause |
|---|---|---|
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.
| Route | What it answers |
|---|---|
GET /v1/volumes | Your 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.
| Route | What 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/move | Moves 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.
| HTTP | Body | Cause |
|---|---|---|
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:
| HTTP | Body | Cause |
|---|---|---|
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.
| Method | Path | Description |
|---|---|---|
POST | /v1/schedules | Make a schedule. 201 with {"schedule": {...}}. |
GET | /v1/schedules | Your 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}/pause | Pause. |
POST | /v1/schedules/{id}/resume | Resume. |
POST | /v1/schedules/{id}/run | Start 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
| Method | Path | Description |
|---|---|---|
GET | /v1/user/rate-limits/usage | Your usage of every resource and stored window your limits name: {"usage": [...], "count": n}. |
POST | /v1/user/rate-limits/usage | Record 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:
| Field | Description |
|---|---|
resource_type | agent_execution, workflow_execution, llm_call, llm_token, or seal_tool:<pattern> for a tool limit. |
bucket | hourly, daily, weekly or monthly. The per-minute window is counted only in memory and has no item. |
current_count | The sum of the charges made while the open window has been open; 0 when the bucket has no open window. |
limit_value | The window's limit. |
window_seconds | The window's length. |
resets_at | The 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.
| Status | When |
|---|---|
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. |
503 | The node has no database for rate limits. |
A body that is not that object is refused before anything is charged.
Administration
| Method | Path | Description |
|---|---|---|
GET | /v1/admin/rate-limits/overrides?tenant_id=&user_id= | The overrides, {"overrides": [...], "count": n}. |
POST | /v1/admin/rate-limits/overrides | Set 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.
| Method | Path | Description |
|---|---|---|
POST | /v1/profiles | Make a profile. |
GET | /v1/profiles | Your 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-tools | The 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.
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/api-keys | key:list | Your 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-keys | key:create | Make 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:create | Set 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
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/credentials | You | Your connections, {"credentials": [...], "count": n}: metadata only, never a value. |
POST | /v1/credentials/api-keys | You | Store a key for yourself. The value goes to the vault before the connection is saved. |
POST | /v1/credentials/mailboxes | You | Connect a mailbox. |
POST | /v1/credentials/calendars | You | Connect a calendar account. |
GET | /v1/credentials/oauth/providers | You | The OAuth providers you can connect. |
POST | /v1/credentials/oauth/initiate | You | Start an OAuth connection. |
GET | /v1/credentials/oauth/callback | You | Where the provider returns after you approve. |
POST | /v1/credentials/oauth/device/poll | You | Poll a device-code connection. |
GET | /v1/credentials/{id} | Owner, team, operator | One connection's metadata. |
POST | /v1/credentials/{id}/rotate | Owner, team manager, operator | Replace the stored value. |
DELETE | /v1/credentials/{id} | Owner, team manager, operator | Revoke 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}/introspect | Owner, team manager, operator | Check a remote tool server's token again and record what it reaches. |
GET | /v1/credentials/{id}/grants | Owner, team, operator | Who the connection is granted to. |
POST | /v1/credentials/{id}/grants | Owner, team manager, operator | Grant the connection. |
DELETE | /v1/credentials/{id}/grants/{grant_id} | Owner, team manager, operator | Remove 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
| Method | Path | Scope | Description |
|---|---|---|---|
POST | /v1/credentials/{id}/value | Owner | Your 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.403vault_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.422vault_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.400vault_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.503vault_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
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/secrets | Operator | Not answered yet: 501 {"error": "Secret listing is not supported via this endpoint"}. |
GET | /v1/secrets/{path} | Operator | A secret path's field names, {"path", "fields"}. Never its values. |
PUT | /v1/secrets/{path} | Operator | Write a secret path. |
DELETE | /v1/secrets/{path} | Operator | Delete 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.
| Method | Path | Scope | Description |
|---|---|---|---|
PUT | /v1/vault/client-secrets/{kind}/{id} | Declared client | Write {"owner_sub": "<the person's sub>", "value": {<token fields>}}. |
POST | /v1/vault/client-secrets/{kind}/{id}/value | Declared client | Read 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 client | Delete 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
| Operation | Your own session | Team member | Operator's session | aegis_ API key | A run, an agent, a container |
|---|---|---|---|---|---|
| List connections | your own, metadata only | your own only | refused 403 | refused 401 | never |
| Store a connection | for yourself | for yourself | refused 403 | refused 401 | never |
| Read a connection's metadata | your own | a team connection | every operator role | refused 401 | never |
| Rotate, revoke, grants | your own | a team manager | aegis:admin, aegis:operator | refused 401 | never |
| Read a value | your own personal key only | refused 404 | refused 403 | refused 401 | never; a tool call inside a run uses it within the platform |
| Secret paths: field names, write, delete | refused 403 | refused 403 | aegis:admin, aegis:operator | refused 401 | never |
| A secret path's value | no route, for anyone | ||||
| Client secrets | refused 403 | refused 403 | refused 403 | refused 401 | never; 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"
}| Field | Type | Required | Description |
|---|---|---|---|
source | string | ✓ | Source identifier. Use "http_api" or a custom source name. |
content | string | ✓ | Stimulus payload — natural language or JSON string. |
idempotency_key | string | — | Deduplication key. Scoped to (source, key) with 24-hour TTL. |
Response 200:
{
"stimulus_id": "stim-uuid",
"workflow_execution_id": "wfex-uuid"
}Errors:
| HTTP | Code | Cause |
|---|---|---|
409 | idempotent_duplicate | Already processed within TTL window |
422 | classification_failed | RouterAgent confidence below threshold |
422 | no_router_configured | No direct route and no RouterAgent |
500 | workflow_error | Workflow execution failed to start |
POST /v1/webhooks/{source}
Ingest a webhook from an external system. Authenticated by HMAC-SHA256.
Required headers:
| Header | Format | Description |
|---|---|---|
X-Aegis-Signature | sha256=<hex> | HMAC-SHA256 of the raw body using the source's shared secret |
X-Idempotency-Key | any string | Optional — 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:
| HTTP | Code | Cause |
|---|---|---|
401 | missing_signature | X-Aegis-Signature header absent |
401 | invalid_signature | HMAC digest mismatch |
401 | secret_not_found | AEGIS_WEBHOOK_SECRET_<SOURCE> not set |
400 | malformed_signature | Header not in sha256=<hex> format |
409 | idempotent_duplicate | Same delivery already processed |
422 | classification_failed | RouterAgent 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:
| Field | Type | Description |
|---|---|---|
metadata.output_schema | object | JSON Schema declaring the workflow's output shape (if declared). |
metadata.output_template | map[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:
| Field | Type | Description |
|---|---|---|
final_output | object | Structured 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:
status | Lists |
|---|---|
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. |
answered | The 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. |
any | Both, 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"
}| Field | Meaning |
|---|---|
response | The word chosen; null for a gate that closed on its timeout. |
feedback | The feedback sent with the answer, or null. |
answered_at | When the gate closed. |
answered_by | Always null: the run's events do not record who answered. |
outcome | went_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"
}| Field | Meaning |
|---|---|
response | The word chosen; null for a gate that closed on its timeout. |
feedback | The feedback sent with the answer, or null. |
answered_at | When the gate closed. |
answered_by | Always null: the run's events do not record who answered. |
outcome | went_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"
}
}
]
}| Field | Type | Description |
|---|---|---|
tiers[].tier | string | Tier slug (pro, business, enterprise) |
tiers[].product_id | string | Stripe Product ID |
tiers[].name | string | Human-readable tier name |
tiers[].description | string | Tier description |
tiers[].included_seats | integer | Number of seats included in the base price |
tiers[].monthly | object or null | Monthly price (price_id, amount in cents, currency) |
tiers[].annual | object or null | Annual price |
tiers[].seat_monthly | object or null | Monthly per-seat price |
tiers[].seat_annual | object or null | Annual 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
}| Field | Type | Required | Description |
|---|---|---|---|
price_id | string | Yes | Stripe Price ID from GET /v1/billing/prices |
seat_price_id | string | No | Stripe Price ID for per-seat billing |
seats | integer | No | Number 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_..."
}| Field | Type | Description |
|---|---|---|
tier | string | Current subscription tier (free, pro, business, enterprise) |
status | string | Stripe subscription status (active, past_due, canceled, trialing, etc.) |
current_period_end | string (ISO 8601) | End of the current billing period |
cancel_at_period_end | boolean | Whether the subscription will cancel at period end |
stripe_customer_id | string | The 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/..."
}
]
}| Field | Type | Description |
|---|---|---|
id | string | Stripe Invoice ID |
amount | integer | Invoice amount in the smallest currency unit (e.g., cents) |
currency | string | Three-letter ISO currency code |
status | string | Invoice status (draft, open, paid, void, uncollectible) |
created | string (ISO 8601) | Invoice creation timestamp |
pdf_url | string | URL 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.
| Route | Caller | Answer |
|---|---|---|
POST /v1/admin/operator-escalation-codes | Zaru 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:operator | 201 { "code", "expires_at" } with Cache-Control: no-store; the code is never returned again |
GET /v1/admin/operator-escalations | the same session | 200 { "escalations": [{ "id", "api_key_id", "aegis_role", "started_at", "expires_at" }] }, the caller's active escalations |
DELETE /v1/admin/operator-escalations/{id} | the same session | 200 { "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-operator | the same session, role aegis:admin | body { "system_sub" }: ends every active escalation of that operator; 200 { "ended": <count> } |
POST /v1/operator-escalations | an aegis_ API key | body { "code" }; 200 { "aegis_role", "expires_at" } |
DELETE /v1/operator-escalations/current | the escalated aegis_ API key | 200 { "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:
| Parameter | Description |
|---|---|
alias | A model alias from spec.llm_providers[].models |
Request headers:
| Header | Required | Description |
|---|---|---|
Authorization | ✓ | Bearer JWT, or an aegis_* API key |
Response 200:
{ "alias": "default", "model": "@cf/zai-org/glm-5.3-flash" }Errors:
| HTTP | Body | Cause |
|---|---|---|
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
- gRPC API Reference — Temporal-worker-facing streaming transport
- Configuring Webhooks — setting up HMAC secrets and routes
- Human Approvals — using the approval gate in workflows
- SEAL Protocol — signed tool invocation protocol
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.
| Method | Path | Purpose |
|---|---|---|
POST | /v1/edge/enrollment-tokens | Issue a one-time enrollment token. |
GET | /v1/edge/hosts | List hosts in the tenant (filterable by tag, label, connected). |
GET | /v1/edge/hosts/:id | Single host detail with recent command history. |
PATCH | /v1/edge/hosts/:id | Update display name and/or tags. |
POST | /v1/edge/hosts/:id/tags | Atomic add/remove on the tags array. |
DELETE | /v1/edge/hosts/:id | Revoke an edge host. |
GET | /v1/edge/groups | List groups. |
POST | /v1/edge/groups | Create a group. |
GET | /v1/edge/groups/:id | Single group with resolved members. |
PATCH | /v1/edge/groups/:id | Update name, selector, pinned members. |
DELETE | /v1/edge/groups/:id | Delete a group. |
POST | /v1/edge/fleet/preview | Resolve a target without dispatching. |
POST | /v1/edge/fleet/invoke | Dispatch a tool against a target with a fleet policy. Server-streamed. |
POST | /v1/edge/fleet/:fleet_command_id/cancel | Broadcast Cancel to in-flight per-node commands. |
GET | /v1/edge/fleet/runs | Fleet run history. |
GET | /v1/edge/fleet/runs/:id | Single 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.