Skip to content

api-reference.md

Latest commit

 

History

History
450 lines (317 loc) · 9.55 KB

api-reference.md

File metadata and controls

450 lines (317 loc) · 9.55 KB

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.

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.

Consensus Endpoints

Create Consensus Review

curl -X POST http://localhost:9100/v1/sessions/abc123/consensus \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": ["correctness", "security", "performance"],
    "reviewers": 3
  }'

Creates a multi-agent consensus review. Multiple Claude Code sessions independently review the work.

Get Consensus Result

curl http://localhost:9100/v1/consensus/review-123

Returns the consensus result including individual reviewer assessments and final verdict.

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

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

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, consensus.completed

Channel Health

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

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

Dead-Letter Queue

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

Lists failed webhook deliveries 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