PublicMetaDB

https://publicmetadb.com/api-docs
Admin
PublicMetaDB offers an external API for third-party applications to access and manage user data...
Tokens:13,530
Snippets:36
Trust Score:1.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### GET /api/external/skips

Source: https://publicmetadb.com/api-docs/index

Get intro/credits skip timestamps for a movie or TV episode.

```APIDOC
## GET /api/external/skips

### Description
Get intro/credits skip timestamps for a movie or TV episode.

### Method
GET

### Endpoint
`https://publicmetadb.com/api/external/skips`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **tmdb_id** (number) - Required - TMDB ID (query parameter).
- **media_type** (string) - Required - 'movie' or 'tv'.
- **season** (number) - Optional - Season number (for TV).
- **episode** (number) - Optional - Episode number (for TV).
- **source** (string) - Optional - 'streaming' or 'physical'.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **skip_timestamps** (array) - List of skip timestamps.
  - **id** (string) - Unique identifier for the skip timestamp.
  - **tmdb_id** (number) - TMDB ID.
  - **media_type** (string) - Type of media ('movie' or 'tv').
  - **season** (number) - Season number (for TV).
  - **episode** (number) - Episode number (for TV).
  - **source** (string) - Source of the timestamp ('streaming' or 'physical').
  - **intro_start_ms** (number) - Intro start time in milliseconds.
  - **intro_end_ms** (number) - Intro end time in milliseconds.
  - **credits_start_ms** (number) - Credits start time in milliseconds.
  - **credits_end_ms** (number) - Credits end time in milliseconds.

#### Response Example
```json
{
  "skip_timestamps": [
    {
      "id": "60c72b2f9b1e8a001f8e4c1d",
      "tmdb_id": 12345,
      "media_type": "movie",
      "season": null,
      "episode": null,
      "source": "streaming",
      "intro_start_ms": 120000,
      "intro_end_ms": 180000,
      "credits_start_ms": null,
      "credits_end_ms": null
    }
  ]
}
```
```

--------------------------------

### Get Votes for Episode Rating

Source: https://publicmetadb.com/api-docs/index

Get votes for an episode rating entry. Returns your vote by default, or all votes with ?all=true. Requires authentication.

```APIDOC
## GET /api/external/episode-ratings/:itemId/votes

### Description
Get votes for an episode rating entry. Returns your vote by default, or all votes with ?all=true.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/episode-ratings/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The episode rating record ID

#### Query Parameters
- **all** (boolean) - Optional - Set to 'true' to get all votes

#### Request Body
None

### Request Example
```json
null
```

### Response
#### Success Response (200)
- **your_vote** (number) - Your vote (1, 0, or -1) if cast, otherwise null
- **total_votes** (object) - Object containing vote counts (if all=true)
  - **upvotes** (number) - Number of upvotes
  - **neutral** (number) - Number of neutral votes
  - **downvotes** (number) - Number of downvotes

#### Response Example
```json
{
  "your_vote": 1
}
```

#### Response Example (with all=true)
```json
{
  "total_votes": {
    "upvotes": 150,
    "neutral": 10,
    "downvotes": 5
  }
}
```
```

--------------------------------

### GET /api/external/watched

Source: https://publicmetadb.com/api-docs/index

Retrieve your complete watch history including movies and TV episodes.

```APIDOC
## GET /api/external/watched

### Description
Retrieve your complete watch history including movies and TV episodes.

### Method
GET

### Endpoint
`https://publicmetadb.com/api/external/watched`

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **watched_history** (array) - List of watched items.
  - **id** (string) - Unique identifier for the watch entry.
  - **tmdb_id** (number) - TMDB ID of the movie or TV show.
  - **media_type** (string) - Type of media ('movie' or 'tv').
  - **watched_at** (string) - Timestamp when the item was marked as watched.
  - **progress_ms** (number) - Playback progress in milliseconds.
  - **season** (number) - Season number (for TV shows).
  - **episode** (number) - Episode number (for TV shows).

