# TVmaze user API

**Provider:** TVmaze user
**Category:** social
**Base URL:** `https://api.tvmaze.com/v1`
**Auth:** basic — `Authorization: Basic BASE64(username:password)`
**Rate Limit:** 20 req/10s (public) · 200 req/10s (commercial)
**Free Tier:** Yes — available
**Pricing:** Enterprise / contact sales (subscription)
**Docs:** http://www.tvmaze.com

## Description

Access to the user API is only possible for users with a premium account. A user can only access their own user data.

Authentication uses HTTP Basic. Use the TVmaze username as authentication username, and the TVmaze API key as authentication password. Your API key

## Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `https://api.tvmaze.com/v1/auth/poll` | Poll whether an authentication request was confirmed |
| POST | `https://api.tvmaze.com/v1/auth/start` | Start an authentication request |
| GET | `https://api.tvmaze.com/v1/auth/validate` | Validate your authentication credentials |
| POST | `https://api.tvmaze.com/v1/scrobble/episodes` | Mark episodes as acquired or watched based on their IDs |
| PUT | `https://api.tvmaze.com/v1/scrobble/episodes/{episode_id}` | Mark an episode as acquired or watched based on its ID |
| POST | `https://api.tvmaze.com/v1/scrobble/shows` | Mark episodes within a show as acquired or watched based on their attributes |
| GET | `https://api.tvmaze.com/v1/scrobble/shows/{show_id}` | List watched and acquired episodes for a show |
| GET | `https://api.tvmaze.com/v1/user/episodes` | List the marked episodes |

## Authentication

HTTP Basic Auth — base64-encoded username:password

```
Authorization: Basic BASE64(username:password)
```

## Sample Request

```bash
curl -X GET 'https://api.tvmaze.com/v1/auth/poll' \
  -H 'Authorization: Basic BASE64(username:password)'
```

## Sample Response

```json
{}
```

## Pricing Details

Free — TVmaze API is free for non-commercial use. TV show database and scheduling. User endpoints require OAuth 2.0. Premium plan $1.99/mo for contributors.

---

*Source: [API Map](https://apimap.dev/apis/tvmaze-user/) — CC BY 4.0*