# Fanio API

> A public, read-only JSON API over the Fanio catalogue, plus licence verification and signed downloads. OpenAPI 3.1: https://fanio.net/v1/openapi.json

No key is needed to read. Requests are rate limited per IP. Every scene id has the form `fanio:<pack>/<scene>`.

## Read

- `GET /v1/packs?page=1`: 24 packs per page, each with up to six preview scenes, full counts and prices
- `GET /v1/packs/{pack}?page=1`: one pack with 24 scenes per page and full counts
- `GET /v1/scenes/{pack}/{scene}`: one scene, with credit line, licence and links
- `GET /v1/scenes/{pack}/{scene}.svg`: the SVG of a free scene (402 for paid scenes)
- `GET /v1/scenes/{pack}/{scene}.png`: a 480 px preview of any scene
- `GET /v1/scenes/{pack}/{scene}/provenance`: how the scene was made
- `GET /v1/search?q=reading`: search in English or Arabic. Use `limit` (1 to 50) and `offset` for pages. Repeat `pack`, `character`, `style`, `activity`, `setting` or `season` to select several values within one facet. Add `free=true` or `free=false`, `sort=title`, and `lang=ar` if needed. The response includes `total` and facet counts. `smart=true` optionally re-ranks eligible first-page results when enabled on the server, with local fallback.
- `GET /v1/licences` and `/v1/licences/{tier}`

## Paid scenes

1. `POST /v1/licences/verify` with `{"key": "fanio_lk_..."}` returns the licensed pack and tier.
2. `POST /v1/licences/download` with `{"key": "...", "scene": "fanio:<pack>/<scene>"}` returns a download URL valid for five minutes.

Keep licence keys secret; they are bearer credentials. Revealing the key again on the order page rotates it.