#### Response Example
```json
{
  "watched_history": [
    {
      "id": "60c72b2f9b1e8a001f8e4c1a",
      "tmdb_id": 12345,
      "media_type": "movie",
      "watched_at": "2023-10-27T10:00:00Z",
      "progress_ms": 600000,
      "season": null,
      "episode": null
    },
    {
      "id": "60c72b2f9b1e8a001f8e4c1b",
      "tmdb_id": 67890,
      "media_type": "tv",
      "watched_at": "2023-10-27T11:00:00Z",
      "progress_ms": 1200000,
      "season": 1,
      "episode": 5
    }
  ]
}
```
```

--------------------------------

### GET /api/external/ratings

Source: https://publicmetadb.com/api-docs/index

Get community ratings for a movie or TV show. Returns individual ratings and an average score.

```APIDOC
## GET /api/external/ratings

### Description
Get community ratings for a movie or TV show. Returns individual ratings and an average score.

### Method
GET

### Endpoint
`https://publicmetadb.com/api/external/ratings`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **tmdb_id** (number) - Required - TMDB ID (query parameter).
- **media_type** (string) - Required - 'movie' or 'tv'.
- **label** (string) - Optional - Filter by rating label.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **ratings** (array) - List of individual ratings.
  - **user_id** (string) - ID of the user who submitted the rating.
  - **rating** (number) - The rating score.
  - **rated_at** (string) - Timestamp when the rating was submitted.
- **average_score** (number) - The average score for the item.

#### Response Example
```json
{
  "ratings": [
    {
      "user_id": "user123",
      "rating": 8.5,
      "rated_at": "2023-10-27T13:00:00Z"
    },
    {
      "user_id": "user456",
      "rating": 7.0,
      "rated_at": "2023-10-27T13:05:00Z"
    }
  ],
  "average_score": 7.75
}
```
```

--------------------------------

### POST /api/external/skips

Source: https://publicmetadb.com/api-docs/index

Submit a new skip timestamp for intros, recaps, or credits.

```APIDOC
## POST /api/external/skips

### Description
Submit a new skip timestamp for intros, recaps, or credits.

### Method
POST

### Endpoint
`https://publicmetadb.com/api/external/skips`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tmdb_id** (number) - Required - TMDB ID.
- **media_type** (string) - Required - 'movie' or 'tv'.
- **season** (number) - Required - Season number (required for TV).
- **episode** (number) - Required - Episode number (required for TV).
- **source** (string) - Optional - 'streaming' or 'physical' (default: streaming).
- **intro_start_ms** (number) - Optional - Intro start time in milliseconds.
- **intro_end_ms** (number) - Optional - Intro end time in milliseconds.
- **credits_start_ms** (number) - Optional - Credits start time in milliseconds.
- **credits_end_ms** (number) - Optional - Credits end time in milliseconds.

### Request Example
```json
{
  "tmdb_id": 67890,
  "media_type": "tv",
  "season": 1,
  "episode": 5,
  "intro_start_ms": 60000,
  "intro_end_ms": 120000
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **skip_record** (object) - Details of the created skip timestamp.
  - **id** (string) - Unique identifier for the skip timestamp.
  - **tmdb_id** (number) - TMDB ID.
  - **media_type** (string) - Type of media ('movie' or 'tv').
  - **season** (number) - Season number (for TV).
  - **episode** (number) - Episode number (for TV).
  - **source** (string) - Source of the timestamp ('streaming' or 'physical').
  - **intro_start_ms** (number) - Intro start time in milliseconds.
  - **intro_end_ms** (number) - Intro end time in milliseconds.
  - **credits_start_ms** (number) - Credits start time in milliseconds.
  - **credits_end_ms** (number) - Credits end time in milliseconds.

#### Response Example
```json
{
  "message": "Skip timestamp created successfully.",
  "skip_record": {
    "id": "60c72b2f9b1e8a001f8e4c1e",
    "tmdb_id": 67890,
    "media_type": "tv",
    "season": 1,
    "episode": 5,
    "source": "streaming",
    "intro_start_ms": 60000,
    "intro_end_ms": 120000,
    "credits_start_ms": null,
    "credits_end_ms": null
  }
}
```
```

--------------------------------

### Lists API

Source: https://publicmetadb.com/api-docs/index

