API overview

Base URL, authentication, response envelope, and error model for the Alumia v1 HTTP API.

The Alumia HTTP API exposes the same resources the dashboard uses: agents, projects, sessions, files, connections, billing, and webhooks. All endpoints are versioned under /api/v1 and scoped to the organization that owns the API key.

Base URL

https://alumia.com/api/v1

Authentication

Every request must carry a Bearer token issued from your organization's developer settings.

Authorization: Bearer alm_<env>_<32-hex-chars>

<env> is live for production keys and test for keys minted in non-production environments.
The 24-byte random suffix is shown once at creation; only its SHA-256 hash and 12-character prefix are stored.
The org and user that own the key are derived from the key itself — you do not pass an org ID header.

See Authentication for key lifecycle and scopes.

Response envelope

Every response uses one of two shapes.

Success (2xx):

{ "success": true, "data": <payload> }

Error (4xx, 5xx):

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found"
  }
}

The data payload is either a single resource object or a list wrapper such as { "items": [...] }. Pagination wrappers (page, limit, nextCursor, hasMore) appear alongside items on listing endpoints that paginate.

Error codes

Code	HTTP	Meaning
`BAD_REQUEST`	400	Malformed input (missing field, wrong type, empty body).
`UNAUTHORIZED`	401	Missing or invalid API key.
`PAYMENT_REQUIRED`	402	Org balance is insufficient to run a paid model.
`FORBIDDEN`	403	Authenticated, but not allowed (workspace scope, role, or step-up required).
`NOT_FOUND`	404	Resource missing or not visible to the caller.
`CONFLICT`	409	Conflicting state (duplicate slug, double-revoke, etc.).
`VALIDATION_ERROR`	422	Input shape is valid but a value is out of range.
`TOO_MANY_REQUESTS`	429	Rate limit exceeded.
`SERVICE_UNAVAILABLE`	503	Upstream provider or background worker temporarily unreachable.
`INTERNAL_ERROR`	500	Unhandled server error; the message is generic in production.

A full list with route-level context lives in Errors.

Rate limiting

Sensitive routes (API key minting, BYOK key creation, auth flows) are protected by a token-bucket limiter keyed on userId + client IP. Exceeding the bucket returns BAD_REQUEST with a Too many requests message. Limits are enforced per process; in development you can disable them by setting DISABLE_RATE_LIMIT=1.

Conventions

All timestamps are ISO 8601 UTC strings.
Monetary amounts are integer cents on the wire (amountCents, balanceCents). Token usage is reported in microcents (*Microcents).
IDs are UUID v4 unless explicitly documented as slugs.
PATCH requests accept partial bodies and only mutate fields that appear in the payload.
Soft-deleted resources return 404 once deletedAt is set; they do not appear in list endpoints.
Multi-tenant scope is enforced server-side: a key issued to org A cannot read or mutate resources in org B even with a valid resource ID.

Idempotency

The current API has no client-supplied idempotency keys. Safe operations (GET, DELETE on already-deleted resources) return the expected terminal response without side effects. For deposits and Stripe checkout sessions, retry only after the prior request has resolved — both direct and Stripe-mediated paths are non-idempotent.

Quickstart

bash

curl https://alumia.com/api/v1/agents \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Search docs