# For AI

Everything here exists as plain text, so an AI assistant can read it without a
browser.

| File                               | What it has                                              |
| ---------------------------------- | -------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)           | Index of every page, one line each                       |
| [`/llms-full.txt`](/llms-full.txt) | All guides and the reference in one file                 |
| `/{page}.md`                       | Any page as Markdown (also with `Accept: text/markdown`) |
| [`/openapi.json`](/openapi.json)   | OpenAPI 3 of the public API                              |

**Download for your AI** gives you one `.md` with all of it plus the rules
below. Signed in, it also includes your API base URL, your workspace and a real
video id from your account — never a secret.

## Rules for the assistant

1. The secret key (`xp_sk_…`) lives on the server. Never put it in a web page,
   a mobile app or a repository.
2. Call `GET /v1/videos/{id}/playback` when the player opens, never earlier.
3. Use `hls_url` as is. Never build, cache or rewrite video URLs.
4. To play, use `hls_url`. `original_url` is the untouched file: use it only if
   your player supports its format.
5. Never download or re-host videos yourself. To get the file, call
   `GET /v1/videos/{id}/download`. To bring in a video from a URL, call
   `POST /v1/videos/imports`.
6. On a fatal player error, call `/playback` again (at most once per minute) and
   resume at the same second.
7. If `/playback` returns `status: "error"`, show its `message`. Offer Reload
   only for retryable codes: `VIDEO_NOT_READY`, `LIVE_NOT_ACTIVE`,
   `RATE_LIMITED`, 5xx. The video host itself (not `/playback`) can also
   answer `MAXIMUM_UNAVAILABLE` (503, plain text, `X-Xona-Error` header) when
   serving the manifest or a segment — it is retryable too, same reload rule.
8. All JSON is snake_case: `hls_url`, `expires_at`, `per_page`.
9. Every response is `{ "status": "ok", "data": … }` or
   `{ "status": "error", "code": …, "message": … }`. Lists add
   `meta: { total, page, per_page, last_page }`.
10. `{id}` accepts the UUID `id` or the `short_id`.
11. Pass `viewer_id` with your own user id so a leaked link can be traced.
12. Verify webhooks with `X-Xona-Signature` over the raw body, and reject
    timestamps older than five minutes.

## Suggested prompt

> Read the attached XonaPlay docs. Integrate video playback in my app using
> `/v1/videos/{id}/playback` from my backend with the secret key in the
> `XONAPLAY_SECRET_KEY` environment variable. Follow the reload rule and the
> rules for the assistant exactly. Do not add an SDK.