OpenAPI 3.1 Specification

Open Astra serves a live OpenAPI 3.1 specification from the gateway. The spec covers all 17 endpoint groups (30+ paths) and is generated from the actual route definitions — it is always in sync with the running server.

Spec endpoints

URL	Format	Auth required
`GET /openapi.json`	OpenAPI 3.1 JSON	Yes — JWT bearer
`GET /openapi.yaml`	OpenAPI 3.1 YAML	Yes — JWT bearer

Fetching the spec

bash

# JSON format
curl http://localhost:3000/openapi.json -H "Authorization: Bearer $TOKEN"

# YAML format
curl http://localhost:3000/openapi.yaml -H "Authorization: Bearer $TOKEN"

Endpoint coverage

text

# 17 endpoint groups, 30+ paths in the OpenAPI spec:
/agents            — CRUD, versioning, rollback, hot-reload
/sessions          — create, list, get sessions
/chat              — send messages, stream (SSE), WebSocket
/memory            — read, write, search across tiers
/memory-profiles   — create and assign memory profiles
/tools             — list registered tools
/jobs              — enqueue, poll, cancel background jobs
/traces            — query per-turn execution traces
/workspaces        — workspace management and member access
/skills            — list registered skills and metrics
/channels          — channel health, webhook endpoints
/auth              — token issue, refresh, rotate
/inference         — provider list, usage stats
/cron              — scheduler status, manual trigger
/webhooks          — outbound webhook registration
/admin             — system stats (workspace-owner only)
/health            — unauthenticated service health probe

Using with Swagger UI / Scalar

bash

# Import into Swagger UI (Docker)
docker run -p 8080:8080 \
  -e SWAGGER_JSON_URL=http://localhost:3000/openapi.json \
  swaggerapi/swagger-ui

# Or use Scalar (modern alternative)
npx @scalar/api-reference@latest --url http://localhost:3000/openapi.json

Importing into Postman

text

# Import into Postman
# 1. Open Postman → Import → Link
# 2. Enter: http://localhost:3000/openapi.json
# 3. Click Import — all 17 endpoint groups are added as a collection

Client code generation

Use the spec to generate a typed API client for any language. The OpenAPI Generator supports 50+ targets:

bash

# Generate a TypeScript fetch client
npx @openapitools/openapi-generator-cli generate \
  -i http://localhost:3000/openapi.json \
  -g typescript-fetch \
  -o ./src/astra-client

# Generate a Python client
openapi-generator generate \
  -i http://localhost:3000/openapi.json \
  -g python \
  -o ./astra-python-client

ℹThe spec is served with authentication required to prevent information disclosure to unauthenticated callers. Use a service account token for CI-based spec fetching and code generation.

See also: API Reference for endpoint documentation, Auth Hardening for token management.