Docs

Authentication

How to authenticate with the Encelade API using API tokens.

Public v1 API requests require an API token passed via x-api-key or Authorization: Bearer YOUR_API_TOKEN.

Creating a token

Go to your workspace settings
Navigate to the API tokens section
Click Create Token and select the scopes your integration needs

Copy the token immediately

Your token is only displayed once. Store it securely — you cannot retrieve it later.

Using the token

Include the token in every request:

curl -X GET https://your-instance.com/api/public/v1/projects \
  -H "x-api-key: YOUR_API_TOKEN"

Scopes

Tokens are scoped to limit access. These scopes are used by the public REST API and MCP:

ScopeDescription
project:readList and view projects
project:writeUpdate projects
project:deleteDelete projects
project:publishPublish and unpublish projects (REST only)
project:generateStart a generation run
project:ai-chatEdit a project with AI
project:exportStart and poll PDF/PPTX exports (REST only)
session:readRead generation runs
session:writeCancel generation runs
webhook:readList webhooks
webhook:writeCreate and delete webhooks
theme:readList custom themes (MCP only)
theme:writeCreate, update and delete custom themes (MCP only)

MCP also accepts project:generate for get_generation_run and cancel_generation_run. REST polling and cancellation require session:read and session:write, respectively. The registered project:plan and media:search scopes have no public v1 endpoints.

Scopes do not override workspace roles, project permissions or plan limits. Webhook management requires a workspace admin's token.

A token created with no scopes selected gets every scope. OAuth tokens get every scope except project:delete unless the client requests it, and never get project:publish. Workspace roles, project permissions and plan limits still apply.

Rate limiting

REST requests are rate-limited per token, with a default of 120 requests per minute. Some operations use separate buckets:

OperationRequests per minute
Start a generation run10
Edit a project with AI10
Cancel a generation run20
Start a PDF or PPTX export (shared bucket)10
Poll an export job120

Request-rate failures return 429 Too Many Requests with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Wait for Retry-After before retrying.

Concurrency limits are separate: exports allow 2 in-flight jobs per workspace, and generation has user and workspace caps on active runs. These refusals also return 429 but may not include rate-limit headers; inspect the error body and wait for an active job or run to finish.

Errors

All error responses follow a consistent format:

{
  "error": "Description of what went wrong"
}

Common status codes:

CodeMeaning
401Invalid or missing API token
402Credits or a plan limit block the operation
403Required scope, role or permission is missing
429Request rate or concurrency limit exceeded
503Token verification or another required service is temporarily unavailable

Responses may also include code, details or limit information. Consult the endpoint reference for its full error contract. A token-verification 503 is retryable; it does not mean your token is invalid.

The API playground on the reference pages sends real requests. Use a test or development token when trying endpoints interactively.