Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

API quickstart

Generate a key, create a session, and stream an agent reply with curl.

Open in ChatGPTOpen in Claude

This guide gets you from zero to a streamed agent response over HTTP. Every example uses real endpoints in packages/web/app/api/v1/**.

1. Generate an API key

Open /<orgSlug>/settings and find API keys. Click Create key, give it a label, and submit. The full key is shown exactly once — copy it now. The format is alm_<env>_<random> (for example, alm_live_…).

Keep the key server-side. Never put it in browser bundles, mobile apps, public repos, or user-visible config.

2. Sanity check: list agents

Confirm the key works.

bash
Sign in to fill in your org and key
curl https://alumia.com/api/v1/agents \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-Alumia-Org: your-org"

You should get a JSON envelope with the org's agents, including Ala. Note the id of the agent you want to chat with.

3. Create a chat session

Sessions hold conversation history and bind to an agent.

bash
Sign in to fill in your org and key
curl -X POST https://alumia.com/api/v1/sessions \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-Alumia-Org: your-org" \
-H "Content-Type: application/json" \
-d '{
  "label": "API quickstart",
  "agentId": "<agent-id-from-step-2>"
}'

The response includes the new session's id. Save it — every subsequent message is tied to it.

4. Stream an agent reply

The streaming chat endpoint is POST /api/v1/chat. It accepts { messages, sessionId, agentId, model, projectId } and returns an AI SDK v6 UI message stream over text/event-stream.

bash
Sign in to fill in your org and key
curl -N -X POST https://alumia.com/api/v1/chat \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-Alumia-Org: your-org" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
  "sessionId": "<session-id-from-step-3>",
  "agentId": "<agent-id-from-step-2>",
  "messages": [
    { "role": "user", "content": "Summarise the periodic table in 3 sentences." }
  ]
}'

The -N flag disables curl's output buffering so you can see the stream as it arrives. Each event is a UI message stream chunk: text deltas, tool call starts/ends, finish reasons, and usage. Parse them with the AI SDK v6 client (readUIMessageStream) or your own SSE reader.

5. Inspect the stored history

After the stream ends, the assistant turn is persisted. Read it back:

bash
Sign in to fill in your org and key
curl https://alumia.com/api/v1/sessions/{{sessionId}}/messages \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-Alumia-Org: your-org"

Pagination uses ?cursor=<message-id>&pageSize=200 (max 500). For a count without bodies, pass ?countOnly=true.

6. Continue the conversation

Reuse the same sessionId on subsequent POST /api/v1/chat calls. The server pulls history from storage; you only need to send the new user message in messages.

Errors you'll see

  • 401 UNAUTHORIZED — bad or missing key.
  • 402 PAYMENT_REQUIRED — the org balance is empty and the model is paid. Add funds: Top up your balance.
  • 429 TOO_MANY_REQUESTS — the chat rate limit is 60 requests/minute per user/IP. The response includes Retry-After.

See Troubleshooting for the full list.