API

API Documentation

Yamtrack provides a REST API for programmatic access to media tracking. The API uses JWT authentication and returns JSON responses.

Base URL

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

Authentication

Obtain Token

POST /api/token/

Request body:

{
  "username": "username",
  "password": "yourpassword"
}

Response:

{
  "access": "eyJhbGciOiJIUzI1NiIs...",
  "refresh": "eyJhbGciOiJIUzI1NiIs..."
}

Refresh Token

POST /api/token/refresh/

Request body:

{
  "refresh": "eyJhbGciOiJIUzI1NiIs..."
}

Get Current User

GET /api/auth/me/

Headers: Authorization: Bearer <access_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"
}

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"
}

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
}

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

Status Values

• Planning
• In progress
• Completed
• Dropped
• Paused