Skip to main content

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