Introduction

The Dbljump API stores and serves structured information about video games, their releases, creators, platforms, places, images, and sources.

The API follows the JSON:API specification for normal resource endpoints. Authentication handoffs and the health endpoint use small, purpose-specific JSON responses.

Base URL

All paths in this reference are relative to:

https://www.dbljump.com

For example:

GET https://www.dbljump.com/games

Use HTTPS for all production requests.

Resource types

JSON:API resource types are singular and camel-cased where necessary. Examples include game, gameVersion, companyAlias, mediaLicense, and user.

Roles

Role	Description
member	Can authenticate and manage their own user account.
editor	Includes member access and can create or edit articles and most article data.
admin	Full access, including administrative catalog records and destructive operations.

Read endpoints are public unless a resource section says otherwise.

Requests and responses

Headers

Typical authenticated request

GET https://www.dbljump.com/games
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Authorization: Bearer {token}

Send Accept: application/vnd.api+json. Send Content-Type: application/vnd.api+json when the request has a JSON:API body. The old custom version media-type parameter is no longer used.

Authenticated requests use Authorization: Bearer {token}. Do not send an Authorization header for signed-out requests.

JSON:API document shape

Minimal create request

{
  "data": {
    "type": "game",
    "attributes": {
      "displayTitle": "New Game",
      "description": "A short description."
    }
  }
}

Relationship linkage

{
  "relationships": {
    "holder": {
      "data": { "type": "company", "id": "12" }
    }
  }
}

Create requests use POST; successful responses return 201 Created. Update requests use PATCH, must include the resource id, and return 200 OK. Deletes return 204 No Content.

Serialized attribute, relationship, filter, sort, and include names use lower camel case. IDs are strings in JSON:API documents.

Collections

All collection endpoints are paginated. The default page size is 30.

Query	Purpose	Example
`page[size]`	Records per page	`?page[size]=20`
`page[number]`	One-based page number	`?page[number]=2`
`sort`	Sort by one or more allowed fields; prefix descending fields with `-`	`?sort=displayTitle,-originYear`
`filter[{field}{predicate}]`	Filter using an allowed field and Ransack predicate	`?filter[slugEq]=pong`
`search`	Full-text search on supported collections	`?search=nintendo`
`include`	Include related resources	`?include=createdBy,primaryImage`
`fields[{type}]`	Sparse fieldset	`?fields[game]=displayTitle,slug`

Collection responses include pagination information under meta.pagination, including records, current, first, prev, next, last, and pages when applicable.

Filtering

The most common predicate is Eq, meaning equality. Other Ransack predicates such as Cont, Gteq, and Lteq can be used with fields listed as queryable in this reference.

The API accepts camel-case query names and converts them internally. Special relationship filters include:

GET /games?filter[genreIdEq]={id}
GET /games?filter[platformIdEq]={id}
GET /images?filter[articleIdEq]={id}
GET /game-version-releases?filter[gameIdEq]={id}

A collection query using filter[slugEq] returns 404 Not Found rather than an empty collection when no record matches.

Search

search is supported for articles, games, companies, people, users, platforms, genres, places, and images.

Metadata

All normal resources include createdAt and updatedAt in meta. Article metadata also includes status, articleType, and keywords. Several resources add relationship totals under meta.total.

Single-record examples

These examples show the current response shape for representative resources. Exact IDs, timestamps, URLs, relationship counts, and included resources depend on the database and the query parameters.

Game response

GET https://www.dbljump.com/games/pong

