Skip to content

API

Jump to bottom
URD0TH edited this page Jul 19, 2026 · 7 revisions

API Documentation

Yamtrack provides a REST API for programmatic access to media tracking. The API is authenticated exclusively with a static API key (per-user token) and returns JSON responses.

Base URL

https://your-yamtrack-instance.com/api/

Authentication

API Key (Static Token)

Every user has a static API token (the same token used for external integrations and webhooks, shown in the user profile under Account settings → Integrations). It is the only way to authenticate the REST API and the MCP server, so a single key works for both.

Send it as a Bearer token:

GET /api/auth/me/

Headers: Authorization: Bearer <api_token>

or via the X-API-Key header:

Headers: X-API-Key: <api_token>

The API key identifies the owning user, so all requests are scoped to that user's data.

Get Current User

GET /api/auth/me/

Headers: Authorization: Bearer <api_token>

Media

List Media

GET /api/media/<media_type>/

media_type can be: movie, tv, anime, manga, game, book, comic, boardgame, season.

Filters (query parameters)

Parameter Type Values / Default
status string (enum) All (default), Completed, In progress, Planning, Paused, Dropped. Invalid values fall back to All.
sort string (enum) score, title, progress, start_date, end_date. Any Item/model field is also accepted (no strict validation). No default (queryset default order).
search string Case-insensitive substring match on item__title.
page int Default 1.
per_page int Default 32.

Example:

GET /api/media/movie/?status=Completed&sort=score&search=spider&page=1&per_page=32

Create from External Source

POST /api/media/<media_type>/create/

Request body:

{
  "media_id": "12345",
  "source": "tmdb",
  "start_date": "2024-01-01T10:00:00Z",
  "end_date": "2024-01-02T12:30:00Z"
}

Optional start_date and end_date accept an ISO 8601 datetime to set a custom watch date instead of the current time.

Manual Create

POST /api/media/manual/create/

{
  "media_type": "movie",
  "title": "My Movie",
  "status": "Completed",
  "progress": 1
}

Get Details

GET /api/details/<source>/<media_type>/<media_id>/

Get Season Details

GET /api/details/<source>/tv/<media_id>/season/<season_number>/

Update Media

PATCH /api/media/<media_type>/<instance_id>/

{
  "score": 8,
  "status": "Completed",
  "start_date": "2024-01-01T10:00:00Z",
  "end_date": "2024-01-02T12:30:00Z"
}

Optional start_date and end_date accept an ISO 8601 datetime.

Delete Media

DELETE /api/media/<media_type>/<instance_id>/delete/

Sync Metadata

POST /api/sync/<source>/<media_type>/<media_id>/

Edit Progress

POST /api/media/<media_type>/<instance_id>/progress/

Request body (increase or decrease):

{
  "operation": "increase"
}
{
  "operation": "decrease"
}

Home

GET /api/home/

Returns in-progress and planning sections for the authenticated user.

Filters (query parameters)

Parameter Type Values / Default
sort string (enum) upcoming (default), recent, completion, episodes_left, title.

Example:

GET /api/home/?sort=recent

Episodes

Create Watched Episode

POST /api/episodes/

{
  "media_id": "999",
  "source": "tmdb",
  "season_number": 1,
  "episode_number": 1,
  "end_date": "2024-01-02T12:30:00Z"
}

Optional end_date accepts an ISO 8601 datetime for a custom watch date/time.

Re-sending the same media_id/season_number/episode_number updates the end_date of the most recent instance (returns 200 OK) instead of creating a new entry. Omit end_date to use the current time.

Search

GET /api/search/?q=<query>&media_type=<media_type>

Filters (query parameters)

Parameter Type Values / Default
q string Required. Search query.
media_type string (enum) Required. tv, movie, anime, manga, game, book, comic, boardgame.
source string Optional. Defaults to the default source for the media type.
page int Default 1.

Example:

GET /api/search/?q=spider&media_type=movie&source=tmdb&page=1

History

GET /api/history/<source>/<media_type>/<media_id>/

Returns change history for a media item.

Filters (query parameters)

Parameter Type Values / Default
season_number int Optional.
episode_number int Optional.

Example:

GET /api/history/tmdb/movie/12345/?season_number=1&episode_number=3

Statistics

GET /api/statistics/

Returns aggregated statistics for the authenticated user.

Filters (query parameters)

Parameter Type Values / Default
start-date string (date YYYY-MM-DD or all) Default: one year ago.
end-date string (date YYYY-MM-DD or all) Default: today. Use all/all to include everything.

Example:

GET /api/statistics/?start-date=2024-01-01&end-date=2024-12-31

Supported Sources

Source Media Types
tmdb movie, tv, season, episode
mal anime, manga
mangaupdates manga
igdb game
hardcover book
openlibrary book
comicvine comic
bgg boardgame
manual all

Response Codes

Code Meaning
200 OK — successful read or update.
201 Created — resource created.
204 No Content — successful delete.
400 Bad Request — invalid or missing data.
404 Not Found — resource missing, or provider metadata unavailable.
409 Conflict — media is already tracked.
429 Too Many Requests — metadata synced too recently.

Status Values

  • Planning
  • In progress
  • Completed
  • Dropped
  • Paused

Clone this wiki locally