API
Authenticate with the Easel REST API, and the conventions every endpoint follows.
The Easel REST API manages projects, environment variables, deployments, domains, webhooks, usage, and tokens. The dashboard, the CLI, and the SDK are all clients of it.
Every endpoint, with its request, response, and permission, is in the API reference. This page covers what they share.
Base URL
Requests and responses are JSON, except deployment archives, which are gzip tarballs. Timestamps are ISO 8601 in UTC.
Authentication
Send a token in the Authorization header:
Tokens start with easel_. Create a workspace token in your workspace's
Settings → Access Tokens, or use the one easel login saves. A token acts
on one workspace, as the user who created it. To limit a token to some
projects, actions, and a lifetime, mint a scoped one; see
Tokens.
A missing, invalid, or expired token, or one without the permission an
endpoint needs, gets 401.
Errors
Every error response has the same body:
erroris a message you can show to a person.codeis a stable identifier for your code to check.records, when present, lists DNS records that fix the problem, such as the TXT record that proves you own a domain.
See Errors for every code.
Idempotency
Every POST that creates something accepts an Idempotency-Key header, such
as a UUID you generate. If you retry with the same key and the same request,
Easel returns the first response, with Idempotent-Replayed: true, instead of
creating a second deployment, project, or token. That makes it safe to retry
after a timeout or a network error.
- The same key with a different request gets
422 idempotency_key_reused. - A retry while the first request is still running gets
409 idempotency_in_progress. - Responses with a
5xxstatus aren't stored, so a retry runs again.
Keys belong to the token that sent them and expire; see Limits. The SDK sends a key with every creating request.
Pagination
List endpoints that page return pagination: { nextCursor, hasMore }. Pass
nextCursor as ?cursor= to get the next page, and set the page size with
?limit=.
Rate limits
Each token has its own rate limit. Over it, requests get 429 rate_limited,
and error says when to try again. See
Limits.