List candidates

GET

/api/v1/candidates

Filterable on stage, status, reliability, bggId and isExpansion, e.g. stage==INTERPRETED;status==PENDING for the review queue.

Authorizations

• bearerAuth
  stx-game-catalog:candidate-read

Parameters

Query Parameters

limit

integer

>= 1 <= 100

Maximum number of items to return

cursor

string

Opaque cursor from a previous response’s nextCursor. Omit to fetch the first page. Clients must treat this value as opaque and only pass back what was previously returned.

filter

string

RSQL filter expression evaluated against this resource’s filterable fields. Combine multiple conditions with ; (AND) or , (OR), e.g. gameId==3fa85f64-...;playedAt=gt=2026-01-01T00:00:00Z. The set of filterable fields is documented per endpoint in the API reference; filtering on a field that isn’t in that whitelist returns 400 Bad Request.

sort

string

/^([a-zA-Z0-9_]+(:(ASC|DESC))?)(,([a-zA-Z0-9_]+(:(ASC|DESC))?))*$/

Sort order. Format: field:direction. Direction is ASC or DESC (default ASC if omitted). Use a comma-separated list for multi-column sorting; priority follows the parameter order.

Examples

Sort by a single column

playedAt:DESC

Sort by multiple columns

playedAt:DESC,status:ASC

Omitted direction defaults to ASC

status,playedAt:DESC

Responses

200

List of candidates

object

limit

required

Maximum number of items returned in this page

integer format: int32

prevCursor

Opaque cursor to pass as the cursor query parameter to fetch the previous page. Null when there is no previous results. Clients must not parse or construct this value.

string | null

nextCursor

Opaque cursor to pass as the cursor query parameter to fetch the next page. Null when there are no more results. Clients must not parse or construct this value.

string | null

items

required

Candidates in this page

Array<object>

object

id

required

string format: uuid

bggId

required

integer format: int64

displayName

required

Name of a game or expansion (game.display_name, candidate.display_name)

string

>= 1 characters <= 255 characters

description

Free text

string

<= 10000 characters

minPlayers

Number of players; the maximum is never below the minimum

integer format: int32

>= 1

maxPlayers

Number of players; the maximum is never below the minimum

integer format: int32

>= 1

playingTime

Playing time in minutes

integer format: int32

minAge

integer format: int32

yearPublished

integer format: int32

imageUrl

At most 500 characters (the column it is stored in); a longer URL is refused with 400. Not declared as maxLength: the services read a uri as a URI type, which length validation does not apply to, so they check the length themselves.

string format: uri

tags

required

Array<string>

<= 20 items unique items

isExpansion

required

boolean

baseGameBggId

BGG id of the base game, for an expansion

integer format: int64

scoreType

How a game is won: by score (SCORE), time (TIME) or number of turns (TURNS), each with a win condition, or by winning and losing (WIN_LOSS), which never has a win condition. The engine (chk_game_win_condition) and the game catalog (chk_candidate_win_condition) enforce the same rule.

string

Allowed values: SCORE TIME TURNS WIN_LOSS

winCondition

Whether the highest or the lowest score wins; required unless the score type is WIN_LOSS, absent then

string

Allowed values: HIGHER_WINS LOWER_WINS

stage

required

How far the automatic pipeline got: PENDING_RULES (created from BGG data), RULES_COLLECTED (rulebook sources found), INTERPRETED (ready for review), FAILED (see failureReason).

string

Allowed values: PENDING_RULES RULES_COLLECTED INTERPRETED FAILED

status

required

Review status: PENDING (awaiting review), APPROVED (queued for publication to the engine), PUBLISHED (in the engine), REJECTED. A PUBLISHED candidate that is approved again with new values is APPROVED until the pipeline has updated the engine’s game or expansion.

string

Allowed values: PENDING APPROVED PUBLISHED REJECTED

reliability

required

How well the LLM’s reading of the rules agrees with the BGG data: HIGH (at least three fields compared, all equal), MEDIUM (all compared fields equal, fewer than three), LOW (at least one mismatch), UNVERIFIED (nothing to compare).

string

Allowed values: HIGH MEDIUM LOW UNVERIFIED

reliabilityChecks

required

Array<object>

One field compared between BGG and the LLM.

object

field

required

E.g. minPlayers, maxPlayers, yearPublished, playingTime, minAge

string

bggValue

string

llmValue

string

matches

required

boolean

failureReason

Why the pipeline or the last publication attempt failed

string

gameId

The engine game: the published game itself, or the base game of a published or approved expansion

string format: uuid

expansionId

The engine expansion, once published

string format: uuid

createdAt

required

Date-time (ISO 8601)

string format: date-time

updatedAt

Date-time (ISO 8601)

string format: date-time

400

Request validation failed

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

errors

Array<object>

object

field

required

Field or property that failed validation

string

code

required

Machine-readable validation error code, e.g. REQUIRED, VALUE_TOO_LONG, INVALID_FORMAT, OUT_OF_RANGE. Canonical list is maintained per resource in the documentation.

string

message

required

Human readable validation message

string

rejectedValue

The actual value that failed validation. Omitted if the value is sensitive.

Examples

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "Received invalid request data",
  "errors": [
    {
      "field": "displayName",
      "code": "REQUIRED",
      "message": "missing required field"
    }
  ]
}

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "Received invalid request data",
  "errors": [
    {
      "field": "participants[2].ghostPlayerId",
      "code": "DUPLICATE_GHOST_PLAYER",
      "message": "the ghost player already takes part in this match"
    }
  ]
}

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "query",
      "code": "INVALID_SEARCH",
      "message": "'nonsense' is not a filterable field"
    }
  ]
}

401

Authentication required or token invalid

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/authentication",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required"
}

403

Insufficient permissions

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/authorization",
  "title": "Access denied",
  "status": 403,
  "detail": "Insufficient permissions"
}

500

Unexpected server error

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/internal",
  "title": "Oops! Something went wrong.",
  "status": 500,
  "detail": "Try again later."
}