API Reference

Aegis exposes a REST API on http://localhost:9100 (configurable via AEGIS_PORT). All endpoints return JSON.

Authentication

Set AEGIS_AUTH_TOKEN to enable bearer token authentication. All endpoints except /v1/health require the Authorization: Bearer <token> header when auth is enabled.

# With auth
curl -H "Authorization: Bearer your-token" http://localhost:9100/v1/sessions

# Without auth (default)
curl http://localhost:9100/v1/sessions

For multi-key auth, see Enterprise Deployment.

Claude Code Hook Receiver Authentication

POST /v1/hooks/{eventName} is the inbound callback endpoint used by Claude Code hooks.

Send the session ID via X-Session-Id header (or sessionId query fallback).
Send the hook secret via X-Hook-Secret header.
Query-param secret is deprecated in compatibility mode and logs a warning.
Set AEGIS_HOOK_SECRET_HEADER_ONLY=true to enforce header-only secret transport and reject query-param secrets.

curl -X POST "http://localhost:9100/v1/hooks/Stop?sessionId=<session-uuid>" \
  -H "X-Hook-Secret: <hook-secret>" \
  -H "Content-Type: application/json" \
  -d '{}'

Core Endpoints

Health Check

curl http://localhost:9100/v1/health

Response:

{
  "status": "ok",
  "version": "0.3.0-alpha",
  "platform": "linux",
  "uptime": 3600,
  "sessions": { "active": 3, "total": 42 },
  "tmux": { "healthy": true, "error": null },
  "timestamp": "2026-04-08T09:00:00.000Z"
}

No authentication required.

Session Statistics

curl http://localhost:9100/v1/sessions/stats

Response: Aggregate session metrics (active, idle, stalled counts).

Create Session

curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature-auth",
    "workDir": "/home/user/my-project",
    "prompt": "Build a login page with email/password fields."
  }'

Parameters:

Parameter	Type	Required	Description
`name`	string	no	Session name (defaults to auto-generated)
`workDir`	string	yes	Absolute path to working directory (must exist)
`prompt`	string	no	Initial prompt to send after boot

Response:

{
  "id": "abc123",
  "name": "feature-auth",
  "workDir": "/home/user/my-project",
  "status": "working",
  "createdAt": "2026-04-08T09:00:00.000Z",
  "promptDelivery": { "delivered": true, "attempts": 1 }
}

Read Session Output

curl http://localhost:9100/v1/sessions/abc123/read

Response:

{
  "id": "abc123",
  "status": "idle",
  "output": "I've created the login page with...",
  "tokenUsage": { "input": 1500, "output": 800 }
}

Send Message

curl -X POST http://localhost:9100/v1/sessions/abc123/send \
  -H "Content-Type: application/json" \
  -d '{"text": "Add form validation."}'

Parameters:

Parameter	Type	Required	Description
`text`	string	yes	Message to send to Claude Code

Interrupt Session

curl -X POST http://localhost:9100/v1/sessions/abc123/interrupt

Sends Ctrl+C to the Claude Code session. Useful when Claude is stuck or working on the wrong task.

Kill Session

curl -X DELETE http://localhost:9100/v1/sessions/abc123

Terminates the tmux window and cleans up resources.

Spawn Child Session

curl -X POST http://localhost:9100/v1/sessions/abc123/spawn \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Review the changes in the parent session."}'

Creates a child Claude Code session within the same tmux window. The child inherits the parent's working directory.

Fork Session

curl -X POST http://localhost:9100/v1/sessions/abc123/fork

Creates a new independent session with the same working directory and context.

Batch Operations

Batch Create:

curl -X POST http://localhost:9100/v1/sessions/batch \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [
      {"name": "task-1", "workDir": "/project", "prompt": "Task 1"},
      {"name": "task-2", "workDir": "/project", "prompt": "Task 2"}
    ]
  }'

Batch Kill:

curl -X DELETE http://localhost:9100/v1/sessions/batch \
  -H "Content-Type: application/json" \
  -d '{"ids": ["abc123", "def456"]}'

Quality Gate Verification

curl -X POST http://localhost:9100/v1/sessions/abc123/verify

Runs verification checks on session output (tests, lint, build). Returns pass/fail results.

Orchestration Endpoints

Pipelines

# Create pipeline
curl -X POST http://localhost:9100/v1/pipelines \
  -H "Content-Type: application/json" \
  -d '{
    "name": "build-and-test",
    "stages": [
      {"prompt": "Run tests and fix failures"},
      {"prompt": "Run lint and fix issues"}
    ]
  }'

# List pipelines
curl http://localhost:9100/v1/pipelines

Session Templates

curl http://localhost:9100/v1/templates

Returns registered session templates with variable substitution support.

Swarm Status

curl http://localhost:9100/v1/swarm

Returns the status of parallel session swarm coordination.

Permission Endpoints

Update Permission Policy

curl -X PUT http://localhost:9100/v1/sessions/abc123/permissions \
  -H "Content-Type: application/json" \
  -d '{"allowRead": true, "allowWrite": true, "allowBash": false}'

Update Permission Profile

curl -X PUT http://localhost:9100/v1/sessions/abc123/permission-profile \
  -H "Content-Type: application/json" \
  -d '{"profile": "restricted"}'

Approve/Reject Permission Request

# Approve
curl -X POST http://localhost:9100/v1/sessions/abc123/approve \
  -H "Content-Type: application/json" \
  -d '{"permissionId": "perm-1"}'

