Undocumented internal JSON API powering metacritic.com (a Fandom property).
Reverse-engineered from the site's public web client. Every request carries a
shared public apiKey that the site embeds in its own JavaScript bundle, so no
user credentials are required for read access.
One backend (backend.metacritic.com) serves every media type. The mcoTypeId
query parameter selects the medium on the browse endpoint: 1 = TV shows,
2 = movies, 13 = games. The {mediaType} path segment (games, movies,
shows) selects the medium on the title-detail, filters, and review endpoints.
The non-obvious insight: Metacritic is not just a review aggregator, it is a
cross-media taste graph. Every gap between a title's Metascore (critics) and
user score is a signal about critic-audience divergence.
Scope: this spec covers games, movies, and TV shows plus search, filters, title
detail, and critic/user reviews. Music (albums) is served through a separate
query shape and is intentionally left as a follow-up.
Learn more at Metacritic.
Created by @coopdogGGs (Ryan Cooper).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export METACRITIC_API_KEY="<paste-your-key>"
You can also persist this in your config file at ~/.config/metacritic-pp-cli/config.toml.
3. Verify Setup
metacritic-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here
Usage
Run metacritic-pp-cli --help for the full command reference and flag list.
Commands
composer
Manage composer
metacritic-pp-cli composer <slug> - Returns the full composed detail payload for a title, including Metascore,
user score, summary, release data, and platform/genre metadata.
finder
Manage finder
metacritic-pp-cli finder browse-titles - Paginated, sortable list of titles for one medium. mcoTypeId selects the
medium (1 = TV shows, 2 = movies, 13 = games). Powers the /browse/ pages.metacritic-pp-cli finder list-filters - Returns the filter facets (genres, platforms, streaming networks, product
types) valid for the given medium.metacritic-pp-cli finder search-titles - Full-text search spanning games, movies, TV, and people.
reviews
Critic and user reviews for a title
metacritic-pp-cli reviews list-critic - List critic reviews for a titlemetacritic-pp-cli reviews list-user - List user reviews for a title
Output Formats
# Human-readable table (default in terminal, JSON when piped)
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here
# JSON for scripting and agents
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --json
# Filter to specific fields
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --json --select id,name,status
# Dry run — show the request without sending
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --dry-run
# Agent mode — JSON + compact + no prompts in one flag
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
metacritic-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/metacritic-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
METACRITIC_API_KEY | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, metacritic-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
metacritic-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $METACRITIC_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press