> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rook.pm/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Authentication, exact amounts, pagination and explicit errors.

## Authentication and requests

Server-to-server requests use `Authorization: Bearer <api-key>`. JSON actions use `Content-Type: application/json`. Keep keys in server-side systems.

The base URL is `https://api.rook.pm/v1`. Collection reads use `GET`; custom actions use a colon, such as `POST /markets:resolve`. POST action parameters belong in the JSON body. Unknown request fields and unsupported filters fail validation.

Events, markets and families each have one read endpoint. Omit the ID to browse, or add `event_id`, `market_id` or `family_id` to retrieve one detailed record. Both forms return the same `items` envelope; an unknown ID returns an empty array. Other filters still narrow the results. For markets, use either `market_id` or batch `market_ids`; `version` requires a single `market_id`.

For a native lookup, use `venue` together with `venue_event_id` on `/events` or `venue_market_id` on `/markets`. These return the Rook ID and family references. The venue is required and never inferred from the numeric ID. Native and Rook ID selectors for the same resource cannot be combined. Use `/events?family_id=...` to browse a family's original venue events without regrouping them.

`X-Client-Request-Id` is optional correlation, not an idempotency guarantee. Responses include `X-Request-Id` for tracing.

## IDs, amounts and time

IDs and versions are opaque strings. Preserve them without numeric conversion. Financial decimals are finite decimal strings; exact calculation results may also use a rational numerator/positive denominator object. Timestamps use RFC 3339 UTC.

Polymarket native event and market IDs have numeric values and use exact decimal text in JSON: `"venue_event_id": "900001"` or `"venue_market_id": "1000001"`. They are separate from condition IDs and outcome token IDs. Rook-issued event, market and family IDs are a separate namespace. Numeric examples are illustrative; real integrations supply their actual venue IDs and use the Rook IDs returned.

An `InstrumentRef` contains exactly one `outcome_id` or `listing_id`. A `ScenarioRef` contains the issued family ID, version and scenario ID. Lists in query strings repeat the same parameter:

```http theme={null}
GET /v1/quotes?listing_ids=lst_a_yes&listing_ids=lst_b_no
```

Different filters combine with AND. Members of the same ID array combine with OR.

## Search by words

Use `q` on events, markets or families to search titles, descriptions and tags. You do not need an ID or an exact title. Matching ignores letter case and returns the most relevant results first; equal scores use ID order so paging stays stable.

```http theme={null}
GET /v1/markets?q=Fed%20rate%20cut&page_size=5
GET /v1/events?q=December%20Fed&page_size=3
GET /v1/families?q=interest%20rates&page_size=5
```

`page_size` is the maximum number of results on the page. Add filters such as `venue=polymarket` or `category=rates` to narrow the search. If there are more matches, repeat the same search with the returned `next_page_token`. No matches returns an empty `items` array.

## Pagination

Collections use `page_size` and `page_token`, returning `items`, `next_page_token`, `snapshot_id` and `as_of`. The default page size is 50; service limits are reported through coverage. Reuse filters and order for continuation. A null continuation means exhaustion.

Batch snapshots report a status for every requested ID. They do not pretend a missing listing has a zero price. Payout calculations page scenario columns under the same selection and version pins.

## Errors

Errors use `application/problem+json`, including a machine-readable `code`, `request_id` and applicable input references.

| Status | Meaning |
| - | - |
| 400 | Malformed or conflicting input |
| 401 / 403 | Authentication / authorization failure |
| 404 | Missing resource |
| 409 | Stale version, revision or cursor |
| 413 | Request exceeds a disclosed bound |
| 422 | Unsupported semantics or financial scope |
| 429 | Rate limit |
| 503 | Service or required upstream unavailable |

Cross-field constraints, scenario compatibility, exact numerical ranges and time-window order are service validations even when JSON Schema cannot express them. Response clients should tolerate additive fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.