Skip to main content

​
User Collections

Manage user anime collections including watch lists, completed anime, and viewing progress.

​
Watch List Endpoints

​
Add to Watch List

Add an anime to the user’s watch list with a specific collection type.

​
Endpoint

POST /api/user/watchList

​
Authentication

Authentication RequiredThis endpoint requires a valid user session. Include session cookies with your request.

​
Request Body

​
animeId
string
required
The unique identifier of the anime to add to the watch list.
​
type
string
required
The collection type/category for this anime:
  • "Collection": Main anime collection
  • "Completed": Finished watching
  • "To Watch": Plan to watch
  • "Watching": Currently watching

​
Response

{
  "success": true,
  "data": {
    "message": "Anime added to watch list"
  }
}

​
Remove from Watch List

Remove an anime from the user’s watch list.

​
Endpoint

DELETE /api/user/watchList

​
Authentication

Authentication Required

​
Request Body

​
animeId
string
required
The unique identifier of the anime to remove from the watch list.

​
Response

{
  "success": true,
  "data": {
    "message": "Anime removed from watch list"
  }
}

​
Get Watch List

Retrieve the user’s complete watch list with all anime details.

​
Endpoint

GET /api/user/watchList

​
Authentication

Authentication Required

​
Response

​
success
boolean
Always true for successful requests.
​
data
array
Array of anime objects in the user’s watch list.
​
data[].id
string
Unique identifier for the watch list entry.
​
data[].user_id
string
User’s unique identifier.
​
data[].anime_id
string
Anime’s unique identifier.
​
data[].type
string
Collection type: "Collection", "Completed", "To Watch", or "Watching".
​
data[].title
string
Anime title.
​
data[].imageUrl
string
Anime cover image URL.
​
data[].rating
number
Anime rating (0-10).
​
data[].episodes
number
Total number of episodes.
{
  "success": true,
  "data": [
    {
      "id": "wl-123",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "anime_id": "anime-456",
      "type": "Watching",
      "title": "Attack on Titan",
      "imageUrl": "https://cdn.myanimelist.net/images/anime/10/47347.jpg",
      "rating": 9.0,
      "episodes": 75,
      "genres": ["Action", "Drama", "Fantasy"]
    },
    {
      "id": "wl-124",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "anime_id": "anime-789",
      "type": "Completed",
      "title": "Death Note",
      "imageUrl": "https://cdn.myanimelist.net/images/anime/9/9453.jpg",
      "rating": 8.6,
      "episodes": 37,
      "genres": ["Mystery", "Psychological", "Thriller"]
    }
  ]
}

​
Search History Endpoints

​
Save Search History

Save a user’s search query to their search history.

​
Endpoint

POST /api/user/searchHistory

​
Authentication

Authentication Required

​
Request Body

The request body should contain the search query data to be saved.
​
query
string
required
The search query text entered by the user.
​
timestamp
string
ISO 8601 timestamp of when the search was performed.

​
Response

{
  "success": true,
  "data": {
    "message": "Search history saved"
  }
}

​
Get Search History

Retrieve the user’s search history.

​
Endpoint

GET /api/user/searchHistory

​
Authentication

Authentication Required

​
Response

{
  "success": true,
  "data": [
    {
      "id": "sh-123",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "query": "attack on titan",
      "timestamp": "2026-03-11T10:30:00Z"
    },
    {
      "id": "sh-124",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "query": "death note",
      "timestamp": "2026-03-11T09:15:00Z"
    }
  ]
}

​
Delete Search History

Clear all search history for the user.

​
Endpoint

DELETE /api/user/searchHistory

​
Authentication

Authentication Required

​
Response

{
  "success": true,
  "data": {
    "message": "Search history deleted"
  }
}

​
Profile Management

​
Save Profile

Update user profile information.

​
Endpoint

POST /api/user/profile

​
Authentication

Authentication Required

​
Request Body

​
name
string
required
User’s first name.
​
last_name
string
required
User’s last name.
​
birthday
string
User’s birthday in ISO 8601 format (e.g., "1995-05-20").
​
gender
string
required
User’s gender: "male", "female", or "other".
​
avatar
string
URL to the user’s avatar image.
​
favorite_animes
array
Array of anime IDs that the user has marked as favorites.
​
favorite_genres
array
Array of genre names the user prefers.
​
favorite_studios
array
Array of studio names the user follows.
​
frequency
string
How often the user watches anime (e.g., "daily", "weekly", "monthly").
​
fanatic_level
string
User’s anime enthusiasm level (e.g., "casual", "enthusiast", "hardcore").
​
preferred_format
string
Preferred anime format (e.g., "TV", "Movie", "OVA").
​
watched_animes
array
Array of anime IDs the user has watched.

​
Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "birthday": "1995-05-20",
    "gender": "male",
    "avatar": "https://example.com/avatar.jpg",
    "favorite_animes": ["anime-1", "anime-2"],
    "favorite_genres": ["Action", "Drama"],
    "favorite_studios": ["Wit Studio", "Madhouse"],
    "frequency": "weekly",
    "fanatic_level": "enthusiast",
    "preferred_format": "TV",
    "watched_animes": ["anime-1", "anime-3", "anime-5"],
    "updated_at": "2026-03-11T10:30:00Z"
  }
}

​
Examples

async function addToWatchList(animeId, collectionType) {
  const response = await fetch('/api/user/watchList', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',
    body: JSON.stringify({
      animeId: animeId,
      type: collectionType
    })
  });
  
  if (!response.ok) {
    throw new Error('Failed to add to watch list');
  }
  
  return await response.json();
}

// Usage
await addToWatchList('anime-123', 'Watching');

​
Collection Types

​
Collection

Main anime collection. General purpose category for saved anime.

​
Completed

Anime that the user has finished watching. Useful for tracking viewing history and generating statistics.

​
To Watch

Planned anime. Build a queue of anime to watch later.

​
Watching

Currently watching anime. Track active viewing progress.
Users can move anime between collection types by removing and re-adding with a different type, or by implementing a custom “move” function that combines both operations.

​
Best Practices

  1. Optimistic UI Updates: Update the UI immediately, then sync with the server
  2. Error Recovery: Provide clear feedback and retry mechanisms for failed operations
  3. Pagination: For large collections, implement client-side pagination or filtering
  4. Caching: Cache collection data locally and refresh periodically
  5. Real-time Sync: Consider implementing WebSocket updates for multi-device sync

Build docs developers (and LLMs) love

Get started for freeTalk to us