API reference

The API reference is the OpenAPI document rendered at /api. It is the single source of truth for routes, parameters, request bodies, response schemas and status codes. This page explains the conventions the document assumes.

The document

• Rendered: /api
• Machine-readable: GET /v2/openapi.json (no key required)
• Dataset field definitions: GET /v2/schemas
• Contract file: contracts/openapi/v2.yaml in the repository

GET /v2/schemas returns the fields of every dataset, the shared fields (symbol, instrument_id, ts, trading_day, seq, flags) and the flag bits. served says whether /v2/data can answer that dataset today. A schema with served: false is a contract definition, not a data promise; datasets on an instrument tells you what it actually has.

Base URL and authentication

https://data.cyberun.cloud
Authorization: Bearer vmk_...

Every /v2 route except GET /v2/openapi.json needs a key. The catalog needs any valid key; data, bars, exports and live need the permissions described in API keys.

Conventions

• Times are RFC 3339 UTC; requests with instants must include a zone or Z.
• Trading days are YYYY-MM-DD in the instrument's exchange calendar.
• Decimals are JSON strings by default; numbers=float returns numbers.
• Paging uses cursor and next_cursor; a cursor belongs to its query.
• Catalog version: every answer carries catalog_version; pass it back to pin a reproducible result until the version is retired.
• Errors are application/problem+json; see Errors.
• Changes are additive: new routes, optional parameters, fields and enum values; clients must ignore what they do not know.

Route groups

Group	Routes	What it does
Catalog	/v2/catalog/venues, /products, /instruments, /instruments/{symbol}, /datasets, /calendar	What exists and when it trades
Data	GET /v2/data/{dataset}	Paged raw rows
Bars	GET /v2/bars	Server-side K-lines, including continuous contracts
Exports	POST /v2/exports, GET /v2/exports/{id}, GET /v2/exports/{id}/files/{file_index}	Bulk files
Stream	GET /v2/stream	WebSocket rows and bars
Meta	GET /v2/openapi.json, GET /v2/schemas, POST /v2/mcp	The contract and agent tools

Each route's parameters, defaults and response fields are on /api. Operational limits that apply across routes are in Limits.

Administration

Principal, key and usage-policy management still uses /v1 and has no OpenAPI document. It is documented in Administration.

Versioning

The public contract is versioned by the /v2 path and by info.version in the OpenAPI document. Additive changes do not change the path. A change that would break an existing request is not made silently; it would be a new path.

The older /v1 data APIs are retired; see v1 (retired).