tracearr-api

# Tracearr API Tracearr monitors Plex, Jellyfin and Emby from one instance and exposes a read-only public REST API (plus one stream-termination endpoint). **Source of truth — the OpenAPI spec, published as a GitHub release asset.** Every stable Tracearr release attaches `openapi-v1.json` and `openapi-v2.json`, and `releases/latest/download` always tracks the newest stable release. These are real OpenAPI 3.0 JSON — the exact files docs.tracearr.com renders — and are fetchable with no auth and queryable with `jq`: - v2: `https://github.com/connorgallopo/tracearr/releases/latest/download/openapi-v2.json` - v1 (legacy — see the media-identifier note): `https://github.com/connorgallopo/tracearr/releases/latest/download/openapi-v1.json` ``` V2=https://github.com/connorgallopo/tracearr/releases/latest/download/openapi-v2.json curl -sL $V2 | jq '.paths | keys' # list endpoints curl -sL $V2 | jq '.paths."/api/v2/public/history".get' # one endpoint (params, responses) curl -sL $V2 | jq '.components.schemas.HistoryRecord' # a response schema curl -sL $V2 | jq '.components.securitySchemes' # auth ``` Other sources, in order of usefulness: **docs.tracearr.com/api** is the human-browsable render of these same two assets (browser only — it is not anonymously fetchable). A running instance serves its own build's spec at **`GET /api/v2/public/docs`** (bearer token required) — use it to match the exact version you run. The route source (`apps/server/src/routes/publicV2/*.ts` + `publicV2.openapi.ts` in `connorgallopo/Tracearr`) is the last resort, for implementation detail the spec doesn't capture. ## Auth, paths, limits - `Authorization: Bearer trr_pub_<token>` — the key is generated in Tracearr's **Settings > General** - Two live versions: `/api/v1/public/*` and `/api/v2/public/*`. An instance may sit under a base path (`/tracearr/api/v2/...`), so never hardcode the root - Rate limited per key on a 1-minute window — handle 429 and back off - Fastify backend, so failures come back as real HTTP status codes ## Use v2 for anything that joins to a MediaItem **v1's `SessionHistory` carries no media identifier** — only `mediaTitle`/`showTitle` strings plus `serverId`/`serverName`, unjoinable to a library item without title matching. v2's `HistoryRecord` carries `rating_key`, `parent_rating_key`, `grandparent_rating_key`, `media_id`, `show_media_id`, `imdb_id`, `tmdb_id`, `tvdb_id`, `library_id`, `server_id` and `server_type`, alongside `state`, `percent_complete`, `progress_ms`/`duration_ms`, `is_transcode`, `video_decision` and `audio_decision`. For this repo: `rating_key` is the join key for `MediaItem.ratingKey` (the map `syncWatchHistory` already builds), and the provider ids line up with `computeSeriesKey`'s `tvdb:` → `tmdb:` precedence as a fallback when a rating key has drifted. - **Pagination differs by version.** v1 takes `page`/`pageSize`; v2 is keyset — `cursor` encodes `{ startedAt, id }`, `pageSize` defaults to 25 and caps at 100 (schemas `HistoryResponse` + `CursorMeta`) - **v2 `/history` filters server-side:** `user_id`, `server_id`, `media_id`, `rating_key`, `imdb_id`, `tmdb_id`, `tvdb_id`, `media_type` (`movie|episode|track|live|photo|unknown`), `watched`, `since`, `until` - `since`/`until` are what make incremental sync viable — page from a stored watermark instead of re-pulling the whole history - **Other v2 routes:** `/media/{ref}`, `/media/{ref}/children`, `/media/{ref}/stats`, `/media/{ref}/watchers`, `/media/{ref}/history`, `/users/{id}`, `/users/{id}/history`, `/users/{id}/stats`, `/recently-added`, `/libraries`, `/streams`