# Zaparoo Online User API Reference

Public contract: <https://developers.zaparoo.com/openapi-user.yaml>

Official origin: `https://user.api.zaparoo.com`

## Command mapping

| CLI | GET path | Scope |
| --- | --- | --- |
| `online status` | `/v1` | Public |
| `online profile` | `/v1/me` | `read:profile` |
| `online sessions list` | `/v1/play-sessions` | `read:play_history` |
| `online sessions active` | `/v1/play-sessions/active` | `read:play_history` |
| `online sessions summary` | `/v1/play-sessions/summary` | `read:play_history` |
| `online cards list` | `/v1/cards` | `read:cards` |
| `online decks list` | `/v1/decks` | `read:decks` |
| `online decks get` | `/v1/decks/{short_id}` | `read:decks` |
| `online decks cards` | `/v1/decks/{short_id}/cards` | `read:decks` |
| `online devices list` | `/v1/devices` | `read:devices` |
| `online backups list` | `/v1/devices/{device_id}/backups` | `read:backups` |
| `online backups files` | `/v1/devices/{device_id}/backups/{backup_id}/files` | `read:backups` |
| `online backups download` | `/v1/devices/{device_id}/backups/{backup_id}/objects/{sha256}` | `read:backups` |

`online request <v1-path>` permits GET requests only on official origin. Prefer first-class commands.

## Pagination

List endpoints accept `--limit` from 1 through 500 and opaque `--cursor`. Continue only with returned `next_cursor`; absence means final page. Cursors are valid only with filters that created them.

`--all-pages` has page and repeated-cursor safeguards. Do not use reported `total` as pagination control.

## Rate limits and polling

- Key: 60 requests/minute.
- Client IP abuse ceiling: 1,000 requests/minute.
- Invalid authentication: 100 attempts/minute/IP.
- Backup downloads: 1 GiB/key/UTC day.
- Honor `Retry-After` on request-limit `429`.
- Active sessions: poll no faster than `X-Poll-Interval` or 10 seconds, whichever is greater; reuse ETag.
- Backup object: use file SHA-256 as `If-None-Match`; matching `304` uses no egress allowance.

## Filters

- Sessions list: device, profile, system, since, until.
- Session summary: group (`media`, `system`, `day`), since, until.
- Cards and decks: case-insensitive name filter.
- Backup files: category.

Treat cursor values, identifiers, and returned private data as opaque unless public contract defines semantics.