Skip to content
Kelly

Developers

askkelly.aiGet a key

search

Copy page

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

On this page
MethodPathTitleAccessPriceMCP tool
GET/v1/searchFind players, teams, games and marketspublic1search_sports
GET/v1/sportsList sportspublic1none
GET/v1/competitionsList competitionspublic1none

GET /v1/search

Find players, teams, games and marketsLink to this section

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).

ParametersLink to this section

qstring · queryrequired

The words to match: a player, team, game or competition's name, or a reference topic.

min length 1 · max length 200

kindstring · 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).

competitionstring · query

Only matches in this competition, by slug (nfl) or ID (cmp_).

min length 1 · max length 40

limitinteger · query

Items per page, 1 to 10; default 5.

min 1 · max 10 · default 5

cursorstring · 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

ResponseLink to this section

200 A page of matches, best first.

objectconstrequired

Always list.

Always "list".

dataarray of objectrequired

The page's matches, in the list's documented order.

Show 5 fields
objectconstrequired

Always search_result.

Always "search_result".

idstringrequired

The match's Kelly ID (cmp_, tm_, plr_, gm_ or ref_).

kindstringrequired

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).

namestringrequired

The name, or a reference entry's title.

contextobject

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_morebooleanrequired

Whether another page follows.

next_cursorstringnullable

Opaque cursor for the next page; send it with the same filters.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/search?q=chiefs&kind=coach
Authorization: Bearer $KELLY_API_KEY
Response, 400
{
  "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."
}
Request
GET https://api.askkelly.ai/v1/search?q=chiefs&limit=3
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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 sportsLink to this section

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.

ResponseLink to this section

200 The sports, by slug.

objectconstrequired

Always list.

Always "list".

dataarray of objectrequired

The page's sports, in the list's documented order.

Show 11 fields
objectconstrequired

Always sport.

Always "sport".

idstringrequired

The sport's Kelly ID (spt_).

pattern ^spt_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

slugstringrequired

Its slug, such as american_football.

namestringrequired

Its name.

competitionsarray of objectrequired

The sport's competitions Kelly holds, by slug.

Show 3 fields
idstring

The competition's Kelly ID (cmp_).

pattern ^cmp_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

slugstring

Its slug, such as nfl.

namestring

Its name.

as_ofstringrequired

When the value was true; for a derived value, its newest input's time.

format date-time

sourcestringrequired

Who produced the value, as shown to readers.

min length 1

attributionstringnullable

Attribution the source's terms require.

request_idstringnullable

The request that produced this response.

live_topicsarray of string

Kelly Wire topics that update this resource (API and cards only).

rg_linestringnullable

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_morebooleanrequired

Whether another page follows.

next_cursorstringnullable

Opaque cursor for the next page; send it with the same filters.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/sports
Response, 200
{
  "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
}
  1. nflverse · as of 2026-10-04T12:00:00Z · nflverse data (CC BY 4.0)

GET /v1/competitions

List competitionsLink to this section

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.

ParametersLink to this section

sportstring · query

Only this sport's competitions, by slug.

pattern ^[a-z0-9][a-z0-9_]{0,40}$

limitinteger · query

Items per page, 1 to 50; default 20.

min 1 · max 50 · default 20

cursorstring · 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

ResponseLink to this section

200 A page of competitions.

objectconstrequired

Always list.

Always "list".

dataarray of objectrequired

The page's competitions, in the list's documented order.

Show 12 fields
objectconstrequired

Always competition.

Always "competition".

idstringrequired

The competition's Kelly ID (cmp_).

pattern ^cmp_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

slugstringrequired

Its slug, such as nfl.

namestringrequired

Its name.

sportstringrequired

Its sport's slug.

seasonsarray of objectrequired

Its seasons Kelly holds, newest first.

Show 5 fields
idstring

The season's Kelly ID (ssn_).

pattern ^ssn_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

labelstring

Its label, such as 2026 or 2026-27.

yearintegernullable

The year it starts in.

starts_onstringnullable

Its first day, when known.

format date

ends_onstringnullable

Its last day, when known.

format date

as_ofstringrequired

When the value was true; for a derived value, its newest input's time.

format date-time

sourcestringrequired

Who produced the value, as shown to readers.

min length 1

attributionstringnullable

Attribution the source's terms require.

request_idstringnullable

The request that produced this response.

live_topicsarray of string

Kelly Wire topics that update this resource (API and cards only).

rg_linestringnullable

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_morebooleanrequired

Whether another page follows.

next_cursorstringnullable

Opaque cursor for the next page; send it with the same filters.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/competitions?sport=american_football
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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
}
  1. nflverse · as of 2026-10-04T12:00:00Z · nflverse data (CC BY 4.0)

Generated from Kelly API 2026-10-05.

Support: support@askkelly.ai · Security and disclosure