{
  "data": {
    "id": "45",
    "type": "game",
    "attributes": {
      "slug": "pong",
      "displayTitle": "Pong",
      "description": "Pong is an early table-tennis video game.",
      "originDate": "1972-11-29",
      "originYear": 1972,
      "ended": null,
      "thumbnail": "https://www.dbljump.com/uploads/images/87/th_pong.jpg"
    },
    "relationships": {
      "platforms": {
        "data": [
          { "id": "4", "type": "platform" }
        ]
      },
      "genres": {
        "data": [
          { "id": "2", "type": "genre" }
        ]
      },
      "versions": {
        "data": [
          { "id": "71", "type": "gameVersion" }
        ]
      },
      "aliases": {
        "data": []
      },
      "notes": {
        "data": []
      },
      "companyCredits": {
        "data": [
          { "id": "108", "type": "companyCredit" }
        ]
      },
      "personCredits": {
        "data": []
      },
      "images": {
        "data": [
          { "id": "87", "type": "image" }
        ]
      },
      "primaryImage": {
        "data": { "id": "87", "type": "image" }
      },
      "headerImage": {
        "data": null
      },
      "createdBy": {
        "data": { "id": "1", "type": "user" }
      },
      "lastUpdatedBy": {
        "data": { "id": "1", "type": "user" }
      }
    },
    "meta": {
      "status": "published",
      "articleType": "game",
      "keywords": "Pong, 1972",
      "createdAt": "2026-01-12T10:30:00.000Z",
      "updatedAt": "2026-07-20T14:15:00.000Z",
      "total": {
        "images": 1,
        "versions": 1,
        "notes": 0,
        "genres": 1,
        "companyCredits": 1,
        "personCredits": 0
      }
    }
  }
}

Relationship objects contain resource linkage. Add include, for example ?include=genres,primaryImage, to return the related records in the top-level included array.

Game-version response

GET https://www.dbljump.com/game-versions/71

{
  "data": {
    "id": "71",
    "type": "gameVersion",
    "attributes": {
      "status": "extant",
      "interfaces": [
        "traditional"
      ],
      "audioChannels": 1.0,
      "audioSystem": "mono",
      "videoFpsTarget": 60,
      "videoFpsUnlocked": false,
      "videoResW": 640,
      "videoResH": 480,
      "videoResUnlocked": false,
      "videoInterlaced": false,
      "videoAspectRatio": "1.333",
      "videoHdr": false,
      "videoStereoscopic": false,
      "videoDynamicScaling": false,
      "playLocal": true,
      "playersLocalMin": 2,
      "playersLocalMax": 2,
      "playLocalVs": true,
      "playLocalCoOp": false,
      "playLocalTeams": false,
      "playLan": false,
      "playersLanMin": null,
      "playersLanMax": null,
      "playLanVs": false,
      "playLanCoOp": false,
      "playLanTeams": false,
      "playOnline": false,
      "playersOnlineMin": null,
      "playersOnlineMax": null,
      "playOnlineVs": false,
      "playOnlineCoOp": false,
      "playOnlineTeams": false
    },
    "relationships": {
      "game": {
        "data": { "id": "45", "type": "game" }
      },
      "platform": {
        "data": { "id": "4", "type": "platform" }
      },
      "releases": {
        "data": [
          { "id": "83", "type": "gameVersionRelease" }
        ]
      },
      "notes": {
        "data": []
      }
    },
    "meta": {
      "createdAt": "2026-02-02T09:00:00.000Z",
      "updatedAt": "2026-05-18T16:42:00.000Z"
    }
  }
}

Image response

GET https://www.dbljump.com/images/pong-arcade-screen

{
  "data": {
    "id": "87",
    "type": "image",
    "attributes": {
      "base64Image": null,
      "original": "https://www.dbljump.com/uploads/images/87/pong.jpg",
      "thumb": "https://www.dbljump.com/uploads/images/87/th_pong.jpg",
      "kind": "screen",
      "title": "Pong arcade screen",
      "description": "A gameplay screen from the arcade release.",
      "height": 1080,
      "width": 1920,
      "size": "lg",
      "year": 1972,
      "date": null,
      "usageType": "fair",
      "attributedName": "Atari",
      "attributedUrl": null,
      "sourceUrl": "https://example.org/pong",
      "slug": "pong-arcade-screen"
    },
    "relationships": {
      "mediaLicense": {
        "data": null
      },
      "place": {
        "data": { "id": "840", "type": "place" }
      },
      "articles": {
        "data": [
          { "id": "45", "type": "article" }
        ]
      },
      "uploadedBy": {
        "data": { "id": "1", "type": "user" }
      },
      "lastUpdatedBy": {
        "data": { "id": "1", "type": "user" }
      }
    },
    "meta": {
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-10T12:00:00.000Z",
      "total": {
        "articles": 1
      }
    }
  }
}

