---
title: "Release a match"
method: PATCH
path: "/v1/matches/{id}/release"
tags: ["Matches"]
---

# Release a match

`PATCH /v1/matches/{id}/release`

## Request

- Base URL: `https://api.hify.club`
- URL: `https://api.hify.club/v1/matches/{id}/release`
- Auth: API key in header `X-User-Token`

Releases the current user's active claim on the match (status becomes released and released_at is stamped) AND hands the match back to the pool: an in_progress match transitions back to pending so another scorer can claim it, which also frees the court for the next match on the game and drops this match from the game's live score channel. A completed match keeps its status.

The scoring event log, match_rounds and score_entries all survive, so the next claimer resumes the match via start_scoring rather than restarting it.

Idempotent: when the user holds no active claim the response is still 204 and neither the match nor anyone else's claim is touched, so a client retry after a timed-out-but-successful release is safe.

## Request body

- object
  - `match` object
    - `device_id` string: Optional — the device that registered as the match's writer. Fences the release the same way event ingest is fenced: if a re-claim from a newer device already bumped the epoch, this returns 409 stale_claim rather than kicking the scorer who replaced it. Omitting it skips the fence.

## Response `204`

Claim released (or no active claim to release — see idempotency)

## Other responses

- `401`: Unauthorized
- `403`: Forbidden — only admins and referees may release a match
- `404`: Match not found
- `409`: stale_claim — the requesting device is not the registered writer for the active claim; nothing was released

---

[API](https://skmtc.dev/hify/apis/hify-apis.md) - [All operations](https://skmtc.dev/hify/apis/hify-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/hify/apis/hify-apis/revisions/b5920403538d?raw)