# search

Find the ID of a player, team, game, market, league or reference topic from its name.

| Method | Path | Title | Access | Price | MCP tool |
| --- | --- | --- | --- | --- | --- |
| GET | [`/v1/search`](#search-sports) | Find players, teams, games and markets | public | 1 | `search_sports` |
| GET | [`/v1/sports`](#list-sports) | List sports | public | 1 | none |
| GET | [`/v1/competitions`](#list-competitions) | List competitions | public | 1 | none |

`GET /v1/search`

## Find players, teams, games and markets
public, no key needed · 1 credit, not charged during the beta · MCP tool `search_sports` · status live

Kelly IDs and names for the words you send, in relevance order (never by a betting measure), up to 10 per page. Pass an ID to the read that takes it. Test-mode keys search the sandbox (the recorded Sunday).

### Parameters
- `q` string · query · required  
  The words to match: a player, team, game or competition's name, or a reference topic.  
  min length 1 · max length 200
- `kind` string · query  
  Only matches of this kind; reference means the reference library's entries.  
  One of: `competition`, `team`, `player`, `game`, `reference` (open: new values may be added).
- `competition` string · query  
  Only matches in this competition, by slug (nfl) or ID (cmp_).  
  min length 1 · max length 40
- `limit` integer · query  
  Items per page, 1 to 10; default 5.  
  min 1 · max 10 · default 5
- `cursor` string · query  
  The next_cursor of the previous page. Send the same filters with it; changed filters are refused with invalid_request.  
  min length 1 · max length 512

### Response
`200` A page of matches, best first.

- `object` const · required  
  Always list.  
  Always `"list"`.
- `data` array of object · required  
  The page's matches, in the list's documented order.
  - `object` const · required  
    Always search_result.  
    Always `"search_result"`.
  - `id` string · required  
    The match's Kelly ID (cmp_, tm_, plr_, gm_ or ref_).
  - `kind` string · required  
    competition, team, player, game, or a reference kind (term, rule, law, tax, policy, guide, help).  
    One of: `competition`, `team`, `player`, `game`, `term`, `rule`, `law`, `tax`, `policy`, `guide`, `help` (open: new values may be added).
  - `name` string · required  
    The name, or a reference entry's title.
  - `context` object  
    What tells close matches apart, by kind: a player's position and team, a game's teams, week and kickoff, a team's competition, a reference entry's topic, jurisdiction and summary. Only members the register serves on the API appear.
- `has_more` boolean · required  
  Whether another page follows.
- `next_cursor` string · nullable  
  Opaque cursor for the next page; send it with the same filters.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`quota_exhausted`](/problems/quota_exhausted) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled)

### Example
```http
GET https://api.askkelly.ai/v1/search?q=chiefs&kind=coach
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "kind: Input should be 'competition', 'team', 'player', 'game' or 'reference'",
  "param": "kind",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_998fa4f70f685278d2522f92",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

```http
GET https://api.askkelly.ai/v1/search?q=chiefs&limit=3
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "search_result",
      "id": "tm_0xcwddhkbjaqggrxg4xg",
      "kind": "team",
      "name": "Kansas City Chiefs",
      "context": {
        "competition": "nfl",
        "abbreviation": "KC"
      }
    },
    {
      "object": "search_result",
      "id": "gm_55zc8ywp3mzwg79py6mv",
      "kind": "game",
      "name": "Kansas City Chiefs at Las Vegas Raiders",
      "context": {
        "week": 4,
        "kickoff_at": "2026-10-04T20:25:00Z"
      }
    },
    {
      "object": "search_result",
      "id": "tm_r46ra6zqhcwmgn5c8b46",
      "kind": "team",
      "name": "Chicago Bears",
      "context": {
        "competition": "nfl",
        "abbreviation": "CHI"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJvIjozLCJmIjoiZTllZGIxMzg4ZDM2MDQyMCJ9"
}
```

`GET /v1/sports`

## List sports
public, no key needed · 1 credit, not charged during the beta · status live

The sports Kelly covers, with their competitions. One page holds them all.

### Response
`200` The sports, by slug.

- `object` const · required  
  Always list.  
  Always `"list"`.
- `data` array of object · required  
  The page's sports, in the list's documented order.
  - `object` const · required  
    Always sport.  
    Always `"sport"`.
  - `id` string · required  
    The sport's Kelly ID (spt_).  
    pattern ^spt_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
  - `slug` string · required  
    Its slug, such as american_football.
  - `name` string · required  
    Its name.
  - `competitions` array of object · required  
    The sport's competitions Kelly holds, by slug.
    - `id` string  
      The competition's Kelly ID (cmp_).  
      pattern ^cmp_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
    - `slug` string  
      Its slug, such as nfl.
    - `name` string  
      Its name.
  - `as_of` string · required  
    When the value was true; for a derived value, its newest input's time.  
    format date-time
  - `source` string · required  
    Who produced the value, as shown to readers.  
    min length 1
  - `attribution` string · nullable  
    Attribution the source's terms require.
  - `request_id` string · nullable  
    The request that produced this response.
  - `live_topics` array of string  
    Kelly Wire topics that update this resource (API and cards only).
  - `rg_line` string · nullable  
    The cost line (COMP-1, D19) on every resource and result that touches wagering: one engine-computed cost fact, or the short form, plus 21+ and the helpline. Show it with the value. Null on resources that don't touch wagering.
- `has_more` boolean · required  
  Whether another page follows.
- `next_cursor` string · nullable  
  Opaque cursor for the next page; send it with the same filters.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`quota_exhausted`](/problems/quota_exhausted) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled)

### Example
```http
GET https://api.askkelly.ai/v1/sports
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "sport",
      "id": "spt_bzcnprg8js5azynzmsyd",
      "slug": "american_football",
      "name": "American football",
      "competitions": [
        {
          "id": "cmp_adgcfptxm2s9mcq24dn3",
          "slug": "nfl",
          "name": "NFL"
        }
      ],
      "as_of": "2026-10-04T12:00:00Z",
      "source": "nflverse",
      "attribution": "nflverse data (CC BY 4.0)",
      "request_id": "req_078b033401011c116b6a8ab7",
      "live_topics": [],
      "rg_line": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Where each value comes from:

1. nflverse · as of 2026-10-04T12:00:00Z · nflverse data (CC BY 4.0)

`GET /v1/competitions`

## List competitions
public, no key needed · 1 credit, not charged during the beta · status live

Leagues and tournaments by sport, with their seasons. Seasons come newest first.

### Parameters
- `sport` string · query  
  Only this sport's competitions, by slug.  
  pattern ^[a-z0-9][a-z0-9_]{0,40}$
- `limit` integer · query  
  Items per page, 1 to 50; default 20.  
  min 1 · max 50 · default 20
- `cursor` string · query  
  The next_cursor of the previous page. Send the same filters with it; changed filters are refused with invalid_request.  
  min length 1 · max length 512

### Response
`200` A page of competitions.

- `object` const · required  
  Always list.  
  Always `"list"`.
- `data` array of object · required  
  The page's competitions, in the list's documented order.
  - `object` const · required  
    Always competition.  
    Always `"competition"`.
  - `id` string · required  
    The competition's Kelly ID (cmp_).  
    pattern ^cmp_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
  - `slug` string · required  
    Its slug, such as nfl.
  - `name` string · required  
    Its name.
  - `sport` string · required  
    Its sport's slug.
  - `seasons` array of object · required  
    Its seasons Kelly holds, newest first.
    - `id` string  
      The season's Kelly ID (ssn_).  
      pattern ^ssn_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
    - `label` string  
      Its label, such as 2026 or 2026-27.
    - `year` integer · nullable  
      The year it starts in.
    - `starts_on` string · nullable  
      Its first day, when known.  
      format date
    - `ends_on` string · nullable  
      Its last day, when known.  
      format date
  - `as_of` string · required  
    When the value was true; for a derived value, its newest input's time.  
    format date-time
  - `source` string · required  
    Who produced the value, as shown to readers.  
    min length 1
  - `attribution` string · nullable  
    Attribution the source's terms require.
  - `request_id` string · nullable  
    The request that produced this response.
  - `live_topics` array of string  
    Kelly Wire topics that update this resource (API and cards only).
  - `rg_line` string · nullable  
    The cost line (COMP-1, D19) on every resource and result that touches wagering: one engine-computed cost fact, or the short form, plus 21+ and the helpline. Show it with the value. Null on resources that don't touch wagering.
- `has_more` boolean · required  
  Whether another page follows.
- `next_cursor` string · nullable  
  Opaque cursor for the next page; send it with the same filters.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`quota_exhausted`](/problems/quota_exhausted) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled)

### Example
```http
GET https://api.askkelly.ai/v1/competitions?sport=american_football
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "competition",
      "id": "cmp_adgcfptxm2s9mcq24dn3",
      "slug": "nfl",
      "name": "NFL",
      "sport": "american_football",
      "seasons": [
        {
          "id": "ssn_2gmz5phv38xj9aqhn51s",
          "label": "2026",
          "year": 2026,
          "starts_on": null,
          "ends_on": null
        }
      ],
      "as_of": "2026-10-04T12:00:00Z",
      "source": "nflverse",
      "attribution": "nflverse data (CC BY 4.0)",
      "request_id": "req_fca373ae11e5850ff23ad552",
      "live_topics": [],
      "rg_line": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Where each value comes from:

1. nflverse · as of 2026-10-04T12:00:00Z · nflverse data (CC BY 4.0)

Generated from Kelly API 2026-10-05.

---

Generated from Kelly API 2026-10-05

Support: support@askkelly.ai · Security and disclosure: https://docs.askkelly.ai/security

Information is the edge. Odds are information, not advice · 21+ · Get help