Manage user-created media lists, including retrieving, creating, and adding/removing items.

```APIDOC
## GET /api/external/lists

### Description
Retrieve all lists you own. Supports pagination.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/lists

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number (default: 1)
- **perPage** (number) - Optional - Items per page, max 500 (default: 30)

### Response
#### Success Response (200)
- **lists** (array) - An array of list objects.
  - **id** (string) - The unique identifier for the list.
  - **name** (string) - The name of the list.
  - **description** (string) - The description of the list.
  - **is_public** (boolean) - Whether the list is public.
  - **type** (string) - The type of list ('watchlist' or 'custom').
  - **item_count** (number) - The number of items in the list.

#### Response Example
{
  "example": "{\"lists\": [{\"id\": \"list_abc\", \"name\": \"My Favorites\", \"description\": \"My top movies\", \"is_public\": true, \"type\": \"custom\", \"item_count\": 50}]}"
}
```

```APIDOC
## POST /api/external/lists

### Description
Create a new list.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/lists

### Parameters
#### Request Body
- **name** (string) - Required - Name of the list
- **description** (string) - Optional - Description of the list
- **is_public** (boolean) - Optional - Whether the list is public (default: true)
- **type** (string) - Optional - 'watchlist' or 'custom' (default: custom)

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **list_id** (string) - The ID of the newly created list.

#### Response Example
{
  "example": "{\"message\": \"List created successfully\", \"list_id\": \"new_list_789\"}"
}
```

```APIDOC
## GET /api/external/lists/:listId/items

### Description
Retrieve items in a specific list. Works for your own lists and public lists. Supports pagination.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/lists/:listId/items

### Parameters
#### Path Parameters
- **listId** (string) - Required - The list ID
#### Query Parameters
- **page** (number) - Optional - Page number (default: 1)
- **perPage** (number) - Optional - Items per page, max 500 (default: 30)

### Response
#### Success Response (200)
- **items** (array) - An array of items in the list.
  - **tmdb_id** (number) - The TMDB ID of the item.
  - **media_type** (string) - The type of media ('movie' or 'tv').
  - **added_at** (string) - Timestamp when the item was added.

#### Response Example
{
  "example": "{\"items\": [{\"tmdb_id\": 12345, \"media_type\": \"movie\", \"added_at\": \"2023-10-27T10:00:00Z\"}]}"
}
```

```APIDOC
## POST /api/external/lists/:listId/items

### Description
Add a movie or TV show to one of your lists.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/lists/:listId/items

### Parameters
#### Path Parameters
- **listId** (string) - Required - The list ID
#### Request Body
- **tmdb_id** (number) - Required - TMDB ID of the movie or TV show
- **media_type** (string) - Required - 'movie' or 'tv'

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.

#### Response Example
{
  "example": "{\"message\": \"Item added to list successfully\"}"
}
```

```APIDOC
## DELETE /api/external/lists/:listId/items/:itemId

### Description
Remove an item from one of your lists.

### Method
DELETE

### Endpoint
https://publicmetadb.com/api/external/lists/:listId/items/:itemId

### Parameters
#### Path Parameters
- **listId** (string) - Required - The list ID
- **itemId** (string) - Required - The item ID to remove (usually the TMDB ID)

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "example": "{\"message\": \"Item removed from list successfully\"}"
}
```

--------------------------------

### Authentication

Source: https://publicmetadb.com/api-docs/index

Details on how to obtain and use API keys for authenticating requests to the PublicMetaDB External API.

```APIDOC
## Authentication

### How to Get an API Key
  1. Log into PublicMetaDB with your account
  2. Navigate to **Settings → API**
  3. Click **"Create"** and copy the generated key
  4. Provide the key to your application

### Using the API Key
Include the API key in the `Authorization` header with every request:
`Authorization: Bearer pm-YourApiKeyHere...`

### API Key Format
API keys follow this format: `pm-[60 alphanumeric characters]`
Example: `pm-Xk9mN2pQrS7tUvWx3yZaB4cD5eF6gH7iJ8kL9mN0oP1qR2sT3uV4wXyZ5aB`

#### Key Security
API keys are only displayed once when created. Users cannot retrieve them later. If a key is lost or compromised, users should delete it and create a new one.
```

