History API

Endpoints for listing past game results and editing scores.

GET /api/events/[id]/history

List all history entries for an event, ordered by date descending.

Response

{
  "data": [
    {
      "id": "clx9abc...",
      "eventId": "clx1abc...",
      "dateTime": "2026-03-13T19:00:00.000Z",
      "status": "played",
      "scoreOne": 3,
      "scoreTwo": 2,
      "teamsSnapshot": "{\"teamOne\":[...],\"teamTwo\":[...]}",
      "createdAt": "2026-03-13T21:00:00.000Z"
    }
  ],
  "nextCursor": "clx9abc...",
  "hasMore": true
}

Pagination

Cursor-based. Pass ?limit= (default 20, max 100) and the previous page's nextCursor as ?cursor=. The cursor is opaque and may reference either a GameHistory or a live Game row.

Fields

Field	Type	Description
`id`	string	History entry ID
`eventId`	string	Parent event ID
`dateTime`	string	When the game was played (ISO 8601)
`status`	string	`"played"` or `"cancelled"`
`scoreOne`	number \| null	Team one score
`scoreTwo`	number \| null	Team two score
`teamsSnapshot`	string	JSON snapshot of team assignments at game time
`mvp`	object \| null	Batched MVP summary for the game (`mvp`, `participants`, `isVotingOpen`, `hasVoted`, `totalVotes`, `eligibleVoters`). `null` for live `Game` rows. Included so the history page does not fetch MVP per card.

PATCH /api/events/[id]/history/[historyId]

Update a history entry. Edits are governed only by role: the event owner, an admin, or a participant of that game (matching the settled-game roll). Returns 403 for users outside those roles.

Request body

Field	Type	Required	Description
`status`	string	No	`"played"` or `"cancelled"`
`scoreOne`	number \| null	No	Team one score (null to clear)
`scoreTwo`	number \| null	No	Team two score (null to clear)
`teamsSnapshot`	object	No	Updated team assignments

Example

curl -X PATCH https://convocados.fly.dev/api/events/EVENT_ID/history/HISTORY_ID \
  -H "Content-Type: application/json" \
  -d '{ "scoreOne": 4, "scoreTwo": 3 }'

Response

Returns the updated history entry in the same format as the GET response.

Error responses

Status	Reason
`404`	History entry not found
`403`	Caller is not the owner, admin, or a participant of the game