> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.eliteprospects.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Response envelope, pagination, sorting, filtering, and field selection.

The Elite Prospects API follows consistent patterns across every endpoint. Learn them once, then they apply everywhere.

## Response envelope

List endpoints return:

```json theme={null}
{
  "data": [ /* records */ ],
  "_meta": {
    "generatedAt": "2026-05-11T12:00:00Z",
    "url": "/api/v1/players?apiKey=...",
    "offset": 0,
    "limit": 100,
    "totalRecords": 12345
  },
  "_links": { "next": "...", "prev": "..." }
}
```

| Field                          | Description                                             |
| ------------------------------ | ------------------------------------------------------- |
| `data`                         | The page of records.                                    |
| `_meta.generatedAt`            | Server timestamp the response was produced.             |
| `_meta.url`                    | The canonical request URL.                              |
| `_meta.offset` / `_meta.limit` | Pagination state for this page.                         |
| `_meta.totalRecords`           | Total records matching the request, across all pages.   |
| `_links`                       | Pagination links (e.g. `next`, `prev`) when applicable. |

Single-item endpoints (`/players/{id}`, etc.) return the record under `data` with the same `_meta` wrapper.

## Pagination

Two query parameters drive pagination on every list endpoint:

| Parameter | Default | Max    | Description                                         |
| --------- | ------- | ------ | --------------------------------------------------- |
| `offset`  | `0`     | —      | Number of records to skip before returning results. |
| `limit`   | `100`   | `1000` | Number of records to return on this page.           |

```bash theme={null}
curl "https://api.eliteprospects.com/v1/players?apiKey=YOUR_KEY&offset=200&limit=50"
```

Use `_meta.totalRecords` and `_links.next` to walk through a list.

## Sorting

The `sort` parameter accepts one or more field names. Prefix a field with `-` to sort descending.

```bash theme={null}
# Ascending by name
curl ".../v1/agencies?apiKey=YOUR_KEY&sort=name"

# Descending by updatedAt
curl ".../v1/agencies?apiKey=YOUR_KEY&sort=-updatedAt"

# Multiple keys (comma-separated)
curl ".../v1/agencies?apiKey=YOUR_KEY&sort=country,name"
```

Each endpoint defines its own sortable fields and default — see the endpoint's parameter list in the [API reference](/api-reference/introduction).

## Filtering

Filters are passed as query parameters. The available filters vary per endpoint and are listed in the reference.

```bash theme={null}
# Filter players by position and nationality
curl ".../v1/players?apiKey=YOUR_KEY&position=F&nationality=USA"

# Filter by country slug (ISO 3166-1 alpha-3)
curl ".../v1/agencies?apiKey=YOUR_KEY&country=SWE"
```

### Operators

Some numeric filters support comparison operators via a colon suffix:

| Suffix | Meaning               |
| ------ | --------------------- |
| `:gt`  | Greater than          |
| `:gte` | Greater than or equal |
| `:lt`  | Less than             |
| `:lte` | Less than or equal    |

```bash theme={null}
# Agencies with id greater than 100
curl ".../v1/agencies?apiKey=YOUR_KEY&id:gt=100"
```

Repeating a parameter (where supported) acts as an OR filter:

```bash theme={null}
curl ".../v1/agencies?apiKey=YOUR_KEY&id=12&id=34"
```

## Field selection

Use the `fields` parameter to request a subset of fields. This reduces payload size and is recommended when you only need a few attributes.

```bash theme={null}
# Repeatable form
curl ".../v1/players?apiKey=YOUR_KEY&fields=id&fields=name&fields=position"

# Comma-separated form (also accepted on many endpoints)
curl ".../v1/players?apiKey=YOUR_KEY&fields=id,name,position"
```

### Default and available fields

Each endpoint defines a default field set returned when `fields` is omitted, and a wider set you can opt into. Available fields can depend on your subscription — the endpoint reference lists everything. Requesting an unknown or unavailable field returns `400 Bad Request`.

## Identifiers and slugs

* **Numeric IDs** identify players (`/players/{id}`), teams, games, transfers, arenas, agencies, etc.
* **Slugs** identify leagues, countries, draft types, and award types — e.g. `/leagues/nhl`, `/countries/swe`, `/draft-types/nhl-entry-draft`.
* Country codes follow **ISO 3166-1 alpha-3** (e.g. `SWE`, `USA`, `FIN`).

## Dates and timestamps

All timestamps in responses are ISO 8601. Server time is **Europe/Stockholm**; timestamps are emitted with explicit timezone offsets.

## Caching

The API ships responses with HTTP cache headers. Most data is updated within minutes of changes at the source. For high-volume integrations, respect `Cache-Control` and conditional requests where present.