API Reference

The Aegis API creates, observes, steers, and approves durable automation runs through the local app. This reference documents methods, paths, scopes, request bodies, and response contracts.

Base URL

Local development defaults to:

http://127.0.0.1:4317

The host and port come from AGENT_HARNESS_HOST and AGENT_HARNESS_PORT. Binding beyond localhost should use bearer-token authentication and a private network boundary.

Authentication

Most API routes require the operator token when AGENT_HARNESS_TOKEN is configured:

Authorization: Bearer <operator-token>
Content-Type: application/json

GET /health is unauthenticated for local process checks. Static UI assets are served without API auth only in localhost local-public mode.

AGENT_HARNESS_AGENT_TOKEN enables a narrower headless-agent token. Agent tokens can inspect allowed state and add steering input, but cannot approve high-risk actions, mutate operator-owned configuration, read secret metadata, or use blocked/destructive operations.

Response Contracts

JSON responses are validated in development and test modes against Zod contracts in src/shared/contracts.ts. Contract validation can also be enabled with:

AGENT_HARNESS_VALIDATE_CONTRACTS=1

Key contract discovery endpoints include GET /agent-client/contract for headless-agent boundaries and GET /agent-profiles for the active coordinator and specialist profile registry.

Errors use a simple JSON envelope:

{
  "error": "Human-readable error message"
}

Typical status codes are 200 for reads and updates, 201 for created records, 202 for accepted webhook work, 400 for invalid input, 401 for missing auth, 403 for token scope denial, 404 for missing routes or records, and 500 for unexpected server errors.

Scope Legend

Core Shapes

Create Coordinator Run

POST /coordinator/runs creates a coordinator-led run with a delegation plan and planned task sessions.

{
  "request": "Inspect this repository and propose a small docs patch.",
  "repoPath": "/path/to/project",
  "worker": {
    "provider": "codex",
    "model": "gpt-5.3-codex"
  },
  "verifier": {
    "command": "npm test"
  }
}

Approval Decision

POST /approvals/:id/approve and POST /approvals/:id/reject accept the same decision body. Repo-write approvals require evidence review fields before the runtime can apply the prepared bundle.

{
  "actorType": "human",
  "reviewerNote": "Reviewed the diff and verifier output.",
  "reviewedEvidence": true,
  "reviewedHashes": true,
  "reviewedPolicyClass": true
}

Memory Record

POST /memory creates durable context for coordinator and run prompts.

{
  "type": "decision",
  "scope": "project",
  "content": "Use static docs pages for API reference.",
  "source": {
    "kind": "conversation",
    "id": "conversation_..."
  }
}

System And Local Service

Notifications

Coordinator And Conversations

Runs, Task Sessions, And Approvals

Project Context And Research Utilities

Secrets, OAuth, And Connector Credentials

Secret values are write-only. API responses return metadata, hashes, redacted previews, storage class, and material status only. Scoped headless-agent tokens cannot read secret records or connector credential metadata.

Planner

Planner endpoints power the local task, calendar, search, and personal context dashboard. They are operator APIs unless otherwise documented in GET /agent-client/contract.

Profiles, Capabilities, Skills, And Workflows

Automations

Memory

Audio Sessions

Models And Providers

Static Dashboard And Local Shell Routes

These routes support the bundled dashboard and local host integration. They are documented for operator awareness, but they should not be treated as stable third-party API contracts.

Safety Notes

• Approval endpoints are not generic action shortcuts. Repo writes, external side effects, and unsupported high-risk approval classes remain human-owned and require explicit evidence review.
• OAuth and connector endpoints store raw tokens and secrets outside the SQLite metadata database in local secret material. API responses must never expose raw secret values.
• Webhook automations are accepted only through configured automation definitions and should use the webhook secret header.
• Purchases, trades, tax advice, self-extension, network automation, and device control are future high-risk domains with explicit blocked policy classes. They cannot execute until a connector deliberately enables the class with verifier coverage, approval checkpoints, and audit traces.
• Public HTTPS is deferred to a later deployment layer behind a reverse proxy or private access layer.
• Model/provider behavior is documented in the model-provider guide and routing API sections.
• Operator dashboard response shapes are summarized in docs/architecture/operator-contracts.md; headless agent boundaries are documented in docs/architecture/headless-agent-client.md.