REST API Reference

The Open Astra gateway exposes a REST API for managing agents, sessions, memory, workspaces, and more. All endpoints require a JWT bearer token except where noted.

Correlation IDs

Every response includes an X-Request-ID header. The gateway reads an incoming X-Request-ID if present, or generates a UUID if none is provided. The same ID is attached to every structured log entry for that request, making it easy to trace a request end-to-end across logs. Attach this header when calling the API from your own code to correlate client-side and server-side logs.

Authentication

Most endpoints require a JWT bearer token obtained via /auth/login. Admin and diagnostic endpoints use an API key sent via the x-api-key header.

# Get a JWT token
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

# Use the token for all authenticated requests
curl -H "Authorization: Bearer ${JWT_TOKEN}" http://localhost:3000/agents

Auth

Chat

All chat endpoints return 404 if the agentId does not exist, and 403 if the agent exists but is not available to the requesting workspace (see Agent Grants).

Agents

Sessions

Memory

Workspaces

Webhooks

Heartbeat

Heartbeat configs let agents monitor external sources (RSS, HTTP) on a schedule.

Skills

Cost Dashboard

Autonomous Execution

Execute agent tasks programmatically. Requires API key authentication via x-api-key header.

Onboarding

Admin

Admin endpoints require API key authentication via x-api-key header.

Diagnostics

Diagnostics endpoints require API key authentication via x-api-key header.

System

WebSocket API

Connect to ws://localhost:3000/ws with a JWT bearer token. Rate limit: 30 requests per 60 seconds per user. Max 1 active agent request per socket.

const ws = new WebSocket("ws://localhost:3000/ws", {
  headers: { Authorization: "Bearer " + token }
})

// Send a message
ws.send(JSON.stringify({
  type: "message",
  agentId: "research-agent",
  message: "Summarize the latest findings",
  surface: "api"
}))

// Receive streaming chunks
ws.onmessage = (event) => {
  const frame = JSON.parse(event.data)
  // frame.type: session_resolved | stream_chunk | tool_call
  //             | tool_result | stream_done | error | pong
}

Inbound frames

Outbound frames