Update match
PATCH/api/v1/matches/{matchId}
Updates match fields. While the match is DRAFT, all fields including participants may be changed here; a participant that is left out of participants is deleted, together with its loadout. Once FINALIZED, only playedAt and editRequestsEnabled remain directly editable; use POST /matches/{matchId}/edits for anything else.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Public match identifier
Header Parameters
Section titled “Header Parameters”Client-generated UUIDv7, required on every mutating request (POST, PUT, PATCH, DELETE), that makes the request safe to retry. A repeated request with the same key and the same payload returns the stored response (marked with the Idempotent-Replayed: true header) instead of executing again; the same key with a different payload is refused with 422. Keys older than the retention window (30 days) are rejected. A key that is not a UUID is refused with 400.
ETag of the resource being modified, for optimistic concurrency control: the request is refused with 412 when the resource changed since. Obtain it from the ETag response header of a previous GET or mutation.
Request Bodyrequired
Section titled “Request Bodyrequired”Update match fields; an absent field keeps its value, and only playsetId and communityId accept null (to clear them). While the match has status DRAFT, all fields below may be updated directly. Once the match is FINALIZED, only playedAt and editRequestsEnabled remain directly editable; attempting to change playsetId, communityId, expansions or participants of a finalized match returns 409 Conflict; use POST /matches/{matchId}/edits instead.
object
Date-time (ISO 8601)
Replaces the complete expansion collection; an empty list removes all expansions.
If omitted, the existing expansions remain unchanged.
Replaces the complete participant collection.
If omitted, the existing participants remain unchanged. If provided, the complete participant collection is replaced by the supplied collection: a participant that is no longer in it is deleted, together with its loadout.
Each participant must be fully specified. Partial participant updates are not supported while the match is in DRAFT status.
A participant of a match; a ghost player takes part at most once.
object
Score of a participant: points (SCORE), seconds (TIME) or turns (TURNS), with at most two decimals; a value with more decimals is refused with 400.
Position in the match, 1 for the winner; tied participants share a rank
object
Responses
Section titled “ Responses ”Match retrieved or changed successfully
object
object
object
object
object
DRAFT matches are freely mutable directly via PATCH. Once a match is finalized it becomes immutable except through the match-edit proposal and approval workflow.
Date-time (ISO 8601)
When the match was finalized; absent while it is a DRAFT.
Date-time (ISO 8601)
object
Date-time (ISO 8601)
Date-time (ISO 8601)
object
object
object
Score of a participant: points (SCORE), seconds (TIME) or turns (TURNS), with at most two decimals; a value with more decimals is refused with 400.
Position in the match, 1 for the winner; tied participants share a rank
object
object
Date-time (ISO 8601)
Date-time (ISO 8601)
Why the player disagrees with the recorded result
Date-time (ISO 8601)
object
Date-time (ISO 8601)
Date-time (ISO 8601)
Headers
Section titled “Headers”Current version of the resource; send it as If-Match to change or delete it
Present (true) when the response was replayed from an earlier request with the same Idempotency-Key, instead of being executed again
Request validation failed
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
object
Field or property that failed validation
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.
Human readable validation message
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" } ]}Authentication required or token invalid
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
Examples
{ "type": "https://errors.stratastax.dev/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication required"}Insufficient permissions
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
Examples
{ "type": "https://errors.stratastax.dev/authorization", "title": "Access denied", "status": 403, "detail": "Insufficient permissions"}Resource not found
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
Examples
{ "type": "https://errors.stratastax.dev/not-found", "title": "Resource not found", "status": 404, "detail": "The requested resource could not be found"}The requested mutation is not allowed in the resource’s current state, or it conflicts with existing data (a unique value that is already taken)
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
Examples
{ "type": "https://errors.stratastax.dev/conflict", "title": "Already exists", "status": 409, "detail": "A game with source bgg:199792 already exists."}{ "type": "https://errors.stratastax.dev/conflict", "title": "Self ghost player", "status": 409, "detail": "The ghost player that represents yourself cannot be deleted or unclaimed."}{ "type": "https://errors.stratastax.dev/conflict", "title": "Match is finalized", "status": 409, "detail": "This match is FINALIZED; propose a change via POST /matches/{matchId}/edits instead."}The If-Match header did not match the current resource’s ETag
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
Examples
{ "type": "https://errors.stratastax.dev/precondition-failed", "title": "Resource has changed", "status": 412, "detail": "The resource was modified since you last fetched it. Reload and try again."}The Idempotency-Key was already used for a request with a different payload
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
object
Field or property that failed validation
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.
Human readable validation message
The actual value that failed validation. Omitted if the value is sensitive.
Examples
{ "type": "https://errors.stratastax.dev/validation", "title": "Unprocessable Content", "status": 422, "detail": "Idempotency key reused for a different request", "errors": [ { "field": "Idempotency-Key", "code": "IDEMPOTENCY_KEY_REUSED", "message": "0192f100-0000-7000-8000-0000000000a5 was already used for a different request" } ]}Unexpected server error
object
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.
Short, human-readable summary
HTTP status code
Human-readable explanation
URI of the request that caused the error
Examples
{ "type": "https://errors.stratastax.dev/internal", "title": "Oops! Something went wrong.", "status": 500, "detail": "Try again later."}