Requests & Responses

The rules every endpoint follows: the formats you can ask for, the shapes responses come back in, how paging works, and how the API tells you a request was wrong. Getting Started covers the basics; this page is the detail.

Response Format

All endpoints return JSON by default. You can request alternative formats using the format query parameter:

# CSV
curl "https://api.bytetree.io/api/rates?format=csv"

# TOON
curl "https://api.bytetree.io/api/rates?format=toon"

Unsupported format values return 400 Bad Request.

Where csv is available

json and toon work on every endpoint. csv is offered only where the response is one table. An endpoint whose response is several tables at once — /api/summary is the documented case — refuses csv with a 400 that names the formats it does support:

{ "error": "format=csv is not available for this endpoint; use json or toon", "formats": ["json", "toon"] }

The refusal itself is JSON, not CSV, and it is decided by the endpoint’s shape, never by its data — an empty result does not change the answer.

How CSV is shaped

Inside a row, an array of primitives is joined into one quoted cell, and an array of objects is written as JSON text in the cell.

Response Conventions

Paginated list envelope

List endpoints that support consumer-driven pagination return:

{
  "count":  10,
  "total":  4287,
  "limit":  10,
  "offset": 0,
  "data":   [ /* records on this page */ ]
}

This is the shape for top-level list endpoints — /api/assets, /api/rates, /api/prices, /api/universes, /api/fx among them.

Compatibility: the envelope is additive. Callers that read only count and data are unaffected. See the Changelog for the cutover note.

Which shape to expect

Rather than memorising a list, read it from the request. Pagination fields appear exactly where you can meaningfully page, and data is an array everywhere except one endpoint:

The keyed map is the one to watch: data is an object, not an array, so iterating it as a list fails rather than returning nothing.

Single-record reads

Single-record endpoints — e.g. GET /api/assets/:id, GET /api/rates/:pair — return { data: ... } and may include the lookup key as a sibling field. They are not paginated.

Unknown query parameters are rejected

Passing a parameter an endpoint doesn’t accept returns 400, rather than being silently ignored:

{ "error": "Unknown query parameter 'typ'. Did you mean 'type'? Accepted parameters: type, region, sector, limit, offset." }

Close misspellings get a suggestion, and the accepted list is always echoed. An endpoint that takes no parameters says so explicitly.

This is deliberate. Silently ignoring an unrecognised parameter means a filter you thought you applied simply didn’t apply, and the response looks plausible — a filtered query returning unfiltered data with a 200. Failing loudly turns a wrong answer into an obvious error.

format is accepted everywhere and never counts as unknown. Authentication is checked first, so an invalid key returns 401 rather than 400, even if the request also carries a bad parameter.

Malformed limit and offset values are rejected

The same rule applies to values. On every paginated list endpoint, limit must be a positive integer and offset a non-negative integer. Anything else returns 400 naming the parameter and the value received:

{ "error": "Invalid value for 'limit': expected a positive integer, received 'abc'." }

Only malformed values are rejected. An over-large limit is still clamped rather than refused, and the echoed limit tells you what was applied. limit=0 is an error, not “no limit”.

Available Endpoints

Every endpoint is a read-only GET.

:universe takes a universe slug — bytetrend, bytefolio and the rest of the roster on Universes. Every API key reaches every universe. macro is not a universe: the whole-registry aggregation is at /api/macro.