# Schema glossary.

> What every Underdog API field means, what null or a missing key means in each case, and sample JSON files you can download. A null is never a zero. Underdog API (https://underdogapi.com) is an independent Underdog Fantasy pick'em data API: Higher/Lower lines with separate payout multipliers per side, line history, changes and graded results as JSON, CSV, MCP and streams.

Canonical page: https://underdogapi.com/docs/schema-glossary

## Free offer

**Free API key, no card: 100 credits a month** on the live board, every league, separate Higher/Lower prices, and the last 24 hours of line history. Sign up: https://underdogapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Get a free key at https://underdogapi.com/sign-up?ref=ai-claudebot (no card), or let your agent request one: `POST https://underdogapi.com/api/v1/agent/signup` with `data_wanted` and `use_case`, then show your user the returned approval_url.
2. Export it: `export UNDERDOG_API_KEY=ud_...`
3. First call with curl:

```bash
curl --fail-with-body 'https://underdogapi.com/api/v1/projections?league=NBA&view=compact&limit=5' \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: NBA dashboard integration check'
```

4. Same call in Python:

```python
import os, requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"league": "NBA", "view": "compact", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
)
r.raise_for_status()
for line in r.json()["data"]:
    print(line["player"]["name"], line["market"]["stat"], line["line"])
```

## Use it from Claude (MCP)

Claude Code, one command:

```bash
claude mcp add --transport http underdog https://underdogapi.com/api/mcp --header "Authorization: Bearer $UNDERDOG_API_KEY"
```

Or add this server to your Claude MCP configuration (the key stays in the environment):

```json
{
  "mcpServers": {
    "underdog": {
      "type": "http",
      "url": "https://underdogapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNDERDOG_API_KEY}"
      }
    }
  }
}
```

Guide: https://underdogapi.com/use-with-claude

## Pricing

| Plan | Price | Credits / month | Notes |
| --- | --- | --- | --- |
| Free | $0 | 100 | No card. Live feed 5 minutes behind; last 24 hours of line history |
| Developer | $49/month | 10,000 | For models that need full training pages and loaded game-log seasons. Live feed, no added plan delay |
| Production | $149/month | 50,000 | For apps with real users and push delivery. Everything in Developer, signed webhooks for every change |
| Scale | $499/month | 250,000 | For apps whose traffic has outgrown Production. Everything in Production, 15 live-feed connections at once |

Full pricing: https://underdogapi.com/pricing

## On this page

Reference



For developers writing a parser or a model: what each field means, and what its null means. For generated types, use [openapi.json](https://underdogapi.com/openapi.json). For every parameter, use the [API reference](https://underdogapi.com/docs).

## Read this first

- null and a missing key never mean zero.
- null means we do not know, the source did not report it, or it does not apply yet. The row below says which.
- false is a statement. available: false says a side is not offered; available: null says that was not established.
- unknown is a value too. A tier of unknown means the board omitted it, so do not treat it as standard.
- Timestamps are ISO 8601 UTC instants. Store them as instants, and keep observed_at beside any line you persist.

## Response meta

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| meta.mode | live \| demo | Whether rows are live or fictional. | Never null. |
| meta.next_cursor | string \| null | Cursor for the next page. | This is the last page. |
| meta.observed_at | datetime \| null | Time of the latest board collection, not of each row. | No collection is recorded yet. |
| meta.source_status | fresh \| partial \| stale \| failed \| not_configured | Board health. Demo responses read demo. | Never null. |
| meta.plan_limit | object, optional | What your plan left out of these real rows. | Absent: no plan limit changed this answer. |

## Projection

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| id | string | Stable market ID. Use it as your key. | Never null. |
| line | number | The base Underdog line. | Never null. |
| status | active \| unavailable | Whether the offer is current. | Never null. |
| player.id, team, position | string \| null | Who the line is on. | Not reported. Do not derive a team from a name. |
| event.id, opponent, starts_at | string \| null | The game the line belongs to. | Not reported on this row. |
| observed_at | datetime | When we last confirmed the row. | Never null. |
| source_updated_at | datetime \| null | The source update time for the line. | The source gave none. If you substitute observed_at, record that you did. |
| source_board_time | datetime \| null | Board time when present. | Not present on this read. |

## Selections, one per side

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| payout_tier | standard \| boosted \| discounted \| null | Derived from the side multiplier. | No numeric multiplier observed. |
| american_price, decimal_price | number \| null | Source price representation for this side. | Not reported or side unavailable. |
| multiplier_scale | legacy_1x | The multiplier reference scale. | Not present on transitional responses. |
| side | higher \| lower | Which outcome the entry describes. | Never null. |
| available | boolean \| null | Whether this side is offered. | Not established, which is different from unavailable. |
| tier | standard \| discounted \| boosted \| unknown | Price class for this side. | Never null. unknown means the board omitted it. |
| payout_multiplier | number \| null | An observed multiplier, never synthesized. | No multiplier was observed or this side is unavailable. Never substitute 1.0x. |

## line_context

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| opening_line | number \| null | The first line we recorded, not necessarily the first ever offered. | No recorded history for this offer. |
| previous_line | number \| null | The line before the most recent move. | The line never moved. |
| last_moved_at | datetime \| null | When the line last moved. | The line never moved. |
| closing_line | number \| null | The last line recorded at or before the start. | The event has not started. |
| closed_at | datetime \| null | The start, or when a pulled offer left the board. | Not closed yet. |

## source_fields

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| any field | value \| null | What the board reports on the row, normalized. | The source omitted it. |

## History and change events

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| previous_line | number \| null | The line before this version or event. | First record, such as line.opened. |
| line_moved | boolean | Whether this version changed the number. | Never null. Tier or availability changes can add a version with false. |
| source_updated_at (history) | datetime \| null | Source update time at that version. | The source gave none. |

## Results and training rows

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| result | higher \| lower \| void \| null | The grade against the closing line. | status is ungraded. Read reason. |
| reason | string \| null | Why a row is void or ungraded. | The row is graded normally. |
| actual_value | number \| null | The final stat. Voids carry it too, for audit. | No box-score value is available. |
| line, opening_line, closing_line | number \| null | Recorded lines used for the grade. | Not recorded for this row. |
| minutes | integer \| null | Minutes played. Post-game, never a pre-game input. | Not available from the box score. |
| rest_days | integer \| null | Full days the team had off. | We cannot prove it, such as the first game we hold for a team. |
| home_away | home \| away \| null | Where the team played. | The team cannot be placed, as on a combined two-team row. |

## Game logs and team stats

| Field | Type | Means | Null or absent means |
| --- | --- | --- | --- |
| stats.<name> | number, key may be absent | A box-score stat. | A missing key was not reported. It is not zero. |
| confirmed | boolean | false for about four days after a game, while numbers can still change. | Never null. |
| minutes | number \| null | Minutes played. | Not reported. |

## Sample JSON files

Fictional rows with the same field names and types as the live API. Safe for fixtures and parser tests.

| File | Shows |
| --- | --- |
| [projections.demo.json](https://underdogapi.com/examples/samples/projections.demo.json) | **Projections, full view.** One fictional player with a boosted Higher side and unavailable Lower. |
| [projections-compact.demo.json](https://underdogapi.com/examples/samples/projections-compact.demo.json) | **Projections, compact view.** The live compact shape, built from demo rows. |
| [history.demo.json](https://underdogapi.com/examples/samples/history.demo.json) | **Projection history.** Changes-only versions of one offer. |
| [changes.demo.json](https://underdogapi.com/examples/samples/changes.demo.json) | **Change feed.** line.opened and line.moved events. |
| [results.sample.json](https://underdogapi.com/examples/samples/results.sample.json) | **Graded results.** Fictional tie-void result, explicitly labelled. |
| [training-set.sample.json](https://underdogapi.com/examples/samples/training-set.sample.json) | **Training set.** One fictional flat training row. |
| [coverage.demo.json](https://underdogapi.com/examples/samples/coverage.demo.json) | **Coverage.** Leagues and markets on the demo board. |
| [payouts.demo.json](https://underdogapi.com/examples/samples/payouts.demo.json) | **Payouts.** Dated Standard, Flex and Streaks reference tables at the 1.0x base scale. |

Prefer a real response? The [first-call path](https://underdogapi.com/docs/first-call) gets you one in three steps.

[Guide **Response schema, field by field** *The walk-through of the projection object.*](https://underdogapi.com/underdog-api-response-schema) [Reference **Objects** *Every field in the API reference.*](https://underdogapi.com/docs#objects) [Integrate **Pair with a broad odds API** *Joining without false matches.*](https://underdogapi.com/compare/when-to-choose-us)

## FAQ

### Is there a free Underdog API?

Yes. The Free plan is a real API key on the live board, not a sample: 100 credits a month, every league, separate Higher/Lower prices and the last 24 hours of line history. No card is needed.

### Is this the official Underdog Fantasy API?

No. Underdog API is an independent data service. It is not affiliated with, endorsed by or sponsored by Underdog Fantasy or Underdog Sports.

### What data does it return?

Underdog Higher/Lower lines with separate payout multipliers and availability for each side, stable market ids through line moves, alternate rungs, recorded line history, changes, graded results and coverage/status endpoints.

### How do I use it from Claude or another AI agent?

Connect the MCP server at https://underdogapi.com/api/mcp with a bearer key, or call the REST API. Agents can request a key for their user with POST /api/v1/agent/signup.

### How much does it cost after the free tier?

Developer is $49/month for 10,000 credits, Production $149/month for 50,000, Scale $499/month for 250,000. Errors and unchanged 304 responses cost zero credits.

### How fresh is the data?

Each row carries its observation time. Check /api/v1/status and /api/v1/coverage before relying on a sport or window; missing collection is reported as unavailable, never filled in.

### Does it place entries or give picks?

No. It is data only: no entries, account operations, guaranteed outcomes or betting advice.

---
Independent data service, not affiliated with Underdog Fantasy or Underdog Sports. Docs: https://underdogapi.com/docs · OpenAPI: https://underdogapi.com/openapi.json · llms.txt: https://underdogapi.com/llms.txt