The base64Image input is never echoed back. Consumers should use original or thumb.

External-resource response

GET https://www.dbljump.com/ext-resources/204

{
  "data": {
    "id": "204",
    "type": "extResource",
    "attributes": {
      "kind": "web_article",
      "title": "The history of Pong",
      "authorNames": [
        {
          "family": "Example",
          "given": "Alex"
        }
      ],
      "volumeTitle": "Game History Journal",
      "doi": null,
      "publisher": "Example Publishing",
      "year": 2024,
      "date": "2024-06-12",
      "sortDate": "2024-06-12",
      "urlOriginal": "https://example.org/history-of-pong",
      "urlArchived": "https://example.org/archive/history-of-pong",
      "lastAccessedAt": "2026-07-28T10:15:00.000Z",
      "approvedAt": "2026-07-29T08:00:00.000Z",
      "flaggedAt": null,
      "pageNumbersBegin": null,
      "pageNumbersEnd": null
    },
    "relationships": {
      "createdBy": {
        "data": { "id": "1", "type": "user" }
      },
      "notes": {
        "data": [
          { "id": "19", "type": "gameNote" }
        ]
      }
    },
    "meta": {
      "createdAt": "2026-07-28T10:15:00.000Z",
      "updatedAt": "2026-07-29T08:00:00.000Z"
    }
  }
}

Authentication

Request

POST https://www.dbljump.com/user-authentications

{
  "data": {
    "type": "userAuthentication",
    "attributes": {
      "email": "member@example.com",
      "password": "correct horse battery staple",
      "rememberMe": true
    }
  }
}

POST /user-authentications signs in an activated user. On success it returns 200 OK, a small user resource, and an Authorization: Bearer {token} response header. Store that complete header value and send it with subsequent authenticated requests.

rememberMe defaults to false and controls the token lifetime.

JWT payload

New tokens use the standard exp expiry claim and include the user’s ID and role. The server also accepts legacy tokens containing expiry.

An invalid token returns TOKEN_INVALID; an expired token returns TOKEN_EXPIRED.

Authentication handoff

Authentication handoffs transfer a signed-in session between Dbljump clients without exposing the current JWT in a URL.

Create a handoff

POST /authentication-handoffs

Requires a valid bearer token. Returns 201 Created:

{
  "code": "single-use-short-lived-code"
}

Exchange a handoff

Request

POST https://www.dbljump.com/authentication-handoffs/exchange

{
  "code": "single-use-short-lived-code"
}

The exchange is unauthenticated. A valid, unused code returns 200 OK:

{
  "authHeader": "Bearer {token}",
  "data": {
    "type": "users",
    "id": "42",
    "attributes": {
      "username": "player",
      "avatarThumb": "https://www.dbljump.com/uploads/user_avatar/42/thumb.jpg"
    }
  }
}

Codes expire after five minutes and can be exchanged only once. Both handoff responses disable caching. Missing, expired, or reused codes return 401.

Articles

Articles provide a combined read-only collection of games, companies, and people.

Method	Path	Description
GET	`/articles`	List all article types together.

Use the dedicated /games, /companies, and /people endpoints to fetch or modify a single typed article.

Attributes

