API overview

Reference

The interactive OpenAPI reference is generated from the API itself and is the source of truth:

This page gives the conventions; Authentication covers the auth endpoints.

Basics


Base URL	`https://api.windle.fun`
Versioning	Path prefix: `/v1/…`
Format	JSON requests and responses (`content-type: application/json`)
Auth	Session cookie `wl_session`, set by SIWS sign-in
Transport	HTTPS only

Errors

Every non-2xx response has the same shape:

{
  "error": {
    "code": "not_found",
    "message": "GET /v1/unknown not found"
  }
}

code is a stable machine-readable string; message is for humans and may change. Branch on code, never on message.

Browsers and CORS

The API accepts credentialed cross-origin requests only from windle’s own origins (*.windle.fun). A page on another site can’t use a visitor’s windle session. Calls from servers and scripts (no browser) are not affected by CORS.

Rate limits

Requests are rate limited per client. Limits are not published yet and will change. A limited request gets HTTP 429 with the standard error body; back off and retry later.

Health

Endpoint	Meaning
`GET /health`	The API process is up (liveness).
`GET /ready`	The API can reach its database and cache (readiness).

Both are meant for monitoring, not for application logic.