Aleph

API reference

Aleph publishes a live OpenAPI contract and an interactive Scalar reference.

Open the generated reference

  • /scalar opens the interactive API explorer.
  • /doc returns the OpenAPI document as JSON.

Use these paths on your configured Aleph API URL.

The generated contract is the authority for current paths, request bodies, response schemas, and status codes. It includes agents, versions and their files, conversations, schedules, channels, catalog, Vault, variables, usage, and billing surfaces.

POST /agents accepts an optional caller-selected UUID agentId for Git-owned identities and returns 409 if it is already used. Version upload returns 201 for newly stored content and 200 with the latest version when the runtime bundle is unchanged.

Authenticate

Browser clients use Better Auth session cookies through /api/auth/*. Non-interactive automation can use user or organization API keys as Bearer credentials.

The Aleph CLI uses Better Auth device authorization with the fixed aleph-cli client ID. Credential precedence is:

  1. --api-key;
  2. ALEPH_API_KEY;
  3. the stored device-authorized Bearer session.

Build against the contract

Generate client types from /doc rather than copying schemas by hand. Path parameters may appear in Hono :param form in the contract, so clients must serialize them correctly.

Aleph is pre-production and the API may make direct breaking changes. Regenerate clients and review the contract whenever the backend version changes; no compatibility shim is implied.