Attribute	Description
`slug`	URL-friendly identifier generated from the display title.
`displayTitle`	Public title.
`description`	Summary of up to 800 characters.
`originDate`	Exact date of origin, when known.
`originYear`	Origin year; derived from `originDate` when a date is supplied.
`ended`	Whether the company or person’s activity has ended.
`thumbnail`	Thumbnail URL derived from the primary image.

Relationships

images, primaryImage, headerImage, createdBy, and lastUpdatedBy.

Queryable fields

id, type, displayTitle, sortTitle, slug, kind, originDate, originSortDate, originYear, ended, status, createdById, primaryImageId, headerImageId, createdAt, and updatedAt.

Find a single article by slug through the collection

GET https://www.dbljump.com/articles?filter[slugEq]=pong

Games

Games are the central articles in the database. A game can have multiple platform versions, releases, aliases, notes, images, genres, and credits.

Method	Path	Authorization
GET	`/games`	Public
GET	`/games/{id-or-slug}`	Public
POST	`/games`	Editor
PATCH	`/games/{id-or-slug}`	Editor
DELETE	`/games/{id-or-slug}`	Admin, or the editor who created an unpublished game

The JSON:API type is game.

Writable attributes

Attribute	Create	Update	Description
`displayTitle`	Yes	Yes	Required; 1–250 characters.
`description`	Yes	Yes	Optional; maximum 800 characters.
`originDate`	Yes	Yes	Date from 1800 onward.
`originYear`	Yes	Yes	Year from 1800 onward.

Writable relationships

Updates additionally accept genres, primaryImage, headerImage, and images. These relationships are intentionally not accepted during creation.

Response relationships

platforms, genres, versions, aliases, notes, companyCredits, personCredits, images, primaryImage, headerImage, createdBy, and lastUpdatedBy.

Querying games

Games use the article queryable fields. They also support genreIdEq and platformIdEq; when both are supplied, only games matching both are returned.

Filter by genre and platform

GET https://www.dbljump.com/games?filter[genreIdEq]=3&filter[platformIdEq]=8

Create a game

POST https://www.dbljump.com/games

{
  "data": {
    "type": "game",
    "attributes": {
      "displayTitle": "New Game",
      "description": "A concise description of the game.",
      "originYear": 2026
    }
  }
}

New games begin with draft status. Status is returned in article metadata and is not directly writable by this endpoint.

Companies

Companies describe publishers, developers, technology firms, and other organizations associated with games.

Method	Path	Authorization
GET	`/companies`	Public
GET	`/companies/{id-or-slug}`	Public
POST	`/companies`	Editor
PATCH	`/companies/{id-or-slug}`	Editor
DELETE	`/companies/{id-or-slug}`	Admin, or the editor who created an unpublished company

The JSON:API type is company.

Writable attributes

displayTitle (required, 1–250 characters), description (maximum 800 characters), originDate, originYear, ended, endDate, and endYear.

Dates and years begin at 1800. endDate and endYear describe when the organization ceased operating.

Writable relationships

originPlace, latestPlace, primaryImage, headerImage, and images.

Response-only fields and relationships

shortName is derived from the newest active styled alias, falling back to displayTitle.

Relationships include aliases, notes, credits, parentKinships, childKinships, platforms, originPlace, latestPlace, the common article image relationships, createdBy, and lastUpdatedBy.

Companies use the article queryable fields plus endDate, endSortDate, and endYear.

People

People describe individuals credited in the video game industry.

Method	Path	Authorization
GET	`/people`	Public
GET	`/people/{id-or-slug}`	Public
POST	`/people`	Editor
PATCH	`/people/{id-or-slug}`	Editor
DELETE	`/people/{id-or-slug}`	Admin, or the editor who created an unpublished person

The JSON:API type is person.

Writable attributes