# Reject
curl -X POST http://127.0.0.1:9100/v1/sessions/abc123/reject \
  -H "Content-Type: application/json" \
  -d '{"permissionId": "perm-1"}'

Auth Management Endpoints

Create API Key

curl -X POST http://localhost:9100/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-bot", "scopes": ["sessions:read", "sessions:write"]}'

List API Keys

curl http://localhost:9100/v1/auth/keys

Delete API Key

curl -X DELETE http://localhost:9100/v1/auth/keys/key-abc123

Rotate API Key

curl -X POST http://localhost:9100/v1/auth/keys/key-abc123/rotate \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttlDays": 365}'

Rotates an API key. Admin-only. Optionally set TTL in days. Returns the updated key metadata.

Create SSE Token

curl -X POST http://localhost:9100/v1/auth/sse-token

Returns a short-lived token for SSE event stream authentication.

Memory Bridge Endpoints

Set Memory Entry

curl -X POST http://localhost:9100/v1/memory \
  -H "Content-Type: application/json" \
  -d '{"key": "project-context", "value": "Using Fastify v5", "ttlMs": 3600000}'

Get Memory Entry

curl http://localhost:9100/v1/memory/project-context

List Memory Entries

# All entries
curl http://localhost:9100/v1/memory

# Filter by prefix
curl "http://localhost:9100/v1/memory?prefix=project-"

Delete Memory Entry

curl -X DELETE http://localhost:9100/v1/memory/project-context

Session-Scoped Memory

# Attach memory to session
curl -X POST http://localhost:9100/v1/sessions/abc123/memories \
  -H "Content-Type: application/json" \
  -d '{"key": "task-status", "value": "in-progress"}'

# Get session memories
curl http://localhost:9100/v1/sessions/abc123/memories

Session Health

curl http://localhost:9100/v1/sessions/{id}/health \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

Returns liveness and health data for a specific session.

Response:

{
  "alive": true,
  "windowExists": true,
  "claudeRunning": true,
  "paneCommand": "claude --no-input",
  "status": "working",
  "hasTranscript": true,
  "lastActivity": 1712650800000,
  "lastActivityAgo": 2340,
  "sessionAge": 45230000,
  "details": "Session healthy"
}

Session Latency

curl http://localhost:9100/v1/sessions/{id}/latency \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

Returns per-operation latency metrics for a session (hook latency, state change detection, permission response, channel delivery).

Observability Endpoints

Metrics

curl http://localhost:9100/v1/metrics

Returns token usage tracking and cost estimation across all sessions.

Diagnostics

curl http://localhost:9100/v1/diagnostics

Returns system diagnostics (tmux health, resource usage, configuration).

MCP Tools

curl http://localhost:9100/v1/tools

Lists all available MCP tools with their schemas. For full tool documentation, see MCP Tools Reference.

SSE Event Stream

curl -N http://localhost:9100/v1/events

Server-Sent Events stream for real-time session state changes. Supports token-based authentication via query parameter: ?token=<sse-token>.

Event types: session.created, session.idle, session.working, session.stalled, session.killed, permission.requested

Channel Health

curl http://localhost:9100/v1/channels/health

Returns health status for all connected channels (Telegram, Slack, Email, webhooks).

Dead-Letter Queue

curl http://localhost:9100/v1/webhooks/dead-letter

Lists failed deliveries across all channels (webhooks, Slack, Email) for inspection and retry.

Unversioned Aliases

All core session endpoints are available without the /v1 prefix for backward compatibility:

v1 Endpoint	Alias
`POST /v1/sessions`	`POST /sessions`
`GET /v1/sessions/:id/read`	`GET /sessions/:id/read`
`POST /v1/sessions/:id/send`	`POST /sessions/:id/send`
`POST /v1/sessions/:id/interrupt`	`POST /sessions/:id/interrupt`
`DELETE /v1/sessions/:id`	`DELETE /sessions/:id`
`POST /v1/sessions/:id/spawn`	`POST /sessions/:id/spawn`
`POST /v1/sessions/:id/fork`	`POST /sessions/:id/fork`
`PUT /v1/sessions/:id/permissions`	`PUT /sessions/:id/permissions`
`PUT /v1/sessions/:id/permission-profile`	`PUT /sessions/:id/permission-profile`

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Session not found",
  "code": "SESSION_NOT_FOUND",
  "statusCode": 404
}

Status Code	Meaning
400	Bad request (invalid parameters)
401	Unauthorized (missing or invalid token)
404	Session or resource not found
409	Conflict (session already exists, etc.)
429	Rate limited
500	Internal server error

Uh oh!

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Authentication

Claude Code Hook Receiver Authentication

Core Endpoints

Health Check

Session Statistics

Create Session

Read Session Output

Send Message

Interrupt Session

Kill Session

Spawn Child Session

Fork Session

Batch Operations

Quality Gate Verification

Orchestration Endpoints

Pipelines

Session Templates

Swarm Status

Permission Endpoints

Update Permission Policy

Update Permission Profile

Approve/Reject Permission Request

Auth Management Endpoints

Create API Key

List API Keys

Delete API Key

Rotate API Key

Create SSE Token

Memory Bridge Endpoints

Set Memory Entry

Get Memory Entry

List Memory Entries

Delete Memory Entry

Session-Scoped Memory

Session Health

Session Latency

Observability Endpoints

Metrics

Diagnostics

MCP Tools

SSE Event Stream

Channel Health

Dead-Letter Queue

Unversioned Aliases

Error Responses