openapi: 3.1.0
info:
title: Twitch IGDB API
description: >-
The Internet Game Database (IGDB) API provides comprehensive video game
information including metadata, ratings, screenshots, videos, and media.
IGDB is owned and operated by Twitch and uses Twitch OAuth for
authentication. The API uses a POST-based query language called Apicalypse.
version: '4.0'
contact:
name: IGDB Support
url: https://api-docs.igdb.com/
termsOfService: https://www.twitch.tv/p/legal/terms-of-service/
externalDocs:
description: IGDB API Documentation
url: https://api-docs.igdb.com/
servers:
- url: https://api.igdb.com/v4
description: IGDB API v4 Production
tags:
- name: Characters
description: Game character data
- name: Collections
description: Game collections and franchises
- name: Companies
description: Game company data
- name: Games
description: Video game data
- name: Genres
description: Game genre data
- name: Media
description: Screenshots, artwork, and videos
- name: Platforms
description: Gaming platform data
- name: Search
description: Multi-resource search
- name: Themes
description: Game theme data
security:
- oauth2: []
paths:
/games:
post:
operationId: queryGames
summary: Twitch Query Games
description: >-
Query the games endpoint using Apicalypse query language. Send the
query as the request body in plain text format.
tags:
- Games
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
example: 'fields name,rating,summary,genres.name; where rating > 90; sort rating desc; limit 10;'
responses:
'200':
description: Games returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Game'
'400':
description: Invalid query syntax
'401':
$ref: '#/components/responses/Unauthorized'
/games/count:
post:
operationId: countGames
summary: Twitch Count Games
description: Returns the count of games matching the query.
tags:
- Games
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
content:
text/plain:
schema:
type: string
responses:
'200':
description: Count returned
content:
application/json:
schema:
type: object
properties:
count:
type: integer
/platforms:
post:
operationId: queryPlatforms
summary: Twitch Query Platforms
description: Query gaming platforms using Apicalypse query language.
tags:
- Platforms
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Platforms returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Platform'
'401':
$ref: '#/components/responses/Unauthorized'
/companies:
post:
operationId: queryCompanies
summary: Twitch Query Companies
description: Query game companies using Apicalypse query language.
tags:
- Companies
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Companies returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Company'
'401':
$ref: '#/components/responses/Unauthorized'
/characters:
post:
operationId: queryCharacters
summary: Twitch Query Characters
description: Query game characters using Apicalypse query language.
tags:
- Characters
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Characters returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Character'
'401':
$ref: '#/components/responses/Unauthorized'
/collections:
post:
operationId: queryCollections
summary: Twitch Query Collections
description: Query game collections and franchises using Apicalypse query language.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Collections returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Collection'
'401':
$ref: '#/components/responses/Unauthorized'
/franchises:
post:
operationId: queryFranchises
summary: Twitch Query Franchises
description: Query game franchises using Apicalypse query language.
tags:
- Collections
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Franchises returned
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Franchise'
/genres:
post:
operationId: queryGenres
summary: Twitch Query Genres
description: Query game genres using Apicalypse query language.
tags:
- Genres
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Genres returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Genre'
/themes:
post:
operationId: queryThemes
summary: Twitch Query Themes
description: Query game themes using Apicalypse query language.
tags:
- Themes
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Themes returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Theme'
/screenshots:
post:
operationId: queryScreenshots
summary: Twitch Query Screenshots
description: Query game screenshots using Apicalypse query language.
tags:
- Media
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Screenshots returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Screenshot'
/artworks:
post:
operationId: queryArtworks
summary: Twitch Query Artworks
description: Query game artworks using Apicalypse query language.
tags:
- Media
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Artworks returned successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Artwork'
/game_videos:
post:
operationId: queryGameVideos
summary: Twitch Query Game Videos
description: Query game video references using Apicalypse query language.
tags:
- Media
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Game videos returned
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GameVideo'
/covers:
post:
operationId: queryCovers
summary: Twitch Query Covers
description: Query game cover art using Apicalypse query language.
tags:
- Media
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Covers returned
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Cover'
/involved_companies:
post:
operationId: queryInvolvedCompanies
summary: Twitch Query Involved Companies
description: Query companies involved in game development or publishing.
tags:
- Companies
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Involved companies returned
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InvolvedCompany'
/release_dates:
post:
operationId: queryReleaseDates
summary: Twitch Query Release Dates
description: Query game release dates across platforms and regions.
tags:
- Games
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Release dates returned
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ReleaseDate'
/search:
post:
operationId: multiSearch
summary: Twitch Multi-Search
description: Search across multiple IGDB resources simultaneously.
tags:
- Search
parameters:
- $ref: '#/components/parameters/clientId'
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Search results returned
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
game:
type: integer
components:
securitySchemes:
oauth2:
type: oauth2
description: Twitch OAuth2 Client Credentials for IGDB access
flows:
clientCredentials:
tokenUrl: https://id.twitch.tv/oauth2/token
scopes: {}
parameters:
clientId:
name: Client-ID
in: header
required: true
schema:
type: string
description: Twitch application client ID
responses:
Unauthorized:
description: Authentication required or token is invalid
schemas:
Game:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
summary:
type: string
storyline:
type: string
rating:
type: number
format: double
rating_count:
type: integer
aggregated_rating:
type: number
format: double
aggregated_rating_count:
type: integer
total_rating:
type: number
format: double
total_rating_count:
type: integer
first_release_date:
type: integer
description: Unix timestamp
category:
type: integer
description: '0=main_game, 1=dlc_addon, 2=expansion, 3=bundle, 4=standalone_expansion, 5=mod, 6=episode, 7=season, 8=remake, 9=remaster, 10=expanded_game, 11=port, 12=fork, 13=pack, 14=update'
status:
type: integer
description: '0=released, 2=alpha, 3=beta, 4=early_access, 5=offline, 6=cancelled, 7=rumored, 8=delisted'
genres:
type: array
items:
type: integer
platforms:
type: array
items:
type: integer
themes:
type: array
items:
type: integer
cover:
type: integer
screenshots:
type: array
items:
type: integer
artworks:
type: array
items:
type: integer
videos:
type: array
items:
type: integer
involved_companies:
type: array
items:
type: integer
franchises:
type: array
items:
type: integer
collection:
type: integer
similar_games:
type: array
items:
type: integer
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Platform:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
abbreviation:
type: string
alternative_name:
type: string
category:
type: integer
description: '1=console, 2=arcade, 3=platform, 4=operating_system, 5=portable_console, 6=computer'
generation:
type: integer
platform_family:
type: integer
platform_logo:
type: integer
summary:
type: string
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Company:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
description:
type: string
country:
type: integer
logo:
type: integer
start_date:
type: integer
url:
type: string
developed:
type: array
items:
type: integer
published:
type: array
items:
type: integer
parent:
type: integer
created_at:
type: integer
updated_at:
type: integer
Character:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
description:
type: string
gender:
type: integer
description: '0=Male, 1=Female, 2=Other'
species:
type: integer
description: '1=Human, 2=Alien, 3=Animal, 4=Android, 5=Unknown'
mug_shot:
type: integer
games:
type: array
items:
type: integer
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Collection:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
games:
type: array
items:
type: integer
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Franchise:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
games:
type: array
items:
type: integer
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Genre:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Theme:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
url:
type: string
created_at:
type: integer
updated_at:
type: integer
Screenshot:
type: object
properties:
id:
type: integer
game:
type: integer
image_id:
type: string
url:
type: string
width:
type: integer
height:
type: integer
Artwork:
type: object
properties:
id:
type: integer
game:
type: integer
image_id:
type: string
url:
type: string
width:
type: integer
height:
type: integer
GameVideo:
type: object
properties:
id:
type: integer
game:
type: integer
name:
type: string
video_id:
type: string
description: YouTube video ID
Cover:
type: object
properties:
id:
type: integer
game:
type: integer
image_id:
type: string
url:
type: string
width:
type: integer
height:
type: integer
InvolvedCompany:
type: object
properties:
id:
type: integer
company:
type: integer
game:
type: integer
developer:
type: boolean
publisher:
type: boolean
porting:
type: boolean
supporting:
type: boolean
created_at:
type: integer
updated_at:
type: integer
ReleaseDate:
type: object
properties:
id:
type: integer
game:
type: integer
platform:
type: integer
date:
type: integer
description: Unix timestamp
region:
type: integer
description: '1=Europe, 2=North America, 3=Australia, 4=New Zealand, 5=Japan, 6=China, 7=Asia, 8=Worldwide, 9=Korea, 10=Brazil'
category:
type: integer
description: '0=YYYYMMMMDD, 1=YYYYMMMM, 2=YYYY, 3=YYYYQ1, 4=YYYYQ2, 5=YYYYQ3, 6=YYYYQ4, 7=TBD'
human:
type: string
description: Human-readable date string
created_at:
type: integer
updated_at:
type: integer