List classes of an edition
GET /v1/editions/{edition_id}/classes
Compatibility policy · Changelog
Lists the classes of one edition. Classes are reachable only through their parent edition. This endpoint is free (0 credits) and rate-limited. It accepts no independent filters in v1; a competition fixes the discipline.
format is a normalized open-set class format: recognized source
values receive a stable code and canonical display, and
unmapped values return code: unknown with the original safe text
as display. date is the effective class date, falling back to
the edition date.
Unknown query parameters are rejected with 422 validation_failed.
The page size is capped and defaulted at 50 (generous so that a
single page normally covers an edition); 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 |
|---|---|---|
edition_id | path · integer (int64) · required | Public edition ID. |
sort | query · string | Sort profile. Allowed values: |
page_size | query · integer | Page size, capped at 50. 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 classes of the edition.
| Field | Type | Description |
|---|---|---|
Body | ClassPage | |
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: ClassPage
Example
{
"data": [
{
"date": "2025-05-11",
"edition_id": 45021,
"format": {
"code": "table_a_with_jump_off",
"display": "Table A with jump-off"
},
"id": 220417,
"max_height_metres": 1.5,
"name": "Grand Prix",
"prize_money_eur_cents": 2500000,
"star_level": 3
},
{
"date": "2025-05-09",
"edition_id": 45021,
"format": {
"code": "unknown",
"display": "bar. A o. verh. 2F"
},
"id": 220401,
"max_height_metres": null,
"name": "Youngster Tour",
"prize_money_eur_cents": null,
"star_level": 3
}
],
"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: ClassPage
Complete OpenAPI definition
{
"description": "Lists the classes of one edition. Classes are reachable only through\ntheir parent edition. This endpoint is free\n(0 credits) and rate-limited. It accepts no independent filters in\nv1; a competition fixes the discipline.\n\n`format` is a normalized open-set class format: recognized source\nvalues receive a stable `code` and canonical `display`, and\nunmapped values return `code: unknown` with the original safe text\nas `display`. `date` is the effective class date, falling back to\nthe edition date.\n\nUnknown query parameters are rejected with `422 validation_failed`.\nThe page size is capped and defaulted at 50 (generous so that a\nsingle page normally covers an edition); a smaller\n`page_size` is allowed and becomes bound to the traversal token,\nafter which `page_size` and `sort` overrides are rejected. Default\nsort is `date_asc`; use `id` for exhaustive traversal.\n",
"operationId": "listEditionClasses",
"parameters": [
{
"description": "Public edition ID.",
"in": "path",
"name": "edition_id",
"required": true,
"schema": {
"format": "int64",
"type": "integer"
}
},
{
"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 50. Bound to the traversal token; rejected as an override once a traversal has begun.",
"in": "query",
"name": "page_size",
"schema": {
"default": 50,
"maximum": 50,
"minimum": 1,
"type": "integer"
}
},
{
"$ref": "#/components/parameters/PageToken"
},
{
"$ref": "#/components/parameters/FreshnessOverride"
},
{
"$ref": "#/components/parameters/VersionHeader"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"data": [
{
"date": "2025-05-11",
"edition_id": 45021,
"format": {
"code": "table_a_with_jump_off",
"display": "Table A with jump-off"
},
"id": 220417,
"max_height_metres": 1.5,
"name": "Grand Prix",
"prize_money_eur_cents": 2500000,
"star_level": 3
},
{
"date": "2025-05-09",
"edition_id": 45021,
"format": {
"code": "unknown",
"display": "bar. A o. verh. 2F"
},
"id": 220401,
"max_height_metres": null,
"name": "Youngster Tour",
"prize_money_eur_cents": null,
"star_level": 3
}
],
"has_more": false,
"next_page_token": null,
"total": 2
},
"schema": {
"$ref": "#/components/schemas/ClassPage"
}
}
},
"description": "One page of classes of the edition.",
"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 classes of an edition",
"tags": [
"hierarchy"
]
}