Attribute	Description
`givenNames`	Required on create; maximum 50 characters.
`familyName`	Optional; maximum 50 characters.
`displayTitle`	Accepted; on create it is generated from the supplied names.
`description`	Optional biography summary; maximum 800 characters.
`gender`	Optional free text; maximum 25 characters.
`originDate`, `originYear`	Birth date or year.
`ended`, `endDate`, `endYear`	Whether and when the person’s life ended.

Writable relationships

originPlace, latestPlace, primaryImage, headerImage, and images.

Response relationships include aliases, notes, credits, the place and image relationships, createdBy, and lastUpdatedBy.

People use the article queryable fields plus gender, endDate, endSortDate, and endYear.

Article data

Aliases, notes, credits, and company kinships use independent, non-nested endpoints. Their IDs are numeric. All reads are public; create, update, and delete operations require an editor unless stated otherwise.

Aliases

Resource	Path	JSON:API type
Game alias	`/game-aliases`	`gameAlias`
Company alias	`/company-aliases`	`companyAlias`
Person alias	`/person-aliases`	`personAlias`

Each supports GET collection, GET /{id}, POST, PATCH /{id}, and DELETE /{id}.

Common writable fields are displayText, kind, and writingSystem. writingSystem must be one of Arab, Hang, Hans, Hant, Cyrl, Grek, Hebr, Jpan, Latn, or Thai.

Alias	Extra fields	Allowed `kind`
Game	`gameVersions` relationship	`official`, `working`, `translated`, `AKA`
Company	`yearAdopted`, `dropped`, `yearDropped`	`official`, `styled`, `AKA`
Person	`givenNames`, `familyName`, `yearAdopted`, `dropped`, `yearDropped`	`official`, `full`, `AKA`

All aliases require an article relationship and may have places.

Queryable fields are id, articleId, displayText, familyName, givenNames, kind, writingSystem, yearAdopted, yearDropped, dropped, createdAt, and updatedAt.

Notes

Resource	Path	JSON:API type
Game note	`/game-notes`	`gameNote`
Company note	`/company-notes`	`companyNote`
Person note	`/person-notes`	`personNote`

Each supports the full CRUD set.

Writable fields are category, heading, body, spoiler, and displayOrder. Notes require an article relationship. Game notes can also relate to gameVersions. Notes may be linked to extResources.

The body is Markdown, 5–5000 characters, and is returned both as body and sanitized bodyHtml. External links are rejected in note Markdown; cite an external resource through extResources instead. heading is at most 40 characters. If omitted during creation, displayOrder is appended automatically within its article and category.

Note type	Allowed categories
Game	`game`, `story`, `development`, `publishing`, `visuals`, `sound`, `addons`, `tech`, `profile`, `sales`, `impact`
Company	`history`, `organization`, `products`, `profile`, `sales`, `impact`
Person	`bio`, `education`, `career`, `views`, `profile`, `impact`

Queryable fields are id, articleId, type, category, heading, displayOrder, spoiler, extResources, createdById, createdAt, and updatedAt.

Credits

Resource	Path	JSON:API type
Company credit	`/company-credits`	`companyCredit`
Person credit	`/person-credits`	`personCredit`

Both support the full CRUD set. Writable attributes are role, category, and leading. Required relationships are credited and game; optional many-valued relationships are places and gameVersions.

Company credit categories are publishing, development, technology, visuals, sound, language, special, and misc.

Person credit categories are creative, development, technology, visuals, sound, language, special, and misc.

Queryable fields are id, creditedId, gameId, placeId, role, category, leading, createdAt, and updatedAt.

Company kinships

/company-kinships uses type companyKinship and supports full CRUD. Kinships connect a parent company and a different child company.

Writable fields are kind, startYear, and endYear. kind is ownership or division; years start at 1800 and the end cannot precede the start.

Queryable fields are id, parentId, childId, kind, startYear, endYear, createdAt, and updatedAt.

Game versions and releases

Game versions

/game-versions uses JSON:API type gameVersion and supports:

Method	Path	Authorization
GET	`/game-versions`	Public
GET	`/game-versions/{id}`	Public
POST	`/game-versions`	Editor
PATCH	`/game-versions/{id}`	Editor
DELETE	`/game-versions/{id}`	Editor

Every version requires one game and one platform. A game can have only one version per platform.

Writable attributes

Group	Attributes
General	`status`, `interfaces`, `audioChannels`, `audioSystem`
Video	`videoFpsTarget`, `videoFpsUnlocked`, `videoResW`, `videoResH`, `videoResUnlocked`, `videoInterlaced`, `videoAspectRatio`, `videoHdr`, `videoStereoscopic`, `videoDynamicScaling`
Local play	`playLocal`, `playersLocalMin`, `playersLocalMax`, `playLocalVs`, `playLocalCoOp`, `playLocalTeams`
LAN play	`playLan`, `playersLanMin`, `playersLanMax`, `playLanVs`, `playLanCoOp`, `playLanTeams`
Online play	`playOnline`, `playersOnlineMin`, `playersOnlineMax`, `playOnlineVs`, `playOnlineCoOp`, `playOnlineTeams`

status is extant, rumored, canceled, or unknown. interfaces accepts traditional, touch, motion, vision, vr, ar, camera, trackball, pressure, lightgun, vehicle, custom, or 3d.

Player counts are cleared when their corresponding playLocal, playLan, or playOnline flag is false. Each maximum must be at least its minimum.

Response relationships are game, platform, releases, and notes.

Queryable fields are id, gameId, platformId, status, videoFpsTarget, videoFpsUnlocked, videoResW, videoResH, videoResUnlocked, createdAt, and updatedAt.

Game version releases

/game-version-releases uses type gameVersionRelease and supports the full CRUD set, with editor authorization for writes.

Writable fields are date, year, physical, and digital. Each release requires a version relationship and at least one places relationship. Dates and years may be up to three years in the future. A version cannot have two releases with the same derived sort date.

Responses include version, game, platform, and places.

Queryable fields are id, versionId, placeId, date, year, physical, digital, sortDate, createdAt, and updatedAt. Use filter[gameIdEq] to return releases belonging to any version of a game.

Platforms and genres

Platforms

Platforms represent hardware, operating systems, streaming services, and other environments on which a game version runs.

/platforms uses type platform and supports full CRUD. Reads are public, editors can create and update, and only admins can delete.

Writable fields are:

Attribute	Requirements
`name`	Required, unique, maximum 50 characters.
`shortName`	Optional, unique, maximum 18 characters.
`sphere`	`arcade`, `cloud`, `home`, `mobile`, `non-gaming`, or `portable`.
`kind`	`add-on`, `OS`, `streaming`, or `system`.

Every platform requires a holder company relationship. Responses also include games, createdBy, and lastUpdatedBy.

Queryable fields are id, name, shortName, sphere, kind, slug, holderId, createdById, createdAt, and updatedAt.

Genres

/genres uses type genre and supports full CRUD. Reads are public; only admins can create, update, or delete genres.

Writable fields are name and shortName. Responses also provide the generated slug and relationships to games, createdBy, and lastUpdatedBy.

Queryable fields are id, name, shortName, slug, createdById, createdAt, and updatedAt.

Places

/places contains geographical regions, countries, subdivisions, and localities. The JSON:API type is place.

Method	Path	Authorization
GET	`/places`	Public
GET	`/places/{id-or-slug}`	Public
POST	`/places`	Editor for localities; admin for all other kinds
PATCH	`/places/{id-or-slug}`	Admin, or the editor who created the locality
DELETE	`/places/{id-or-slug}`	Admin, or the editor who created the locality

Writable fields

kind is required on create and selects the underlying place type. It must be region, country, subdivision, or locality; it cannot be changed later.

Other writable attributes are slug, name, latitude, longitude, and isoCode. Writable relationships are parent, regions, and children.

