API overview

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 /<orgSlug>/developers → API Keys.

Authorization: Bearer alm_<env>_<48-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

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

Request body limits

Mutating routes enforce size caps before JSON parsing: 128 KB default for JSON bodies, 256 KB for webhook payloads (some routes set higher caps). Oversized bodies return 413 Payload Too Large. In production, POST requests without Content-Length return 411 Length Required.

User-editable metadata JSON is capped at 32 KB serialized (project metadata allows depth 12; other entities default depth 8). Project settings is capped at 8 KB.

Browser-only mutations

Some routes reject API-key auth even for org owners: workspace create/delete, project share links, org membership management, account-security changes, webhook and MCP server management, domain administration, skill and guardrail edits, org settings, memory deletes, session participant sharing, and agent patches that touch privileged tool/peer/connector restrictions. Use the dashboard with step-up for those operations.

Rate limiting

Sensitive routes (API key minting, legacy provider-key maintenance, auth flows, CLI device login) 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.
• Billing credit amounts are returned as credits plus integer creditMicrounits. Stripe top-up and invoice amounts still use integer cents (amountCents) where money changes hands.
• 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 universal client-supplied idempotency key. Safe operations (GET, DELETE on already-deleted resources) return the expected terminal response without side effects. Billing top-ups accept per-operation idempotency keys for PaymentIntent creation; Stripe subscription Checkout retries should wait until the prior request resolves.

Reference pages

Public utilities

Admin-only /api/v1/admin/* routes are operator surfaces and are documented internally, not in this public reference.

Quickstart

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