--------------------------------

### Rate Limits

Source: https://publicmetadb.com/api-docs/index

Information on rate limits enforced per IP address to ensure fair usage and protect the service.

```APIDOC
## Rate Limits

### External API Limits
Endpoint| Max Requests| Interval  
---|---|---  
/api/*| 300| 10 seconds  
/api/batch| 3| 1 second  

### Contribution Limits
These limits apply to creating and updating user-contributed data.
Action| Max Requests| Per  
---|---|---  
Submit ratings| 200| hour  
Update ratings| 100| hour  
Submit skip timestamps| 30| hour  
Update skip timestamps| 60| hour  
Submit highlights| 50| hour  
Submit anime season mappings| 30| hour  
Submit external ID mappings| 100| hour  
Create lists| 10| hour  

### Error Responses
`401` Invalid or missing API key
`429` Rate limit exceeded – wait and retry
`500` Server error

When rate limited, check the `Retry-After` header for when you can retry.
```

--------------------------------

### Highlights API

Source: https://publicmetadb.com/api-docs/index

Endpoints for retrieving and managing notable scene timestamps (highlights) for movies and TV episodes.

```APIDOC
## GET /api/external/highlights

### Description
Get notable scene timestamps (highlights) for a movie or TV episode.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/highlights

### Parameters
#### Query Parameters
- **tmdb_id** (number) - Yes - TMDB ID (query parameter)
- **media_type** (string) - Yes - 'movie' or 'tv'
- **season** (number) - No - Season number (for TV)
- **episode** (number) - No - Episode number (for TV)

### Response
#### Success Response (200)
- **highlights** (array) - Array of highlight objects.

#### Response Example
```json
{
  "highlights": [
    {
      "id": "highlight_aaa111",
      "start_ms": 120000,
      "end_ms": 135000,
      "description": "Key plot twist"
    }
  ]
}
```

## POST /api/external/highlights

### Description
Submit a new highlight (notable moment) for a movie or TV episode.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/highlights

### Parameters
#### Request Body
- **tmdb_id** (number) - Yes - TMDB ID
- **media_type** (string) - Yes - 'movie' or 'tv'
- **season** (number) - No - Season number (for TV)
- **episode** (number) - No - Episode number (for TV)
- **highlight_start_ms** (number) - Yes - Highlight start time in milliseconds
- **highlight_end_ms** (number) - Yes - Highlight end time in milliseconds
- **description** (string) - No - Short description of the moment

### Request Example
```json
{
  "tmdb_id": 12345,
  "media_type": "movie",
  "highlight_start_ms": 150000,
  "highlight_end_ms": 165000,
  "description": "Epic action sequence"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique ID of the created highlight.
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "id": "highlight_bbb222",
  "message": "Highlight created successfully."
}
```

## DELETE /api/external/highlights/:id

### Description
Delete a highlight that you created. You can only delete your own data.

### Method
DELETE

### Endpoint
https://publicmetadb.com/api/external/highlights/:id

### Parameters
#### Path Parameters
- **id** (string) - Yes - The highlight record ID (path parameter)

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Highlight deleted successfully."
}
```
```

--------------------------------

### Voting on Highlights

Source: https://publicmetadb.com/api-docs/index

Endpoints for retrieving and submitting votes for highlight entries.

```APIDOC
## GET /api/external/highlights/:itemId/votes

### Description
Get votes for a highlight entry. Returns your vote by default, or all votes with ?all=true.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/highlights/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The highlight record ID

#### Query Parameters
- **all** (boolean) - Optional - Set to 'true' to get all votes

### Request Example
```
GET https://publicmetadb.com/api/external/highlights/some_highlight_id/votes?all=true
```

### Response
#### Success Response (200)
- **vote** (object) - Details about the vote
  - **upvotes** (integer) - Number of upvotes
  - **downvotes** (integer) - Number of downvotes
  - **your_vote** (integer) - Your vote (-1, 0, or 1)

#### Response Example
```json
{
  "upvotes": 7,
  "downvotes": 0,
  "your_vote": 1
}
```

