API Reference Overview

Open Astra exposes a REST API, a CLI, and a YAML schema for all runtime operations. This section is the complete reference for all three, plus the event system and webhooks for integrating with external services.

Authentication

All API requests require a JWT bearer token. Issue tokens using the POST /auth/token endpoint with your workspace credentials:

bash

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

Pass the returned token as a header on subsequent requests:

bash

curl http://localhost:3000/agents \
  -H 'Authorization: Bearer <your-token>'

For production JWT hardening, see Auth Hardening.

Reference sections

Section	Description
API Reference	Full REST endpoint catalog — agents, memory, tools, workspaces, channels
CLI Reference	All `astra` CLI commands, flags, and examples
astra.yml Schema	Complete annotated schema for the configuration file
Event System	Internal events emitted during agent turns, memory writes, and tool calls
Webhooks	Outbound webhooks for external integrations triggered by events
Auth Hardening	JWT configuration, token rotation, and rate limiting

Base URL

All REST endpoints are served from the gateway base URL. The default local URL is http://localhost:3000. Set GATEWAY_BASE_URL to configure this for production deployments.

API versioning

The current API is unversioned (no /v1 prefix). Breaking changes will introduce versioned endpoints with a migration period. Check the changelog event stream for deprecation notices.