canonical: https://jentic.com/apis/igdb.com/igdb-igdb

# IGDB API

The IGDB (Internet Game Database) API provides programmatic access to a comprehensive video game database covering games, platforms, characters, companies, genres, themes, game modes, release dates, screenshots, and artwork. Queries are issued as POST requests using the Apicalypse query language, which lets clients filter, sort, and select specific fields. Authentication is via Twitch app credentials - a Client-ID header and a Twitch OAuth bearer token. Counterpart count endpoints (for example /games/count) let clients page through large result sets efficiently.

## For AI agents

Query a comprehensive video game database - games, platforms, companies, characters, genres, and artwork - using the Apicalypse query language.

## Scope

Does not handle game purchases, user libraries, or live match data - use for video game catalogue metadata queries only.

## Capabilities

- Query games by title, platform, genre, or release year via POST /games
- Count matching results to drive pagination via POST /games/count
- Look up platforms, platform families, and platform logos for catalogue UIs
- Retrieve characters, companies, and company logos linked to a game
- Pull genres, themes, and game modes for taxonomy-driven recommendations
- Compose Apicalypse queries with where, sort, fields, and limit clauses

## Use cases

### Game Catalogue and Search

Build a game discovery feature that lets users search by title, platform, or genre and returns rich metadata including cover art, summary, and developer. The Apicalypse query language sent to POST /games supports complex filters like rating ranges, platform IDs, and release-date windows in a single request, making IGDB suitable for streaming-service guides, recommendation widgets, and AI gaming assistants.

Example prompt: Send POST /games with body 'fields name,cover.url,rating; where platforms=48 & rating > 80; sort rating desc; limit 10;' and list the top 10 PS4 games by rating.

### Platform and Company Reference Data

Power a developer-facing CMS or admin panel that needs canonical IDs and logos for every gaming platform and publisher. IGDB's platform, platform_families, company, and company_logos endpoints provide stable references that internal teams can map to their own catalogues without curating the data themselves.

Example prompt: Query POST /platforms with 'fields name,abbreviation,platform_family;' and store the result as a lookup table.

### Personalised Game Recommendations

Drive a recommendation engine using genres, themes, and game_modes as feature vectors. By querying /genres and /themes alongside /games, an agent can match a user's expressed preferences to games with similar tags, then enrich the result with cover art and rating before returning the recommendation.

Example prompt: Find games tagged with the user's favourite genres and themes, sort by rating, and return the top 5 with cover URLs.

### AI Agent Gaming Assistant

An AI agent acts as a gaming companion that answers questions like 'what RPGs came out last year' or 'show me Hideo Kojima's catalogue'. Through Jentic, the agent finds the IGDB games operation, builds the Apicalypse query, and returns structured results - credentials stay in your Jentic One instance.

Example prompt: Use Jentic to call POST /games with an Apicalypse filter for 'RPG games released in 2024' and return the names with cover art URLs.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /games | Query games with Apicalypse filters |
| POST | /games/count | Count games matching a query |
| POST | /platforms | Query gaming platforms |
| POST | /companies | Query game development and publishing companies |
| POST | /characters | Query game characters |
| POST | /genres | Query game genres |
| POST | /themes | Query game themes |
| POST | /game_modes | Query game modes |

## Key resources

- **Games** — Query and count games with Apicalypse filters.
- **Platforms** — Look up platforms, platform families, and platform logos.
- **Companies** — Retrieve companies and company logos that develop or publish games.
- **Characters** — Look up characters that appear in games.
- **Taxonomy** — Genres, themes, and game modes for filtering and recommendations.

## Why Jentic

- **Setup:** Wiring IGDB by hand means sending both the Twitch Client-ID header and a bearer token, and writing Apicalypse query bodies against api.igdb.com yourself. Through Jentic you install once, import the IGDB API from the API Directory, store the Client-ID and bearer token once, and your agent calls it.
- **Permission scoping:** IGDB is a read query API where the target travels in the Apicalypse request body rather than the URL path, so scope the agent to the operations it needs, such as querying games, platforms, and genres. Because you choose the allowed operations, an agent limited to game lookups never gets the companies or characters operation unless you add it.
- **Credential handling:** Your IGDB Client-ID and Twitch bearer token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find video games by genre' or 'count games on a platform', and Jentic returns the matching IGDB operation with its Apicalypse query schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **RAWG Video Games Database API** — RAWG is a comparable video game database with simpler REST query syntax.
- **Steam Web API** — Steam exposes user libraries, achievements, and store data that complement IGDB's reference catalogue.
- **Riot Games API** — Riot exposes live match data for League of Legends, Valorant, and TFT.

## FAQ

### What authentication does the IGDB API use?

IGDB requires both a Client-ID header (your Twitch app's client ID) and a Bearer token obtained via Twitch OAuth. Through Jentic, both credentials are held in the vault and injected at execution time, so the agent never sees the raw values.

### Can I search for games by genre or platform with the IGDB API?

Yes. POST /games with an Apicalypse body like 'fields name,rating; where genres=12 & platforms=48;' filters by genre and platform IDs. Combine with sort and limit clauses to paginate.

### What is the Apicalypse query language?

Apicalypse is IGDB's filter language sent in the POST request body. It supports fields, where, sort, limit, offset, and search clauses, all in a single string - for example 'fields name,rating; where rating > 80; limit 10;'.

### What are the rate limits for the IGDB API?

IGDB enforces a rate limit of 4 requests per second per Twitch app credential. Burst over the limit returns 429; pace requests or batch with Apicalypse multi-query support to stay within limits.

### How do I count results for pagination?

Use the matching count endpoint, for example POST /games/count with the same Apicalypse where clause. The response returns the total matching count so the agent can compute pages with limit and offset.

### How do I query games through Jentic?

Run pip install jentic, search 'find video games by genre and platform', load the schema for POST /games, and execute with the Apicalypse query string in the request body.

### Can I limit what my agent is allowed to do with the IGDB API?

Yes. Because Jentic One is self-hosted and you set its rules, you choose exactly which IGDB operations your agent may call, such as querying games, platforms, or genres, and which stored credentials it may use. IGDB is a read-only query API where the target travels in the Apicalypse request body rather than the URL, so an agent scoped to game lookups never gains the companies or characters operation unless you explicitly add it. The Twitch Client-ID and bearer token stay in your own instance and are injected only for the operations you have allowed.