Building with AI
Point your AI assistant at files written for it, and keep your key out of the conversation.
Files for AI tools
Every page of these docs is also published as plain Markdown, and the whole set is available in forms an AI assistant or coding agent can read in one go.
| File | What it holds |
|---|---|
| /llms.txt | A short index: what the API is, the base URL, how to authenticate, and a link to every docs page as Markdown. |
| /llms-full.txt | Every docs page in one Markdown file, samples and recorded outputs included. |
| /openapi.json | The OpenAPI 3.1 contract: every route, parameter, object and error. It is the source of the API reference. |
| /docs/reference.md | The API reference as Markdown, with a runnable sample for each operation. |
Markdown for any page
Add .md to a page's path to get the same page as Markdown. For example, /docs/quickstart.md is the quickstart, and /docs/best-practices.md is best practices. The Markdown has the same text, the same code samples and the same recorded outputs as the page, without the site's navigation. Coverage lists work the same way: /leagues.md, /bookmakers.md and /docs/markets.md.
Starting a session
Give your assistant the index first and let it fetch what it needs, or paste the contract if it cannot fetch pages. A prompt that works well:
I am building with the SockOdds API v1.
Read https://sockodds.com/llms.txt and the pages it links to, and use
https://sockodds.com/openapi.json as the source of truth for routes and fields.
Rules for the code you write:
- Read the API key from the SOCKODDS_API_KEY environment variable. Never ask me
for the key and never write it into code, config files or logs.
- Send it only as the Authorization: Bearer header, from server-side code.
- Follow links.next unchanged until it is null.
- Prices are decimal_odds. Check observed_at, and treat a missing price as
"no current quote", never as zero.
- Handle application/problem+json errors, and wait for Retry-After on a 429.Keep your key out of the chat
An assistant does not need your key to write code for this API. Keep the key in an environment variable on your machine or server, and let the code read it at run time:
- Do not paste your key into a prompt, an issue or a shared notebook. Treat anything you type into a chat as something others may read.
- If an agent runs code for you, set
SOCKODDS_API_KEYin the environment it runs in, rather than giving it the key as text. - If a key ends up in a conversation, a commit or a log, rotate it from your account.
Check what it writes
AI assistants sometimes fill gaps from memory or from other APIs. Before you ship code an assistant wrote, check it against the API reference:
- Every request uses the
Authorization: Bearerheader, not a key in the URL. - Field names match the contract:
decimal_odds,observed_at,links.next,verdictand so on. - Ids keep their prefixes (
ev_,pl_,mk_,oc_) and keys are lowercase, such asrlwcorsportsbet. - History, snapshots and the stream are used only if your plan includes them (Pro).
The examples are short, complete programs you can hand to an assistant as a starting point. Each one is run against a local copy of the API, and the output under it is what it printed.