Responses also include shortName, formatted, createdBy, and lastUpdatedBy. The retired nested /places/{slug}/children and /places/{slug}/regions routes have been replaced by these relationships and collection filters.

Queryable fields are id, name, formatted, type, kind, isoCode, slug, latitude, longitude, parentId, createdById, createdAt, and updatedAt.

Media

Images

/images replaces the old /media/images path. Its JSON:API type is image.

Reads are public. Editors can create and update images. Admins can delete any image; an editor can delete an image they uploaded.

Writable attributes

Attribute	Description
`base64Image`	Required on create; a `data:image/...;base64,...` string. It cannot be changed later.
`kind`	Required: `artwork`, `boxart`, `doc`, `logo`, `photo`, `poster`, or `screen`.
`title`	Required; maximum 100 characters.
`description`	Optional; maximum 500 characters.
`year`, `date`	Image creation date, from 1800 through the present.
`usageType`	`free`, `fair`, or `licensed`.
`attributedName`, `attributedUrl`	Credit for the image creator or owner.
`sourceUrl`	Original source.

Writable relationships are mediaLicense, place, articles, games, companies, and people.

Responses include original, thumb, height, width, size, slug, uploadedBy, and lastUpdatedBy. base64Image is always returned as null.

Queryable fields are id, kind, title, year, date, sortDate, usageType, width, height, size, placeId, mediaLicenseId, uploadedById, slug, createdAt, and updatedAt. Use filter[articleIdEq] to find images linked to an article.

External resources

/ext-resources is used for citations and other material outside Dbljump. The JSON:API type is extResource.

Reads are public. Editors can create and update; only admins can delete.

Writable attributes are kind, title, authorNames, volumeTitle, doi, publisher, year, date, sortDate, urlOriginal, urlArchived, pageNumbersBegin, and pageNumbersEnd. A notes relationship can link the source to notes.

kind must be book, print_article, twitter, web_article, webpage, website, or youtube. urlOriginal is required for every kind except book and print_article. Page numbers are integers from 1–10000; supplying only the beginning creates a one-page range.

The response also exposes lastAccessedAt, approvedAt, and flaggedAt, which are currently response-only, plus createdBy.

Queryable fields are id, kind, title, year, date, sortDate, urlOriginal, urlArchived, volumeTitle, doi, publisher, lastAccessedAt, approvedAt, flaggedAt, createdById, createdAt, and updatedAt.

Media licenses

/media-licenses replaces /media/licenses and uses type mediaLicense. Reads are public; only admins can create, update, or delete.

Writable attributes are name (required, unique, maximum 100 characters), shortName (required, unique, maximum 15 characters), and url (required, unique, maximum 250 characters). Responses include image totals in metadata.

Users

User resources

/users uses type user.

Method	Path	Authorization
GET	`/users`	Public
GET	`/users/{id}`	Public
POST	`/users`	Public registration
PATCH	`/users/{id}`	Same user or admin
DELETE	`/users/{id}`	Same user, or admin deleting a non-admin

Registration

Writable registration fields are email, username, password, passwordConfirmation, acceptedTerms, and editorRequest.

Email must be valid and unique. Username must be unique, contain only letters, numbers, underscores, or dots, begin and end with a letter or number, and be 2–12 characters. Password must be 8–24 characters. Terms acceptance is required.

Registration returns 201 Created and sends an activation email.

Updating a user

A user or admin can write unconfirmedEmail, username, acceptedTerms, base64Image, removeAvatar, givenNames, familyName, gender, birthday, place, password, and passwordConfirmation.

Only admins can also write role and editorRequestApproved. Roles are member, editor, and admin.

Email and administrative metadata are returned only to the same user or an admin. Public responses include username, role, names, gender, birthday, avatar, avatarThumb, and place.

Queryable fields are id, username, gender, role, placeId, editorRequestOpen, lastSignedInAt, activatedAt, birthday, lastActiveAt, createdAt, and updatedAt.

