Agent quickstart

Written for an LLM or autonomous agent integrating against Big Balls Sports Data for the first time. Three steps.

1. Obtain a key

Keys are issued to humans through the dashboard. The agent's owner signs up at https://bigballsdata.com/signup (magic link or OAuth), copies the key from https://bigballsdata.com/dashboard/keys, and provisions it to the agent through whichever secret store the agent reads from.

2. Discover the catalogue

Fetch the MCP manifest. It returns schema_version, server metadata, transport details, and a tools array with name, description, JSON Schema inputs, and the REST endpoint each tool maps to. No authentication required for this request.

bashbash
curl https://bigballsdata.com/mcp
Response (trimmed)json
{
  "schema_version": "v1",
  "server": { "name": "bigballsports", "display_name": "Big Balls Sports Data", "version": "1.0.0" },
  "transport": {
    "base_url": "https://api.bigballsdata.com",
    "auth": { "type": "bearer", "header": "Authorization", "format": "Bearer <api_key>", "key_url": "https://bigballsdata.com/dashboard/keys" },
    "openapi_url": "https://bigballsdata.com/openapi.json"
  },
  "tools": [
    {
      "name": "get_scores",
      "description": "Live and recent scores for matches in a sport or league...",
      "inputSchema": { "type": "object", "properties": { "sport": { "type": "string", "enum": ["football", ...] }, ... }, "required": ["sport"] },
      "endpoint": { "method": "GET", "path": "/v1/matches" }
    }
    /* ... seven more tools ... */
  ]
}

3. Call a tool

Map the chosen tool to its REST endpoint and call it with the bearer token. get_scores maps to GET /v1/matches:

bashbash
curl "https://api.bigballsdata.com/v1/matches?sport=football&league=epl&status=live" \
  -H "Authorization: Bearer bbs_live_a1b2c3d4..."
Responsejson
{
  "data": [
    {
      "id": "match_4a2f...",
      "sport": "football",
      "league_id": "epl",
      "home": { "team_id": "team_arsenal", "display_name": "Arsenal" },
      "away": { "team_id": "team_liverpool", "display_name": "Liverpool" },
      "scores": { "value": { "home": 2, "away": 1, "status": "live", "period_scores": [/* ... */] }, "confidence": 0.95, "freshness_ms": 1240 },
      "start_time": "2026-05-15T19:00:00Z",
      "status": "live"
    }
  ],
  "meta": { "source": "official-league", "confidence": 0.95, "cached": false, "cache_age_ms": 0, "request_id": "..." },
  "error": null
}

Envelope rules

  • data is the requested resource; error is non-null only on failure.
  • Each field on data carries its own confidence and freshness_ms, surface them when uncertainty matters.
  • meta.source is a tier label (official-league, aggregator-paid, aggregator-free, community-scraper), not a vendor identifier.
  • On error, follow /docs/errors, retry only the codes marked retryable.

Idempotency

All GET endpoints are idempotent. The only non-idempotent endpoint an agent should reach is POST /v1/webhooks, which requires an Idempotency-Key header to retry safely. Agents that only consume data never need that header.