---
title: Responses
description: The envelope, pages, caching, ids, and versions.
sidebar:
  order: 5
---

## The envelope

Every answer is JSON. What you asked for is under `data`. A list that comes in pages also carries `next_cursor`. An error carries `error` instead:

```json
{ "error": { "code": "not_found", "message": "No such game." } }
```

Dates are ISO 8601, in UTC. Linked things are ids: a game names its teams, a player names their team. Fetch `/teams` and `/modifiers` once and look them up.

## Pages

`/players` and `/games` come in pages. `limit` sets the size (up to 100; 50 by default). When `next_cursor` is not `null`, pass it back as `cursor` for the next page:

```bash
curl -H "x-api-key: hck_…" "https://hockay.com/api/v1/players?limit=100"
curl -H "x-api-key: hck_…" "https://hockay.com/api/v1/players?limit=100&cursor=MTAw"
```

## Caching

Every answer carries an `ETag` and a `Cache-Control: private, max-age=…` that says how long it is good for: seconds for a live game, an hour for a final box score, a day for the arenas. Send the `ETag` back as `If-None-Match` and an unchanged answer comes back as an empty `304`.

## Ids

| Thing | Looks like |
|---|---|
| Season | `S04` |
| Matchday | `S04D05` (regular), `S04W01` (wildcard), `S04P03` (playoffs) |
| Team | `mtl` |
| Game | `S04D05-MTL-ANC` |
| Player | `player_…` |
| Event | `evt_…` |

## Versions

The `v1` in the path is a promise. Within it, things are only added: new endpoints, new fields. A change that would break your code ships as `/api/v2`, next to `v1`, and `v1` keeps answering.

The full description is an [OpenAPI document](https://hockay.com/api/v1/openapi.json). Point a client generator at it for Swift, Kotlin, or TypeScript.