Skip to content

API

Jump to bottom
URD0TH edited this page Jul 18, 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
mal anime, manga
igdb game
openlibrary book
custom 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