Turtle +EV Data API

Authentication

Every data endpoint is deny-by-default. Pass your key as either header, no key (or a revoked/expired one) returns 401:

Authorization: Bearer <your_key>
# or
X-API-Key: <your_key>

Keys are issued per client with scoped permissions, a per-minute rate limit, and a daily quota. Request a key →

Errors & validation

Every parameter is validated. Nothing is silently ignored, a typo must never look like an empty result:

• 400 unknown_parameter, a query param this endpoint does not accept (the response lists the ones it does). ?cursor= on /picks is a 400, because /picks has no cursor.
• 400 invalid_parameter, a known param with a bad value: an unknown sport, a non-integer limit, min_prob outside 0–1, a malformed as_of, a non-numeric cursor.
• 401 missing/invalid/revoked key · 403 insufficient_scope (e.g. ?include=raw_odds without raw_odds:read) · 404 not_found (JSON, never HTML, once authenticated; without a key every path is a 401) · 429 with Retry-After.

A known sport with no rows returns 200 with an empty array, not a 400, ?sport=nfl in July is a valid question with a legitimately empty answer. Only an unrecognised sport is a 400. Note that ?league= on the discovery endpoints validates against the wider ingest store (about 40 active leagues, 42 on Sept 2, 2026, including ones we do not model), so /events?league=cricket is valid while /picks?sport=cricket is a 400.

Data responses carry an ETag; send If-None-Match to get a 304 when the board has not changed.

Reading the data honestly

The things most likely to make you draw a wrong conclusion, stated plainly. All of this is machine-readable in /schema under field_readiness and field_units.

• Scales are not uniform across a row. On /sharp, edge is a percent while expected_value is a fraction, assuming both are percent is a 100× error. divergence_pp is percentage points. Every numeric field’s unit is declared in field_units.
• Never average identity coverage across the board. Segment by sport × row type using the player_name_is_matchup flag. Game-level rows (tennis Total Games is a market on the match) have no single player, so canonical_player_id/team are null by definition. Worked example: tennis canonical_player_id reads 12% in aggregate and is 100% on individual-player rows , the board was 194 game-level + 26 player rows. Likewise team is always null for tennis: it is an individual sport.
• line_movement is null on game-level markets, by construction. Our tracked-line source is keyed (player, stat_type), so Moneyline / Total / Spread can never carry it. A default /sharp?days=2 is dominated by those and can legitimately return zero populated rows. Filter to a market that can carry it, /sharp?league=wnba, and it was 95% (153 of 161 WNBA player-prop rows, measured July 16, 2026). Use market as the tell: a game-level market (Moneyline, Total, Spread) can never carry line movement. It is also forward-only: the source retains 3 days, so older rows are permanently null. FLAT is the explicit no-movement value, null never means “no movement”.
• /picks is pre-game, /results is post-game, and they resolve identity from different sources, do not read the /results population rates as /picks rates.
• We serve null rather than a guess. A soccer player’s team is accepted only if it is one of the two sides named in that row’s own matchup; uncorroborated candidates are dropped. We do not serve tennis best_of/format at all, because our only source for it is stale and deriving it from a tournament name would be a heuristic.
• Dedup before you count. /results is one row per pick × book (deduplicated server-side since Sept 2, 2026: a pick graded twice for the same book counts once, most recent grade wins); graded is book-level and distinct_picks is the unique-pick count. Dedup on pick_key before computing n / win-rate / ROI, and expect your pick-level figure to differ from summary.roi_pct, which is book-level (units divided by wins + losses + pushes).

Build with AI

The surface is described by a typed OpenAPI 3.0.3 spec covering every endpoint (the data endpoints are fully typed; the five discovery endpoints are described in prose). Point an AI coding assistant (Claude, ChatGPT, Cursor) or an API client (Postman, Insomnia) at the URL below and it can generate a working, typed client for you:

# Give these three URLs to your AI agent, all public, no key needed to read them:
https://turtleevlabs.com/api/v1/openapi.json   # typed spec: every endpoint, param, response
https://turtleevlabs.com/api/v1/schema         # live field contract: units, population, caveats
https://turtleevlabs.com/llms.txt              # what Turtle is, in plain text

