Skip to content

Authentication

Create the token while signed in on the company dashboard, at API keys. Give it a name and at least one of read, write, and analytics. The secret is shown once and starts with es_. The list keeps a short prefix. Revoking stops that token.

Header

Send Authorization: Bearer <token> on every call except the OpenAPI document. The client account that owns the key must be active. A missing token, an unknown token, a revoked token, or an inactive client returns 401 unauthorized. A token without the scope for that route returns 403 insufficient_scope.

Rate limit

Each key allows 60 requests per UTC minute. Over that, the response is 429 rate_limited and Retry-After is the seconds left in the minute. Creating links has a second cap: 60 new links per rolling hour for the client, including links that were later disabled or deleted. That response is also 429 rate_limited, with Retry-After: 3600.

Errors

Failures are JSON: { "error": { "code", "message" } }. A non-429 error can include details.

  • unauthorized — 401
  • insufficient_scope — 403
  • not_found — 404
  • conflict — 409
  • validation_error — 422
  • rate_limited — 429, with Retry-After
  • internal_error — 500

Wait for Retry-After on a 429. Change the request before retrying another 4xx. Retry a 5xx with backoff.

Pages

List uses page (default 1) and page_size (default 50, maximum 100). The body is { "items", "page", "page_size", "total" }. A single link is the object itself. Newest links come first unless order=asc.

Idempotency

POST /links and POST /links/bulk accept an optional Idempotency-Key of at most 255 characters. The same key, token, and body replays the stored status and body. A different body, or a key that is still in progress, returns 409 conflict.