## POST /api/external/highlights/:itemId/votes

### Description
Submit or update your vote on a highlight entry. Use 1 for upvote, -1 for downvote, 0 for neutral.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/highlights/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The highlight record ID

#### Request Body
- **vote** (number) - Required - 1 (upvote), 0 (neutral), or -1 (downvote)

### Request Example
```json
{
  "vote": 1
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Vote submitted successfully."
}
```

## DELETE /api/external/highlights/:itemId/votes

### Description
Remove your vote from a highlight entry.

### Method
DELETE

### Endpoint
https://publicmetadb.com/api/external/highlights/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The highlight record ID

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Vote removed successfully."
}
```
```

--------------------------------

### Vote on Anime Season

Source: https://publicmetadb.com/api-docs/index

Submit or update your vote on an anime season mapping entry. Requires authentication.

```APIDOC
## POST /api/external/anime-seasons/:itemId/votes

### Description
Submit or update your vote on an anime season mapping entry.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/anime-seasons/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The anime season record ID

#### Query Parameters
None

#### Request Body
- **vote** (number) - Required - 1 (upvote), 0 (neutral), or -1 (downvote)

### Request Example
```json
{
  "vote": 1
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Vote updated successfully."
}
```
```

--------------------------------

### Anime Seasons API

Source: https://publicmetadb.com/api-docs/index

Manage and retrieve anime season mappings that link logical anime seasons to TMDB season/episode ranges.

```APIDOC
## GET /api/external/anime-seasons

### Description
Get anime season mappings that map logical anime seasons to TMDB season/episode ranges.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/anime-seasons

### Parameters
#### Query Parameters
- **tmdb_id** (number) - Required - TMDB ID of the anime

### Response
#### Success Response (200)
- **mappings** (array) - An array of anime season mapping objects.
  - **id** (string) - The unique identifier for the mapping.
  - **tmdb_id** (number) - The TMDB ID of the anime.
  - **season_number** (number) - The logical anime season number.
  - **season_name** (string) - The name of the season/arc.
  - **episode_count** (number) - Total episodes in this logical season.
  - **is_complete** (boolean) - Whether this season is complete.
  - **tmdb_season** (number) - The TMDB season number.
  - **tmdb_episode_start** (number) - The first TMDB episode in this mapping.
  - **tmdb_episode_end** (number) - The last TMDB episode in this mapping.

#### Response Example
{
  "example": "{\"mappings\": [{\"id\": \"anime_season_789\", \"tmdb_id\": 98765, \"season_number\": 1, \"season_name\": \"First Arc\", \"episode_count\": 12, \"is_complete\": true, \"tmdb_season\": 1, \"tmdb_episode_start\": 1, \"tmdb_episode_end\": 12}]}"
}
```

```APIDOC
## POST /api/external/anime-seasons

### Description
Submit a new anime season mapping to link logical anime seasons to TMDB seasons/episodes.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/anime-seasons

### Parameters
#### Request Body
- **tmdb_id** (number) - Required - TMDB ID of the anime
- **season_number** (number) - Required - Logical anime season number
- **season_name** (string) - Optional - Name of the season/arc
- **episode_count** (number) - Optional - Total episodes in this logical season
- **is_complete** (boolean) - Optional - Whether this season is complete (default: false)
- **tmdb_season** (number) - Optional - TMDB season number
- **tmdb_episode_start** (number) - Optional - First episode in the TMDB season for this mapping
- **tmdb_episode_end** (number) - Optional - Last episode in the TMDB season for this mapping

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **mapping_id** (string) - The ID of the newly created mapping.

#### Response Example
{
  "example": "{\"message\": \"Anime season mapping created successfully\", \"mapping_id\": \"new_anime_season_101\"}"
}
```

```APIDOC
## DELETE /api/external/anime-seasons/:id

### Description
Delete an anime season mapping that you created. You can only delete your own data.

### Method
DELETE

### Endpoint
https://publicmetadb.com/api/external/anime-seasons/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The anime season record ID

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "example": "{\"message\": \"Anime season mapping deleted successfully\"}"
}
```

--------------------------------

### POST /api/external/ratings

Source: https://publicmetadb.com/api-docs/index

