API Overview

Base URL: https://athena-dev-api.leanscale.com

Swagger UI: https://athena-dev-api.leanscale.com/swagger-ui/

All endpoints return JSON. All requests that carry a body use Content-Type: application/json unless specified (multipart for file uploads).

---

Authentication

All non-public endpoints require:

X-API-Key: eak_...        (ephemeral key — client-side)
X-API-Key: wak_...        (workspace key — server-side)
X-Workspace-Id: workspace:YOUR_ID

Public CMS endpoints (/public/cms/...) require no authentication.

See Authentication for key types, scopes, and token exchange details.

---

Response Envelope

Success:

{
  "data": { ... }
}

Error:

{
  "error": {
    "code": "snake_case_string",
    "message": "Human-readable message",
    "details": { ... },
    "timestamp": "2026-05-12T10:30:00Z",
    "trace_id": "uuid-v4"
  }
}

code is stable across releases — build your error-handling logic on code, not message. details is omitted for most errors but present for validation and rate limit responses.

---

Endpoint Groups

Group	Path prefix	Description
Auth	/auth/, /ephemeral-keys/	Token exchange, key management
Agent Execution	/agents/{id}/execute*	Sync, stream, batch, preview
Execution Lifecycle	/executions/{id}/	Resume, cancel, tool results
Conversations	/my/conversations/	Multi-turn chat, message history
Attachments	/attachments/, /my/attachments/	File upload and management
Credits	/my/credits	Balance read
Media	/my/media	Generated media assets
Notifications	/my/notifications/, /my/preferences	Push notification management
CMS	/public/cms/	Storefront agents, pages, categories
Webhooks	/webhooks/{ws}/revenuecat	RevenueCat subscription events

---

Pagination

List endpoints support cursor-based pagination:

GET /my/conversations?cursor=opaque_cursor_string&limit=20

Response includes:

{
  "data": [ ... ],
  "next_cursor": "opaque_string_or_null"
}

When next_cursor is null, you have reached the end of the list. Default limit is 20. Maximum is 100.

---

Idempotency

For non-idempotent POST requests (executions, conversation operations), send an Idempotency-Key header:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

• Use a UUID v4 or any sufficiently random string
• Keys are valid for 24 hours
• Duplicate requests within the window return 409 Conflict
• If the original request failed with 5xx, generate a new key for the retry

---

Rate Limits

See Rate Limits for the full scope hierarchy and limit types. On 429 Too Many Requests:

• Retry-After: <seconds> is always present
• X-RateLimit-Limit: <N> is present for request and token limits

---

Versioning

The API has no version prefix in the URL. Breaking changes are announced with migration guides. Non-breaking additions (new fields, new endpoints) may be deployed at any time.

---

Special Response Types

Endpoint	Content-Type	Notes
/agents/{id}/execute/stream	text/event-stream	SSE — see Execute
/agents/{id}/execute/batch	text/event-stream	SSE batch progress events
/executions/{id}/resume	JSON or SSE	SSE if Accept: text/event-stream
/executions/{id}/tool-result	JSON or SSE	SSE if Accept: text/event-stream
/realtime/ws	WebSocket	Real-time workspace events

---

Related Docs

• REST Conventions — error handling, pagination, content types
• Error Reference — complete error code catalog
• Authentication — key types and scopes
• Execute — full execution endpoint reference