API overview

Base URL, authentication, errors, rate limits, CORS.

Base URL

https://cloud.flaresinc.com/v1/projects/{project}/…      Basket DB and Auth
https://cloud.flaresinc.com/run/{project}/{function}     Functions gateway
wss://cloud.flaresinc.com/realtime                       Realtime

Authentication

Authorization: Bearer basket_public_…     # or basket_secret_…
X-Basket-Key: basket_public_…             # alternative

The key names its project and the URL names one; they must agree. Using project A's key against project B is refused. Keys →

An end user's identity travels separately, in X-Basket-User-Token (Basket) or X-Flares-User-Token (Auth and Functions).

Errors

Every error is JSON with a stable shape:

{ "error": "invalid_request", "message": "A valid email address is required." }

Status	`error`	Means
401	`unauthorized`	Missing or invalid credentials, or a bad user token.
403	`forbidden`	Authenticated, but a rule or a key kind refused it.
404	`not_found`	No such project, collection, record, function — or a service that is not enabled.
409	`request_failed`	A precondition is unmet (e.g. no reset URL configured).
413	`payload_too_large`	Request body over the limit.
422	`invalid_request`	Validation failed. `message` names the problem.
429	`rate_limited`	Too many attempts. Back off and retry.
500	`server_error`	Flares' fault. Messages never carry a host, a credential or SQL.
503	`no_deployment`	A function exists but has no live deployment.

Rate limits

Auth endpoints are limited per project, address and identifier (the table). The Functions gateway allows 600 invocations per minute per project by default. A 429 is refused before dispatch and never billed.

CORS

Responses allow any origin with Authorization, Content-Type and the user-token headers. Credentials are never sent by the browser — the key is the authority — which is what makes a permissive origin correct here rather than lax.

Versioning

/v1 is the current version. Additive changes (new fields, new endpoints) happen within it; anything that would break a working client gets a new version.