Account activation

POST /user-activations activates an account using email and activationToken. It returns the activated user with 200 OK.

PATCH /user-activations requests a replacement activation email using email. It returns 204 No Content.

Both operations are unauthenticated.

Email confirmation

POST /email-confirmations confirms a pending email-address change. Send unconfirmedEmail and confirmToken in a JSON:API document. The user must already be activated. Success returns the updated user with 200 OK.

Password reset

POST /user-passwords requests a password-reset email. Send email; success returns 204 No Content.

PATCH /user-passwords completes the reset. Send email, password, and passwordResetToken; success returns 204 No Content.

Both password operations are unauthenticated.

Special endpoints

Reorder article notes

PATCH /article-note-orders/{id} atomically reorders every note in one article category. It requires an editor and returns 204 No Content.

The resource ID is {article-type}-{article-id}-{category}, for example game-45-development. Article type is game, company, or person.

Reorder all development notes for game 45

PATCH https://www.dbljump.com/article-note-orders/game-45-development

{
  "data": {
    "type": "article_note_order",
    "id": "game-45-development",
    "attributes": {
      "category": "development"
    },
    "relationships": {
      "article": {
        "data": { "type": "game", "id": "45" }
      },
      "notes": {
        "data": [
          { "type": "game_note", "id": "19" },
          { "type": "game_note", "id": "12" }
        ]
      }
    }
  }
}

Unlike normal serialized resources, this endpoint validates its raw resource identifiers and therefore requires the snake-case types shown above.

The request must contain every note in the category exactly once. IDs must be unique and must all belong to the specified article and category. An invalid set returns 422 INVALID_NOTE_ORDER; a mismatched URL or resource identity returns 409 RESOURCE_MISMATCH.

Health

GET /health is a lightweight service health check. A healthy application returns 200 OK with an empty body.

Errors

JSON:API errors are returned in an errors array.

Validation error

{
  "errors": [
    {
      "status": 422,
      "code": "blank",
      "source": {
        "pointer": "/data/attributes/displayTitle"
      },
      "title": "can't be blank"
    }
  ]
}

Status	Meaning
400	Malformed or incomplete request data.
401	Missing/invalid authentication or insufficient authorization.
404	Record not found.
409	Request resource identity conflicts with the URL.
422	Validation failed or the request is semantically invalid.
500	Mailer or other server-side operation failed.

Common application codes include BAD_REQUEST, REQUEST_DATA_MISSING, NOT_AUTHORIZED, TOKEN_INVALID, TOKEN_EXPIRED, USER_CREDENTIALS_INVALID, USER_ACTIVATION_REQUIRED, USER_ALREADY_ACTIVATED, INVALID_NOTE_ORDER, RESOURCE_MISMATCH, MAILER_ERROR, and SERVER_ERROR.

Validation error pointers use lower camel case and point to either /data/attributes/{name} or /data/relationships/{name}.

Introduction

Base URL

Resource types

Roles

Requests and responses

Headers

JSON:API document shape

Collections

Filtering

Search

Metadata

Single-record examples

Game response

Game-version response

Image response

External-resource response

Authentication

Sign in

JWT payload

Authentication handoff

Create a handoff

Exchange a handoff

Articles

Attributes

Relationships

Queryable fields

Games

Writable attributes

Writable relationships

Response relationships

Querying games

Companies

Writable attributes

Writable relationships

Response-only fields and relationships

People

Writable attributes

Writable relationships

Article data

Aliases

Notes

Credits

Company kinships

Game versions and releases

Game versions

Writable attributes

Game version releases

Platforms and genres

Platforms

Genres

Places

Writable fields

Media

Images

Writable attributes

External resources

Media licenses

Users

User resources

Registration

Updating a user

Account activation

Email confirmation

Password reset

Special endpoints

Reorder article notes

Health

Errors