Skip to Content
PredictorSDK

Every documented example identifier now resolves, and CI keeps it that way

FixInfra

Almost every copy-pasteable identifier in the reference and the guides had expired. An external audit extracted 42 example market ids, event tickers, and canonical event keys from api/openapi.yaml plus the docs and found 38 of them dead — including the market_id parameter's own example (kalshi:KXNBA-26-SAS), the quickstart's headline lookup, and the spec's list-mode and Kalshi-fanout examples. The two worst cases returned 200 with an empty body rather than an error, which is the hardest failure for a new caller to diagnose. Every example identifier in the spec, the quickstart, the concept pages, the guides, and the Yaak request stubs has been refreshed against live data and verified to resolve.

The rot was structural rather than editorial, so the strings alone were not the fix. Kalshi game tickers, Polymarket game slugs, and canonical event keys stop resolving once an event settles, and Hyperliquid's entire live catalog is a handful of daily-recurring outcomes — so any specific Hyperliquid integer id is valid for about a day. Three things change as a result:

  • The quickstart now leads with a call that needs no identifier, shows the response, and then looks up a key taken from it. The first thing a new caller copies no longer contains an identifier that can expire, and a callout says plainly that the sample identifiers elsewhere in the docs are samples.
  • GET /v1/markets/{market_id} and GET /v1/events/{event_id} now say which identifier spaces expire and where to get current ones. Long-dated markets (Kalshi season futures, multi-year AlphaArcade questions) and settled Polymarket, Predict, and SX Bet ids stay resolvable; game lines do not.
  • A live check requests every published identifier after each deploy and fails when one stops resolving, counting an empty 200 as a failure. On failure it prints current identifiers pulled from the API, so refreshing an expired example is a substitution rather than an investigation.

Two examples also became more accurate in the process. The /v1/markets list example previously showed a fabricated Polymarket id in 0x-hex form, which is not the shape Polymarket ids take; it now shows real rows. The NFL examples on /v1/matching-markets/sports were removed — NFL is not in that endpoint's coverage (NBA, WNBA, NHL, MLB), so they could not have matched anything.

No API behaviour changed. The SDKs are regenerated because the descriptions and examples they embed came from the spec.