List editions of a competition
GET /v1/competitions/{competition_id}/editions
Compatibility policy · Changelog
Lists the dated editions of one competition that contain at least one class. Editions are reachable only through their parent competition. This endpoint is free (0 credits) and rate-limited; its counts size a results job before credits are spent.
The date range is inclusive; either bound may stand alone, and when
both are present date_from must not exceed date_to
(422 validation_failed otherwise). Unknown query parameters are
rejected with 422 validation_failed. The page size is capped and
defaulted at 100; a smaller page_size is allowed and becomes bound
to the traversal token, after which page_size and sort
overrides are rejected. Default sort is date_asc; use id for
exhaustive traversal.
Parameters
| Field | Type | Description |
|---|---|---|
competition_id | path · integer (int64) · required | Public competition ID. |
date_from | query · string (date) | Inclusive lower bound on the edition start date. |
date_to | query · string (date) | Inclusive upper bound on the edition start date. |
international | query · boolean | Filter on international editions. Omission means no filter. |
sort | query · string | Sort profile. Allowed values: |
page_size | query · integer | Page size, capped at 100. Bound to the traversal token; rejected as an override once a traversal has begun. Default: |
page_token | query · string | Opaque signed continuation token from Once a traversal has begun, per-request |
X-Hippomundo-Freshness | header · string | Requests fresher data for this call. Allowed values: |
Hippomundo-Version | header · string | Optional pin to the API version your integration was built against.
The only accepted value is |
Response 200 · application/json
One page of editions of the competition.
| Field | Type | Description |
|---|---|---|
Body | EditionPage | |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Charged-Milli-Credits | integer (int64) · required | The milli-credits this request debited from your balance, read from
the recorded charge; one credit is 1,000 milli-credits. Minimum: |
Header: Hippomundo-Data-Generation | string | Sandbox only. Names the copy of the sandbox data that answered this
request. The weekly data refresh replaces that copy and publishes a
new value, so a client that keeps sandbox data can key it on this
value. HTTP caches still may not store the response
( Pattern: |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Header: X-RateLimit-Limit | integer | Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses. |
Header: X-RateLimit-Remaining | integer | Requests remaining in the applied rate-limit window. |
Related schemas: EditionPage
Example
{
"data": [
{
"competition_id": 3120,
"date_from": "2025-05-08",
"date_to": "2025-05-11",
"id": 45021,
"international": true,
"name": "CSI Grimbergen 2025",
"star_level": 3
},
{
"competition_id": 3120,
"date_from": "2024-05-09",
"date_to": null,
"id": 41288,
"international": true,
"name": "CSI Grimbergen 2024",
"star_level": null
}
],
"has_more": false,
"next_page_token": null,
"total": 2
}Response 400 · application/problem+json
400 — one of the registered codes malformed_request, invalid_page_token, page_token_expired or unsupported_version; branch on the body code. Not retryable without changing the request. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
Page token is malformed or mismatched
{
"charged": false,
"code": "invalid_page_token",
"detail": "The supplied page token is not valid for this query and API key.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000001",
"request_id": "01J5AR8Q2K0000000000000001",
"retryable": false,
"status": 400,
"title": "Invalid page token",
"type": "https://enterprise.hippomundo.com/docs/errors/invalid_page_token"
}Request syntax cannot be parsed
{
"charged": false,
"code": "malformed_request",
"detail": "The request could not be parsed.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000000",
"request_id": "01J5AR8Q2K0000000000000000",
"retryable": false,
"status": 400,
"title": "Malformed request",
"type": "https://enterprise.hippomundo.com/docs/errors/malformed_request"
}Page token past its public expiry
{
"charged": false,
"code": "page_token_expired",
"detail": "The traversal token has expired; restart from page one.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000002",
"request_id": "01J5AR8Q2K0000000000000002",
"retryable": false,
"status": 400,
"title": "Page token expired",
"type": "https://enterprise.hippomundo.com/docs/errors/page_token_expired"
}Hippomundo-Version is not supported
{
"charged": false,
"code": "unsupported_version",
"detail": "The requested API version is not supported.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000003",
"request_id": "01J5AR8Q2K0000000000000003",
"retryable": false,
"status": 400,
"title": "Unsupported version",
"type": "https://enterprise.hippomundo.com/docs/errors/unsupported_version"
}Response 401 · application/problem+json
401 invalid_api_key — the API key is missing, invalid, revoked or otherwise unusable; the states are deliberately indistinguishable. Not retryable without different credentials. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Header: WWW-Authenticate | string · required | Always |
Related schemas: Problem
API key missing, invalid, revoked or otherwise unusable
{
"charged": false,
"code": "invalid_api_key",
"detail": "The request was not authenticated.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000004",
"request_id": "01J5AR8Q2K0000000000000004",
"retryable": false,
"status": 401,
"title": "Invalid API key",
"type": "https://enterprise.hippomundo.com/docs/errors/invalid_api_key"
}Response 403 · application/problem+json
403 endpoint_not_entitled — the authenticated Customer lacks a required entitlement for a discoverable public endpoint it has not purchased. Private endpoints never return 403; they return 404 not_found. Not retryable without purchasing the entitlement. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
Public endpoint not purchased
{
"charged": false,
"code": "endpoint_not_entitled",
"detail": "The account is not entitled to this endpoint.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000007",
"request_id": "01J5AR8Q2K0000000000000007",
"retryable": false,
"status": 403,
"title": "Endpoint not entitled",
"type": "https://enterprise.hippomundo.com/docs/errors/endpoint_not_entitled"
}Response 404 · application/problem+json
404 not_found — the route or resource is absent, not public, or a private endpoint is intentionally concealed. Nonexistent, unavailable and unauthorized-private resources are deliberately indistinguishable; the response is never an existence oracle. Not retryable. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
Route or resource absent, unavailable or concealed
{
"charged": false,
"code": "not_found",
"detail": "The requested resource does not exist.",
"instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000008",
"request_id": "01J5AR8Q2K0000000000000008",
"retryable": false,
"status": 404,
"title": "Not found",
"type": "https://enterprise.hippomundo.com/docs/errors/not_found"
}Response 406 · application/problem+json
406 not_acceptable — the Accept header excludes application/json, the media type of every successful response. Omit the header or send one that admits application/json, for example application/json, application/* or */*. Error responses are always application/problem+json. Not retryable without changing the Accept header. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
Requested response media type unsupported
{
"charged": false,
"code": "not_acceptable",
"detail": "The requested response media type is not supported.",
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000A",
"request_id": "01J5AR8Q2K000000000000000A",
"retryable": false,
"status": 406,
"title": "Not acceptable",
"type": "https://enterprise.hippomundo.com/docs/errors/not_acceptable"
}Response 422 · application/problem+json
422 validation_failed — parsed public inputs fail the documented schema or combination rules. errors lists up to 20 field-level items in request-field order, without messages or rejected values; errors_truncated may be true when more exist. Not retryable without correcting the request. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
Parsed public inputs fail the documented rules
{
"charged": false,
"code": "validation_failed",
"detail": "One or more request parameters are invalid.",
"errors": [
{
"code": "invalid_format",
"field": "date_from",
"location": "query"
}
],
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000E",
"request_id": "01J5AR8Q2K000000000000000E",
"retryable": false,
"status": 422,
"title": "Request validation failed",
"type": "https://enterprise.hippomundo.com/docs/errors/validation_failed"
}Response 429 · application/problem+json
429 rate_limit_exceeded — the Customer or key rate policy rejected the request. Retryable after waiting at least Retry-After; preserve the same idempotency key for a billable retry. Carries the same rate-limit headers used on successful authenticated responses. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Header: Retry-After | integer | Seconds to wait before retrying. Required on Minimum: |
Header: X-RateLimit-Limit | integer | Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses. |
Header: X-RateLimit-Remaining | integer | Requests remaining in the applied rate-limit window. |
Related schemas: Problem
Rate policy rejected the request
{
"charged": false,
"code": "rate_limit_exceeded",
"detail": "The rate limit for this API key was exceeded.",
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000F",
"request_id": "01J5AR8Q2K000000000000000F",
"retryable": true,
"status": 429,
"title": "Rate limit exceeded",
"type": "https://enterprise.hippomundo.com/docs/errors/rate_limit_exceeded"
}Response 500 · application/problem+json
500 internal_error — an unexpected Hippomundo failure with no safer public classification. Retryability is occurrence-specific; honor the body retryable field, use exponential backoff with jitter, preserve the idempotency key and report persistent failures with the request_id. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
Unexpected failure with no safer classification
{
"charged": false,
"code": "internal_error",
"detail": "An unexpected internal error occurred.",
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000G",
"request_id": "01J5AR8Q2K000000000000000G",
"retryable": false,
"status": 500,
"title": "Internal error",
"type": "https://enterprise.hippomundo.com/docs/errors/internal_error"
}Response 502 · application/problem+json
502 dependency_error — a required managed dependency returned an invalid or failing response. Retryability is occurrence-specific; honor the body retryable field. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
A managed dependency returned an invalid or failing response
{
"charged": false,
"code": "dependency_error",
"detail": "A required internal dependency failed.",
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000H",
"request_id": "01J5AR8Q2K000000000000000H",
"retryable": false,
"status": 502,
"title": "Dependency error",
"type": "https://enterprise.hippomundo.com/docs/errors/dependency_error"
}Response 503 · application/problem+json
503 service_unavailable — the service or a required ledger or dependency is temporarily unavailable. Retryable; honor Retry-After when present and use exponential backoff with jitter. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Header: Retry-After | integer | Seconds to wait before retrying. Required on Minimum: |
Related schemas: Problem
Service temporarily unavailable
{
"charged": false,
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000J",
"request_id": "01J5AR8Q2K000000000000000J",
"retryable": true,
"status": 503,
"title": "Service unavailable",
"type": "https://enterprise.hippomundo.com/docs/errors/service_unavailable"
}Response 504 · application/problem+json
504 dependency_timeout — a required dependency exceeded its deadline. Retryable with exponential backoff and jitter; preserve the idempotency key so a billable retry cannot double-charge. Uncharged.
| Field | Type | Description |
|---|---|---|
Body | Problem | RFC 9457 problem document used by every managed error response
under |
Header: Cache-Control | string · required | Always |
Header: Hippomundo-Request-ID | string · required | Compact server-generated request identifier carried on every
response. On errors it equals the body |
Related schemas: Problem
A dependency exceeded its deadline
{
"charged": false,
"code": "dependency_timeout",
"detail": "A required internal dependency timed out.",
"instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000K",
"request_id": "01J5AR8Q2K000000000000000K",
"retryable": true,
"status": 504,
"title": "Dependency timeout",
"type": "https://enterprise.hippomundo.com/docs/errors/dependency_timeout"
}OpenAPI definition
Related schemas: EditionPage
Complete OpenAPI definition
{
"description": "Lists the dated editions of one competition that contain at least one\nclass. Editions are reachable only through their parent competition.\nThis endpoint is free (0 credits) and rate-limited; its counts size a results job\nbefore credits are spent.\n\nThe date range is inclusive; either bound may stand alone, and when\nboth are present `date_from` must not exceed `date_to`\n(`422 validation_failed` otherwise). Unknown query parameters are\nrejected with `422 validation_failed`. The page size is capped and\ndefaulted at 100; a smaller `page_size` is allowed and becomes bound\nto the traversal token, after which `page_size` and `sort`\noverrides are rejected. Default sort is `date_asc`; use `id` for\nexhaustive traversal.\n",
"operationId": "listCompetitionEditions",
"parameters": [
{
"description": "Public competition ID.",
"in": "path",
"name": "competition_id",
"required": true,
"schema": {
"format": "int64",
"type": "integer"
}
},
{
"description": "Inclusive lower bound on the edition start date.",
"in": "query",
"name": "date_from",
"schema": {
"format": "date",
"type": "string"
}
},
{
"description": "Inclusive upper bound on the edition start date.",
"in": "query",
"name": "date_to",
"schema": {
"format": "date",
"type": "string"
}
},
{
"description": "Filter on international editions. Omission means no filter.",
"in": "query",
"name": "international",
"schema": {
"type": "boolean"
}
},
{
"description": "Sort profile. `id` is recommended for exhaustive traversal. Rejected as an override once a traversal has begun.",
"in": "query",
"name": "sort",
"schema": {
"default": "date_asc",
"enum": [
"date_asc",
"date_desc",
"id"
],
"type": "string"
}
},
{
"description": "Page size, capped at 100. Bound to the traversal token; rejected as an override once a traversal has begun.",
"in": "query",
"name": "page_size",
"schema": {
"default": 100,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"$ref": "#/components/parameters/PageToken"
},
{
"$ref": "#/components/parameters/FreshnessOverride"
},
{
"$ref": "#/components/parameters/VersionHeader"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"data": [
{
"competition_id": 3120,
"date_from": "2025-05-08",
"date_to": "2025-05-11",
"id": 45021,
"international": true,
"name": "CSI Grimbergen 2025",
"star_level": 3
},
{
"competition_id": 3120,
"date_from": "2024-05-09",
"date_to": null,
"id": 41288,
"international": true,
"name": "CSI Grimbergen 2024",
"star_level": null
}
],
"has_more": false,
"next_page_token": null,
"total": 2
},
"schema": {
"$ref": "#/components/schemas/EditionPage"
}
}
},
"description": "One page of editions of the competition.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControlPrivateNoStore"
},
"Hippomundo-Charged-Milli-Credits": {
"$ref": "#/components/headers/HippomundoChargedMilliCredits"
},
"Hippomundo-Data-Generation": {
"$ref": "#/components/headers/HippomundoDataGeneration"
},
"Hippomundo-Request-ID": {
"$ref": "#/components/headers/HippomundoRequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"$ref": "#/components/responses/EndpointNotEntitled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/NotAcceptable"
},
"422": {
"$ref": "#/components/responses/ValidationFailed"
},
"429": {
"$ref": "#/components/responses/RateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/DependencyError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/DependencyTimeout"
}
},
"summary": "List editions of a competition",
"tags": [
"hierarchy"
]
}