Submit a new rating for a movie or TV show.

```APIDOC
## POST /api/external/ratings

### Description
Submit a new rating for a movie or TV show.

### Method
POST

### Endpoint
`https://publicmetadb.com/api/external/ratings`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tmdb_id** (number) - Required - TMDB ID of the movie or TV show.
- **media_type** (string) - Required - 'movie' or 'tv'.
- **rating** (number) - Required - The rating score (e.g., 1-10).

### Request Example
```json
{
  "tmdb_id": 12345,
  "media_type": "movie",
  "rating": 9.0
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **rating_entry** (object) - Details of the created rating.
  - **id** (string) - Unique identifier for the rating.
  - **tmdb_id** (number) - TMDB ID.
  - **media_type** (string) - Type of media ('movie' or 'tv').
  - **rating** (number) - The rating score.
  - **rated_at** (string) - Timestamp when the rating was submitted.

#### Response Example
```json
{
  "message": "Rating submitted successfully.",
  "rating_entry": {
    "id": "60c72b2f9b1e8a001f8e4c1f",
    "tmdb_id": 12345,
    "media_type": "movie",
    "rating": 9.0,
    "rated_at": "2023-10-27T14:00:00Z"
  }
}
```
```

--------------------------------

### External ID Mappings API

Source: https://publicmetadb.com/api-docs/index

Manage and retrieve external database ID mappings (IMDb, TVDB, MAL, etc.) for TMDB entries.

```APIDOC
## GET /api/external/mappings

### Description
Get external database IDs (IMDb, TVDB, MAL, etc.) for a TMDB ID.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/mappings

### Parameters
#### Query Parameters
- **tmdb_id** (number) - Required - TMDB ID
- **media_type** (string) - Required - 'movie' or 'tv'
- **id_type** (string) - Optional - Filter by ID type (imdb, tvdb, mal, anilist, etc.)

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the mapping record.
- **tmdb_id** (number) - The TMDB ID associated with the mapping.
- **media_type** (string) - The type of media ('movie' or 'tv').
- **id_type** (string) - The type of external ID (e.g., 'imdb', 'tvdb').
- **id_value** (string) - The value of the external ID.

#### Response Example
{
  "example": "{\"id\": \"mapping_123\", \"tmdb_id\": 12345, \"media_type\": \"movie\", \"id_type\": \"imdb\", \"id_value\": \"tt0111161\"}"
}
```

```APIDOC
## GET /api/external/mappings/lookup

### Description
Find a TMDB ID from an external ID (reverse lookup).

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/mappings/lookup

### Parameters
#### Query Parameters
- **id_type** (string) - Required - External ID type (imdb, tvdb, mal, anilist, etc.)
- **id_value** (string) - Required - The external ID value
- **media_type** (string) - Optional - Filter by 'movie' or 'tv'

### Response
#### Success Response (200)
- **tmdb_id** (number) - The TMDB ID found.
- **media_type** (string) - The type of media ('movie' or 'tv').
- **mappings** (array) - An array of mapping objects, each containing `id_type` and `id_value`.

#### Response Example
{
  "example": "{\"tmdb_id\": 12345, \"media_type\": \"movie\", \"mappings\": [{\"id_type\": \"imdb\", \"id_value\": \"tt0111161\"}]}"
}
```

```APIDOC
## POST /api/external/mappings

### Description
Submit a new external ID mapping for a TMDB entry.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/mappings

### Parameters
#### Request Body
- **tmdb_id** (number) - Required - TMDB ID
- **media_type** (string) - Required - 'movie' or 'tv'
- **id_type** (string) - Required - External ID type (imdb, tvdb, mal, anilist, anidb, trakt)
- **id_value** (string) - Required - The external ID value

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **mapping_id** (string) - The ID of the newly created mapping.

#### Response Example
{
  "example": "{\"message\": \"Mapping created successfully\", \"mapping_id\": \"new_mapping_456\"}"
}
```

```APIDOC
## DELETE /api/external/mappings/:id

### Description
Delete an ID mapping that you created. You can only delete your own data.

### Method
DELETE

### Endpoint
https://publicmetadb.com/api/external/mappings/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The mapping record ID

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "example": "{\"message\": \"Mapping deleted successfully\"}"
}
```

