Schema and spec

Three surfaces describe the REST API, and all three live under /v1/ on data.vike.io, served by the same application as the operations they describe. They sit under /v1/ rather than at the framework's default bare paths, because /v1/ is the only prefix that reaches that application on this host — the bare paths are routed nowhere and answer 404. Both halves of that placement are pinned by tests, so neither moves quietly.

All three are unauthenticated at the application and gated at the edge: the credential check covers the whole /v1/ prefix, with no exemption for the schema paths. Measured with no credential on 2026-09-03: /v1/openapi.json, /v1/docs and /v1/redoc each answered 401; /openapi.json, /docs and /redoc each answered 404.

Every request to these three paths is metered like any other /v1 call and spends one unit of the hourly budget, each under its own usage label. Fetching the spec there is a normal API call, not a free one.

To read the spec without a key, use the copy at https://vike.io/data/openapi.json: no credential, and not metered. Every /v1 response points at it, the edge's own 401 included, in a Link header:

Link: <https://vike.io/data/openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json", <https://vike.io/docs/data/>; rel="service-doc"

The three surfaces

What the spec declares

Every count on this page is rendered at build time from the application's own openapi() — the document /v1/openapi.json serves — so it cannot fall behind the routes. The same export renders every request line and parameter list in this reference.

Those counts are reproducible from the live document — this prints six of the rows above.

curl -s -H "X-API-KEY: $VIKE_API_KEY" https://data.vike.io/v1/openapi.json | jq '{
  paths: (.paths | length),
  described: [.paths[][] | select(.description)] | length,
  params: [.paths[][].parameters // [] | .[]] | length,
  params_described: [.paths[][].parameters // [] | .[] | select(.description)] | length,
  schemas: (.components.schemas | keys),
  codes: [.paths[][].responses | keys[]] | unique
}'

{
  "paths": 71,
  "described": 71,
  "params": 307,
  "params_described": 307,
  "schemas": [
    "HTTPValidationError",
    "ValidationError"
  ],
  "codes": [
    "200",
    "422"
  ]
}

Every path in the document starts with /v1/. Internal operational routes are excluded from the spec by design; nothing outside /v1/ is API a key-holder can call. The three surfaces in this namespace are excluded too, so the document does not describe itself.

Every one of its 71 operations is a hyperliquid, hl-cohorts, onchain or polymarket endpoint these pages document, so the whole-document counts above describe exactly this reference's REST surface.

Parameters are the part the spec carries in full: all 307 declare a name, a location, a type, whether they are required and a description — the same text the parameter lists in this reference show, because those lists are rendered from it. 4 operations declare no parameters at all — /v1/hl-cohorts/cohorts, /v1/hl-cohorts/segments, /v1/hyperliquid/positions/symbols and /v1/hyperliquid/archive/datasets.

A handful of Polymarket parameters are validated by the route itself rather than by the framework, so a missing one is a 400 with the route's own error body rather than a 422. The schema still marks every one of them required, so a generated client enforces them.

The auth block is real, and it is what makes generation viable at all. The document publishes both credentials — ApiKeyHeader (apiKey, in header, named X-API-KEY) and OAuth2Bearer (http/bearer, bearerFormat: vk_oat_...) — and the top-level security is a list of single-key requirements, which in OpenAPI means either, not both. A generated client therefore sends a credential header instead of 401ing on its first call. It is schema only: it declares the auth the API already enforces, and adding or removing a scheme cannot change whether a call is accepted. No operation opts out with security: [], and a test holds that true. Both schemes landed on 2026-09-02; before that the document declared no authentication at all, on a key-gated, per-call-billed API.

The three gaps

Be clear-eyed about these before planning to generate anything from the document.

1. There are no response schemas. components.schemas holds exactly two entries and both are error types, reached only from the 422 response that 67 operations declare. (The operations with no 422 are exactly the ones that take no parameters, so there is nothing to validate.) Every 200 in the document is {"schema": {}}, an undeclared object, so a generated client gives you typed requests and untyped responses. That is a deliberate property of the API rather than an oversight in the export: responses are undeclared objects, and no count of "schema gaps" can make them otherwise. Where a response field matters, these pages state it; the document will not.

2. Only success and validation failure are declared. The document declares 200 and 422 and nothing else, while the API really returns 400 for rejected input, 401 for a bad or missing credential, 429 for the hourly limit and 503 for an upstream failure — see Errors. Error handling is the part of a generated client you write yourself, and a generator that treats an undeclared status as a protocol violation will treat a normal rate-limit trip as one.

3. It covers 71 of the endpoints in this reference. Every one it leaves out is missing for a structural reason, not because someone forgot:

The keyless copy

curl -s https://vike.io/data/openapi.json -o openapi.json

https://vike.io/data/openapi.json is served by the website, not by the API host: no key, no usage row, nothing spent from the hourly budget. It is the document exported with the code, which a test holds equal to what /v1/openapi.json serves for the same commit, with one addition: a top-level x-vike-limits block (credits_per_call, credit_overrides, hourly_limit, minute_limit) that the live document does not carry. Everything on this page about paths, parameters and the three gaps applies to it unchanged.

The bare path on the API host still does not work. https://data.vike.io/openapi.json and the host root https://data.vike.io/ both answer 404: that host routes only the API's own paths.

Related

• Authentication — the two credentials, and where to create a key.
• Rate limits — the one hourly counter these three surfaces spend from.
• Errors — the status codes the spec does not declare.
• Endpoint overview — the namespace table every endpoint in this reference sits in.