Route Reference

Complete endpoint reference for the Open Astra gateway. Every HTTP endpoint is listed below, organized by route group, with its method, path, and description.

Auth conventions

1. Auth

Public endpoints for user registration, login, token rotation, and logout. No authentication required.

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "s3cret!"}'

# Response
{
  "user": { "id": "usr_abc", "email": "user@example.com" },
  "accessToken": "eyJhbG...",
  "refreshToken": "eyJhbG..."
}

2. Agent Chat

Core conversation endpoints. Middleware chain: JWT + tokenBudget + workspace + rateLimiter + userRateLimit + timeout.

Request body

Both /agent/chat and /agent/chat/stream accept the same body shape.

{
  "message": "Summarize my calendar for today",   // 1-10 000 chars, required
  "agentId": "chad",                               // default "chad"
  "surface": "chat",                               // "chat" | "prop" | "group"
  "surfaceId": "main",                             // default "main"
  "webhookUrl": "https://example.com/hook"          // optional, non-streaming only
}

Response (non-streaming)

{
  "content": "You have 3 meetings today...",
  "sessionId": "ses_abc123",
  "toolsUsed": ["google_calendar"],
  "usage": {
    "promptTokens": 1240,
    "completionTokens": 310,
    "totalTokens": 1550
  }
}

SSE events (streaming)

event: session_resolved
data: { "sessionId": "ses_abc", "isNew": true }

event: content
data: { "content": "Here's what I found..." }

event: tool_call
data: { "index": 0, "name": "web_search", "toolCallId": "tc_1" }

event: tool_call_complete
data: { "index": 0, "name": "web_search", "arguments": "{...}" }

event: tool_result
data: { "name": "web_search", "durationMs": 320 }

event: done
data: { "content": "...", "sessionId": "ses_abc", "usage": {...}, "toolsUsed": [...] }

event: error
data: { "message": "Rate limit exceeded", "code": "RATE_LIMIT" }

3. Memory

User long-term memory management. Middleware chain: JWT + tokenBudget + workspace + rateLimiter.

4. Agents

CRUD for agent configurations with versioning and rollback. Middleware: JWT + workspaceResolver. List and detail endpoints return ETag headers (30s cache).

5. Workspaces

Workspace management, member invitations, usage stats, cross-workspace grants, and provider restrictions. Middleware: JWT only.

6. Sessions

Session listing, detail retrieval, full-text search, and agent handoff. Middleware: JWT only.

7. Webhooks

Register webhook URLs to receive events. Middleware: JWT only.

8. Costs

Workspace cost tracking and breakdowns. Middleware: JWT + workspace.

9. Heartbeat

Scheduled monitoring configs for RSS feeds and HTTP endpoints. Middleware: JWT + workspace.

10. Skills

Skill registry and cache management. List and detail endpoints are public. Cache management requires JWT.

11. Traces

Agent execution traces for debugging and observability. Middleware: JWT + workspace.

12. Jobs

Background job queue. Middleware: JWT + workspace.

13. Memory Profiles

Reusable memory profile templates that can be assigned to agents. Middleware: JWT + workspace.

14. Onboarding

First-run setup endpoint. Middleware: JWT only.

15. Autonomous

Run agent tasks programmatically from backend services. Auth: internal API key via X-Api-Key. Rate limited to 60 requests per minute.

curl -X POST http://localhost:8080/autonomous/run \
  -H "X-Api-Key: ${INTERNAL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "usr_abc",
    "agentId": "chad",
    "taskMessage": "Summarize overnight alerts"
  }'

16. Admin

Operational visibility into the running gateway. Auth: internal API key via X-Api-Key.

17. Diagnostics

System diagnostics and circuit breaker inspection. Auth: internal API key via X-Api-Key.

Health & Metrics

Public system endpoints. No authentication required.

// GET /health
{
  "status": "ok",
  "checks": { "typesense": true, "postgres": true },
  "wsConnections": 42,
  "timestamp": "2026-02-27T12:00:00.000Z"
}

// GET /readiness — 200 or 503
{ "ready": true }

// GET /metrics
{
  "uptime": 86400,
  "wsConnections": 42,
  "tools": 106,
  "skills": 48,
  "sessions": { "active": 15, "total": 1240 },
  "messages": 28400,
  "billing": { "month": "2026-02", "totalCost": 12.40 },
  "cache": { "hits": 9820, "misses": 1430 }
}

See also

• Gateway Overview -- architecture, middleware stack, and WebSocket transport
• Middleware Reference -- auth, CSRF, rate limiting, RBAC, security headers
• WebSocket Reference -- frame types, back-pressure, multi-device
• Event System -- all emitted events and webhook delivery
• REST API Reference -- authentication flow, WebSocket API, and correlation IDs