# Or generate a typed client in any language:
npx @openapitools/openapi-generator-cli generate \
  -i https://turtleevlabs.com/api/v1/openapi.json \
  -g python -o ./turtle-client

All three are public. Contract tests in the repository check the spec's enums, defaults and endpoint list against the live serializers. Fetch /schema before you model on any number , it carries per-field units, measured population rates, and the caveats above in a form an agent can read, so your assistant does not have to guess whether a field is a percent or a fraction, or whether a null means “zero” or “not applicable”.

A prompt that works well: “Read https://turtleevlabs.com/api/v1/openapi.json and https://turtleevlabs.com/api/v1/schema. Using field_units and field_readiness, write a client that pulls graded results, dedups on pick_key, and computes realized ROI , respecting which fields are percents vs fractions.”

Response envelope

Every response is wrapped in a stable envelope. Each pick carries full provenance , you can trace raw_prob → calibrated_prob → probability (final, capped, graded) alongside ev, fair_value, and cap_applied.

{
  "schema_version": 1,
  "generated_at": "2026-07-10T19:47:07Z",
  "count": 25,
  "cursor": null,
  "data": [
    {
      "sport": "mlb", "player_name": "J. Crawford",
      "canonical_player_id": "crawfjp01", "team": "SEA", "opponent": "LAA",
      "canonical_fixture_id": "746215",
      "stat_type": "Total Bases", "line": 1.5, "pick": "UNDER", "book": "...",
      "raw_prob": 0.70, "calibrated_prob": 0.70, "probability": 0.70,
      "cap_applied": false, "ev": 30.2, "fair_value": -233,
      "payout": 1.86, "computed_at": "...", "game_datetime": "..."
    }
  ]
}

Field conventions

• Identity: most rows carry canonical canonical_player_id, team, opponent, and canonical_fixture_id, stamped from maintained per-sport sources so you can join straight onto your data (coverage varies by sport; see /schema.field_readiness). Null means unresolved, not absent. For game-level markets player_name is a matchup, check player_name_is_matchup and use matchup_sides. stat_type follows a documented per-sport vocabulary in /schema.
• CLV: on /results, clv gives honest closing-line value from real tracked movement, open_line (first seen), close_line (last before start), line_delta, and favorable. It is null when no tracked data exists (never an empty object). basis labels whose line it is: book means the row’s own book; consensus means the median across the n_books tracked books for that player/stat/date, served only when the row’s book was not tracked for that stat. Filter on basis if you want book-exact only. It is never derived from a synthetic opening line, and it is served only when the pick line sits inside the tracked open/close band: a tracked line from another line family (alternate lines) is served as null.
• Joining picks to results: pick_key is served on /picks, /history, and /results and is identical for the same logical pick, so the board-to-graded join is exact (add book for the row-level match). The board is pre-lock: publication crystallizes when a pick locks near game time, so filter /history rows to locked_published != false before reconciling against /results. If you build your own join instead, include game_date: without it, consecutive-day picks at the same line collide and read as cross-book grading inconsistency (we measured 98 colliding groups without the date vs 1 real divergence with it, over 7 days).
• Units: numeric encodings are declared per field in /schema.field_units, American (fair_value, best_odds), decimal (payout, fair_decimal), probability 0–1 (probability, win_probability), percent (ev, roi_pct).
• Dedup: /results returns one row per pick × book, already deduplicated across engine tags. Dedup on pick_key (stable across books) before computing sample size, win rate, or ROI; the summary.graded count is book-level and summary.distinct_picks is the unique-pick count. HR 1+, NRFI and YRFI grades are a separate ledger, opt-in via ?include=expansion_markets.

Rate limits & scopes

