GraphQL Schema Reference¶

This reference documents the query signatures, type definitions, and relationships in the Nostalgia GraphQL API schema.

Query Signatures¶

The root Query type exposes the following entry points:

`release(id: Int!): Release`¶

Fetch a single release by its unique release ID.

query {
  release(id: 12345) {
    releaseId
    title
    system
    score
  }
}

`releases(system: String, genre: String, region: String, search: String, limit: Int, offset: Int): [Release!]!`¶

List releases matching the optional filters.

Argument	Type	Description
`system`	String	Filter by system code (case-insensitive, e.g., `"SNES"`, `"NES"`)
`genre`	String	Filter by genre (ILIKE match, e.g., `"RPG"`, `"Platformer"`)
`region`	String	Filter by region (ILIKE match, e.g., `"USA"`, `"Japan"`)
`search`	String	Search by title (ILIKE match)
`limit`	Int	Max results to return (1-100, default 20)
`offset`	Int	Number of results to skip (for pagination)

query {
  releases(system: "SNES", genre: "RPG", limit: 10) {
    title
    score
    developer
  }
}

`rom(id: Int!): Rom`¶

Fetch a single ROM by its unique ROM ID.

`roms(systemId: Int, crc: String, md5: String, sha1: String, filename: String, limit: Int, offset: Int): [Rom!]!`¶

List ROM files matching the optional filters.

Argument	Type	Description
`systemId`	Int	Filter by system ID
`crc`	String	Filter by CRC32 hash (case-insensitive)
`md5`	String	Filter by MD5 hash (case-insensitive)
`sha1`	String	Filter by SHA1 hash (case-insensitive)
`filename`	String	Filter by filename (ILIKE match)
`limit`	Int	Max results (1-100, default 20)
`offset`	Int	Pagination offset

Type Reference¶

Release¶

Field	Type	Description
`releaseId`	Int	Unique release identifier
`title`	String	Game title
`system`	String	System short code (e.g., `"SNES"`)
`systemName`	String	Full system name (e.g., `"Super Nintendo"`)
`region`	String	Release region
`genre`	String	Primary genre
`genre2`	String	Secondary genre
`description`	String	Short description
`advancedDescription`	String	Detailed description
`developer`	String	Developer name
`publisher`	String	Publisher name
`releaseDate`	String	General release date
`dateUs`	String	US release date
`dateJp`	String	Japan release date
`dateEu`	String	Europe release date
`score`	Int	Rating or score (0-100)
`players`	String	Player count
`online`	Boolean	Online multiplayer support
`discCount`	Int	Number of discs
`series`	String	Series identifier
`seriesName`	String	Series name
`gameType`	String	Game type classification
`qualityScore`	Float	Internal quality score
`imageUrl(type: ImageType!)`	String	Presigned image URL (valid 15 min)
`videoUrl`	String	Presigned video URL (valid 15 min)
`rom`	Rom	Associated ROM data
`reviews`	[Review]	User and critic reviews
`otherRegions`	[Release]	Same game in other regions
`otherSystems`	[Release]	Same game on other platforms

ImageType Enum¶

Available image types for the imageUrl field:

front, back, cart, main, screenshot, screenshottitle, texture, video, manual, wheel, wheelcarbon, wheelsteel, marquee, marqueesmall, smallmarquee, box3d, boxtexture, side

query {
  release(id: 12345) {
    title
    imageUrl(type: front)
    imageUrl(type: screenshot)
  }
}

Image URL Lifespan

Image and video URLs are presigned S3 URLs valid for 15 minutes (900 seconds) from time of generation. Do not store these URLs permanently in database caches; query the API dynamically to obtain fresh URLs.

Rom¶

Field	Type	Description
`romId`	Int	Unique ROM identifier
`filename`	String	Full filename
`filenameNoExt`	String	Filename without extension
`size`	Int	File size in bytes
`crc`	String	CRC32 hash
`md5`	String	MD5 hash
`sha1`	String	SHA1 hash
`language`	String	ROM language
`region`	String	ROM region
`serial`	String	Serial number
`parent`	String	Parent ROM identifier
`header`	String	Header data
`dumpSource`	String	Dump source
`system`	System	Associated system
`releases`	[Release]	Associated releases

System¶

Field	Type	Description
`systemId`	Int	Unique system identifier
`name`	String	Full system name
`shortName`	String	Short code (e.g., `"SNES"`)
`manufacturer`	String	Hardware manufacturer
`releaseYear`	Int	Year of release
`generation`	Int	Console generation
`mediaType`	String	Media type (cartridge, CD, etc.)
`region`	String	System region
`unitsSold`	String	Units sold worldwide
`specs`	String	Hardware specifications
`description`	String	System description
`downloadUrl`	String	Presigned SQLite DB download URL (valid 1 hour)

Review¶

Field	Type	Description
`id`	Int	Review identifier
`title`	String	Review title
`body`	String	Review content
`rating`	Float	Review rating
`source`	String	Review source (publication)
`author`	String	Review author
`date`	String	Review date
`platform`	String	Reviewed on platform
`url`	String	Source URL
`type`	String	Review type
`createdAt`	String	Record creation date