API reference

Hypothetical matches

Copy as Markdown

# Hypothetical matches

## List teams for hypothetical matches

`GET /v1/hypothetical/teams`

List, at zero credits, the teams a hypothetical match can be played between: the covered teams with a published match in the next 8 days, which their squads and predicted elevens come from.

Authentication: Bearer API key with `data.read`; active Plus or Pro plan required.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `league` | integer | No | Only clubs of this league; minimum: 1. |
| `national` | boolean | No | true: national teams only; false: clubs only. |
| `country` | string | No | Only teams of this country, by name; maximum length: 200. |
| `search` | string | No | Team name contains this text; maximum length: 200. |
| `limit` | integer | No | Maximum rows to return; range: 1–200; default: 100. |
| `cursor` | string | No | next_cursor from the previous page, with the same filters, the same day; maximum length: 4096. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

### Example request

```bash
curl 'https://api.opono.com/v1/hypothetical/teams?league=8' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | list. |
| `dates` | object or null | from and to: the dates a hypothetical match may be played on. null while the model's teams are being refreshed. |
| `data` | array | Teams in team ID order. |
| `data[].team_id / name / short` | integer / string / string or null | Team labels. |
| `data[].country` | string or null | Country label. |
| `data[].national` | boolean | A national team. Clubs and national teams never meet. |
| `data[].league` | object or null | A club's league ID and name; null for a national team. |
| `data[].cross_country` | boolean | Whether the club can meet a club from another country: its league plays enough continental matches. Both clubs need it. |
| `has_more / next_cursor` | boolean / string or null | Pass next_cursor as cursor for the next page. Filters can leave a page short. |

### Example response

200 response with a test key.

```json
{
  "object": "list",
  "dates": {
    "from": "2026-10-28",
    "to": "2026-11-03"
  },
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 503 | `maintenance` | The API is paused for maintenance. |

## List competitions for hypothetical matches

`GET /v1/hypothetical/competitions`

List, at zero credits, the competitions a hypothetical match can be played in. The kind decides which pairs fit it.

Authentication: Bearer API key with `data.read`; active Plus or Pro plan required.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `national` | boolean | No | true: national teams only; false: clubs only. |
| `limit` | integer | No | Maximum rows to return; range: 1–200; default: 100. |
| `cursor` | string | No | next_cursor from the previous page, with the same filters, the same day; maximum length: 4096. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

### Example request

```bash
curl 'https://api.opono.com/v1/hypothetical/competitions?national=false' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | list. |
| `dates` | object or null | As for teams. |
| `data` | array | Competitions in competition ID order. |
| `data[].competition_id / name` | integer / string | Competition labels. |
| `data[].country` | string or null | Country label. |
| `data[].kind` | string or null | domestic: a league, both clubs in it. domestic_cup or play-offs: both clubs from its country. cup_international or friendly: any pair that can meet. international: national teams. |
| `data[].national` | boolean | Its matches are national teams' matches. |
| `has_more / next_cursor` | boolean / string or null | As for teams. |

### Example response

200 response with a test key.

```json
{
  "object": "list",
  "dates": {
    "from": "2026-10-28",
    "to": "2026-11-03"
  },
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 503 | `maintenance` | The API is paused for maintenance. |

## Squad for a hypothetical match

`GET /v1/hypothetical/teams/{team_id}/squad`

Get, at zero credits, the squad a hypothetical match on this date plays from: the team's published match nearest the date. Use its player IDs for custom sides and players left out.

Authentication: Bearer API key with `data.read`; active Plus or Pro plan required.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | integer | Yes | A team ID from GET /v1/hypothetical/teams; minimum: 1. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | Yes | The match date in YYYY-MM-DD format, in the window GET /v1/hypothetical/teams lists. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

### Example request

```bash
curl 'https://api.opono.com/v1/hypothetical/teams/1/squad?date=2026-10-30' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | hypothetical_squad. |
| `team` | object | Team ID and name. |
| `date` | string | The match date asked for. |
| `from_fixture` | object or null | The fixture ID and kick-off the squad comes from; null for test keys. |
| `squad_version` | string | Squad identity. |
| `formations` | array | Accepted formation strings for custom sides. |
| `as_of` | string | Input watermark in ISO 8601 UTC. |
| `players` | array | Eligible players: player_id, name and position. |

### Example response

200 synthetic test response, shortened to one player.

```json
{
  "object": "hypothetical_squad",
  "team": {
    "team_id": 1,
    "name": "Sample Home"
  },
  "date": "2026-10-30",
  "from_fixture": null,
  "squad_version": "sq1:example",
  "formations": [
    "4-3-3"
  ],
  "as_of": "2026-10-17T09:00:00Z",
  "players": [
    {
      "player_id": 1001,
      "name": "Sample Goalkeeper",
      "position": "goalkeeper"
    }
  ]
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 503 | `maintenance` | The API is paused for maintenance. |
| 404 | `not_found` | A public catalog id names no team, player or competition. |
| 503 | `refreshing` | The request can't be checked right now. |

List teams for hypothetical matches

GET /v1/hypothetical/teams

List, at zero credits, the teams a hypothetical match can be played between: the covered teams with a published match in the next 8 days, which their squads and predicted elevens come from.

Authentication: Bearer API key with data.read; active Plus or Pro plan required.

Parameters

Path parameters

Name	Type	Required	Description
—	—	—	None.

Query parameters

Name	Type	Required	Description
`league`	integer	No	Only clubs of this league; minimum: 1.
`national`	boolean	No	true: national teams only; false: clubs only.
`country`	string	No	Only teams of this country, by name; maximum length: 200.
`search`	string	No	Team name contains this text; maximum length: 200.
`limit`	integer	No	Maximum rows to return; range: 1–200; default: 100.
`cursor`	string	No	next_cursor from the previous page, with the same filters, the same day; maximum length: 4096.

Body parameters

Name	Type	Required	Description
—	—	—	None.

Example request

bash

curl 'https://api.opono.com/v1/hypothetical/teams?league=8' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`object`	string	list.
`dates`	object or null	from and to: the dates a hypothetical match may be played on. null while the model's teams are being refreshed.
`data`	array	Teams in team ID order.
`data[].team_id / name / short`	integer / string / string or null	Team labels.
`data[].country`	string or null	Country label.
`data[].national`	boolean	A national team. Clubs and national teams never meet.
`data[].league`	object or null	A club's league ID and name; null for a national team.
`data[].cross_country`	boolean	Whether the club can meet a club from another country: its league plays enough continental matches. Both clubs need it.
`has_more / next_cursor`	boolean / string or null	Pass next_cursor as cursor for the next page. Filters can leave a page short.

Example response

200 response with a test key.

json

{
  "object": "list",
  "dates": {
    "from": "2026-10-28",
    "to": "2026-11-03"
  },
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
403	`scope_missing`	The key lacks the required scope.
403	`tier_restricted`	The organisation plan does not include this operation.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
429	`rate_limited`	A request or authentication rate limit was exceeded.
503	`dependency_unavailable`	Request admission is unavailable.
503	`maintenance`	The API is paused for maintenance.

List competitions for hypothetical matches

GET /v1/hypothetical/competitions

List, at zero credits, the competitions a hypothetical match can be played in. The kind decides which pairs fit it.

Authentication: Bearer API key with data.read; active Plus or Pro plan required.

Parameters

Path parameters

Name	Type	Required	Description
—	—	—	None.

Query parameters

Name	Type	Required	Description
`national`	boolean	No	true: national teams only; false: clubs only.
`limit`	integer	No	Maximum rows to return; range: 1–200; default: 100.
`cursor`	string	No	next_cursor from the previous page, with the same filters, the same day; maximum length: 4096.

Body parameters

Name	Type	Required	Description
—	—	—	None.

Example request

bash

curl 'https://api.opono.com/v1/hypothetical/competitions?national=false' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`object`	string	list.
`dates`	object or null	As for teams.
`data`	array	Competitions in competition ID order.
`data[].competition_id / name`	integer / string	Competition labels.
`data[].country`	string or null	Country label.
`data[].kind`	string or null	domestic: a league, both clubs in it. domestic_cup or play-offs: both clubs from its country. cup_international or friendly: any pair that can meet. international: national teams.
`data[].national`	boolean	Its matches are national teams' matches.
`has_more / next_cursor`	boolean / string or null	As for teams.

Example response

200 response with a test key.

json

{
  "object": "list",
  "dates": {
    "from": "2026-10-28",
    "to": "2026-11-03"
  },
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
403	`scope_missing`	The key lacks the required scope.
403	`tier_restricted`	The organisation plan does not include this operation.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
429	`rate_limited`	A request or authentication rate limit was exceeded.
503	`dependency_unavailable`	Request admission is unavailable.
503	`maintenance`	The API is paused for maintenance.

Squad for a hypothetical match

GET /v1/hypothetical/teams/{team_id}/squad

Get, at zero credits, the squad a hypothetical match on this date plays from: the team's published match nearest the date. Use its player IDs for custom sides and players left out.

Authentication: Bearer API key with data.read; active Plus or Pro plan required.

Parameters

Path parameters

Name	Type	Required	Description
`team_id`	integer	Yes	A team ID from GET /v1/hypothetical/teams; minimum: 1.

Query parameters

Name	Type	Required	Description
`date`	string	Yes	The match date in YYYY-MM-DD format, in the window GET /v1/hypothetical/teams lists.

Body parameters

Name	Type	Required	Description
—	—	—	None.

Example request

bash

curl 'https://api.opono.com/v1/hypothetical/teams/1/squad?date=2026-10-30' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`object`	string	hypothetical_squad.
`team`	object	Team ID and name.
`date`	string	The match date asked for.
`from_fixture`	object or null	The fixture ID and kick-off the squad comes from; null for test keys.
`squad_version`	string	Squad identity.
`formations`	array	Accepted formation strings for custom sides.
`as_of`	string	Input watermark in ISO 8601 UTC.
`players`	array	Eligible players: player_id, name and position.

Example response

200 synthetic test response, shortened to one player.

json

{
  "object": "hypothetical_squad",
  "team": {
    "team_id": 1,
    "name": "Sample Home"
  },
  "date": "2026-10-30",
  "from_fixture": null,
  "squad_version": "sq1:example",
  "formations": [
    "4-3-3"
  ],
  "as_of": "2026-10-17T09:00:00Z",
  "players": [
    {
      "player_id": 1001,
      "name": "Sample Goalkeeper",
      "position": "goalkeeper"
    }
  ]
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
403	`scope_missing`	The key lacks the required scope.
403	`tier_restricted`	The organisation plan does not include this operation.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
429	`rate_limited`	A request or authentication rate limit was exceeded.
503	`dependency_unavailable`	Request admission is unavailable.
503	`maintenance`	The API is paused for maintenance.
404	`not_found`	A public catalog id names no team, player or competition.
503	`refreshing`	The request can't be checked right now.