• Your key’s limits are authoritative in the response headers: X-RateLimit-Limit is the per-minute cap, with X-RateLimit-Remaining and X-RateLimit-Reset (unix epoch). A separate daily quota also applies. A breach returns 429 with Retry-After.
• Invalid query params return 400 invalid_parameter (unparseable or out-of-range limit, days, as_of, cursor, min_prob, or enum filters); a limit above 1000 clamps to 1000. Unknown /api/v1 paths return a JSON 404 once authenticated.
• Conditional requests: every data response carries an ETag; send it back as If-None-Match and an unchanged board returns 304 Not Modified, poll frequently without transferring bytes.
• An OpenAPI 3.0 spec is published for typed-client codegen.
• picks:read, the live edge board and point-in-time history (derived fields only).
• raw_odds:read, approved raw per-book odds/props from covered sources (explicit client entitlement required). Requesting ?include=raw_odds without this scope returns 403.

Versioning

/v1 is GA. Changes within a major version are additive only , we never remove or re-type a field in place. One documented exception: on 2026-07-19,/results.prediction_id was renamed to model_tag. That field held the producing engine’s tag, never an id, and its name collided with /picks' numeric prediction_id, so any join between them produced garbage. We treated a field that could not be used as named as a defect and renamed it while the integrator base was small, rather than preserving a trap. Breaking changes ship as /v2 with at least 90 days of deprecation notice.

Coverage & honesty

The vetted /picks board is a narrow, real edge. Live modeled sports on Sept 2, 2026: MLB, soccer, tennis, WNBA, UNDER-focused, from a few dozen picks in the morning to a few hundred at slate peak (summary.pipeline_stale_seconds tells you which you are looking at). NFL model picks are not live yet; NBA and NHL return with their seasons. Graded results in the 30 days to Sept 2, 2026: 4,795 distinct picks across MLB, WNBA, soccer and tennis. Sharp-money signals: 98,730 graded since April 6, 2026 across nine leagues, five active in the last 30 days. /projections exposes every market we model. We are downstream of official settlement, make no official-league-rights claim, and disclose recency on every response. Where a number is a track record we say so; where it's a raw projection we label it. If you need cheap multi-sport raw odds, we'll tell you we aren't the cheapest option.

Examples

cURL

# List the current MLB edge board (one row per served pick)
curl -H "Authorization: Bearer $TEV_API_KEY" \
  "https://turtleevlabs.com/api/v1/picks?sport=mlb&limit=25"

# Point-in-time history: the board as it stood at a past instant
curl -H "X-API-Key: $TEV_API_KEY" \
  "https://turtleevlabs.com/api/v1/history?sport=tennis&as_of=2026-07-09T14:30:00Z&limit=100"

Python

import os, requests

BASE = "https://turtleevlabs.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TEV_API_KEY']}"}

# Page through graded results with the keyset cursor; read the calibration + CLV fields
cursor, rows = None, []
while True:
    r = requests.get(f"{BASE}/results", headers=HEADERS,
                     params={"sport": "mlb", "days": 7, "limit": 200, "cursor": cursor},
                     timeout=15)
    r.raise_for_status()
    body = r.json()              # {schema_version, count, cursor, data:[...], summary:{...}}
    rows += body["data"]
    cursor = body["cursor"]      # null on the last page
    if not cursor:
        break

for p in rows[:5]:
    clv = p.get("clv") or {}
    print(p["player_name"], p["canonical_player_id"], p["result"],
          "units", p["units"], "model_prob", p["probability"],
          "clv", clv.get("open_line"), "->", clv.get("close_line"))

JavaScript

const BASE = "https://turtleevlabs.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.TEV_API_KEY}` };

// /picks is a snapshot (no cursor; poll it with ETag / If-None-Match).
// Keyset cursors live on /results, /history and /sharp. Walk graded results:
async function resultsPage(cursor?: string) {
  const url = new URL(`${BASE}/results`);
  url.searchParams.set("sport", "mlb");
  url.searchParams.set("days", "30");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();             // {schema_version, count, cursor, data, summary}
}
let cursor: string | undefined;
do {
  const page = await resultsPage(cursor);
  for (const row of page.data) console.log(row.pick_key, row.book, row.result, row.units);
  cursor = page.cursor ?? undefined;   // null on the last page
} while (cursor);