Guides · 7 September 2026 · updated 13 October 2026

AI-Assisted Development with the SockOdds API

Give your AI coding assistant the real API, not a guess, and keep your key out of the conversation.

AI coding assistants are quick when they have the right context and confidently wrong when they do not. An assistant that has never seen SockOdds API v1 will invent field names and routes. This post shows how to hand it the real contract instead.

1. Point it at llms.txt

/llms.txt is a short index written for language models: the base URL, how authentication works, the response shape, and a link to every documentation page as Markdown. Most assistants can fetch a URL you paste, so start a session with something like: "Read https://sockodds.com/llms.txt before writing any code that calls the SockOdds API."

For a model that wants everything at once, /llms-full.txt holds the whole documentation in one file.

2. Give it the OpenAPI contract

/openapi.json is the OpenAPI 3.1 contract: every route, parameter, schema and error. It is the most precise thing you can give an assistant. Many agent tools can also turn it into typed functions or a client for you.

3. Use the Markdown twins

Every page on this site has a Markdown twin at the same path ending in .md. The quickstart is at /docs/quickstart.md and the reference is at /docs/reference.md. Markdown is shorter than HTML and easier for a model to read, and the code samples in it are the same ones that are tested against the API.

curl -sS https://sockodds.com/llms.txt
curl -sS https://sockodds.com/docs/quickstart.md

4. Keep the key in an environment variable

Never paste your API key into a chat or a prompt, and never let an assistant write it into a source file. Put it in an environment variable and tell the assistant to read it from there:

export SOCKODDS_API_KEY="paste-your-key-here"

Every sample on this site reads SOCKODDS_API_KEY, so code an assistant copies from the docs will pick it up without changes. If a key does leak, rotate it from your account.

5. A few rules worth adding to your project

Paste these into your assistant's rules or instructions file:

• Base URL is the v1 path on api.sockodds.com. Send the key as Authorization: Bearer from SOCKODDS_API_KEY.
• Responses are {data, meta, links}. Follow links.next unchanged; never build a cursor yourself.
• Errors are application/problem+json. Print the body; it says what went wrong.
• Prices are decimal_odds, with observed_at. A missing price is not a price of zero.
• Only use market, league and bookmaker keys that appear in the API's own responses or in /openapi.json. Never invent one.

6. Check it works

Ask the assistant to make one small request first, such as the rugby league leagues:

curl -sS "https://api.sockodds.com/v1/leagues?sport=rugby_league" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"

const response = await fetch("https://api.sockodds.com/v1/leagues?sport=rugby_league", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));

import json, os, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/leagues?sport=rugby_league",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
with urllib.request.urlopen(request) as response:
    print(json.dumps(json.load(response), indent=2))

{
  "data": [
    {
      "key": "nrl",
      "name": "NRL",
      "sport": "rugby_league",
      "region": "au",
      "periods": [
        "full",
        "regulation",
        "half_1",
        "half_2"
      ]
    },
    {
      "key": "nrlw",
      "name": "NRL Women's",
      "sport": "rugby_league",
      "region": "au",
      "periods": [
        "full",
        "regulation",
        "half_1",
        "half_2"
      ]
    },
    {
      "key": "rlwc",
      "name": "Rugby League World Cup",
      "sport": "rugby_league",
      "region": "intl",
      "periods": [
        "full",
        "regulation",
        "half_1",
        "half_2"
      ]
    },
    {
      "key": "rlwcw",
      "name": "Rugby League World Cup Women's",
      "sport": "rugby_league",
      "region": "intl",
      "periods": [
        "full",
        "regulation",
        "half_1",
        "half_2"
      ]
    }
  ],
  "meta": {
    "count": 4,
    "cursor": null
  },
  "links": {
    "next": null
  }
}

Then make sure the code it writes handles an error. This is what a revoked key gets back; good generated code prints that body instead of crashing on it:

curl -sS "https://api.sockodds.com/v1/sports" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"

const response = await fetch("https://api.sockodds.com/v1/sports", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));

import json, os, urllib.error, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/sports",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
try:
    with urllib.request.urlopen(request) as response:
        print(json.dumps(json.load(response), indent=2))
except urllib.error.HTTPError as e:
    print(json.dumps(json.load(e), indent=2))

{
  "type": "https://api.sockodds.com/problems/401",
  "title": "Unauthorised",
  "status": 401,
  "detail": "Provide a valid bearer key.",
  "instance": "/v1/sports"
}

More on wiring SockOdds into AI tools is in AI tools, and every error type is listed in errors.