> For the complete documentation index, see [llms.txt](https://rock-odds.gitbook.io/rock-odds-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rock-odds.gitbook.io/rock-odds-docs/rest-quickstart.md).

# REST quickstart

Make your first REST request and identify a usable betting line in about five minutes.

## Before you begin

You need:

* Your RockOdds API key
* A terminal with `curl`
* The production base URL: `https://rockodds.live/api/v2`

## 1. Store your API key

Set the key in your shell so it does not appear directly in each command:

```bash
export ODDS_API_KEY="YOUR_API_KEY"
```

Do not commit API keys to source control or expose them in browser code.

## 2. Request upcoming odds

Request non-live NBA games:

```bash
curl --silent --show-error \
  --url "https://rockodds.live/api/v2/pregame?sport=NBA" \
  --header "X-API-Key: ${ODDS_API_KEY}"
```

The top-level response contains:

| Field   | Type    | Meaning                                 |
| ------- | ------- | --------------------------------------- |
| `count` | integer | Number of returned games                |
| `games` | array   | The current games matching your filters |

Getting `{"count":0,"games":[]}` is a valid response. It means no games currently match the filters.

## 3. Read a market

Each game has a `markets` object. Markets contain one or more lines, and each line contains its available selections.

```json
{
  "market_type": "spread",
  "period": "game",
  "side": null,
  "label": null,
  "limit": 500,
  "lines": [
    {
      "selections": [
        {"name": "home", "odds": "-110", "line": "-3.5"},
        {"name": "away", "odds": "-110", "line": "3.5"}
      ],
      "locked": false,
      "is_mainline": true,
      "updated_at": "2026-08-28T20:15:30+00:00"
    }
  ]
}
```

For an immediately usable line:

1. Find the market with the `market_type` and `period` you need.
2. Prefer the line where `is_mainline` is `true`.
3. Confirm `locked` is `false` before using the line.
4. Match selections by `name`, not by array position.

## 4. Make the request with Python

```python
import os

import httpx


response = httpx.get(
    "https://rockodds.live/api/v2/pregame",
    headers={"X-API-Key": os.environ["ODDS_API_KEY"]},
    params={"sport": "NBA"},
    timeout=10.0,
)
response.raise_for_status()

for game in response.json()["games"]:
    for market_id, market in game["markets"].items():
        mainline = next(
            (
                line
                for line in market["lines"]
                if line["is_mainline"] and not line["locked"]
            ),
            None,
        )
        if mainline:
            print(game["game_id"], market_id, mainline["selections"])
```

Install the Python client used above with `pip install httpx`.

## 5. Make the request with JavaScript

This example uses the built-in `fetch` available in Node.js 18 and later.

```javascript
const response = await fetch(
  "https://rockodds.live/api/v2/pregame?sport=NBA",
  {
    headers: {
      "X-API-Key": process.env.ODDS_API_KEY,
    },
  },
);

if (!response.ok) {
  throw new Error(`RockOdds API returned ${response.status}`);
}

const { games } = await response.json();

for (const game of games) {
  for (const [marketId, market] of Object.entries(game.markets)) {
    const mainline = market.lines.find(
      (line) => line.is_mainline && !line.locked,
    );

    if (mainline) {
      console.log(game.game_id, marketId, mainline.selections);
    }
  }
}
```

## Next steps

* Learn how games, markets, lines, and selections fit together in the [data model](/rock-odds-docs/data-model.md).
* Review all available [filters](/rock-odds-docs/filters-and-coverage.md).
* Complete the [SSE quickstart](/rock-odds-docs/sse-quickstart.md) to receive changes without polling.
