Skip to main content
The account API provides endpoints for managing user account data including profile information, favorites, watchlist, and ratings. All account endpoints require authentication.

​
Get Account Details

Retrieve the authenticated user’s account information. 
curl -X GET https://your-domain.com/api/account

​
Response

​
id
integer
required
The account ID
​
name
string
required
The account name
​
username
string
required
The account username
​
include_adult
boolean
required
Whether adult content is included
​
iso_639_1
string
required
The language code
​
iso_3166_1
string
required
The country code
​
avatar
object
required
Avatar information including gravatar hash

​
Response Example

{
  "id": 12345,
  "name": "John Doe",
  "username": "johndoe",
  "include_adult": false,
  "iso_639_1": "en",
  "iso_3166_1": "US",
  "avatar": {
    "gravatar": {
      "hash": "a1b2c3d4e5f6g7h8"
    }
  }
}

​
Error Response

​
message
string
Error message when not authenticated
{
  "message": "You are not authenticated"
}

​
Get Account Lists

Retrieve favorites, watchlist, or rated items for the authenticated user. 
curl -X GET "https://your-domain.com/api/account/12345/favorites/movies?language=en-US&page=1&sort_by=created_at.desc"

​
Path Parameters

​
account_id
integer
required
The account ID from /api/account
​
section
string
required
The section to retrieve. Options:
  • favorites - User’s favorite items
  • watchlist - User’s watchlist items
  • rated - User’s rated items
​
media_type
string
required
The type of media. Options:
  • movies - Movies
  • tv - TV shows

​
Query Parameters

​
language
string
default:"en-US"
ISO 639-1 language code for the results
​
page
integer
default:"1"
Page number for pagination
​
sort_by
string
default:"created_at.desc"
Sort order. Options:
  • created_at.asc - Oldest first
  • created_at.desc - Newest first

​
Response

​
page
integer
required
Current page number
​
results
array
required
Array of movie or TV show objects
​
total_pages
integer
required
Total number of pages
​
total_results
integer
required
Total number of results

​
Response Example

{
  "page": 1,
  "results": [
    {
      "id": 550,
      "title": "Fight Club",
      "overview": "A ticking-time-bomb insomniac...",
      "poster_path": "/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg",
      "backdrop_path": "/fCayJrkfRaCRCTh8GqN30f8oyQF.jpg",
      "release_date": "1999-10-15",
      "vote_average": 8.4,
      "vote_count": 26000
    }
  ],
  "total_pages": 5,
  "total_results": 98
}

​
Add to Favorites or Watchlist

Add or remove an item from the user’s favorites or watchlist. 
curl -X POST https://your-domain.com/api/account/12345/favorite \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "movie",
    "media_id": 550,
    "favorite": true
  }'

​
Path Parameters

​
account_id
integer
required
The account ID from /api/account
​
section
string
required
The section to update. Options:
  • favorite - Add/remove from favorites
  • watchlist - Add/remove from watchlist

​
Body Parameters

​
media_type
string
required
The type of media. Options:
  • movie - Movie
  • tv - TV show
​
media_id
integer
required
The ID of the movie or TV show
​
favorite
boolean
Whether to add (true) or remove (false) from favorites. Required when section is favorite.
​
watchlist
boolean
Whether to add (true) or remove (false) from watchlist. Required when section is watchlist.

​
Response

​
favorite
boolean
The new favorite status (when updating favorites)
​
watchlist
boolean
The new watchlist status (when updating watchlist)

​
Response Example

{
  "favorite": true
}

​
Example: Add to Watchlist

curl -X POST https://your-domain.com/api/account/12345/watchlist \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "tv",
    "media_id": 1399,
    "watchlist": true
  }'

​
Rate Media

Add or update a rating for a movie or TV show. 
curl -X POST https://your-domain.com/api/movie/550/rating \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 8.5
  }'

​
Path Parameters

​
media_type
string
required
The type of media. Options:
  • movie - Movie
  • tv - TV show
​
media_id
integer
required
The ID of the movie or TV show

​
Body Parameters

​
rating
number
required
Rating value between 0.5 and 10.0 (in increments of 0.5)

​
Response

​
rated
object
required
Object containing the rating value

​
Response Example

{
  "rated": {
    "value": 8.5
  }
}

​
Delete Rating

Remove a rating from a movie or TV show. 
curl -X DELETE https://your-domain.com/api/movie/550/rating

​
Path Parameters

​
media_type
string
required
The type of media. Options:
  • movie - Movie
  • tv - TV show
​
media_id
integer
required
The ID of the movie or TV show

​
Response

​
rated
null
required
Null value indicating the rating was removed

​
Response Example

{
  "rated": null
}

​
Usage Examples

​
Get User Favorites

// Get account info first
const accountResponse = await fetch('/api/account');
const { id } = await accountResponse.json();

// Get favorite movies
const favoritesResponse = await fetch(
  `/api/account/${id}/favorites/movies?page=1&sort_by=created_at.desc`
);
const favorites = await favoritesResponse.json();

​
Add to Watchlist

const accountResponse = await fetch('/api/account');
const { id } = await accountResponse.json();

await fetch(`/api/account/${id}/watchlist`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    media_type: 'movie',
    media_id: 550,
    watchlist: true
  })
});

​
Rate a Movie

await fetch('/api/movie/550/rating', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ rating: 9.0 })
});

​
Error Responses

​
Not Authenticated (401)

{
  "message": "You are not authenticated"
}

​
Rate Limit Exceeded (429)

"Rate Limit Exceeded"

​
Not Found (404)

{
  "message": "Not found"
}

​
Method Not Allowed (405)

{
  "message": "Method Not Allowed"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us