CoverVault API

A small, read-only JSON API over the site's public data (approved covers only — pending or rejected uploads never appear here). It exists so external tools/scripts have a stable way to consume this data instead of scraping HTML.

Du brauchst ein Konto, um einen API-Key zu beantragen. Los geht's mit Anmelden / Registrieren.

Getting an API key

The API requires an API key on every request. To get one: create an account, then go to API-Schlüssel from your account menu and submit a request — you'll need to say what you're building it for and provide a website URL for the project. A moderator reviews each request; you'll get an email once it's approved (or rejected, with a reason). The raw key is shown exactly once on that page right after approval, so copy it somewhere safe immediately.

Authentication

Send your key on every request as either header:

curl -H "Authorization: Bearer cvk_..." https://covervault.org/api/v1/platforms

curl -H "X-Api-Key: cvk_..." https://covervault.org/api/v1/platforms

A missing, invalid, rejected or revoked key returns 401.

Rate limits

Each key is limited to a fixed number of requests per minute (shown on your API keys page once approved). Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers. Exceeding the limit returns 429 with a Retry-After header (seconds). Need a higher limit? Mention it in your request's purpose field.

Base URL

https://covervault.org/api/v1

Conventions

All responses are Content-Type: application/json, UTF-8.
All endpoints are GET only.
A resource that doesn't exist (unknown slug/id, or a cover that isn't approved) returns 404 with {"error": "Not found"}.
Endpoints returning a list of games accept page (default 1) and per_page (default 50, max 100), and include page/per_page/total/total_pages in the response.

Endpoints

Method	Path	Description
GET	`/platforms`	List every platform
GET	`/platforms/{slug}`	A single platform
GET	`/platforms/{slug}/games`	Games on a platform, paginated
GET	`/games/{platformSlug}/{gameSlug}`	A single game's metadata
GET	`/games/{platformSlug}/{gameSlug}/covers`	All approved covers for a game, with files
GET	`/covers/{coverId}`	A single approved cover, with files
GET	`/covers/recent`	Most recently approved covers site-wide
GET	`/search`	Full-text game search with filters
GET	`/stats`	Site-wide statistics

`GET /search` query parameters

Param	Default	Notes
`q`	—	free-text title search
`platform`	—	filter by platform slug
`region`	—	filter to games with a cover in this region
`type`	—	filter to games with a cover of this type
`genre`	—	substring match against genres
`sort`	`title_asc`	`title_asc`, `title_desc`, `year_asc`, `year_desc`
`page`, `per_page`	1, 50	see Conventions above

Example: a single game

{
  "id": 1,
  "slug": "far-cry-3",
  "title": "Far Cry 3",
  "release_year": 2012,
  "description": "Explore an island playground...",
  "genres": "Shooter, Adventure",
  "developer": "Ubisoft Montreal",
  "publisher": "Ubisoft Entertainment",
  "cover_count": 1,
  "platform": { "slug": "playstation-3", "name": "PlayStation 3" },
  "url": "https://example.com/en/platform/playstation-3/game/far-cry-3"
}

This page covers the essentials; the full field-by-field reference (every endpoint's response shape) lives in docs/API.md in the project repository.