formulas
Copy page
Save your own attributes and templates from the formula bar, and read, share, version and trace them with your own key or a token you granted.
On this page
- List your saved attributes
- Parameters
- Response
- Errors
- Example
- Save a attribute
- Parameters
- Response
- Errors
- Example
- Keep a copy of a shared attribute
- Parameters
- Response
- Errors
- Example
- Get a saved attribute
- Parameters
- Response
- Errors
- Example
- Change a saved attribute
- Parameters
- Response
- Errors
- Example
- Delete a saved attribute
- Parameters
- Response
- Errors
- Example
- List a saved attribute's versions
- Parameters
- Response
- Errors
- Example
- Trace a saved attribute
- Parameters
- Response
- Errors
- Example
- Share a saved attribute
- Parameters
- Response
- Errors
- Example
- List your saved templates
- Parameters
- Response
- Errors
- Example
- Save a template
- Parameters
- Response
- Errors
- Example
- Keep a copy of a shared template
- Parameters
- Response
- Errors
- Example
- Get a saved template
- Parameters
- Response
- Errors
- Example
- Change a saved template
- Parameters
- Response
- Errors
- Example
- Delete a saved template
- Parameters
- Response
- Errors
- Example
- List a saved template's versions
- Parameters
- Response
- Errors
- Example
- Trace a saved template
- Parameters
- Response
- Errors
- Example
- Share a saved template
- Parameters
- Response
- Errors
- Example
- Check a formula
- Parameters
- Response
- Errors
- Example
- Preview a formula on real rows
- Parameters
- Response
- Errors
- Example
- Read a shared formula
- Parameters
- Response
- Errors
- Example
- List your macros
- Response
- Errors
- Example
- Save a macro
- Parameters
- Response
- Errors
- Example
- Get a macro
- Parameters
- Response
- Errors
- Example
- Change a macro
- Parameters
- Response
- Errors
- Example
- Delete a macro
- Parameters
- Response
- Errors
- Example
- Run a macro
- Parameters
- Response
- Errors
- Example
- List your automations
- Response
- Errors
- Example
- Make an automation
- Parameters
- Response
- Errors
- Example
- Get an automation
- Parameters
- Response
- Errors
- Example
- Change an automation
- Parameters
- Response
- Errors
- Example
- Delete an automation
- Parameters
- Response
- Errors
- Example
- List an automation's runs
- Parameters
- Response
- Errors
- Example
- Make a rule link
- Parameters
- Response
- Errors
- Example
- Get your ways to import rules
- Response
- Errors
- Example
| Method | Path | Title | Access | Price | MCP tool |
|---|---|---|---|---|---|
| GET | /v1/attributes | List your saved attributes | read:formulas | 0 | get_my_formulas |
| POST | /v1/attributes | Save a attribute | write:formulas | 0 | update_my_formulas |
| POST | /v1/attributes/copies | Keep a copy of a shared attribute | write:formulas | 0 | none |
| GET | /v1/attributes/{ref} | Get a saved attribute | read:formulas | 0 | none |
| PATCH | /v1/attributes/{ref} | Change a saved attribute | write:formulas | 0 | update_my_formulas |
| DELETE | /v1/attributes/{ref} | Delete a saved attribute | write:formulas | 0 | update_my_formulas |
| GET | /v1/attributes/{ref}/versions | List a saved attribute's versions | read:formulas | 0 | none |
| GET | /v1/attributes/{ref}/trace | Trace a saved attribute | read:formulas | 0 | none |
| POST | /v1/attributes/{ref}/share | Share a saved attribute | write:formulas | 0 | update_my_formulas |
| GET | /v1/templates | List your saved templates | read:formulas | 0 | get_my_formulas |
| POST | /v1/templates | Save a template | write:formulas | 0 | none |
| POST | /v1/templates/copies | Keep a copy of a shared template | write:formulas | 0 | none |
| GET | /v1/templates/{ref} | Get a saved template | read:formulas | 0 | none |
| PATCH | /v1/templates/{ref} | Change a saved template | write:formulas | 0 | none |
| DELETE | /v1/templates/{ref} | Delete a saved template | write:formulas | 0 | none |
| GET | /v1/templates/{ref}/versions | List a saved template's versions | read:formulas | 0 | none |
| GET | /v1/templates/{ref}/trace | Trace a saved template | read:formulas | 0 | none |
| POST | /v1/templates/{ref}/share | Share a saved template | write:formulas | 0 | none |
| POST | /v1/attributes:validate | Check a formula | read:formulas | 0 | check_formula |
| POST | /v1/attributes:preview | Preview a formula on real rows | read:formulas | 0 | preview_formula |
| GET | /v1/shared-formulas/{code} | Read a shared formula | public | 0 | none |
| GET | /v1/macros | List your macros | read:formulas | 0 | get_my_automations |
| POST | /v1/macros | Save a macro | write:formulas | 0 | update_my_automations |
| GET | /v1/macros/{ref} | Get a macro | read:formulas | 0 | none |
| PATCH | /v1/macros/{ref} | Change a macro | write:formulas | 0 | none |
| DELETE | /v1/macros/{ref} | Delete a macro | write:formulas | 0 | none |
| POST | /v1/macros/{ref}:run | Run a macro | read:formulas | 0 | update_my_automations |
| GET | /v1/automations | List your automations | read:formulas | 0 | get_my_automations |
| POST | /v1/automations | Make an automation | write:formulas | 0 | update_my_automations |
| GET | /v1/automations/{automation_id} | Get an automation | read:formulas | 0 | none |
| PATCH | /v1/automations/{automation_id} | Change an automation | write:formulas | 0 | update_my_automations |
| DELETE | /v1/automations/{automation_id} | Delete an automation | write:formulas | 0 | none |
| GET | /v1/automations/{automation_id}/runs | List an automation's runs | read:formulas | 0 | get_my_automations |
| POST | /v1/rules:link | Make a rule link | public | 0 | make_rule_link |
| GET | /v1/me/rule-import-ways | Get your ways to import rules | read:tracker | 0 | get_my_rule_import_ways |
GET /v1/attributes
List your saved attributesLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool get_my_formulas · status live
Your saved attributes, most recently changed first, each with its formula, the mode it was written in, its type, shape, format and roll-up rule and its version. Filter by sport or by words in its name or label (q).
ParametersLink to this section
limitinteger · querySaves per page, 1 to 200.
min 1 · max 200 · default 50
cursorstring · queryThe next_cursor of the page before.
max length 200
sportstring · queryOnly saves for this sport (and those for every sport).
pattern ^[a-z0-9_]{2,16}$
qstring · queryWords in its name or label.
min length 1 · max length 70
ResponseLink to this section
200 A page of your saved attributes.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredThe saves, most recently changed first.
Show 23 fields
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
has_morebooleanrequiredWhether another page follows.
next_cursorstringrequirednullablePass as cursor for the next page.
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
GET https://api.askkelly.ai/v1/attributes
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [
{
"id": "attr_6m77a97zzz32wcct2zw5",
"object": "attribute",
"name": "target_trend",
"reference": "my.target_trend",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 2,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": null,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
},
{
"id": "attr_4dfs6tgt65dxt62a7drm",
"object": "attribute",
"name": "rush_form",
"reference": "my.rush_form",
"label": "Rush form",
"description": null,
"sports": [
"nfl"
],
"entity": null,
"formula": "=MY.FORM(rush_yards, 3)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": null,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}
],
"has_more": false,
"next_cursor": null
}POST /v1/attributes
Save a attributeLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_formulas · status live
Saves a named formula you can use as my.target_trend in any formula, on askkelly.ai, in chat, the API and MCP. The formula is checked first and refused with the spot and a plain-words reason when it can't run; a name you already use, or a formula that would read itself through others, is refused. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
namestringIts name: letters, digits and _, starting with a letter. my. is optional.
min length 1 · max length 70
formulastringThe formula, starting with =. A template starts with =LAMBDA(.
min length 1 · max length 2000
modestringThe language it is written in.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
default "excel"
labelstringIts column heading.
min length 1 · max length 80
descriptionstringWhat it means.
min length 1 · max length 1000
sportsarray of stringThe sports it applies to; none for every sport.
max items 12
entitystringThe kind of row it is for.
pattern ^[a-z][a-z_]{0,31}$
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does.
One of: recompute, sum, avg, min, max, none (open: new values may be added).
ResponseLink to this section
201 The attribute as saved.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · conflict
ExampleLink to this section
POST https://api.askkelly.ai/v1/attributes
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "target_trend",
"formula": "=ROLLING_AVG(targets, 4) - SEASON_AVG(targets)",
"sports": [
"nfl"
],
"description": "Targets over the last four games against his season average."
}
{
"id": "attr_6m77a97zzz32wcct2zw5",
"object": "attribute",
"name": "target_trend",
"reference": "my.target_trend",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 4) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [
"targets"
],
"saves": [],
"functions": [
"ROLLING_AVG",
"SEASON_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}POST https://api.askkelly.ai/v1/attributes
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "bad",
"formula": "=nope * 2"
}
{
"type": "https://docs.askkelly.ai/problems/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "nope isn't a stat Kelly knows.",
"param": "formula",
"doc_url": "https://docs.askkelly.ai/problems/invalid_request",
"request_id": "req_34ad8b6834278584b3ae0728",
"retryable": false,
"display_message": "Something in that request was not understood."
}POST https://api.askkelly.ai/v1/attributes
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "rush_form",
"formula": "=MY.FORM(rush_yards, 3)",
"sports": [
"nfl"
]
}
{
"id": "attr_4dfs6tgt65dxt62a7drm",
"object": "attribute",
"name": "rush_form",
"reference": "my.rush_form",
"label": "Rush form",
"description": null,
"sports": [
"nfl"
],
"entity": null,
"formula": "=MY.FORM(rush_yards, 3)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [
"rush_yards"
],
"saves": [
"tmpl_prhdz0jmqgawb2v92nw7"
],
"functions": []
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}POST /v1/attributes/copies
Keep a copy of a shared attributeLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Saves a copy of a attribute someone shared with you, by its share code, as your own. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
namestringThe name to keep it under; its own name by default.
min length 1 · max length 70
ResponseLink to this section
201 Your copy.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found · conflict
ExampleLink to this section
POST https://api.askkelly.ai/v1/attributes/copies
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"share_code": "pSDuF7gBjRQW",
"name": "trend_copy"
}
{
"id": "attr_5mhmvdcng5n0k1799ndh",
"object": "attribute",
"name": "trend_copy",
"reference": "my.trend_copy",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [
"targets"
],
"saves": [],
"functions": [
"ROLLING_AVG",
"SEASON_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}GET /v1/attributes/{ref}
Get a saved attributeLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
One of your saved attributes, by its ID or as a formula writes it (my.target_trend), with what it reads: Kelly's attributes, your other saves and the functions it calls. Anyone else's answers 404.
ParametersLink to this section
refstring · pathrequiredThe attribute's ID (attr_…) or how a formula writes it (my.target_trend).
min length 1 · max length 70
ResponseLink to this section
200 The attribute.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/attributes/my.target_trend
Authorization: Bearer $KELLY_API_KEY{
"id": "attr_6m77a97zzz32wcct2zw5",
"object": "attribute",
"name": "target_trend",
"reference": "my.target_trend",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 4) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [
"targets"
],
"saves": [],
"functions": [
"ROLLING_AVG",
"SEASON_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}GET https://api.askkelly.ai/v1/attributes/my.nothing_here
Authorization: Bearer $KELLY_API_KEY{
"type": "https://docs.askkelly.ai/problems/not_found",
"title": "Not found",
"status": 404,
"code": "not_found",
"detail": "You have no saved formula called my.nothing_here.",
"param": "name",
"doc_url": "https://docs.askkelly.ai/problems/not_found",
"request_id": "req_db2c052a87a5a981fc171165",
"retryable": false,
"display_message": "That could not be found."
}PATCH /v1/attributes/{ref}
Change a saved attributeLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_formulas · status live
Changes the fields you send. A new formula, mode, format or roll-up rule makes a new version; a new name changes nothing that uses it, because formulas hold its ID. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
refstring · pathrequiredThe attribute's ID (attr_…) or how a formula writes it (my.target_trend).
min length 1 · max length 70
Body, application/json (required):
namestringIts name: letters, digits and _, starting with a letter. my. is optional.
min length 1 · max length 70
formulastringThe formula, starting with =. A template starts with =LAMBDA(.
min length 1 · max length 2000
modestringThe language it is written in.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
labelstringIts column heading.
min length 1 · max length 80
descriptionstringWhat it means.
min length 1 · max length 1000
sportsarray of stringThe sports it applies to; none for every sport.
max items 12
entitystringThe kind of row it is for.
pattern ^[a-z][a-z_]{0,31}$
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does.
One of: recompute, sum, avg, min, max, none (open: new values may be added).
ResponseLink to this section
200 The attribute as it now is.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found · conflict
ExampleLink to this section
PATCH https://api.askkelly.ai/v1/attributes/my.target_trend
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)"
}
{
"id": "attr_6m77a97zzz32wcct2zw5",
"object": "attribute",
"name": "target_trend",
"reference": "my.target_trend",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 2,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [
"targets"
],
"saves": [],
"functions": [
"ROLLING_AVG",
"SEASON_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}DELETE /v1/attributes/{ref}
Delete a saved attributeLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_formulas · status live
Deletes it. While your other saves use it the answer is 409 naming them; send force=true to delete it anyway. Old answers still show the formula they used. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
refstring · pathrequiredThe attribute's ID (attr_…) or how a formula writes it (my.target_trend).
min length 1 · max length 70
forceboolean · queryDelete it even while your other saves use it.
default false
ResponseLink to this section
200 Deleted.
idstringrequiredThe deleted save's ID.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
deletedconstrequiredAlways true.
Always true.
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 · not_found · conflict
ExampleLink to this section
DELETE https://api.askkelly.ai/v1/attributes/my.trend_copy
Authorization: Bearer $KELLY_API_KEY{
"id": "attr_5mhmvdcng5n0k1799ndh",
"object": "attribute",
"deleted": true
}GET /v1/attributes/{ref}/versions
List a saved attribute's versionsLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
Every version, newest first: its formula, mode, type, shape and the catalogue and language versions it was checked against.
ParametersLink to this section
refstring · pathrequiredThe attribute's ID (attr_…) or how a formula writes it (my.target_trend).
min length 1 · max length 70
ResponseLink to this section
200 Every version, newest first.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredThe versions, newest first.
Show 10 fields
versionintegerThe version, from 1.
formulastringThe formula as typed.
modestringIts language.
value_typestringIts type.
shapestringIts shape.
rollupstringIts roll-up rule.
catalogue_versionstringThe catalogue it was checked against.
language_versionstringThe language it was checked against.
created_atstringWhen this version was saved.
format date-time
paramsarray of stringA template's parameters.
has_morebooleanrequiredAlways false: every version is listed.
next_cursornullrequiredAlways null.
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/attributes/my.target_trend/versions
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [
{
"version": 2,
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"rollup": "recompute",
"catalogue_version": "cat-1",
"language_version": "lang-1",
"created_at": "2026-10-04T17:30:00Z"
},
{
"version": 1,
"formula": "=ROLLING_AVG(targets, 4) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"rollup": "recompute",
"catalogue_version": "cat-1",
"language_version": "lang-1",
"created_at": "2026-10-04T17:30:00Z"
}
],
"has_more": false,
"next_cursor": null
}GET /v1/attributes/{ref}/trace
Trace a saved attributeLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
Excel's trace precedents and dependents: the saves it reads, directly or through others, the attributes and functions it reads, and your saves that use it.
ParametersLink to this section
refstring · pathrequiredThe attribute's ID (attr_…) or how a formula writes it (my.target_trend).
min length 1 · max length 70
ResponseLink to this section
200 What it reads and what uses it.
objectstringrequiredattribute_trace or template_trace.
One of: attribute_trace, template_trace (open: new values may be added).
idstringrequiredThe save traced.
referencestringrequiredHow a formula writes it.
attributesarray of stringrequiredKelly's attributes it reads directly.
functionsarray of stringrequiredThe functions it calls directly.
precedentsarray of objectrequiredYour saves it reads, directly or through others, nearest first.
Show 2 fields
idstringIts ID.
referencestringnullableHow a formula writes it.
dependentsarray of objectrequiredYour saves that use it, directly or through others, nearest first.
Show 2 fields
idstringIts ID.
referencestringnullableHow a formula writes it.
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/attributes/my.rush_form/trace
Authorization: Bearer $KELLY_API_KEY{
"object": "attribute_trace",
"id": "attr_4dfs6tgt65dxt62a7drm",
"reference": "my.rush_form",
"attributes": [
"rush_yards"
],
"functions": [],
"precedents": [
{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"reference": "MY.FORM"
}
],
"dependents": []
}POST /v1/attributes/{ref}/share
Share a saved attributeLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_formulas · status live
Turns its read-only share link on (on: true) or off. Anyone with the code reads its formula and how to use it, never whose it is. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
ResponseLink to this section
200 The attribute as it now is.
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 · payload_too_large · not_found
ExampleLink to this section
POST https://api.askkelly.ai/v1/attributes/my.target_trend/share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"on": true
}
{
"id": "attr_6m77a97zzz32wcct2zw5",
"object": "attribute",
"name": "target_trend",
"reference": "my.target_trend",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 2,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [
"targets"
],
"saves": [],
"functions": [
"ROLLING_AVG",
"SEASON_AVG"
]
},
"shared": true,
"share_code": "pSDuF7gBjRQW",
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}GET /v1/templates
List your saved templatesLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool get_my_formulas · status live
Your saved templates, most recently changed first, each with its formula, the mode it was written in, its type, shape, format and roll-up rule and its version. Filter by sport or by words in its name or label (q).
ParametersLink to this section
limitinteger · querySaves per page, 1 to 200.
min 1 · max 200 · default 50
cursorstring · queryThe next_cursor of the page before.
max length 200
sportstring · queryOnly saves for this sport (and those for every sport).
pattern ^[a-z0-9_]{2,16}$
qstring · queryWords in its name or label.
min length 1 · max length 70
ResponseLink to this section
200 A page of your saved templates.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredThe saves, most recently changed first.
Show 23 fields
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
has_morebooleanrequiredWhether another page follows.
next_cursorstringrequirednullablePass as cursor for the next page.
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
GET https://api.askkelly.ai/v1/templates
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [
{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"object": "template",
"name": "form",
"reference": "MY.FORM",
"label": "Form",
"description": "Any stat averaged over the last n games.",
"sports": [],
"entity": null,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": null,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}
],
"has_more": false,
"next_cursor": null
}POST /v1/templates
Save a templateLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Saves a named LAMBDA you can use as MY.FORM in any formula, on askkelly.ai, in chat, the API and MCP. The formula is checked first and refused with the spot and a plain-words reason when it can't run; a name you already use, or a formula that would read itself through others, is refused. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
namestringIts name: letters, digits and _, starting with a letter. my. is optional.
min length 1 · max length 70
formulastringThe formula, starting with =. A template starts with =LAMBDA(.
min length 1 · max length 2000
modestringThe language it is written in.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
default "excel"
labelstringIts column heading.
min length 1 · max length 80
descriptionstringWhat it means.
min length 1 · max length 1000
sportsarray of stringThe sports it applies to; none for every sport.
max items 12
entitystringThe kind of row it is for.
pattern ^[a-z][a-z_]{0,31}$
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does.
One of: recompute, sum, avg, min, max, none (open: new values may be added).
ResponseLink to this section
201 The template as saved.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · conflict
ExampleLink to this section
POST https://api.askkelly.ai/v1/templates
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "form",
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"description": "Any stat over the last n games."
}
{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"object": "template",
"name": "form",
"reference": "MY.FORM",
"label": "Form",
"description": "Any stat over the last n games.",
"sports": [],
"entity": null,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [],
"saves": [],
"functions": [
"LAMBDA",
"ROLLING_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}POST /v1/templates/copies
Keep a copy of a shared templateLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Saves a copy of a template someone shared with you, by its share code, as your own. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
namestringThe name to keep it under; its own name by default.
min length 1 · max length 70
ResponseLink to this section
201 Your copy.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found · conflict
ExampleLink to this section
POST https://api.askkelly.ai/v1/templates/copies
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"share_code": "WqsP9KnVosVe",
"name": "form_copy"
}
{
"id": "tmpl_g56yvg9xk677npq9brsj",
"object": "template",
"name": "form_copy",
"reference": "MY.FORM_COPY",
"label": "Form",
"description": "Any stat averaged over the last n games.",
"sports": [],
"entity": null,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [],
"saves": [],
"functions": [
"LAMBDA",
"ROLLING_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}GET /v1/templates/{ref}
Get a saved templateLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
One of your saved templates, by its ID or as a formula writes it (MY.FORM), with what it reads: Kelly's attributes, your other saves and the functions it calls. Anyone else's answers 404.
ParametersLink to this section
refstring · pathrequiredThe template's ID (tmpl_…) or how a formula writes it (MY.FORM).
min length 1 · max length 70
ResponseLink to this section
200 The template.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/templates/MY.FORM
Authorization: Bearer $KELLY_API_KEY{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"object": "template",
"name": "form",
"reference": "MY.FORM",
"label": "Form",
"description": "Any stat over the last n games.",
"sports": [],
"entity": null,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [],
"saves": [],
"functions": [
"LAMBDA",
"ROLLING_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}PATCH /v1/templates/{ref}
Change a saved templateLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Changes the fields you send. A new formula, mode, format or roll-up rule makes a new version; a new name changes nothing that uses it, because formulas hold its ID. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
refstring · pathrequiredThe template's ID (tmpl_…) or how a formula writes it (MY.FORM).
min length 1 · max length 70
Body, application/json (required):
namestringIts name: letters, digits and _, starting with a letter. my. is optional.
min length 1 · max length 70
formulastringThe formula, starting with =. A template starts with =LAMBDA(.
min length 1 · max length 2000
modestringThe language it is written in.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
labelstringIts column heading.
min length 1 · max length 80
descriptionstringWhat it means.
min length 1 · max length 1000
sportsarray of stringThe sports it applies to; none for every sport.
max items 12
entitystringThe kind of row it is for.
pattern ^[a-z][a-z_]{0,31}$
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does.
One of: recompute, sum, avg, min, max, none (open: new values may be added).
ResponseLink to this section
200 The template as it now is.
idstringrequiredIts ID: attr_… for an attribute, tmpl_… for a template.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
namestringrequiredIts name, lower case.
referencestringrequiredHow a formula writes it: my.target_trend or MY.FORM.
labelstringIts column heading.
descriptionstringnullableWhat it means, in the person's words.
sportsarray of stringThe sports it applies to; empty for every sport.
entitystringnullableThe kind of row it is for (player, team, game, market).
formulastringrequiredThe formula as typed, in its mode.
modestringrequiredThe language it was written in; Excel unless the person chose another.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
paramsarray of stringA template's LAMBDA parameters, in order; empty for an attribute.
value_typestringIts type: number, percent, price, probability, money:USD…
shapestringOne value per row, one per group, or a table.
One of: column, summary, table (open: new values may be added).
formatobjectHow it is shown: decimals, percent, odds format.
rollupstringWhat a totals row does: recompute from parts (ratios), sum, avg…
One of: recompute, sum, avg, min, max, none (open: new values may be added).
versionintegerrequiredIts current version, from 1.
catalogue_versionstringThe stat catalogue it was checked against.
language_versionstringThe formula language it was checked against.
readsobjectnullableWhat it reads: attributes, saves (IDs) and functions; on a single read.
Show 3 fields
attributesarray of stringKelly's attributes, by key.
savesarray of stringYour other saves, by ID.
functionsarray of stringThe functions it calls.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found · conflict
ExampleLink to this section
PATCH https://api.askkelly.ai/v1/templates/MY.FORM
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"description": "Any stat averaged over the last n games."
}
{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"object": "template",
"name": "form",
"reference": "MY.FORM",
"label": "Form",
"description": "Any stat averaged over the last n games.",
"sports": [],
"entity": null,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [],
"saves": [],
"functions": [
"LAMBDA",
"ROLLING_AVG"
]
},
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}DELETE /v1/templates/{ref}
Delete a saved templateLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Deletes it. While your other saves use it the answer is 409 naming them; send force=true to delete it anyway. Old answers still show the formula they used. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
refstring · pathrequiredThe template's ID (tmpl_…) or how a formula writes it (MY.FORM).
min length 1 · max length 70
forceboolean · queryDelete it even while your other saves use it.
default false
ResponseLink to this section
200 Deleted.
idstringrequiredThe deleted save's ID.
objectstringrequiredattribute or template.
One of: attribute, template (open: new values may be added).
deletedconstrequiredAlways true.
Always true.
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 · not_found · conflict
ExampleLink to this section
DELETE https://api.askkelly.ai/v1/templates/MY.FORM?force=true
Authorization: Bearer $KELLY_API_KEY{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"object": "template",
"deleted": true
}DELETE https://api.askkelly.ai/v1/templates/MY.FORM
Authorization: Bearer $KELLY_API_KEY{
"type": "https://docs.askkelly.ai/problems/conflict",
"title": "Conflict",
"status": 409,
"code": "conflict",
"detail": "my.rush_form still use it. Change those first, or delete with force.",
"param": "id",
"doc_url": "https://docs.askkelly.ai/problems/conflict",
"request_id": "req_2eb417b38770bd24b3cc58b4",
"retryable": false,
"display_message": "That's already in use."
}GET /v1/templates/{ref}/versions
List a saved template's versionsLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
Every version, newest first: its formula, mode, type, shape and the catalogue and language versions it was checked against.
ParametersLink to this section
refstring · pathrequiredThe template's ID (tmpl_…) or how a formula writes it (MY.FORM).
min length 1 · max length 70
ResponseLink to this section
200 Every version, newest first.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredThe versions, newest first.
Show 10 fields
versionintegerThe version, from 1.
formulastringThe formula as typed.
modestringIts language.
value_typestringIts type.
shapestringIts shape.
rollupstringIts roll-up rule.
catalogue_versionstringThe catalogue it was checked against.
language_versionstringThe language it was checked against.
created_atstringWhen this version was saved.
format date-time
paramsarray of stringA template's parameters.
has_morebooleanrequiredAlways false: every version is listed.
next_cursornullrequiredAlways null.
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/templates/MY.FORM/versions
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [
{
"version": 1,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"rollup": "recompute",
"catalogue_version": "cat-1",
"language_version": "lang-1",
"created_at": "2026-10-04T17:30:00Z"
}
],
"has_more": false,
"next_cursor": null
}GET /v1/templates/{ref}/trace
Trace a saved templateLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
Excel's trace precedents and dependents: the saves it reads, directly or through others, the attributes and functions it reads, and your saves that use it.
ParametersLink to this section
refstring · pathrequiredThe template's ID (tmpl_…) or how a formula writes it (MY.FORM).
min length 1 · max length 70
ResponseLink to this section
200 What it reads and what uses it.
objectstringrequiredattribute_trace or template_trace.
One of: attribute_trace, template_trace (open: new values may be added).
idstringrequiredThe save traced.
referencestringrequiredHow a formula writes it.
attributesarray of stringrequiredKelly's attributes it reads directly.
functionsarray of stringrequiredThe functions it calls directly.
precedentsarray of objectrequiredYour saves it reads, directly or through others, nearest first.
Show 2 fields
idstringIts ID.
referencestringnullableHow a formula writes it.
dependentsarray of objectrequiredYour saves that use it, directly or through others, nearest first.
Show 2 fields
idstringIts ID.
referencestringnullableHow a formula writes it.
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/templates/MY.FORM/trace
Authorization: Bearer $KELLY_API_KEY{
"object": "template_trace",
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"reference": "MY.FORM",
"attributes": [],
"functions": [
"LAMBDA",
"ROLLING_AVG"
],
"precedents": [],
"dependents": [
{
"id": "attr_4dfs6tgt65dxt62a7drm",
"reference": "my.rush_form"
}
]
}POST /v1/templates/{ref}/share
Share a saved templateLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Turns its read-only share link on (on: true) or off. Anyone with the code reads its formula and how to use it, never whose it is. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
ResponseLink to this section
200 The template as it now is.
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 · payload_too_large · not_found
ExampleLink to this section
POST https://api.askkelly.ai/v1/templates/MY.FORM/share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"on": true
}
{
"id": "tmpl_prhdz0jmqgawb2v92nw7",
"object": "template",
"name": "form",
"reference": "MY.FORM",
"label": "Form",
"description": "Any stat averaged over the last n games.",
"sports": [],
"entity": null,
"formula": "=LAMBDA(stat, n, ROLLING_AVG(stat, n))",
"mode": "excel",
"params": [
"stat",
"n"
],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 1,
"catalogue_version": "cat-1",
"language_version": "lang-1",
"reads": {
"attributes": [],
"saves": [],
"functions": [
"LAMBDA",
"ROLLING_AVG"
]
},
"shared": true,
"share_code": "WqsP9KnVosVe",
"created_at": "2026-10-04T17:30:00Z",
"updated_at": "2026-10-04T17:30:00Z"
}POST /v1/attributes:validate
Check a formulaLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool check_formula · status live
Checks a formula without saving it: the parse tree, its type and unit, its shape, what it reads, the source tags that say where its result may go, and each mistake with its spot, a plain-words reason and a fix. Your saved attributes and templates are in scope.
ParametersLink to this section
Body, application/json (required):
formulastringThe formula, starting with =.
min length 1 · max length 2000
modestringThe language it is written in.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
default "excel"
sportstringThe sport whose attributes it reads.
pattern ^[a-z0-9_]{2,16}$
entitystringThe kind of row it is for.
pattern ^[a-z][a-z_]{0,31}$
ResponseLink to this section
200 The language's check: errors, when it has any, are in the body.
treeobjectrequirednullableThe bound parse tree, every node with its [start, end) spot; null when the formula has errors.
value_typeobjectnullableIts type: {base, unit?, currency?}.
shapestringnullablecolumn, summary or table.
One of: column, summary, table (open: new values may be added).
paramsarray of stringA LAMBDA's parameters, in order.
refsobjectWhat it reads: Kelly's attributes, your saves, the functions it calls.
catalogue_versionstringThe attribute catalogue it was checked against.
language_versionstringrequiredThe formula language's version.
errorsarray of objectrequiredEach mistake: code, a plain-words message, its at spot and a suggestion when there is one.
tagsobjectSource tags: the strictest rights class of its inputs, their tags, and the uses its result allows (a value built on Kelly's edge is never sorted, filtered, ranked or alerted on, D16).
hashstringSHA-256 of the tree without positions.
show_asobjectThe formula written in every input mode (Show as, AB7), keyed by mode; null for a mode that cannot say it. Off askkelly.ai an input you may not show is written as a placeholder. Present only when the formula checks.
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 · payload_too_large
ExampleLink to this section
POST https://api.askkelly.ai/v1/attributes:validate
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"formula": "=nope + my.target_trend",
"sport": "nfl"
}
{
"tree": {
"src": "nope + my.target_trend"
},
"value_type": {
"base": "number"
},
"shape": "column",
"params": [],
"refs": {
"attributes": [],
"saves": [
"attr_6m77a97zzz32wcct2zw5"
],
"functions": []
},
"catalogue_version": "cat-1",
"language_version": "lang-1",
"errors": [
{
"code": "unknown_attribute",
"message": "nope isn't a stat Kelly knows.",
"at": [
0,
0
]
}
],
"tags": {
"rights": "owner_only",
"tags": [],
"uses": [
"show"
]
}
}POST /v1/attributes:preview
Preview a formula on real rowsLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool preview_formula · status live
Checks a formula and runs it on up to 50 rows of a data-grid view (a competition, players or teams, game or season rows, seasons): each row's inputs and the formula's value, or one value for a summary formula. A template runs with the inputs you give. Nothing is saved. Relations and saved formulas are listed as not yet previewable.
ParametersLink to this section
Body, application/json (required):
formulastringThe formula, starting with =.
min length 1 · max length 2000
modestringThe language it is written in.
One of: excel, sheets, sql, polars, pandas, dplyr, dax, tableau, pine (open: new values may be added).
default "excel"
competitionstringThe competition slug (nfl, nba, ncaaf).
pattern ^[a-z0-9_]{2,16}$
entitystringplayer (default) or team.
One of: player, team (open: new values may be added).
default "player"
grainstringOne row per game, season (default) or career.
One of: game, season, career (open: new values may be added).
default "season"
entity_idsarray of stringUp to 20 players or teams (plr_, tm_); none runs it on a page of every one.
max items 20
from_seasonstringFirst season.
pattern ^[0-9]{4}$
to_seasonstringLast season.
pattern ^[0-9]{4}$
season_typestringregular (default), postseason or both.
One of: regular, postseason, both (open: new values may be added).
limitintegerRows, 1 to 50; default 20.
min 1 · max 50 · default 20
inputsobjectA template's inputs by parameter name: a number, text or true/false each.
ResponseLink to this section
200 The check, and the formula run on the rows.
objectstringrequiredformula_preview.
One of: formula_preview (open: new values may be added).
checkobjectrequiredA formula checked by the language (ADR-K591, registry/contracts/formulas/formula-check.schema.json): the same body as Kelly MCP's check_formula.
Show 11 fields
treeobjectrequirednullableThe bound parse tree, every node with its [start, end) spot; null when the formula has errors.
value_typeobjectnullableIts type: {base, unit?, currency?}.
shapestringnullablecolumn, summary or table.
One of: column, summary, table (open: new values may be added).
paramsarray of stringA LAMBDA's parameters, in order.
refsobjectWhat it reads: Kelly's attributes, your saves, the functions it calls.
catalogue_versionstringThe attribute catalogue it was checked against.
language_versionstringrequiredThe formula language's version.
errorsarray of objectrequiredEach mistake: code, a plain-words message, its at spot and a suggestion when there is one.
tagsobjectSource tags: the strictest rights class of its inputs, their tags, and the uses its result allows (a value built on Kelly's edge is never sorted, filtered, ranked or alerted on, D16).
hashstringSHA-256 of the tree without positions.
show_asobjectThe formula written in every input mode (Show as, AB7), keyed by mode; null for a mode that cannot say it. Off askkelly.ai an input you may not show is written as a placeholder. Present only when the formula checks.
columnsarray of objectrequiredThe attributes it reads, as the view's columns: key, attribute ID, label, unit and locked.
rowsarray of objectrequiredEach row: key, label, href, season, at (its date or season), the inputs it read and the formula's value (an Excel error as its text, null for no value).
summarynumber | string | booleannullableA summary formula's one value.
unsupportedarray of stringrequiredWhat it reads that the preview can't yet: a relation (opponent.x) or a saved formula. Nothing runs while any is listed.
lockedarray of stringColumns the Rights Register withholds here: no values.
total_rowsintegerrequiredRows the view has across every page.
sourcesarray of objectThe view's sources: licence and attribution.
as_ofstringnullableWhen the data was read (ISO 8601).
format date-time
snapshot_idstringnullableThe lake snapshot read.
summary_textstringOne sentence: what ran, on how many rows.
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 · payload_too_large · unknown_metric · query_too_broad · snapshot_expired · upstream_timeout
ExampleLink to this section
POST https://api.askkelly.ai/v1/attributes:preview
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"formula": "=points / games",
"competition": "nba",
"grain": "season",
"limit": 3
}
{
"object": "formula_preview",
"check": {
"language_version": "1.0.0",
"mode": "excel",
"source": "=points / games",
"ok": true,
"errors": [],
"catalogue_version": "1:0",
"tree": {
"k": "op",
"op": "/",
"args": [
{
"k": "ref",
"id": "stat.basketball.points",
"name": "points",
"at": [
1,
7
]
},
{
"k": "ref",
"id": "stat.basketball.games_played",
"name": "games",
"at": [
10,
15
]
}
],
"at": [
1,
15
]
},
"hash": "b2082662a016db478df573781495885c5d4c098a020ff1fa8228882aa73b4438",
"shape": "column",
"value_type": {
"base": "number",
"unit": "pts/games"
},
"tags": {
"rights": "redistribute_derived",
"tags": [],
"uses": [
"show",
"sort",
"filter",
"rank",
"alert",
"export",
"api",
"mcp"
]
},
"params": [],
"refs": {
"attributes": [
"stat.basketball.points",
"stat.basketball.games_played"
],
"saves": [],
"functions": []
},
"grain": "game"
},
"columns": [
{
"key": "points",
"attribute": "stat.basketball.points",
"label": "Points",
"unit": "pts",
"locked": false
},
{
"key": "games_played",
"attribute": "stat.basketball.games_played",
"label": "Games played",
"unit": "games",
"locked": false
}
],
"rows": [
{
"key": "plr_emrxad012xnt6nbe4vy4:2025-26",
"label": "Pam Two",
"href": "/players/pam-two-emrxad012xnt6nbe4vy4",
"season": "2025-26",
"at": "2025-26",
"inputs": {
"points": 900,
"games_played": 70
},
"value": 12.857142857142858
},
{
"key": "plr_znvh1bpfvdj2d79szye4:2025-26",
"label": "Pat One",
"href": "/players/pat-one-znvh1bpfvdj2d79szye4",
"season": "2025-26",
"at": "2025-26",
"inputs": {
"points": 96,
"games_played": 3
},
"value": 32
}
],
"summary": null,
"unsupported": [],
"total_rows": 2,
"sources": [
{
"key": "s1",
"source": "balldontlie",
"licence": "BALLDONTLIE Terms of Service, last updated September 17, 2026, §6: Data may be used for lawful commercial purposes, incl",
"snapshot_id": "snap_52",
"recorded_at": null,
"official": true,
"reconstructed": false,
"disagrees": false,
"precedence": 1
}
],
"as_of": "2026-11-06T00:00:00Z",
"snapshot_id": "snap_52",
"locked": [],
"summary_text": "The formula on 2 rows of 2."
}GET /v1/shared-formulas/{code}
Read a shared formulaLink to this section
public, no key needed · 0 credits, not charged during the beta · status live
A saved attribute or template someone shared, by its link's code: its formula, mode, type and parameters, never whose it is. No key needed. A link turned off answers 404.
ParametersLink to this section
ResponseLink to this section
200 The shared formula.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/shared-formulas/pSDuF7gBjRQW{
"object": "shared_formula",
"kind": "attribute",
"name": "target_trend",
"reference": "my.target_trend",
"label": "Target trend",
"description": "Targets over the last four games against his season average.",
"sports": [
"nfl"
],
"entity": null,
"formula": "=ROLLING_AVG(targets, 3) - SEASON_AVG(targets)",
"mode": "excel",
"params": [],
"value_type": "number",
"shape": "column",
"format": {},
"rollup": "recompute",
"version": 2
}GET https://api.askkelly.ai/v1/shared-formulas/abcdefghjk{
"type": "https://docs.askkelly.ai/problems/not_found",
"title": "Not found",
"status": 404,
"code": "not_found",
"detail": "That share link is off or never existed.",
"param": "code",
"doc_url": "https://docs.askkelly.ai/problems/not_found",
"request_id": "req_191e28751ceadd037caa0773",
"retryable": false,
"display_message": "That could not be found."
}GET /v1/macros
List your macrosLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool get_my_automations · status live
Your saved macros, most recently changed first: each one's steps (commands such as grid.sort, never keys), its named inputs, its palette code and hotkey and how often it has run.
ResponseLink to this section
200 Your macros.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredYour macros.
Show 13 fields
idstringrequiredIts ID (mac_…).
objectconstrequiredAlways macro.
Always "macro".
namestringrequiredIts name.
codestringnullableIts palette code, such as SUN.
hotkeystringnullableIts hotkey or key sequence.
stepsarray of objectrequiredIts steps, in order.
Show 4 fields
commandstringA command ID such as grid.sort or page.tab.stats.
colstringnullableThe column it acts on, when it acts on one.
arganyIts argument; {{name}} names an input.
countintegernullableHow many times, for a repeatable step.
inputsarray of objectrequiredIts named inputs.
Show 5 fields
namestringIts name.
labelstringnullableIts label.
typestringIts type.
One of: text, number, integer, column, player, team, game, season, week, sport, formula (open: new values may be added).
defaultanyIts value when none is given; absent when it has none.
requiredbooleanWhether a run must give it.
gridstringnullableThe grid it was recorded on, when it was.
runsintegerHow often it has run.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
has_morebooleanrequiredAlways false: every one is listed.
next_cursornullrequiredAlways null.
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
GET https://api.askkelly.ai/v1/macros
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [
{
"id": "mac_7d161b44rs7heyddj4zr",
"object": "macro",
"name": "Sunday targets",
"code": "SUN",
"hotkey": null,
"steps": [
{
"arg": "{{week}}",
"col": "week",
"command": "grid.filter"
},
{
"arg": "desc",
"col": "targets",
"command": "grid.sort"
}
],
"inputs": [
{
"name": "week",
"type": "week",
"label": null,
"required": true
}
],
"grid": null,
"runs": 0,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}
],
"has_more": false,
"next_cursor": null
}POST /v1/macros
Save a macroLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_automations · status live
Saves a list of steps with named inputs ({{week}}) that runs on askkelly.ai, in chat, the API and MCP. A step that would place a bet, submit a slip or confirm a league move is refused (D8); a name or code you already use is refused. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
namestringIts name.
min length 1 · max length 200
codestringA palette code: a capital letter then up to 7 capitals or digits.
pattern ^[A-Z][A-Z0-9]{1,7}$
hotkeystringA hotkey or key sequence.
min length 1 · max length 40
stepsarray of objectIts steps: {command, col?, arg?, count?}.
min items 1 · max items 50
inputsarray of objectIts inputs: {name, label?, type?, default?, required?}.
max items 10
gridstringThe grid it is for.
pattern ^[a-z][a-z0-9_.]{0,63}$
ResponseLink to this section
201 The macro as saved.
idstringrequiredIts ID (mac_…).
objectconstrequiredAlways macro.
Always "macro".
namestringrequiredIts name.
codestringnullableIts palette code, such as SUN.
hotkeystringnullableIts hotkey or key sequence.
stepsarray of objectrequiredIts steps, in order.
Show 4 fields
commandstringA command ID such as grid.sort or page.tab.stats.
colstringnullableThe column it acts on, when it acts on one.
arganyIts argument; {{name}} names an input.
countintegernullableHow many times, for a repeatable step.
inputsarray of objectrequiredIts named inputs.
Show 5 fields
namestringIts name.
labelstringnullableIts label.
typestringIts type.
One of: text, number, integer, column, player, team, game, season, week, sport, formula (open: new values may be added).
defaultanyIts value when none is given; absent when it has none.
requiredbooleanWhether a run must give it.
gridstringnullableThe grid it was recorded on, when it was.
runsintegerHow often it has run.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · conflict
ExampleLink to this section
POST https://api.askkelly.ai/v1/macros
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "Sunday targets",
"code": "SUN",
"inputs": [
{
"name": "week",
"type": "week"
}
],
"steps": [
{
"command": "grid.filter",
"col": "week",
"arg": "{{week}}"
},
{
"command": "grid.sort",
"col": "targets",
"arg": "desc"
}
]
}
{
"id": "mac_7d161b44rs7heyddj4zr",
"object": "macro",
"name": "Sunday targets",
"code": "SUN",
"hotkey": null,
"steps": [
{
"arg": "{{week}}",
"col": "week",
"command": "grid.filter"
},
{
"arg": "desc",
"col": "targets",
"command": "grid.sort"
}
],
"inputs": [
{
"name": "week",
"type": "week",
"label": null,
"required": true
}
],
"grid": null,
"runs": 0,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}GET /v1/macros/{ref}
Get a macroLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
One of your macros, by its ID, its palette code or its name. Anyone else's answers 404.
ParametersLink to this section
refstring · pathrequiredThe macro's ID (mac_…), palette code or name.
min length 1 · max length 200
ResponseLink to this section
200 The macro.
idstringrequiredIts ID (mac_…).
objectconstrequiredAlways macro.
Always "macro".
namestringrequiredIts name.
codestringnullableIts palette code, such as SUN.
hotkeystringnullableIts hotkey or key sequence.
stepsarray of objectrequiredIts steps, in order.
Show 4 fields
commandstringA command ID such as grid.sort or page.tab.stats.
colstringnullableThe column it acts on, when it acts on one.
arganyIts argument; {{name}} names an input.
countintegernullableHow many times, for a repeatable step.
inputsarray of objectrequiredIts named inputs.
Show 5 fields
namestringIts name.
labelstringnullableIts label.
typestringIts type.
One of: text, number, integer, column, player, team, game, season, week, sport, formula (open: new values may be added).
defaultanyIts value when none is given; absent when it has none.
requiredbooleanWhether a run must give it.
gridstringnullableThe grid it was recorded on, when it was.
runsintegerHow often it has run.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/macros/SUN
Authorization: Bearer $KELLY_API_KEY{
"id": "mac_7d161b44rs7heyddj4zr",
"object": "macro",
"name": "Sunday targets",
"code": "SUN",
"hotkey": null,
"steps": [
{
"arg": "{{week}}",
"col": "week",
"command": "grid.filter"
},
{
"arg": "desc",
"col": "targets",
"command": "grid.sort"
}
],
"inputs": [
{
"name": "week",
"type": "week",
"label": null,
"required": true
}
],
"grid": null,
"runs": 0,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}GET https://api.askkelly.ai/v1/macros/NOPE
Authorization: Bearer $KELLY_API_KEY{
"type": "https://docs.askkelly.ai/problems/not_found",
"title": "Not found",
"status": 404,
"code": "not_found",
"detail": "No such macro.",
"param": "id",
"doc_url": "https://docs.askkelly.ai/problems/not_found",
"request_id": "req_10fb714f9832e4db29e37d11",
"retryable": false,
"display_message": "That could not be found."
}PATCH /v1/macros/{ref}
Change a macroLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Changes the fields you send; every step's inputs must still be the macro's inputs. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
refstring · pathrequiredThe macro's ID (mac_…), palette code or name.
min length 1 · max length 200
Body, application/json (required):
namestringIts name.
min length 1 · max length 200
codestringA palette code: a capital letter then up to 7 capitals or digits.
pattern ^[A-Z][A-Z0-9]{1,7}$
hotkeystringA hotkey or key sequence.
min length 1 · max length 40
stepsarray of objectIts steps: {command, col?, arg?, count?}.
min items 1 · max items 50
inputsarray of objectIts inputs: {name, label?, type?, default?, required?}.
max items 10
gridstringThe grid it is for.
pattern ^[a-z][a-z0-9_.]{0,63}$
ResponseLink to this section
200 The macro as it now is.
idstringrequiredIts ID (mac_…).
objectconstrequiredAlways macro.
Always "macro".
namestringrequiredIts name.
codestringnullableIts palette code, such as SUN.
hotkeystringnullableIts hotkey or key sequence.
stepsarray of objectrequiredIts steps, in order.
Show 4 fields
commandstringA command ID such as grid.sort or page.tab.stats.
colstringnullableThe column it acts on, when it acts on one.
arganyIts argument; {{name}} names an input.
countintegernullableHow many times, for a repeatable step.
inputsarray of objectrequiredIts named inputs.
Show 5 fields
namestringIts name.
labelstringnullableIts label.
typestringIts type.
One of: text, number, integer, column, player, team, game, season, week, sport, formula (open: new values may be added).
defaultanyIts value when none is given; absent when it has none.
requiredbooleanWhether a run must give it.
gridstringnullableThe grid it was recorded on, when it was.
runsintegerHow often it has run.
created_atstringWhen it was saved.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found · conflict
ExampleLink to this section
PATCH https://api.askkelly.ai/v1/macros/SUN
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"hotkey": "g s"
}
{
"id": "mac_7d161b44rs7heyddj4zr",
"object": "macro",
"name": "Sunday targets",
"code": "SUN",
"hotkey": "g s",
"steps": [
{
"arg": "{{week}}",
"col": "week",
"command": "grid.filter"
},
{
"arg": "desc",
"col": "targets",
"command": "grid.sort"
}
],
"inputs": [
{
"name": "week",
"type": "week",
"label": null,
"required": true
}
],
"grid": null,
"runs": 0,
"shared": false,
"share_code": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}DELETE /v1/macros/{ref}
Delete a macroLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Deletes it. An automation that ran it keeps its condition and action, without the macro. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
refstring · pathrequiredThe macro's ID (mac_…), palette code or name.
min length 1 · max length 200
ResponseLink to this section
200 Deleted.
idstringrequiredIts ID.
objectconstrequiredAlways macro.
Always "macro".
deletedconstrequiredAlways true.
Always true.
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 · not_found
ExampleLink to this section
DELETE https://api.askkelly.ai/v1/macros/SUN
Authorization: Bearer $KELLY_API_KEY{
"id": "mac_7d161b44rs7heyddj4zr",
"object": "macro",
"deleted": true
}POST /v1/macros/{ref}:run
Run a macroLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool update_my_automations · status live
Fills in the macro's inputs and answers its steps, ready to apply to a view (get_view in the API and MCP, the grid on askkelly.ai). A missing or mistyped input is refused, named.
ParametersLink to this section
refstring · pathrequiredThe macro's ID (mac_…), palette code or name.
min length 1 · max length 200
Body, application/json (required):
inputsobjectEach input's value, by name.
ResponseLink to this section
200 The steps, filled in.
objectconstrequiredAlways macro_run.
Always "macro_run".
idstringrequiredThe macro's ID.
namestringIts name.
gridstringnullableThe grid it was recorded on.
stepsarray of objectrequiredThe steps to apply, in order.
Show 4 fields
commandstringA command ID such as grid.sort or page.tab.stats.
colstringnullableThe column it acts on, when it acts on one.
arganyIts argument; {{name}} names an input.
countintegernullableHow many times, for a repeatable step.
ran_atstringWhen it ran.
format date-time
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 · payload_too_large · not_found
ExampleLink to this section
POST https://api.askkelly.ai/v1/macros/SUN:run
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"inputs": {
"week": 10
}
}
{
"object": "macro_run",
"id": "mac_7d161b44rs7heyddj4zr",
"name": "Sunday targets",
"grid": null,
"steps": [
{
"arg": 10,
"col": "week",
"command": "grid.filter"
},
{
"arg": "desc",
"col": "targets",
"command": "grid.sort"
}
],
"ran_at": "2026-10-04T17:30:00+00:00"
}GET /v1/automations
List your automationsLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool get_my_automations · status live
Your automations: each one's trigger (a schedule or a data event), condition, macro, action, cooldown, whether it is on or paused, and when it last ran and acted.
ResponseLink to this section
200 Your automations.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredYour automations.
Show 18 fields
idstringrequiredIts ID (auto_…).
objectconstrequiredAlways automation.
Always "automation".
namestringrequiredIts name.
triggerobjectrequiredkind (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and every_minutes, sport or min_points as the kind takes.
scopeobjectThe sport and kind of row its condition reads, and window (this_week: the sport's games this week) when it has one; or a saved rule whose matches it alerts on (backtester T6, F52).
Show 4 fields
rule_idstringA saved rule (rl_…): the automation alerts on its matches, with no condition or view.
pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
rule_versionintegerThe version alerted; the latest when absent.
min 1
rule_eventsarray of stringThe events it alerts on (all three when absent).
min_price_americanintegerAlert only at this American price or better.
conditionstringnullableIts condition, a formula, as typed.
macro_idstringnullableThe macro it runs, when it runs one.
viewobjectnullableThe view spec its condition runs over.
actionobjectrequiredkind (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
cooldown_secondsintegerThe quiet time after it acts, in seconds.
enabledbooleanrequiredWhether it runs.
paused_reasonstringnullableWhy Kelly paused it, when it did.
failuresintegerFailed checks in a row.
last_run_atstringnullableIts last check.
format date-time
last_fired_atstringnullableWhen it last acted.
format date-time
next_run_atstringnullableIts next scheduled check.
format date-time
created_atstringWhen it was made.
format date-time
updated_atstringWhen it last changed.
format date-time
has_morebooleanrequiredAlways false: every one is listed.
next_cursornullrequiredAlways null.
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
GET https://api.askkelly.ai/v1/automations
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [
{
"id": "auto_nkqn9520r75fqfmcrhjr",
"object": "automation",
"name": "Big spread moves",
"trigger": {
"kind": "line_move",
"sport": "nfl",
"min_points": 1.5
},
"scope": {
"sport": "nfl",
"window": "this_week"
},
"condition": "=spread >= 3",
"macro_id": null,
"view": null,
"action": {
"kind": "alert",
"note": "Spread moved past 3.",
"once_per": "match"
},
"cooldown_seconds": 3600,
"enabled": true,
"paused_reason": null,
"failures": 0,
"last_run_at": null,
"last_fired_at": null,
"next_run_at": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}
],
"has_more": false,
"next_cursor": null
}POST /v1/automations
Make an automationLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_automations · status live
A trigger (every N minutes, prices refreshed, a line move, a game going final, an injury update, a lineup posted), an optional condition written as a formula, an optional macro, and one action: an alert, a saved view refreshed, a watchlist, or a bet slip filled for you to confirm. It never places a bet (D8). A condition on Kelly's own probability or edge is refused (D16). Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
Body, application/json (required):
namestringIts name.
min length 1 · max length 200
triggerobject{kind, every_minutes?, sport?, min_points?}.
scopeobject{sport?, entity?, window?}: the rows its condition reads; window: this_week reads the sport's games this week. Or {rule_id, rule_version?, rule_events?, min_price_american?}: alert on a saved rule's matches (backtester T6).
conditionstringA formula, starting with =.
min length 1 · max length 2000
modestringThe condition's language.
default "excel"
macrostringA macro's ID, code or name.
max length 200
viewobjectA view spec its condition runs over.
actionobject{kind, view_id?, watchlist?, note?, once_per?}; once_per: match acts once per match (each game told once), set (default) once per set of matches.
cooldown_secondsintegerQuiet time after it acts, in seconds.
min 0 · max 604800 · default 3600
enabledbooleanWhether it runs.
default true
ResponseLink to this section
201 The automation as made.
idstringrequiredIts ID (auto_…).
objectconstrequiredAlways automation.
Always "automation".
namestringrequiredIts name.
triggerobjectrequiredkind (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and every_minutes, sport or min_points as the kind takes.
scopeobjectThe sport and kind of row its condition reads, and window (this_week: the sport's games this week) when it has one; or a saved rule whose matches it alerts on (backtester T6, F52).
Show 4 fields
rule_idstringA saved rule (rl_…): the automation alerts on its matches, with no condition or view.
pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
rule_versionintegerThe version alerted; the latest when absent.
min 1
rule_eventsarray of stringThe events it alerts on (all three when absent).
min_price_americanintegerAlert only at this American price or better.
conditionstringnullableIts condition, a formula, as typed.
macro_idstringnullableThe macro it runs, when it runs one.
viewobjectnullableThe view spec its condition runs over.
actionobjectrequiredkind (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
cooldown_secondsintegerThe quiet time after it acts, in seconds.
enabledbooleanrequiredWhether it runs.
paused_reasonstringnullableWhy Kelly paused it, when it did.
failuresintegerFailed checks in a row.
last_run_atstringnullableIts last check.
format date-time
last_fired_atstringnullableWhen it last acted.
format date-time
next_run_atstringnullableIts next scheduled check.
format date-time
created_atstringWhen it was made.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found
ExampleLink to this section
POST https://api.askkelly.ai/v1/automations
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "Big spread moves",
"trigger": {
"kind": "line_move",
"sport": "nfl",
"min_points": 1.5
},
"scope": {
"sport": "nfl",
"window": "this_week"
},
"condition": "=spread >= 3",
"action": {
"kind": "alert",
"once_per": "match",
"note": "Spread moved past 3."
}
}
{
"id": "auto_nkqn9520r75fqfmcrhjr",
"object": "automation",
"name": "Big spread moves",
"trigger": {
"kind": "line_move",
"sport": "nfl",
"min_points": 1.5
},
"scope": {
"sport": "nfl",
"window": "this_week"
},
"condition": "=spread >= 3",
"macro_id": null,
"view": null,
"action": {
"kind": "alert",
"note": "Spread moved past 3.",
"once_per": "match"
},
"cooldown_seconds": 3600,
"enabled": true,
"paused_reason": null,
"failures": 0,
"last_run_at": null,
"last_fired_at": null,
"next_run_at": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}POST https://api.askkelly.ai/v1/automations
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"name": "Edge",
"trigger": {
"kind": "line_move",
"sport": "nfl",
"min_points": 1.5
},
"scope": {
"sport": "nfl",
"window": "this_week"
},
"condition": "=kelly_edge > 0.03",
"action": {
"kind": "alert",
"once_per": "match",
"note": "Spread moved past 3."
}
}
{
"type": "https://docs.askkelly.ai/problems/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "That condition reads Kelly's own probability or edge, which can be shown but never used to filter or alert (D16). Your own probability with KELLY() works.",
"param": "condition",
"doc_url": "https://docs.askkelly.ai/problems/invalid_request",
"request_id": "req_3e350d25d1bc1d4734d4c941",
"retryable": false,
"display_message": "Something in that request was not understood."
}GET /v1/automations/{automation_id}
Get an automationLink to this section
scope read:formulas · 0 credits, not charged during the beta · status live
One of your automations. Anyone else's answers 404.
ParametersLink to this section
automation_idstring · pathrequiredThe automation's ID (auto_…).
min length 1 · max length 200
ResponseLink to this section
200 The automation.
idstringrequiredIts ID (auto_…).
objectconstrequiredAlways automation.
Always "automation".
namestringrequiredIts name.
triggerobjectrequiredkind (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and every_minutes, sport or min_points as the kind takes.
scopeobjectThe sport and kind of row its condition reads, and window (this_week: the sport's games this week) when it has one; or a saved rule whose matches it alerts on (backtester T6, F52).
Show 4 fields
rule_idstringA saved rule (rl_…): the automation alerts on its matches, with no condition or view.
pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
rule_versionintegerThe version alerted; the latest when absent.
min 1
rule_eventsarray of stringThe events it alerts on (all three when absent).
min_price_americanintegerAlert only at this American price or better.
conditionstringnullableIts condition, a formula, as typed.
macro_idstringnullableThe macro it runs, when it runs one.
viewobjectnullableThe view spec its condition runs over.
actionobjectrequiredkind (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
cooldown_secondsintegerThe quiet time after it acts, in seconds.
enabledbooleanrequiredWhether it runs.
paused_reasonstringnullableWhy Kelly paused it, when it did.
failuresintegerFailed checks in a row.
last_run_atstringnullableIts last check.
format date-time
last_fired_atstringnullableWhen it last acted.
format date-time
next_run_atstringnullableIts next scheduled check.
format date-time
created_atstringWhen it was made.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr
Authorization: Bearer $KELLY_API_KEY{
"id": "auto_nkqn9520r75fqfmcrhjr",
"object": "automation",
"name": "Big spread moves",
"trigger": {
"kind": "line_move",
"sport": "nfl",
"min_points": 1.5
},
"scope": {
"sport": "nfl",
"window": "this_week"
},
"condition": "=spread >= 3",
"macro_id": null,
"view": null,
"action": {
"kind": "alert",
"note": "Spread moved past 3.",
"once_per": "match"
},
"cooldown_seconds": 3600,
"enabled": true,
"paused_reason": null,
"failures": 0,
"last_run_at": null,
"last_fired_at": null,
"next_run_at": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}PATCH /v1/automations/{automation_id}
Change an automationLink to this section
scope write:formulas · 0 credits, not charged during the beta · MCP tool update_my_automations · status live
Changes the fields you send; enabled: false pauses it and enabled: true turns it back on, clearing a pause after failed checks. A new condition is checked again. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
automation_idstring · pathrequiredThe automation's ID (auto_…).
min length 1 · max length 200
Body, application/json (required):
namestringIts name.
min length 1 · max length 200
triggerobject{kind, every_minutes?, sport?, min_points?}.
scopeobject{sport?, entity?, window?}: the rows its condition reads; window: this_week reads the sport's games this week. Or {rule_id, rule_version?, rule_events?, min_price_american?}: alert on a saved rule's matches (backtester T6).
conditionstringA formula, starting with =.
min length 1 · max length 2000
modestringThe condition's language.
macrostringA macro's ID, code or name.
max length 200
viewobjectA view spec its condition runs over.
actionobject{kind, view_id?, watchlist?, note?, once_per?}; once_per: match acts once per match (each game told once), set (default) once per set of matches.
cooldown_secondsintegerQuiet time after it acts, in seconds.
min 0 · max 604800
enabledbooleanWhether it runs.
ResponseLink to this section
200 The automation as it now is.
idstringrequiredIts ID (auto_…).
objectconstrequiredAlways automation.
Always "automation".
namestringrequiredIts name.
triggerobjectrequiredkind (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and every_minutes, sport or min_points as the kind takes.
scopeobjectThe sport and kind of row its condition reads, and window (this_week: the sport's games this week) when it has one; or a saved rule whose matches it alerts on (backtester T6, F52).
Show 4 fields
rule_idstringA saved rule (rl_…): the automation alerts on its matches, with no condition or view.
pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
rule_versionintegerThe version alerted; the latest when absent.
min 1
rule_eventsarray of stringThe events it alerts on (all three when absent).
min_price_americanintegerAlert only at this American price or better.
conditionstringnullableIts condition, a formula, as typed.
macro_idstringnullableThe macro it runs, when it runs one.
viewobjectnullableThe view spec its condition runs over.
actionobjectrequiredkind (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
cooldown_secondsintegerThe quiet time after it acts, in seconds.
enabledbooleanrequiredWhether it runs.
paused_reasonstringnullableWhy Kelly paused it, when it did.
failuresintegerFailed checks in a row.
last_run_atstringnullableIts last check.
format date-time
last_fired_atstringnullableWhen it last acted.
format date-time
next_run_atstringnullableIts next scheduled check.
format date-time
created_atstringWhen it was made.
format date-time
updated_atstringWhen it last changed.
format date-time
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 · payload_too_large · not_found
ExampleLink to this section
PATCH https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"enabled": false
}
{
"id": "auto_nkqn9520r75fqfmcrhjr",
"object": "automation",
"name": "Big spread moves",
"trigger": {
"kind": "line_move",
"sport": "nfl",
"min_points": 1.5
},
"scope": {
"sport": "nfl",
"window": "this_week"
},
"condition": "=spread >= 3",
"macro_id": null,
"view": null,
"action": {
"kind": "alert",
"note": "Spread moved past 3.",
"once_per": "match"
},
"cooldown_seconds": 3600,
"enabled": false,
"paused_reason": null,
"failures": 0,
"last_run_at": null,
"last_fired_at": null,
"next_run_at": null,
"created_at": "2026-10-04T17:30:00+00:00",
"updated_at": "2026-10-04T17:30:00+00:00"
}DELETE /v1/automations/{automation_id}
Delete an automationLink to this section
scope write:formulas · 0 credits, not charged during the beta · status live
Deletes it; it stops at once. Needs your own live API key with write:formulas; an AI app writes through Kelly MCP, which asks you first.
ParametersLink to this section
automation_idstring · pathrequiredThe automation's ID (auto_…).
min length 1 · max length 200
ResponseLink to this section
200 Deleted.
idstringrequiredIts ID.
objectconstrequiredAlways automation.
Always "automation".
deletedconstrequiredAlways true.
Always true.
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 · not_found
ExampleLink to this section
DELETE https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr
Authorization: Bearer $KELLY_API_KEY{
"id": "auto_nkqn9520r75fqfmcrhjr",
"object": "automation",
"deleted": true
}GET /v1/automations/{automation_id}/runs
List an automation's runsLink to this section
scope read:formulas · 0 credits, not charged during the beta · MCP tool get_my_automations · status live
Its last 50 checks, newest first: acted (fired), no match, cooldown, duplicate, off or failed, with what it matched.
ParametersLink to this section
automation_idstring · pathrequiredThe automation's ID (auto_…).
min length 1 · max length 200
ResponseLink to this section
200 Its checks.
objectconstrequiredAlways list.
Always "list".
dataarray of objectrequiredIts checks, newest first.
Show 9 fields
idstringIts ID (arun_…).
objectconstAlways automation_run.
Always "automation_run".
automation_idstringThe automation.
statusstringWhat happened.
One of: fired, no_match, cooldown, duplicate, off, failed (open: new values may be added).
matchedintegerRows the condition held for.
detailobjectThe action and the matches kept, or why it was off.
errorstringnullableThe failure's class, when it failed.
started_atstringWhen it started.
format date-time
finished_atstringnullableWhen it finished.
format date-time
has_morebooleanrequiredAlways false: every one is listed.
next_cursornullrequiredAlways null.
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 · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr/runs
Authorization: Bearer $KELLY_API_KEY{
"object": "list",
"data": [],
"has_more": false,
"next_cursor": null
}POST /v1/rules:link
Make a rule linkLink to this section
public, no key needed · 0 credits, not charged during the beta · MCP tool make_rule_link · status live
A link that opens a betting rule in Kelly for whoever clicks it: the rule (formula, competition, market, side, bet moment, seasons, stake, name, notes) packed into the address after #, so no server reads it on the way. It also returns the formula's numeric thresholds as inputs (in1, in2...) a person may change, a plain HTML button to paste on a page, and import_arguments, the body of POST /v1/rules:import. Pass inputs ("in1=-7") to make a variant. A link carries no record: whoever opens it imports the rule and tests it themselves. Keyless and free. A field the rule doesn't fit is 400 invalid_request with param.
ParametersLink to this section
Body, application/json (required):
formulastringThe rule as a Kelly formula, true or false on each team-game, e.g. =AND(home, spread_close >= 3).
min length 1 · max length 4000
competitionstringThe competition it bets, e.g. nfl.
pattern ^[a-z0-9_]{2,24}$
marketstringThe bet: spread, moneyline, over, under or teaser.
One of: spread, moneyline, over, under, teaser (open: new values may be added).
sidestringrule (bet the team the rule matched) or fade (the other side).
One of: rule, fade (open: new values may be added).
bet_momentstringWhen the bet is priced: open, edition (the weekly sheet's) or close.
One of: open, edition, close (open: new values may be added).
seasonsarray of stringThe seasons it was built on, oldest first, e.g. ["2021", "2022"].
min items 1 · max items 60
season_typestringregular, postseason or all.
One of: regular, postseason, all (open: new values may be added).
stakestringrisk one unit (default) or to_win one unit.
One of: risk, to_win (open: new values may be added).
pricestringconsensus (Kelly's consensus price, default) or flat_110.
One of: consensus, flat_110 (open: new values may be added).
namestringThe rule's name, shown when the link opens.
min length 1 · max length 120
notesstringNotes shown when the link opens.
min length 1 · max length 1000
inputsarray of stringChange the formula's numbers first, by the input IDs a call returned, e.g. ["in1=-7"].
max items 24
ResponseLink to this section
200 The link.
objectconstrequiredAlways rule_link.
Always "rule_link".
urlstringrequiredThe link (askkelly.ai/rules/open#k1....). The rule rides after #, which browsers never send to a server.
format uri
tokenstringrequiredThe part after #, a k1. token.
ruleobjectrequiredThe rule the link carries, as given (empty fields left out).
Show 11 fields
formulastringrequiredThe rule as a Kelly formula, true or false on each team-game, e.g. =AND(home, spread_close >= 3).
min length 1 · max length 4000
competitionstringrequiredThe competition it bets, e.g. nfl.
pattern ^[a-z0-9_]{2,24}$
marketstringThe bet: spread, moneyline, over, under or teaser.
One of: spread, moneyline, over, under, teaser (open: new values may be added).
sidestringrule (bet the team the rule matched) or fade (the other side).
One of: rule, fade (open: new values may be added).
bet_momentstringWhen the bet is priced: open, edition (the weekly sheet's) or close.
One of: open, edition, close (open: new values may be added).
seasonsarray of stringThe seasons it was built on, oldest first, e.g. ["2021", "2022"].
min items 1 · max items 60
season_typestringregular, postseason or all.
One of: regular, postseason, all (open: new values may be added).
stakestringrisk one unit (default) or to_win one unit.
One of: risk, to_win (open: new values may be added).
pricestringconsensus (Kelly's consensus price, default) or flat_110.
One of: consensus, flat_110 (open: new values may be added).
namestringThe rule's name, shown when the link opens.
min length 1 · max length 120
notesstringNotes shown when the link opens.
min length 1 · max length 1000
inputsarray of objectrequiredThe formula's numeric thresholds a person may change, in reading order.
Show 5 fields
idstringrequiredIts ID, in1, in2... in reading order; pass it back in inputs.
labelstringrequiredWhat the number is compared with, as the formula writes it.
opstringrequiredThe comparison, read with the label on the left.
One of: <, <=, >, >=, =, <> (open: new values may be added).
valuenumberrequiredThe number now.
atarray of integerrequiredIts place in the formula: start and end character.
min items 2 · max items 2
button_htmlstringrequiredA plain HTML link to paste on a page: no script, no tracking, no logo.
import_argumentsobjectrequiredThe body of POST /v1/rules:import (MCP import_rule) that imports this rule as a draft: source_kind url, via link, tool kelly, its formula as format formula.
Show 15 fields
textstringrequiredThe formula.
formatconstrequiredAlways formula.
Always "formula".
toolconstrequiredAlways kelly.
Always "kelly".
source_kindconstrequiredAlways url.
Always "url".
viaconstrequiredAlways link.
Always "link".
raw_refstringThe link.
max length 500
dry_runbooleanrequiredfalse: the import keeps a draft to confirm.
namestringThe rule's name, shown when the link opens.
min length 1 · max length 120
competitionstringThe competition it bets, e.g. nfl.
pattern ^[a-z0-9_]{2,24}$
marketstringThe bet: spread, moneyline, over, under or teaser.
One of: spread, moneyline, over, under, teaser (open: new values may be added).
sidestringrule (bet the team the rule matched) or fade (the other side).
One of: rule, fade (open: new values may be added).
bet_momentstringWhen the bet is priced: open, edition (the weekly sheet's) or close.
One of: open, edition, close (open: new values may be added).
seasonsarray of stringThe seasons it was built on, oldest first, e.g. ["2021", "2022"].
min items 1 · max items 60
season_typestringregular, postseason or all.
One of: regular, postseason, all (open: new values may be added).
stakestringrisk one unit (default) or to_win one unit.
One of: risk, to_win (open: new values may be added).
as_ofstringrequiredWhen the value was true; for a derived value, its newest input's time.
format date-time
sourcestringrequiredWho produced the value, as shown to readers.
min length 1
attributionstringnullableAttribution the source's terms require.
request_idstringrequirednullableThe request that produced this response.
live_topicsarray of stringKelly Wire topics that update this resource (API and cards only).
rg_linestringnullableThe 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.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · payload_too_large
ExampleLink to this section
POST https://api.askkelly.ai/v1/rules:link
Content-Type: application/json{
"formula": "=AND(home, spread_close >= 3)",
"competition": "nfl",
"market": "spread",
"name": "Home underdogs of 3 or more",
"seasons": [
"2021",
"2022",
"2023",
"2024"
]
}
{
"object": "rule_link",
"url": "https://askkelly.ai/rules/open#k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBWMNYFqcoFqIBJATh6Q4wFUq1Cal5JalJKfXqyQn6ZgrJBfpJCbX5QKVFGpZBWtZGRgZAhkAykjCGUMoUyUYmsBWdMjOQ",
"token": "k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBWMNYFqcoFqIBJATh6Q4wFUq1Cal5JalJKfXqyQn6ZgrJBfpJCbX5QKVFGpZBWtZGRgZAhkAykjCGUMoUyUYmsBWdMjOQ",
"rule": {
"formula": "=AND(home, spread_close >= 3)",
"competition": "nfl",
"market": "spread",
"seasons": [
"2021",
"2022",
"2023",
"2024"
],
"name": "Home underdogs of 3 or more"
},
"inputs": [
{
"id": "in1",
"label": "spread_close",
"op": ">=",
"value": 3,
"at": [
27,
28
]
}
],
"button_html": "<a href=\"https://askkelly.ai/rules/open#k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBWMNYFqcoFqIBJATh6Q4wFUq1Cal5JalJKfXqyQn6ZgrJBfpJCbX5QKVFGpZBWtZGRgZAhkAykjCGUMoUyUYmsBWdMjOQ\" rel=\"noopener\" target=\"_blank\">Open in Kelly</a>",
"import_arguments": {
"dry_run": false,
"source_kind": "url",
"via": "link",
"raw_ref": "https://askkelly.ai/rules/open#k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBWMNYFqcoFqIBJATh6Q4wFUq1Cal5JalJKfXqyQn6ZgrJBfpJCbX5QKVFGpZBWtZGRgZAhkAykjCGUMoUyUYmsBWdMjOQ",
"text": "=AND(home, spread_close >= 3)",
"format": "formula",
"tool": "kelly",
"name": "Home underdogs of 3 or more",
"competition": "nfl",
"market": "spread",
"seasons": [
"2021",
"2022",
"2023",
"2024"
]
},
"as_of": "2026-10-04T17:30:00Z",
"source": "kelly",
"attribution": null,
"request_id": "req_5ac2a5d89fd555fdca6dd732",
"live_topics": [],
"rg_line": null
}- kelly · as of 2026-10-04T17:30:00Z
POST https://api.askkelly.ai/v1/rules:link
Content-Type: application/json{
"formula": "=home",
"competition": "nfl",
"market": "parlay"
}
{
"type": "https://docs.askkelly.ai/problems/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "market is one of spread, moneyline, over, under, teaser.",
"param": "market",
"doc_url": "https://docs.askkelly.ai/problems/invalid_request",
"request_id": "req_7f936adf4c2781279b495a7e",
"retryable": false,
"display_message": "Something in that request was not understood."
}POST https://api.askkelly.ai/v1/rules:link
Content-Type: application/json{
"formula": "=AND(home, spread_close >= 3)",
"competition": "nfl",
"market": "spread",
"inputs": [
"in1=7"
]
}
{
"object": "rule_link",
"url": "https://askkelly.ai/rules/open#k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBXMNYFqcoFqIBJKtQAQlBHI",
"token": "k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBXMNYFqcoFqIBJKtQAQlBHI",
"rule": {
"formula": "=AND(home, spread_close >= 7)",
"competition": "nfl",
"market": "spread"
},
"inputs": [
{
"id": "in1",
"label": "spread_close",
"op": ">=",
"value": 7,
"at": [
27,
28
]
}
],
"button_html": "<a href=\"https://askkelly.ai/rules/open#k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBXMNYFqcoFqIBJKtQAQlBHI\" rel=\"noopener\" target=\"_blank\">Open in Kelly</a>",
"import_arguments": {
"dry_run": false,
"source_kind": "url",
"via": "link",
"raw_ref": "https://askkelly.ai/rules/open#k1.eNqrVkpWslLKS8tR0lFKA7JsHf1cNDLyc1N1FIoLilITU-KTc_KLUxXsbBXMNYFqcoFqIBJKtQAQlBHI",
"text": "=AND(home, spread_close >= 7)",
"format": "formula",
"tool": "kelly",
"competition": "nfl",
"market": "spread"
},
"as_of": "2026-10-04T17:30:00Z",
"source": "kelly",
"attribution": null,
"request_id": "req_f95cc1c410f8bd729b956d7a",
"live_topics": [],
"rg_line": null
}- kelly · as of 2026-10-04T17:30:00Z
GET /v1/me/rule-import-ways
Get your ways to import rulesLink to this section
scope read:tracker · 0 credits, not charged during the beta · MCP tool get_my_rule_import_ways · status live
Every way to send a betting system to your Kelly account from off askkelly.ai: your own mail-in address (forward a system email from your sign-in address), the Send to Kelly bookmarklet, Android's share sheet, the Chrome extension's Import this system, Open in Kelly links and POST /v1/rules:import for Zapier or Make, each with its steps. Each way makes a draft you check before anything is saved. Needs your own key or an OAuth token with read:tracker. Read only. Test-mode keys read the same account as live ones.
ResponseLink to this section
200 Your ways to send a system to Kelly.
objectconstrequiredAlways rule_import_ways.
Always "rule_import_ways".
emailobjectrequiredForwarding a system email.
Show 3 fields
addressstringrequirednullableThe person's own mail-in address; null while mail-in is off. Mail is read only from their sign-in address.
onbooleanrequiredWhether mail-in is switched on.
stepsarray of stringrequiredWhat to do, in order.
bookmarkletobjectrequiredThe Send to Kelly bookmarklet.
Show 2 fields
hrefstringrequiredThe bookmarklet's javascript: address, to drag to the bookmarks bar.
stepsarray of stringrequiredWhat to do, in order.
extensionobjectrequiredKelly's Chrome extension.
Show 2 fields
editionstringThe build that has it: full.
stepsarray of stringrequiredWhat to do, in order.
linksobjectrequiredOpen in Kelly links and Kelly's own share links.
Show 3 fields
open_in_kellystringAn example Open in Kelly address.
fieldsarray of stringThe fields an Open in Kelly link may carry after #.
stepsarray of stringrequiredWhat to do, in order.
automationobjectrequiredZapier, Make or n8n.
Show 2 fields
apisarray of stringThe routes to call.
stepsarray of stringrequiredWhat to do, in order.
as_ofstringrequiredWhen the value was true; for a derived value, its newest input's time.
format date-time
sourcestringrequiredWho produced the value, as shown to readers.
min length 1
attributionstringnullableAttribution the source's terms require.
request_idstringrequirednullableThe request that produced this response.
live_topicsarray of stringKelly Wire topics that update this resource (API and cards only).
rg_linestringnullableThe 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.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · insufficient_scope · not_entitled
ExampleLink to this section
GET https://api.askkelly.ai/v1/me/rule-import-ways
Authorization: Bearer $KELLY_API_KEY{
"object": "rule_import_ways",
"email": {
"address": null,
"on": false,
"steps": [
"Forward a system email, a system-match alert or a tout's picks email to this address from your Kelly sign-in address (or set an auto-forward rule in your mail).",
"Kelly reads it into a draft rule and mails you a link to check each condition.",
"Nothing is saved until you confirm it."
]
},
"bookmarklet": {
"href": "javascript:(() => { const K = 'https://askkelly.ai'; const sel = String(window.getSelection() || '').trim(); const main = document.querySelector('main, article, [role=main]') || document.body; const data = {via: 'bookmarklet', url: location.href, title: document.title, selection: sel.slice(0, 60000), text: sel ? '' : String(main.innerText || '').slice(0, 60000)}; const w = window.open(K + '/rules/send?from=bookmarklet', 'kellysend', 'width=520,height=640'); if (!w) { alert('Kelly: allow pop-ups for this site, or copy the system and paste it into Kelly.'); return; } const on = (e) => { if (e.origin === K && e.source === w && e.data === 'kelly.send.ready') { w.postMessage({type: 'kelly.send', payload: data}, K); window.removeEventListener('message', on); } }; window.addEventListener('message', on); })();",
"steps": [
"Drag \"Send to Kelly\" to your bookmarks bar.",
"On a system page, select the system's filters (or select nothing to send the page's main text) and click the bookmark.",
"Check the source in the Kelly window and press Send."
]
},
"share_sheet": {
"steps": [
"Add Kelly to your home screen (Android: Chrome's menu, Install app).",
"In any app, share a system's link, text or screenshot and pick Kelly."
],
"platforms": [
"android"
],
"ios": "iPhone's share sheet doesn't list web apps: copy the link or text and paste it into Kelly, or forward it by email."
},
"extension": {
"edition": "full",
"steps": [
"Kelly's Chrome extension (the full build, installed with Load unpacked) has Import this system in its toolbar popup: it reads only the tab you are on, when you click."
]
},
"links": {
"open_in_kelly": "https://askkelly.ai/rules/open#sdql=...&competition=nfl&from=yoursite",
"fields": [
"formula",
"sdql",
"text",
"competition",
"market",
"side",
"bet_moment",
"name",
"from"
],
"steps": [
"Any site can link a system into Kelly: put sdql, formula or text (and competition, market, side, name, from) after # in the address.",
"Kelly's own share links (make_rule_link) carry a rule exactly, with its thresholds as inputs the person can change."
]
},
"automation": {
"apis": [
"POST /v1/rules:import"
],
"steps": [
"Zapier, Make or n8n: call POST /v1/rules:import with a Kelly API key; send text, tool, source_kind api and via zapier or make."
]
},
"as_of": "2026-10-04T17:30:00Z",
"source": "kelly",
"attribution": null,
"request_id": "req_6bca60c91d00574a0c09dfe0",
"live_topics": [],
"rg_line": null
}- kelly · as of 2026-10-04T17:30:00Z
Generated from Kelly API 2026-10-05.