Easy Ads API Reference
Easy Ads exposes an HTTP API used by the web app at lucentideai.com. It is a browser-facing backend: requests carry a signed session cookie, and state-changing calls additionally require a CSRF token. There is no public developer key or OAuth client registration.
Machine-readable contracts
The authoritative description of every endpoint is the OpenAPI 3.1 document for the surface you are calling. Each is published in YAML at a stable URL and listed in the API catalog:
- /api/openapi.yaml — the account BFF surface under
/api - /api/v1/openapi.yaml — the V1 surface under
/api/v1 - /.well-known/api-catalog — RFC 9727 catalog listing both surfaces
API surfaces
Two surfaces are served by the same process. They are separate contracts with separate specifications, so a client should pick one rather than mixing paths:
| Surface | Base path | Specification |
|---|---|---|
| Account BFF | /api | openapi.yaml |
| V1 | /api/v1 | openapi-v1.yaml |
Authentication
A browser obtains a session by calling the session bootstrap endpoint, which sets a signed, HttpOnly az8_pv_session cookie together with a browser-readable az8_pv_csrf cookie. The session may be anonymous to begin with and can later be bound to an account through the OAuth flow.
Read operations only require the session cookie. State-changing operations (POST) must additionally send the CSRF value back in the x-csrf-token header and be same-origin; without it the request is rejected with 403. Some operations, such as starting a generation, additionally require the session to be bound to an account and return 401 otherwise.
Errors
Error responses use a single JSON shape:
{ "error": { "code": "invalid_input", "message": "...", "retryable": false } }code is the stable, machine-readable value a client should branch on; message is user-facing text and may change. retryable is true for 503 and 429, and false for every other status. Rejections of state-changing browser requests add a requestId field and an x-request-id header so a failure can be traced in support requests.
Common status codes are 400 invalid input, 401 account required, 402 insufficient credits, 403 rejected session or CSRF token, 404 unknown or unowned resource, 409 revision conflict, 410 expired resource, 429 rate limited and 503 unavailable dependency or disabled feature.
Service status
/api/health/ready reports whether the service and its dependencies are ready. It returns 200 when ready and 503 when a dependency is unavailable. /api/health/live reports only that the process is running.
Response caching
Responses carrying account or generation data are sent with cache-control: no-store and must not be cached by intermediaries. Only the public example catalog is cacheable, and it revalidates on every request.