Hippomundo Enterprise API
Reference

Get the entitlement-filtered OpenAPI document

GET /v1/openapi.json

Compatibility policy · Changelog

Returns an OpenAPI document containing exactly the operations currently available to the authenticated customer. Unavailable operations are absent rather than marked as disabled, including from any path that would otherwise become empty. Grant changes are reflected without a documentation deployment. This endpoint is free (0 credits) and rate-limited.

Parameters

FieldTypeDescription
X-Hippomundo-Freshnessheader · string

Requests fresher data for this call. live bypasses the freshness cache; the override may only request fresher data and never affects price. Any other value fails validation.

Allowed values: ["cached","live"].

Hippomundo-Versionheader · string

Optional pin to the API version your integration was built against. The only accepted value is v1, which today changes nothing. If a later version of the API changes behaviour in a way that is not backwards compatible, requests that send v1 keep the v1 behaviour. Any other value returns 400 unsupported_version.

Response 200 · application/json

OpenAPI document filtered to current entitlements.

FieldTypeDescription
BodyFilteredOpenAPIDocument

Valid OpenAPI document whose paths contain only operations currently available to the authenticated customer. Each operation carries an x-credits extension with its current price. Other standard OpenAPI fields may be present.

Additional properties: true.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Header: X-RateLimit-Limitinteger

Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses.

Header: X-RateLimit-Remaininginteger

Requests remaining in the applied rate-limit window.

Related schemas: FilteredOpenAPIDocument

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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Header: WWW-Authenticatestring · required

Always ApiKey, without credential detail.

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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

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 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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Header: Retry-Afterinteger

Seconds to wait before retrying. Required on 429 and on 402 api_key_credit_cap_reached, where it counts to the start of the next UTC day or month; present on 503 when the service knows a meaningful recovery interval.

Minimum: 0.

Header: X-RateLimit-Limitinteger

Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses.

Header: X-RateLimit-Remaininginteger

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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

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 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.

FieldTypeDescription
BodyProblem

RFC 9457 problem document used by every managed error response under /v1, regardless of which layer produced it. Content type is always application/problem+json. Clients branch on code, retain an unknown-code fallback, use status only for broad handling and must ignore unknown top-level fields. title and detail are human-readable English, may be clarified without versioning and are never parsed.

Header: Cache-Controlstring · required

Always no-store on error responses.

Header: Hippomundo-Request-IDstring · required

Compact server-generated request identifier carried on every response. On errors it equals the body request_id. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Header: Retry-Afterinteger

Seconds to wait before retrying. Required on 429 and on 402 api_key_credit_cap_reached, where it counts to the start of the next UTC day or month; present on 503 when the service knows a meaningful recovery interval.

Minimum: 0.

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"
}

OpenAPI definition

Related schemas: FilteredOpenAPIDocument

Complete OpenAPI definition
{
  "description": "Returns an OpenAPI document containing exactly the operations currently\navailable to the authenticated customer. Unavailable operations are\nabsent rather than marked as disabled, including from any path that\nwould otherwise become empty. Grant changes are reflected without a\ndocumentation deployment. This endpoint is free (0 credits) and\nrate-limited.\n",
  "operationId": "getEntitlementFilteredOpenAPI",
  "parameters": [
    {
      "$ref": "#/components/parameters/FreshnessOverride"
    },
    {
      "$ref": "#/components/parameters/VersionHeader"
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FilteredOpenAPIDocument"
          }
        }
      },
      "description": "OpenAPI document filtered to current entitlements.",
      "headers": {
        "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"
    },
    "406": {
      "$ref": "#/components/responses/NotAcceptable"
    },
    "422": {
      "$ref": "#/components/responses/ValidationFailed"
    },
    "429": {
      "$ref": "#/components/responses/RateLimitExceeded"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    },
    "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
    }
  },
  "summary": "Get the entitlement-filtered OpenAPI document",
  "tags": [
    "account"
  ]
}

Sandbox

Build and test with fictional data, and find a demo request for every operation.

Get current usage

GET /v1/usage