Skip to content
Athena Docs

Quickstart

This guide walks through the minimal path from nothing to a running agent execution. You will need:

  • A workspace ID (workspace:...)
  • A workspace API key (wak_...) — ask your workspace admin
  • A published agent ID (agent:...) with api_enabled: true
  • curl (or any HTTP client)

Step 1 — Exchange Your Firebase JWT for an Ephemeral Key

If your app uses Firebase authentication, exchange the Firebase ID token for an Athena ephemeral key (eak_). This key is safe to store on the device for the session.

Terminal window
curl -X POST https://athena-dev-api.leanscale.com/auth/external/workspace:YOUR_ID \
  -H 'Content-Type: application/json' \
  -d '{"provider":"firebase","token":"YOUR_FIREBASE_ID_TOKEN"}'

Response:

{
  "data": {
    "key": "eak_a1b2c3...",
    "expires_at": "2026-05-13T12:00:00Z",
    "customer": {
      "id": "external_customer:abc123",
      "active_credits": 100.0,
      "frozen_credits": 0.0,
      "inactive_credits": 0.0
    }
  }
}

Store key and expires_at. The key is valid for 24 hours.

Step 2 — Execute an Agent (Streaming)

Pass the ephemeral key in X-API-Key. Streaming uses Server-Sent Events (SSE).

Terminal window
curl -X POST https://athena-dev-api.leanscale.com/agents/agent:YOUR_AGENT_ID/execute/stream \
  -H 'X-API-Key: eak_a1b2c3...' \
  -H 'Content-Type: application/json' \
  -H 'X-Workspace-Id: workspace:YOUR_ID' \
  -d '{
    "message": "Summarise my last 7 days of activity",
    "external_user_id": "firebase_uid_xyz"
  }'

The response is a stream of SSE events:

data: {"type":"node_start","node_id":"trigger_1"}
data: {"type":"text","text":"Here is a summary of"}
data: {"type":"text","text":" your recent activity..."}
data: {"type":"llm_final","usage":{"total_tokens":312}}
data: {"type":"final","status":"Completed","execution_id":"execution:xyz"}

Step 3 — Execute Synchronously (Non-Streaming)

For short workflows or server-to-server use:

Terminal window
curl -X POST https://athena-dev-api.leanscale.com/agents/agent:YOUR_AGENT_ID/execute \
  -H 'X-API-Key: eak_a1b2c3...' \
  -H 'Content-Type: application/json' \
  -H 'X-Workspace-Id: workspace:YOUR_ID' \
  -d '{"message":"Hello"}'

Response is a single JSON object once the workflow completes.

Step 4 — Check Credit Balance

Terminal window
curl https://athena-dev-api.leanscale.com/my/credits \
  -H 'X-API-Key: eak_a1b2c3...' \
  -H 'X-Workspace-Id: workspace:YOUR_ID'
{
  "data": {
    "active_credits": 87.4,
    "frozen_credits": 25.0,
    "inactive_credits": 0.0,
    "next_refresh_at": null,
    "recommended_topup_pack_id": null,
    "recommended_topup_pack_credits": null,
    "recommended_topup_pack_currency": null,
    "frozen_card_dismissed_at": null
  }
}

active_credits is the spendable balance. frozen_credits > 0 means the customer has top-ups locked behind a lapsed subscription — render the “Resubscribe to unlock” CTA. Add ?generation_cost=N to the request to receive a recommended top-up pack big enough to cover that cost.

Common Error Codes

HTTPCodeFix
401unauthorizedJWT expired or invalid. Re-exchange for a new eak_.
402payment_requiredCredit balance depleted. Top up consumable credits.
403forbiddenAgent api_enabled is off, or key lacks the required scope.
429rate_limit_requests_exceededSlow down. Check Retry-After header.

Next Steps