--------------------------------

### Voting on Skips

Source: https://publicmetadb.com/api-docs/index

Endpoints for retrieving and submitting votes for skip timestamp entries.

```APIDOC
## GET /api/external/skips/:itemId/votes

### Description
Get votes for a skip timestamp entry. Returns your vote by default, or all votes with ?all=true.

### Method
GET

### Endpoint
https://publicmetadb.com/api/external/skips/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The skip record ID

#### Query Parameters
- **all** (boolean) - Optional - Set to 'true' to get all votes, otherwise returns only your vote

### Request Example
```
GET https://publicmetadb.com/api/external/skips/some_skip_id/votes?all=true
```

### Response
#### Success Response (200)
- **vote** (object) - Details about the vote
  - **upvotes** (integer) - Number of upvotes
  - **downvotes** (integer) - Number of downvotes
  - **your_vote** (integer) - Your vote (-1, 0, or 1)

#### Response Example
```json
{
  "upvotes": 10,
  "downvotes": 2,
  "your_vote": 1
}
```

## POST /api/external/skips/:itemId/votes

### Description
Submit or update your vote on a skip timestamp. Use 1 for upvote, -1 for downvote, 0 for neutral.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/skips/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The skip record ID

#### Request Body
- **vote** (number) - Required - 1 (upvote), 0 (neutral), or -1 (downvote)

### Request Example
```json
{
  "vote": 1
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Vote submitted successfully."
}
```

## DELETE /api/external/skips/:itemId/votes

### Description
Remove your vote from a skip timestamp entry.

### Method
DELETE

### Endpoint
https://publicmetadb.com/api/external/skips/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The skip record ID

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Vote removed successfully."
}
```
```

--------------------------------

### POST /api/external/watched

Source: https://publicmetadb.com/api-docs/index

Mark a movie or TV episode as watched.

```APIDOC
## POST /api/external/watched

### Description
Mark a movie or TV episode as watched.

### Method
POST

### Endpoint
`https://publicmetadb.com/api/external/watched`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tmdb_id** (number) - Required - TMDB ID of the movie or TV show.
- **media_type** (string) - Required - 'movie' or 'tv'.
- **season** (number) - Optional - Season number (required for TV).
- **episode** (number) - Optional - Episode number (required for TV).
- **progress_ms** (number) - Optional - Playback progress in milliseconds.

### Request Example
```json
{
  "tmdb_id": 12345,
  "media_type": "movie",
  "progress_ms": 300000
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **watch_entry** (object) - Details of the created watch entry.
  - **id** (string) - Unique identifier for the watch entry.
  - **tmdb_id** (number) - TMDB ID of the movie or TV show.
  - **media_type** (string) - Type of media ('movie' or 'tv').
  - **watched_at** (string) - Timestamp when the item was marked as watched.
  - **progress_ms** (number) - Playback progress in milliseconds.
  - **season** (number) - Season number (for TV shows).
  - **episode** (number) - Episode number (for TV shows).

#### Response Example
```json
{
  "message": "Successfully marked as watched.",
  "watch_entry": {
    "id": "60c72b2f9b1e8a001f8e4c1c",
    "tmdb_id": 12345,
    "media_type": "movie",
    "watched_at": "2023-10-27T12:00:00Z",
    "progress_ms": 300000,
    "season": null,
    "episode": null
  }
}
```
```

--------------------------------

### Vote on Episode Rating

Source: https://publicmetadb.com/api-docs/index

Submit or update your vote on an episode rating entry. Requires authentication.

```APIDOC
## POST /api/external/episode-ratings/:itemId/votes

### Description
Submit or update your vote on an episode rating entry.

### Method
POST

### Endpoint
https://publicmetadb.com/api/external/episode-ratings/:itemId/votes

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The episode rating record ID

#### Query Parameters
None

#### Request Body
- **vote** (number) - Required - 1 (upvote), 0 (neutral), or -1 (downvote)

### Request Example
```json
{
  "vote": -1
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Vote submitted successfully."
}
```
```
Tokens:
Raw