# formulas

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.

| Method | Path | Title | Access | Price | MCP tool |
| --- | --- | --- | --- | --- | --- |
| GET | [`/v1/attributes`](#list-attributes) | List your saved attributes | `read:formulas` | 0 | `get_my_formulas` |
| POST | [`/v1/attributes`](#create-attribute) | Save a attribute | `write:formulas` | 0 | `update_my_formulas` |
| POST | [`/v1/attributes/copies`](#copy-attribute) | Keep a copy of a shared attribute | `write:formulas` | 0 | none |
| GET | [`/v1/attributes/{ref}`](#get-attribute) | Get a saved attribute | `read:formulas` | 0 | none |
| PATCH | [`/v1/attributes/{ref}`](#update-attribute) | Change a saved attribute | `write:formulas` | 0 | `update_my_formulas` |
| DELETE | [`/v1/attributes/{ref}`](#delete-attribute) | Delete a saved attribute | `write:formulas` | 0 | `update_my_formulas` |
| GET | [`/v1/attributes/{ref}/versions`](#list-attribute-versions) | List a saved attribute's versions | `read:formulas` | 0 | none |
| GET | [`/v1/attributes/{ref}/trace`](#trace-attribute) | Trace a saved attribute | `read:formulas` | 0 | none |
| POST | [`/v1/attributes/{ref}/share`](#share-attribute) | Share a saved attribute | `write:formulas` | 0 | `update_my_formulas` |
| GET | [`/v1/templates`](#list-templates) | List your saved templates | `read:formulas` | 0 | `get_my_formulas` |
| POST | [`/v1/templates`](#create-template) | Save a template | `write:formulas` | 0 | none |
| POST | [`/v1/templates/copies`](#copy-template) | Keep a copy of a shared template | `write:formulas` | 0 | none |
| GET | [`/v1/templates/{ref}`](#get-template) | Get a saved template | `read:formulas` | 0 | none |
| PATCH | [`/v1/templates/{ref}`](#update-template) | Change a saved template | `write:formulas` | 0 | none |
| DELETE | [`/v1/templates/{ref}`](#delete-template) | Delete a saved template | `write:formulas` | 0 | none |
| GET | [`/v1/templates/{ref}/versions`](#list-template-versions) | List a saved template's versions | `read:formulas` | 0 | none |
| GET | [`/v1/templates/{ref}/trace`](#trace-template) | Trace a saved template | `read:formulas` | 0 | none |
| POST | [`/v1/templates/{ref}/share`](#share-template) | Share a saved template | `write:formulas` | 0 | none |
| POST | [`/v1/attributes:validate`](#validate-attribute) | Check a formula | `read:formulas` | 0 | `check_formula` |
| POST | [`/v1/attributes:preview`](#preview-attribute) | Preview a formula on real rows | `read:formulas` | 0 | `preview_formula` |
| GET | [`/v1/shared-formulas/{code}`](#get-shared-formula) | Read a shared formula | public | 0 | none |
| GET | [`/v1/macros`](#list-macros) | List your macros | `read:formulas` | 0 | `get_my_automations` |
| POST | [`/v1/macros`](#create-macro) | Save a macro | `write:formulas` | 0 | `update_my_automations` |
| GET | [`/v1/macros/{ref}`](#get-macro) | Get a macro | `read:formulas` | 0 | none |
| PATCH | [`/v1/macros/{ref}`](#update-macro) | Change a macro | `write:formulas` | 0 | none |
| DELETE | [`/v1/macros/{ref}`](#delete-macro) | Delete a macro | `write:formulas` | 0 | none |
| POST | [`/v1/macros/{ref}:run`](#run-macro) | Run a macro | `read:formulas` | 0 | `update_my_automations` |
| GET | [`/v1/automations`](#list-automations) | List your automations | `read:formulas` | 0 | `get_my_automations` |
| POST | [`/v1/automations`](#create-automation) | Make an automation | `write:formulas` | 0 | `update_my_automations` |
| GET | [`/v1/automations/{automation_id}`](#get-automation) | Get an automation | `read:formulas` | 0 | none |
| PATCH | [`/v1/automations/{automation_id}`](#update-automation) | Change an automation | `write:formulas` | 0 | `update_my_automations` |
| DELETE | [`/v1/automations/{automation_id}`](#delete-automation) | Delete an automation | `write:formulas` | 0 | none |
| GET | [`/v1/automations/{automation_id}/runs`](#list-automation-runs) | List an automation's runs | `read:formulas` | 0 | `get_my_automations` |
| POST | [`/v1/rules:link`](#make-rule-link) | Make a rule link | public | 0 | `make_rule_link` |
| GET | [`/v1/me/rule-import-ways`](#get-my-rule-import-ways) | Get your ways to import rules | `read:tracker` | 0 | `get_my_rule_import_ways` |

`GET /v1/attributes`

## List your saved attributes
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`).

### Parameters
- `limit` integer · query  
  Saves per page, 1 to 200.  
  min 1 · max 200 · default 50
- `cursor` string · query  
  The next_cursor of the page before.  
  max length 200
- `sport` string · query  
  Only saves for this sport (and those for every sport).  
  pattern ^[a-z0-9_]{2,16}$
- `q` string · query  
  Words in its name or label.  
  min length 1 · max length 70

### Response
`200` A page of your saved attributes.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  The saves, most recently changed first.
  - `id` string · required  
    Its ID: attr_… for an attribute, tmpl_… for a template.
  - `object` string · required  
    `attribute` or `template`.  
    One of: `attribute`, `template` (open: new values may be added).
  - `name` string · required  
    Its name, lower case.
  - `reference` string · required  
    How a formula writes it: `my.target_trend` or `MY.FORM`.
  - `label` string  
    Its column heading.
  - `description` string · nullable  
    What it means, in the person's words.
  - `sports` array of string  
    The sports it applies to; empty for every sport.
  - `entity` string · nullable  
    The kind of row it is for (player, team, game, market).
  - `formula` string · required  
    The formula as typed, in its mode.
  - `mode` string · required  
    The 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).
  - `params` array of string  
    A template's LAMBDA parameters, in order; empty for an attribute.
  - `value_type` string  
    Its type: number, percent, price, probability, money:USD…
  - `shape` string  
    One value per row, one per group, or a table.  
    One of: `column`, `summary`, `table` (open: new values may be added).
  - `format` object  
    How it is shown: decimals, percent, odds format.
  - `rollup` string  
    What a totals row does: recompute from parts (ratios), sum, avg…  
    One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
  - `version` integer · required  
    Its current version, from 1.
  - `catalogue_version` string  
    The stat catalogue it was checked against.
  - `language_version` string  
    The formula language it was checked against.
  - `reads` object · nullable  
    What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
    - `attributes` array of string  
      Kelly's attributes, by key.
    - `saves` array of string  
      Your other saves, by ID.
    - `functions` array of string  
      The functions it calls.
  - `shared` boolean  
    Whether its share link is on.
  - `share_code` string · nullable  
    The share link's code while it is on.
  - `created_at` string  
    When it was saved.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `has_more` boolean · required  
  Whether another page follows.
- `next_cursor` string · required · nullable  
  Pass as `cursor` for the next page.

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

### Example
```http
GET https://api.askkelly.ai/v1/attributes
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 attribute
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.

### Parameters
Body, `application/json` (required):

- `name` string  
  Its name: letters, digits and _, starting with a letter. `my.` is optional.  
  min length 1 · max length 70
- `formula` string  
  The formula, starting with =. A template starts with =LAMBDA(.  
  min length 1 · max length 2000
- `mode` string  
  The language it is written in.  
  One of: `excel`, `sheets`, `sql`, `polars`, `pandas`, `dplyr`, `dax`, `tableau`, `pine` (open: new values may be added).  
  default "excel"
- `label` string  
  Its column heading.  
  min length 1 · max length 80
- `description` string  
  What it means.  
  min length 1 · max length 1000
- `sports` array of string  
  The sports it applies to; none for every sport.  
  max items 12
- `entity` string  
  The kind of row it is for.  
  pattern ^[a-z][a-z_]{0,31}$
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does.  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).

### Response
`201` The attribute as saved.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
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."
}
```

```json
{
  "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"
}
```

```http
POST https://api.askkelly.ai/v1/attributes
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "name": "bad",
  "formula": "=nope * 2"
}
```

```json
{
  "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."
}
```

```http
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"
  ]
}
```

```json
{
  "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 attribute
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.

### Parameters
Body, `application/json` (required):

- `share_code` string  
  The share link's code.  
  pattern ^[0-9A-Za-z]{10,16}$
- `name` string  
  The name to keep it under; its own name by default.  
  min length 1 · max length 70

### Response
`201` Your copy.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
POST https://api.askkelly.ai/v1/attributes/copies
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "share_code": "pSDuF7gBjRQW",
  "name": "trend_copy"
}
```

```json
{
  "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 attribute
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.

### Parameters
- `ref` string · path · required  
  The attribute's ID (attr_…) or how a formula writes it (`my.target_trend`).  
  min length 1 · max length 70

### Response
`200` The attribute.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
GET https://api.askkelly.ai/v1/attributes/my.target_trend
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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"
}
```

```http
GET https://api.askkelly.ai/v1/attributes/my.nothing_here
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 attribute
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.

### Parameters
- `ref` string · path · required  
  The attribute's ID (attr_…) or how a formula writes it (`my.target_trend`).  
  min length 1 · max length 70

Body, `application/json` (required):

- `name` string  
  Its name: letters, digits and _, starting with a letter. `my.` is optional.  
  min length 1 · max length 70
- `formula` string  
  The formula, starting with =. A template starts with =LAMBDA(.  
  min length 1 · max length 2000
- `mode` string  
  The language it is written in.  
  One of: `excel`, `sheets`, `sql`, `polars`, `pandas`, `dplyr`, `dax`, `tableau`, `pine` (open: new values may be added).
- `label` string  
  Its column heading.  
  min length 1 · max length 80
- `description` string  
  What it means.  
  min length 1 · max length 1000
- `sports` array of string  
  The sports it applies to; none for every sport.  
  max items 12
- `entity` string  
  The kind of row it is for.  
  pattern ^[a-z][a-z_]{0,31}$
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does.  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).

### Response
`200` The attribute as it now is.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
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)"
}
```

```json
{
  "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 attribute
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.

### Parameters
- `ref` string · path · required  
  The attribute's ID (attr_…) or how a formula writes it (`my.target_trend`).  
  min length 1 · max length 70

- `force` boolean · query  
  Delete it even while your other saves use it.  
  default false

### Response
`200` Deleted.

- `id` string · required  
  The deleted save's ID.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `deleted` const · required  
  Always true.  
  Always `true`.

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

### Example
```http
DELETE https://api.askkelly.ai/v1/attributes/my.trend_copy
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "id": "attr_5mhmvdcng5n0k1799ndh",
  "object": "attribute",
  "deleted": true
}
```

`GET /v1/attributes/{ref}/versions`

## List a saved attribute's versions
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.

### Parameters
- `ref` string · path · required  
  The attribute's ID (attr_…) or how a formula writes it (`my.target_trend`).  
  min length 1 · max length 70

### Response
`200` Every version, newest first.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  The versions, newest first.
  - `version` integer  
    The version, from 1.
  - `formula` string  
    The formula as typed.
  - `mode` string  
    Its language.
  - `value_type` string  
    Its type.
  - `shape` string  
    Its shape.
  - `rollup` string  
    Its roll-up rule.
  - `catalogue_version` string  
    The catalogue it was checked against.
  - `language_version` string  
    The language it was checked against.
  - `created_at` string  
    When this version was saved.  
    format date-time
  - `params` array of string  
    A template's parameters.
- `has_more` boolean · required  
  Always false: every version is listed.
- `next_cursor` null · required  
  Always null.

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

### Example
```http
GET https://api.askkelly.ai/v1/attributes/my.target_trend/versions
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 attribute
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.

### Parameters
- `ref` string · path · required  
  The attribute's ID (attr_…) or how a formula writes it (`my.target_trend`).  
  min length 1 · max length 70

### Response
`200` What it reads and what uses it.

- `object` string · required  
  `attribute_trace` or `template_trace`.  
  One of: `attribute_trace`, `template_trace` (open: new values may be added).
- `id` string · required  
  The save traced.
- `reference` string · required  
  How a formula writes it.
- `attributes` array of string · required  
  Kelly's attributes it reads directly.
- `functions` array of string · required  
  The functions it calls directly.
- `precedents` array of object · required  
  Your saves it reads, directly or through others, nearest first.
  - `id` string  
    Its ID.
  - `reference` string · nullable  
    How a formula writes it.
- `dependents` array of object · required  
  Your saves that use it, directly or through others, nearest first.
  - `id` string  
    Its ID.
  - `reference` string · nullable  
    How a formula writes it.

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

### Example
```http
GET https://api.askkelly.ai/v1/attributes/my.rush_form/trace
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 attribute
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.

### Parameters
- `ref` string · path · required  
  The attribute's ID (attr_…) or how a formula writes it (`my.target_trend`).  
  min length 1 · max length 70

Body, `application/json` (required):

- `on` boolean  
  true turns it on, false off.

### Response
`200` The attribute as it now is.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
POST https://api.askkelly.ai/v1/attributes/my.target_trend/share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "on": true
}
```

```json
{
  "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 templates
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`).

### Parameters
- `limit` integer · query  
  Saves per page, 1 to 200.  
  min 1 · max 200 · default 50
- `cursor` string · query  
  The next_cursor of the page before.  
  max length 200
- `sport` string · query  
  Only saves for this sport (and those for every sport).  
  pattern ^[a-z0-9_]{2,16}$
- `q` string · query  
  Words in its name or label.  
  min length 1 · max length 70

### Response
`200` A page of your saved templates.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  The saves, most recently changed first.
  - `id` string · required  
    Its ID: attr_… for an attribute, tmpl_… for a template.
  - `object` string · required  
    `attribute` or `template`.  
    One of: `attribute`, `template` (open: new values may be added).
  - `name` string · required  
    Its name, lower case.
  - `reference` string · required  
    How a formula writes it: `my.target_trend` or `MY.FORM`.
  - `label` string  
    Its column heading.
  - `description` string · nullable  
    What it means, in the person's words.
  - `sports` array of string  
    The sports it applies to; empty for every sport.
  - `entity` string · nullable  
    The kind of row it is for (player, team, game, market).
  - `formula` string · required  
    The formula as typed, in its mode.
  - `mode` string · required  
    The 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).
  - `params` array of string  
    A template's LAMBDA parameters, in order; empty for an attribute.
  - `value_type` string  
    Its type: number, percent, price, probability, money:USD…
  - `shape` string  
    One value per row, one per group, or a table.  
    One of: `column`, `summary`, `table` (open: new values may be added).
  - `format` object  
    How it is shown: decimals, percent, odds format.
  - `rollup` string  
    What a totals row does: recompute from parts (ratios), sum, avg…  
    One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
  - `version` integer · required  
    Its current version, from 1.
  - `catalogue_version` string  
    The stat catalogue it was checked against.
  - `language_version` string  
    The formula language it was checked against.
  - `reads` object · nullable  
    What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
    - `attributes` array of string  
      Kelly's attributes, by key.
    - `saves` array of string  
      Your other saves, by ID.
    - `functions` array of string  
      The functions it calls.
  - `shared` boolean  
    Whether its share link is on.
  - `share_code` string · nullable  
    The share link's code while it is on.
  - `created_at` string  
    When it was saved.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `has_more` boolean · required  
  Whether another page follows.
- `next_cursor` string · required · nullable  
  Pass as `cursor` for the next page.

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

### Example
```http
GET https://api.askkelly.ai/v1/templates
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 template
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.

### Parameters
Body, `application/json` (required):

- `name` string  
  Its name: letters, digits and _, starting with a letter. `my.` is optional.  
  min length 1 · max length 70
- `formula` string  
  The formula, starting with =. A template starts with =LAMBDA(.  
  min length 1 · max length 2000
- `mode` string  
  The language it is written in.  
  One of: `excel`, `sheets`, `sql`, `polars`, `pandas`, `dplyr`, `dax`, `tableau`, `pine` (open: new values may be added).  
  default "excel"
- `label` string  
  Its column heading.  
  min length 1 · max length 80
- `description` string  
  What it means.  
  min length 1 · max length 1000
- `sports` array of string  
  The sports it applies to; none for every sport.  
  max items 12
- `entity` string  
  The kind of row it is for.  
  pattern ^[a-z][a-z_]{0,31}$
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does.  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).

### Response
`201` The template as saved.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
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."
}
```

```json
{
  "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 template
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.

### Parameters
Body, `application/json` (required):

- `share_code` string  
  The share link's code.  
  pattern ^[0-9A-Za-z]{10,16}$
- `name` string  
  The name to keep it under; its own name by default.  
  min length 1 · max length 70

### Response
`201` Your copy.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
POST https://api.askkelly.ai/v1/templates/copies
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "share_code": "WqsP9KnVosVe",
  "name": "form_copy"
}
```

```json
{
  "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 template
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.

### Parameters
- `ref` string · path · required  
  The template's ID (tmpl_…) or how a formula writes it (`MY.FORM`).  
  min length 1 · max length 70

### Response
`200` The template.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
GET https://api.askkelly.ai/v1/templates/MY.FORM
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 template
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.

### Parameters
- `ref` string · path · required  
  The template's ID (tmpl_…) or how a formula writes it (`MY.FORM`).  
  min length 1 · max length 70

Body, `application/json` (required):

- `name` string  
  Its name: letters, digits and _, starting with a letter. `my.` is optional.  
  min length 1 · max length 70
- `formula` string  
  The formula, starting with =. A template starts with =LAMBDA(.  
  min length 1 · max length 2000
- `mode` string  
  The language it is written in.  
  One of: `excel`, `sheets`, `sql`, `polars`, `pandas`, `dplyr`, `dax`, `tableau`, `pine` (open: new values may be added).
- `label` string  
  Its column heading.  
  min length 1 · max length 80
- `description` string  
  What it means.  
  min length 1 · max length 1000
- `sports` array of string  
  The sports it applies to; none for every sport.  
  max items 12
- `entity` string  
  The kind of row it is for.  
  pattern ^[a-z][a-z_]{0,31}$
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does.  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).

### Response
`200` The template as it now is.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
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."
}
```

```json
{
  "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 template
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.

### Parameters
- `ref` string · path · required  
  The template's ID (tmpl_…) or how a formula writes it (`MY.FORM`).  
  min length 1 · max length 70

- `force` boolean · query  
  Delete it even while your other saves use it.  
  default false

### Response
`200` Deleted.

- `id` string · required  
  The deleted save's ID.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `deleted` const · required  
  Always true.  
  Always `true`.

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

### Example
```http
DELETE https://api.askkelly.ai/v1/templates/MY.FORM?force=true
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "id": "tmpl_prhdz0jmqgawb2v92nw7",
  "object": "template",
  "deleted": true
}
```

```http
DELETE https://api.askkelly.ai/v1/templates/MY.FORM
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 versions
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.

### Parameters
- `ref` string · path · required  
  The template's ID (tmpl_…) or how a formula writes it (`MY.FORM`).  
  min length 1 · max length 70

### Response
`200` Every version, newest first.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  The versions, newest first.
  - `version` integer  
    The version, from 1.
  - `formula` string  
    The formula as typed.
  - `mode` string  
    Its language.
  - `value_type` string  
    Its type.
  - `shape` string  
    Its shape.
  - `rollup` string  
    Its roll-up rule.
  - `catalogue_version` string  
    The catalogue it was checked against.
  - `language_version` string  
    The language it was checked against.
  - `created_at` string  
    When this version was saved.  
    format date-time
  - `params` array of string  
    A template's parameters.
- `has_more` boolean · required  
  Always false: every version is listed.
- `next_cursor` null · required  
  Always null.

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

### Example
```http
GET https://api.askkelly.ai/v1/templates/MY.FORM/versions
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 template
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.

### Parameters
- `ref` string · path · required  
  The template's ID (tmpl_…) or how a formula writes it (`MY.FORM`).  
  min length 1 · max length 70

### Response
`200` What it reads and what uses it.

- `object` string · required  
  `attribute_trace` or `template_trace`.  
  One of: `attribute_trace`, `template_trace` (open: new values may be added).
- `id` string · required  
  The save traced.
- `reference` string · required  
  How a formula writes it.
- `attributes` array of string · required  
  Kelly's attributes it reads directly.
- `functions` array of string · required  
  The functions it calls directly.
- `precedents` array of object · required  
  Your saves it reads, directly or through others, nearest first.
  - `id` string  
    Its ID.
  - `reference` string · nullable  
    How a formula writes it.
- `dependents` array of object · required  
  Your saves that use it, directly or through others, nearest first.
  - `id` string  
    Its ID.
  - `reference` string · nullable  
    How a formula writes it.

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

### Example
```http
GET https://api.askkelly.ai/v1/templates/MY.FORM/trace
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 template
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.

### Parameters
- `ref` string · path · required  
  The template's ID (tmpl_…) or how a formula writes it (`MY.FORM`).  
  min length 1 · max length 70

Body, `application/json` (required):

- `on` boolean  
  true turns it on, false off.

### Response
`200` The template as it now is.

- `id` string · required  
  Its ID: attr_… for an attribute, tmpl_… for a template.
- `object` string · required  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.
- `catalogue_version` string  
  The stat catalogue it was checked against.
- `language_version` string  
  The formula language it was checked against.
- `reads` object · nullable  
  What it reads: `attributes`, `saves` (IDs) and `functions`; on a single read.
  - `attributes` array of string  
    Kelly's attributes, by key.
  - `saves` array of string  
    Your other saves, by ID.
  - `functions` array of string  
    The functions it calls.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
POST https://api.askkelly.ai/v1/templates/MY.FORM/share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "on": true
}
```

```json
{
  "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 formula
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.

### Parameters
Body, `application/json` (required):

- `formula` string  
  The formula, starting with =.  
  min length 1 · max length 2000
- `mode` string  
  The language it is written in.  
  One of: `excel`, `sheets`, `sql`, `polars`, `pandas`, `dplyr`, `dax`, `tableau`, `pine` (open: new values may be added).  
  default "excel"
- `sport` string  
  The sport whose attributes it reads.  
  pattern ^[a-z0-9_]{2,16}$
- `entity` string  
  The kind of row it is for.  
  pattern ^[a-z][a-z_]{0,31}$

### Response
`200` The language's check: errors, when it has any, are in the body.

- `tree` object · required · nullable  
  The bound parse tree, every node with its [start, end) spot; null when the formula has errors.
- `value_type` object · nullable  
  Its type: `{base, unit?, currency?}`.
- `shape` string · nullable  
  column, summary or table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `params` array of string  
  A LAMBDA's parameters, in order.
- `refs` object  
  What it reads: Kelly's attributes, your saves, the functions it calls.
- `catalogue_version` string  
  The attribute catalogue it was checked against.
- `language_version` string · required  
  The formula language's version.
- `errors` array of object · required  
  Each mistake: `code`, a plain-words `message`, its `at` spot and a `suggestion` when there is one.
- `tags` object  
  Source 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).
- `hash` string  
  SHA-256 of the tree without positions.
- `show_as` object  
  The 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.

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

### Example
```http
POST https://api.askkelly.ai/v1/attributes:validate
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "formula": "=nope + my.target_trend",
  "sport": "nfl"
}
```

```json
{
  "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 rows
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.

### Parameters
Body, `application/json` (required):

- `formula` string  
  The formula, starting with =.  
  min length 1 · max length 2000
- `mode` string  
  The language it is written in.  
  One of: `excel`, `sheets`, `sql`, `polars`, `pandas`, `dplyr`, `dax`, `tableau`, `pine` (open: new values may be added).  
  default "excel"
- `competition` string  
  The competition slug (nfl, nba, ncaaf).  
  pattern ^[a-z0-9_]{2,16}$
- `entity` string  
  player (default) or team.  
  One of: `player`, `team` (open: new values may be added).  
  default "player"
- `grain` string  
  One row per game, season (default) or career.  
  One of: `game`, `season`, `career` (open: new values may be added).  
  default "season"
- `entity_ids` array of string  
  Up to 20 players or teams (plr_, tm_); none runs it on a page of every one.  
  max items 20
- `from_season` string  
  First season.  
  pattern ^[0-9]{4}$
- `to_season` string  
  Last season.  
  pattern ^[0-9]{4}$
- `season_type` string  
  regular (default), postseason or both.  
  One of: `regular`, `postseason`, `both` (open: new values may be added).
- `limit` integer  
  Rows, 1 to 50; default 20.  
  min 1 · max 50 · default 20
- `inputs` object  
  A template's inputs by parameter name: a number, text or true/false each.

### Response
`200` The check, and the formula run on the rows.

- `object` string · required  
  formula_preview.  
  One of: `formula_preview` (open: new values may be added).
- `check` object · required  
  A formula checked by the language (ADR-K591, registry/contracts/formulas/formula-check.schema.json): the same body as Kelly MCP's check_formula.
  - `tree` object · required · nullable  
    The bound parse tree, every node with its [start, end) spot; null when the formula has errors.
  - `value_type` object · nullable  
    Its type: `{base, unit?, currency?}`.
  - `shape` string · nullable  
    column, summary or table.  
    One of: `column`, `summary`, `table` (open: new values may be added).
  - `params` array of string  
    A LAMBDA's parameters, in order.
  - `refs` object  
    What it reads: Kelly's attributes, your saves, the functions it calls.
  - `catalogue_version` string  
    The attribute catalogue it was checked against.
  - `language_version` string · required  
    The formula language's version.
  - `errors` array of object · required  
    Each mistake: `code`, a plain-words `message`, its `at` spot and a `suggestion` when there is one.
  - `tags` object  
    Source 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).
  - `hash` string  
    SHA-256 of the tree without positions.
  - `show_as` object  
    The 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.
- `columns` array of object · required  
  The attributes it reads, as the view's columns: key, attribute ID, label, unit and locked.
- `rows` array of object · required  
  Each 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).
- `summary` number | string | boolean · nullable  
  A summary formula's one value.
- `unsupported` array of string · required  
  What it reads that the preview can't yet: a relation (opponent.x) or a saved formula. Nothing runs while any is listed.
- `locked` array of string  
  Columns the Rights Register withholds here: no values.
- `total_rows` integer · required  
  Rows the view has across every page.
- `sources` array of object  
  The view's sources: licence and attribution.
- `as_of` string · nullable  
  When the data was read (ISO 8601).  
  format date-time
- `snapshot_id` string · nullable  
  The lake snapshot read.
- `summary_text` string  
  One sentence: what ran, on how many rows.

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

### Example
```http
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
}
```

```json
{
  "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 formula
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.

### Parameters
- `code` string · path · required  
  The share link's code.  
  pattern ^[0-9A-Za-z]{10,16}$

### Response
`200` The shared formula.

- `object` const · required  
  Always `shared_formula`.  
  Always `"shared_formula"`.
- `kind` string  
  `attribute` or `template`.  
  One of: `attribute`, `template` (open: new values may be added).
- `name` string · required  
  Its name, lower case.
- `reference` string · required  
  How a formula writes it: `my.target_trend` or `MY.FORM`.
- `label` string  
  Its column heading.
- `description` string · nullable  
  What it means, in the person's words.
- `sports` array of string  
  The sports it applies to; empty for every sport.
- `entity` string · nullable  
  The kind of row it is for (player, team, game, market).
- `formula` string · required  
  The formula as typed, in its mode.
- `mode` string · required  
  The 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).
- `params` array of string  
  A template's LAMBDA parameters, in order; empty for an attribute.
- `value_type` string  
  Its type: number, percent, price, probability, money:USD…
- `shape` string  
  One value per row, one per group, or a table.  
  One of: `column`, `summary`, `table` (open: new values may be added).
- `format` object  
  How it is shown: decimals, percent, odds format.
- `rollup` string  
  What a totals row does: recompute from parts (ratios), sum, avg…  
  One of: `recompute`, `sum`, `avg`, `min`, `max`, `none` (open: new values may be added).
- `version` integer · required  
  Its current version, from 1.

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

### Example
```http
GET https://api.askkelly.ai/v1/shared-formulas/pSDuF7gBjRQW
```

```json
{
  "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
}
```

```http
GET https://api.askkelly.ai/v1/shared-formulas/abcdefghjk
```

```json
{
  "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 macros
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.

### Response
`200` Your macros.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  Your macros.
  - `id` string · required  
    Its ID (mac_…).
  - `object` const · required  
    Always `macro`.  
    Always `"macro"`.
  - `name` string · required  
    Its name.
  - `code` string · nullable  
    Its palette code, such as SUN.
  - `hotkey` string · nullable  
    Its hotkey or key sequence.
  - `steps` array of object · required  
    Its steps, in order.
    - `command` string  
      A command ID such as grid.sort or page.tab.stats.
    - `col` string · nullable  
      The column it acts on, when it acts on one.
    - `arg` any  
      Its argument; `{{name}}` names an input.
    - `count` integer · nullable  
      How many times, for a repeatable step.
  - `inputs` array of object · required  
    Its named inputs.
    - `name` string  
      Its name.
    - `label` string · nullable  
      Its label.
    - `type` string  
      Its type.  
      One of: `text`, `number`, `integer`, `column`, `player`, `team`, `game`, `season`, `week`, `sport`, `formula` (open: new values may be added).
    - `default` any  
      Its value when none is given; absent when it has none.
    - `required` boolean  
      Whether a run must give it.
  - `grid` string · nullable  
    The grid it was recorded on, when it was.
  - `runs` integer  
    How often it has run.
  - `shared` boolean  
    Whether its share link is on.
  - `share_code` string · nullable  
    The share link's code while it is on.
  - `created_at` string  
    When it was saved.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `has_more` boolean · required  
  Always false: every one is listed.
- `next_cursor` null · required  
  Always null.

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

### Example
```http
GET https://api.askkelly.ai/v1/macros
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 macro
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.

### Parameters
Body, `application/json` (required):

- `name` string  
  Its name.  
  min length 1 · max length 200
- `code` string  
  A palette code: a capital letter then up to 7 capitals or digits.  
  pattern ^[A-Z][A-Z0-9]{1,7}$
- `hotkey` string  
  A hotkey or key sequence.  
  min length 1 · max length 40
- `steps` array of object  
  Its steps: `{command, col?, arg?, count?}`.  
  min items 1 · max items 50
- `inputs` array of object  
  Its inputs: `{name, label?, type?, default?, required?}`.  
  max items 10
- `grid` string  
  The grid it is for.  
  pattern ^[a-z][a-z0-9_.]{0,63}$

### Response
`201` The macro as saved.

- `id` string · required  
  Its ID (mac_…).
- `object` const · required  
  Always `macro`.  
  Always `"macro"`.
- `name` string · required  
  Its name.
- `code` string · nullable  
  Its palette code, such as SUN.
- `hotkey` string · nullable  
  Its hotkey or key sequence.
- `steps` array of object · required  
  Its steps, in order.
  - `command` string  
    A command ID such as grid.sort or page.tab.stats.
  - `col` string · nullable  
    The column it acts on, when it acts on one.
  - `arg` any  
    Its argument; `{{name}}` names an input.
  - `count` integer · nullable  
    How many times, for a repeatable step.
- `inputs` array of object · required  
  Its named inputs.
  - `name` string  
    Its name.
  - `label` string · nullable  
    Its label.
  - `type` string  
    Its type.  
    One of: `text`, `number`, `integer`, `column`, `player`, `team`, `game`, `season`, `week`, `sport`, `formula` (open: new values may be added).
  - `default` any  
    Its value when none is given; absent when it has none.
  - `required` boolean  
    Whether a run must give it.
- `grid` string · nullable  
  The grid it was recorded on, when it was.
- `runs` integer  
  How often it has run.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
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"
    }
  ]
}
```

```json
{
  "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 macro
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.

### Parameters
- `ref` string · path · required  
  The macro's ID (mac_…), palette code or name.  
  min length 1 · max length 200

### Response
`200` The macro.

- `id` string · required  
  Its ID (mac_…).
- `object` const · required  
  Always `macro`.  
  Always `"macro"`.
- `name` string · required  
  Its name.
- `code` string · nullable  
  Its palette code, such as SUN.
- `hotkey` string · nullable  
  Its hotkey or key sequence.
- `steps` array of object · required  
  Its steps, in order.
  - `command` string  
    A command ID such as grid.sort or page.tab.stats.
  - `col` string · nullable  
    The column it acts on, when it acts on one.
  - `arg` any  
    Its argument; `{{name}}` names an input.
  - `count` integer · nullable  
    How many times, for a repeatable step.
- `inputs` array of object · required  
  Its named inputs.
  - `name` string  
    Its name.
  - `label` string · nullable  
    Its label.
  - `type` string  
    Its type.  
    One of: `text`, `number`, `integer`, `column`, `player`, `team`, `game`, `season`, `week`, `sport`, `formula` (open: new values may be added).
  - `default` any  
    Its value when none is given; absent when it has none.
  - `required` boolean  
    Whether a run must give it.
- `grid` string · nullable  
  The grid it was recorded on, when it was.
- `runs` integer  
  How often it has run.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
GET https://api.askkelly.ai/v1/macros/SUN
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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"
}
```

```http
GET https://api.askkelly.ai/v1/macros/NOPE
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 macro
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.

### Parameters
- `ref` string · path · required  
  The macro's ID (mac_…), palette code or name.  
  min length 1 · max length 200

Body, `application/json` (required):

- `name` string  
  Its name.  
  min length 1 · max length 200
- `code` string  
  A palette code: a capital letter then up to 7 capitals or digits.  
  pattern ^[A-Z][A-Z0-9]{1,7}$
- `hotkey` string  
  A hotkey or key sequence.  
  min length 1 · max length 40
- `steps` array of object  
  Its steps: `{command, col?, arg?, count?}`.  
  min items 1 · max items 50
- `inputs` array of object  
  Its inputs: `{name, label?, type?, default?, required?}`.  
  max items 10
- `grid` string  
  The grid it is for.  
  pattern ^[a-z][a-z0-9_.]{0,63}$

### Response
`200` The macro as it now is.

- `id` string · required  
  Its ID (mac_…).
- `object` const · required  
  Always `macro`.  
  Always `"macro"`.
- `name` string · required  
  Its name.
- `code` string · nullable  
  Its palette code, such as SUN.
- `hotkey` string · nullable  
  Its hotkey or key sequence.
- `steps` array of object · required  
  Its steps, in order.
  - `command` string  
    A command ID such as grid.sort or page.tab.stats.
  - `col` string · nullable  
    The column it acts on, when it acts on one.
  - `arg` any  
    Its argument; `{{name}}` names an input.
  - `count` integer · nullable  
    How many times, for a repeatable step.
- `inputs` array of object · required  
  Its named inputs.
  - `name` string  
    Its name.
  - `label` string · nullable  
    Its label.
  - `type` string  
    Its type.  
    One of: `text`, `number`, `integer`, `column`, `player`, `team`, `game`, `season`, `week`, `sport`, `formula` (open: new values may be added).
  - `default` any  
    Its value when none is given; absent when it has none.
  - `required` boolean  
    Whether a run must give it.
- `grid` string · nullable  
  The grid it was recorded on, when it was.
- `runs` integer  
  How often it has run.
- `shared` boolean  
  Whether its share link is on.
- `share_code` string · nullable  
  The share link's code while it is on.
- `created_at` string  
  When it was saved.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
PATCH https://api.askkelly.ai/v1/macros/SUN
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "hotkey": "g s"
}
```

```json
{
  "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 macro
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.

### Parameters
- `ref` string · path · required  
  The macro's ID (mac_…), palette code or name.  
  min length 1 · max length 200

### Response
`200` Deleted.

- `id` string · required  
  Its ID.
- `object` const · required  
  Always `macro`.  
  Always `"macro"`.
- `deleted` const · required  
  Always true.  
  Always `true`.

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

### Example
```http
DELETE https://api.askkelly.ai/v1/macros/SUN
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "id": "mac_7d161b44rs7heyddj4zr",
  "object": "macro",
  "deleted": true
}
```

`POST /v1/macros/{ref}:run`

## Run a macro
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.

### Parameters
- `ref` string · path · required  
  The macro's ID (mac_…), palette code or name.  
  min length 1 · max length 200

Body, `application/json` (required):

- `inputs` object  
  Each input's value, by name.

### Response
`200` The steps, filled in.

- `object` const · required  
  Always `macro_run`.  
  Always `"macro_run"`.
- `id` string · required  
  The macro's ID.
- `name` string  
  Its name.
- `grid` string · nullable  
  The grid it was recorded on.
- `steps` array of object · required  
  The steps to apply, in order.
  - `command` string  
    A command ID such as grid.sort or page.tab.stats.
  - `col` string · nullable  
    The column it acts on, when it acts on one.
  - `arg` any  
    Its argument; `{{name}}` names an input.
  - `count` integer · nullable  
    How many times, for a repeatable step.
- `ran_at` string  
  When it ran.  
  format date-time

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

### Example
```http
POST https://api.askkelly.ai/v1/macros/SUN:run
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "inputs": {
    "week": 10
  }
}
```

```json
{
  "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 automations
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.

### Response
`200` Your automations.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  Your automations.
  - `id` string · required  
    Its ID (auto_…).
  - `object` const · required  
    Always `automation`.  
    Always `"automation"`.
  - `name` string · required  
    Its name.
  - `trigger` object · required  
    `kind` (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and `every_minutes`, `sport` or `min_points` as the kind takes.
  - `scope` object  
    The 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).
    - `rule_id` string  
      A saved rule (rl_…): the automation alerts on its matches, with no condition or view.  
      pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
    - `rule_version` integer  
      The version alerted; the latest when absent.  
      min 1
    - `rule_events` array of string  
      The events it alerts on (all three when absent).
    - `min_price_american` integer  
      Alert only at this American price or better.
  - `condition` string · nullable  
    Its condition, a formula, as typed.
  - `macro_id` string · nullable  
    The macro it runs, when it runs one.
  - `view` object · nullable  
    The view spec its condition runs over.
  - `action` object · required  
    `kind` (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
  - `cooldown_seconds` integer  
    The quiet time after it acts, in seconds.
  - `enabled` boolean · required  
    Whether it runs.
  - `paused_reason` string · nullable  
    Why Kelly paused it, when it did.
  - `failures` integer  
    Failed checks in a row.
  - `last_run_at` string · nullable  
    Its last check.  
    format date-time
  - `last_fired_at` string · nullable  
    When it last acted.  
    format date-time
  - `next_run_at` string · nullable  
    Its next scheduled check.  
    format date-time
  - `created_at` string  
    When it was made.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `has_more` boolean · required  
  Always false: every one is listed.
- `next_cursor` null · required  
  Always null.

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

### Example
```http
GET https://api.askkelly.ai/v1/automations
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 automation
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.

### Parameters
Body, `application/json` (required):

- `name` string  
  Its name.  
  min length 1 · max length 200
- `trigger` object  
  `{kind, every_minutes?, sport?, min_points?}`.
- `scope` object  
  `{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).
- `condition` string  
  A formula, starting with =.  
  min length 1 · max length 2000
- `mode` string  
  The condition's language.  
  default "excel"
- `macro` string  
  A macro's ID, code or name.  
  max length 200
- `view` object  
  A view spec its condition runs over.
- `action` object  
  `{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_seconds` integer  
  Quiet time after it acts, in seconds.  
  min 0 · max 604800 · default 3600
- `enabled` boolean  
  Whether it runs.  
  default true

### Response
`201` The automation as made.

- `id` string · required  
  Its ID (auto_…).
- `object` const · required  
  Always `automation`.  
  Always `"automation"`.
- `name` string · required  
  Its name.
- `trigger` object · required  
  `kind` (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and `every_minutes`, `sport` or `min_points` as the kind takes.
- `scope` object  
  The 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).
  - `rule_id` string  
    A saved rule (rl_…): the automation alerts on its matches, with no condition or view.  
    pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
  - `rule_version` integer  
    The version alerted; the latest when absent.  
    min 1
  - `rule_events` array of string  
    The events it alerts on (all three when absent).
  - `min_price_american` integer  
    Alert only at this American price or better.
- `condition` string · nullable  
  Its condition, a formula, as typed.
- `macro_id` string · nullable  
  The macro it runs, when it runs one.
- `view` object · nullable  
  The view spec its condition runs over.
- `action` object · required  
  `kind` (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
- `cooldown_seconds` integer  
  The quiet time after it acts, in seconds.
- `enabled` boolean · required  
  Whether it runs.
- `paused_reason` string · nullable  
  Why Kelly paused it, when it did.
- `failures` integer  
  Failed checks in a row.
- `last_run_at` string · nullable  
  Its last check.  
  format date-time
- `last_fired_at` string · nullable  
  When it last acted.  
  format date-time
- `next_run_at` string · nullable  
  Its next scheduled check.  
  format date-time
- `created_at` string  
  When it was made.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
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."
  }
}
```

```json
{
  "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"
}
```

```http
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."
  }
}
```

```json
{
  "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 automation
scope `read:formulas` · 0 credits, not charged during the beta · status live

One of your automations. Anyone else's answers 404.

### Parameters
- `automation_id` string · path · required  
  The automation's ID (auto_…).  
  min length 1 · max length 200

### Response
`200` The automation.

- `id` string · required  
  Its ID (auto_…).
- `object` const · required  
  Always `automation`.  
  Always `"automation"`.
- `name` string · required  
  Its name.
- `trigger` object · required  
  `kind` (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and `every_minutes`, `sport` or `min_points` as the kind takes.
- `scope` object  
  The 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).
  - `rule_id` string  
    A saved rule (rl_…): the automation alerts on its matches, with no condition or view.  
    pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
  - `rule_version` integer  
    The version alerted; the latest when absent.  
    min 1
  - `rule_events` array of string  
    The events it alerts on (all three when absent).
  - `min_price_american` integer  
    Alert only at this American price or better.
- `condition` string · nullable  
  Its condition, a formula, as typed.
- `macro_id` string · nullable  
  The macro it runs, when it runs one.
- `view` object · nullable  
  The view spec its condition runs over.
- `action` object · required  
  `kind` (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
- `cooldown_seconds` integer  
  The quiet time after it acts, in seconds.
- `enabled` boolean · required  
  Whether it runs.
- `paused_reason` string · nullable  
  Why Kelly paused it, when it did.
- `failures` integer  
  Failed checks in a row.
- `last_run_at` string · nullable  
  Its last check.  
  format date-time
- `last_fired_at` string · nullable  
  When it last acted.  
  format date-time
- `next_run_at` string · nullable  
  Its next scheduled check.  
  format date-time
- `created_at` string  
  When it was made.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
GET https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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 automation
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.

### Parameters
- `automation_id` string · path · required  
  The automation's ID (auto_…).  
  min length 1 · max length 200

Body, `application/json` (required):

- `name` string  
  Its name.  
  min length 1 · max length 200
- `trigger` object  
  `{kind, every_minutes?, sport?, min_points?}`.
- `scope` object  
  `{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).
- `condition` string  
  A formula, starting with =.  
  min length 1 · max length 2000
- `mode` string  
  The condition's language.
- `macro` string  
  A macro's ID, code or name.  
  max length 200
- `view` object  
  A view spec its condition runs over.
- `action` object  
  `{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_seconds` integer  
  Quiet time after it acts, in seconds.  
  min 0 · max 604800
- `enabled` boolean  
  Whether it runs.

### Response
`200` The automation as it now is.

- `id` string · required  
  Its ID (auto_…).
- `object` const · required  
  Always `automation`.  
  Always `"automation"`.
- `name` string · required  
  Its name.
- `trigger` object · required  
  `kind` (schedule, prices_refreshed, line_move, game_final, injury_update, lineup_posted), and `every_minutes`, `sport` or `min_points` as the kind takes.
- `scope` object  
  The 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).
  - `rule_id` string  
    A saved rule (rl_…): the automation alerts on its matches, with no condition or view.  
    pattern ^rl_[0-9a-hjkmnp-tv-z]{20}$
  - `rule_version` integer  
    The version alerted; the latest when absent.  
    min 1
  - `rule_events` array of string  
    The events it alerts on (all three when absent).
  - `min_price_american` integer  
    Alert only at this American price or better.
- `condition` string · nullable  
  Its condition, a formula, as typed.
- `macro_id` string · nullable  
  The macro it runs, when it runs one.
- `view` object · nullable  
  The view spec its condition runs over.
- `action` object · required  
  `kind` (alert, refresh_view, watchlist, fill_slip) and its fields. Never a bet placed or a move confirmed (D8).
- `cooldown_seconds` integer  
  The quiet time after it acts, in seconds.
- `enabled` boolean · required  
  Whether it runs.
- `paused_reason` string · nullable  
  Why Kelly paused it, when it did.
- `failures` integer  
  Failed checks in a row.
- `last_run_at` string · nullable  
  Its last check.  
  format date-time
- `last_fired_at` string · nullable  
  When it last acted.  
  format date-time
- `next_run_at` string · nullable  
  Its next scheduled check.  
  format date-time
- `created_at` string  
  When it was made.  
  format date-time
- `updated_at` string  
  When it last changed.  
  format date-time

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

### Example
```http
PATCH https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "enabled": false
}
```

```json
{
  "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 automation
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.

### Parameters
- `automation_id` string · path · required  
  The automation's ID (auto_…).  
  min length 1 · max length 200

### Response
`200` Deleted.

- `id` string · required  
  Its ID.
- `object` const · required  
  Always `automation`.  
  Always `"automation"`.
- `deleted` const · required  
  Always true.  
  Always `true`.

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

### Example
```http
DELETE https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "id": "auto_nkqn9520r75fqfmcrhjr",
  "object": "automation",
  "deleted": true
}
```

`GET /v1/automations/{automation_id}/runs`

## List an automation's runs
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.

### Parameters
- `automation_id` string · path · required  
  The automation's ID (auto_…).  
  min length 1 · max length 200

### Response
`200` Its checks.

- `object` const · required  
  Always `list`.  
  Always `"list"`.
- `data` array of object · required  
  Its checks, newest first.
  - `id` string  
    Its ID (arun_…).
  - `object` const  
    Always `automation_run`.  
    Always `"automation_run"`.
  - `automation_id` string  
    The automation.
  - `status` string  
    What happened.  
    One of: `fired`, `no_match`, `cooldown`, `duplicate`, `off`, `failed` (open: new values may be added).
  - `matched` integer  
    Rows the condition held for.
  - `detail` object  
    The action and the matches kept, or why it was off.
  - `error` string · nullable  
    The failure's class, when it failed.
  - `started_at` string  
    When it started.  
    format date-time
  - `finished_at` string · nullable  
    When it finished.  
    format date-time
- `has_more` boolean · required  
  Always false: every one is listed.
- `next_cursor` null · required  
  Always null.

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

### Example
```http
GET https://api.askkelly.ai/v1/automations/auto_nkqn9520r75fqfmcrhjr/runs
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

`POST /v1/rules:link`

## Make a rule link
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.

### Parameters
Body, `application/json` (required):

- `formula` string  
  The 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
- `competition` string  
  The competition it bets, e.g. nfl.  
  pattern ^[a-z0-9_]{2,24}$
- `market` string  
  The bet: spread, moneyline, over, under or teaser.  
  One of: `spread`, `moneyline`, `over`, `under`, `teaser` (open: new values may be added).
- `side` string  
  rule (bet the team the rule matched) or fade (the other side).  
  One of: `rule`, `fade` (open: new values may be added).
- `bet_moment` string  
  When the bet is priced: open, edition (the weekly sheet's) or close.  
  One of: `open`, `edition`, `close` (open: new values may be added).
- `seasons` array of string  
  The seasons it was built on, oldest first, e.g. ["2021", "2022"].  
  min items 1 · max items 60
- `season_type` string  
  regular, postseason or all.  
  One of: `regular`, `postseason`, `all` (open: new values may be added).
- `stake` string  
  risk one unit (default) or to_win one unit.  
  One of: `risk`, `to_win` (open: new values may be added).
- `price` string  
  consensus (Kelly's consensus price, default) or flat_110.  
  One of: `consensus`, `flat_110` (open: new values may be added).
- `name` string  
  The rule's name, shown when the link opens.  
  min length 1 · max length 120
- `notes` string  
  Notes shown when the link opens.  
  min length 1 · max length 1000
- `inputs` array of string  
  Change the formula's numbers first, by the input IDs a call returned, e.g. ["in1=-7"].  
  max items 24

### Response
`200` The link.

- `object` const · required  
  Always rule_link.  
  Always `"rule_link"`.
- `url` string · required  
  The link (askkelly.ai/rules/open#k1....). The rule rides after #, which browsers never send to a server.  
  format uri
- `token` string · required  
  The part after #, a k1. token.
- `rule` object · required  
  The rule the link carries, as given (empty fields left out).
  - `formula` string · required  
    The 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
  - `competition` string · required  
    The competition it bets, e.g. nfl.  
    pattern ^[a-z0-9_]{2,24}$
  - `market` string  
    The bet: spread, moneyline, over, under or teaser.  
    One of: `spread`, `moneyline`, `over`, `under`, `teaser` (open: new values may be added).
  - `side` string  
    rule (bet the team the rule matched) or fade (the other side).  
    One of: `rule`, `fade` (open: new values may be added).
  - `bet_moment` string  
    When the bet is priced: open, edition (the weekly sheet's) or close.  
    One of: `open`, `edition`, `close` (open: new values may be added).
  - `seasons` array of string  
    The seasons it was built on, oldest first, e.g. ["2021", "2022"].  
    min items 1 · max items 60
  - `season_type` string  
    regular, postseason or all.  
    One of: `regular`, `postseason`, `all` (open: new values may be added).
  - `stake` string  
    risk one unit (default) or to_win one unit.  
    One of: `risk`, `to_win` (open: new values may be added).
  - `price` string  
    consensus (Kelly's consensus price, default) or flat_110.  
    One of: `consensus`, `flat_110` (open: new values may be added).
  - `name` string  
    The rule's name, shown when the link opens.  
    min length 1 · max length 120
  - `notes` string  
    Notes shown when the link opens.  
    min length 1 · max length 1000
- `inputs` array of object · required  
  The formula's numeric thresholds a person may change, in reading order.
  - `id` string · required  
    Its ID, in1, in2... in reading order; pass it back in inputs.
  - `label` string · required  
    What the number is compared with, as the formula writes it.
  - `op` string · required  
    The comparison, read with the label on the left.  
    One of: `<`, `<=`, `>`, `>=`, `=`, `<>` (open: new values may be added).
  - `value` number · required  
    The number now.
  - `at` array of integer · required  
    Its place in the formula: start and end character.  
    min items 2 · max items 2
- `button_html` string · required  
  A plain HTML link to paste on a page: no script, no tracking, no logo.
- `import_arguments` object · required  
  The 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.
  - `text` string · required  
    The formula.
  - `format` const · required  
    Always formula.  
    Always `"formula"`.
  - `tool` const · required  
    Always kelly.  
    Always `"kelly"`.
  - `source_kind` const · required  
    Always url.  
    Always `"url"`.
  - `via` const · required  
    Always link.  
    Always `"link"`.
  - `raw_ref` string  
    The link.  
    max length 500
  - `dry_run` boolean · required  
    false: the import keeps a draft to confirm.
  - `name` string  
    The rule's name, shown when the link opens.  
    min length 1 · max length 120
  - `competition` string  
    The competition it bets, e.g. nfl.  
    pattern ^[a-z0-9_]{2,24}$
  - `market` string  
    The bet: spread, moneyline, over, under or teaser.  
    One of: `spread`, `moneyline`, `over`, `under`, `teaser` (open: new values may be added).
  - `side` string  
    rule (bet the team the rule matched) or fade (the other side).  
    One of: `rule`, `fade` (open: new values may be added).
  - `bet_moment` string  
    When the bet is priced: open, edition (the weekly sheet's) or close.  
    One of: `open`, `edition`, `close` (open: new values may be added).
  - `seasons` array of string  
    The seasons it was built on, oldest first, e.g. ["2021", "2022"].  
    min items 1 · max items 60
  - `season_type` string  
    regular, postseason or all.  
    One of: `regular`, `postseason`, `all` (open: new values may be added).
  - `stake` string  
    risk one unit (default) or to_win one unit.  
    One of: `risk`, `to_win` (open: new values may be added).
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `attribution` string · nullable  
  Attribution the source's terms require.
- `request_id` string · required · nullable  
  The request that produced this response.
- `live_topics` array of string  
  Kelly Wire topics that update this resource (API and cards only).
- `rg_line` string · nullable  
  The cost line (COMP-1, D19) on every resource and result that touches wagering: one engine-computed cost fact, or the short form, plus 21+ and the helpline. Show it with the value. Null on resources that don't touch wagering.

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

### Example
```http
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"
  ]
}
```

```json
{
  "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
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00Z

```http
POST https://api.askkelly.ai/v1/rules:link
Content-Type: application/json

{
  "formula": "=home",
  "competition": "nfl",
  "market": "parlay"
}
```

```json
{
  "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."
}
```

```http
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"
  ]
}
```

```json
{
  "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
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00Z

`GET /v1/me/rule-import-ways`

## Get your ways to import rules
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.

### Response
`200` Your ways to send a system to Kelly.

- `object` const · required  
  Always rule_import_ways.  
  Always `"rule_import_ways"`.
- `email` object · required  
  Forwarding a system email.
  - `address` string · required · nullable  
    The person's own mail-in address; null while mail-in is off. Mail is read only from their sign-in address.
  - `on` boolean · required  
    Whether mail-in is switched on.
  - `steps` array of string · required  
    What to do, in order.
- `bookmarklet` object · required  
  The Send to Kelly bookmarklet.
  - `href` string · required  
    The bookmarklet's javascript: address, to drag to the bookmarks bar.
  - `steps` array of string · required  
    What to do, in order.
- `share_sheet` object · required  
  Sharing to Kelly from a phone's share sheet.
  - `platforms` array of string  
    Where it works (android).
  - `ios` string  
    What to do on an iPhone instead.
  - `steps` array of string · required  
    What to do, in order.
- `extension` object · required  
  Kelly's Chrome extension.
  - `edition` string  
    The build that has it: full.
  - `steps` array of string · required  
    What to do, in order.
- `links` object · required  
  Open in Kelly links and Kelly's own share links.
  - `open_in_kelly` string  
    An example Open in Kelly address.
  - `fields` array of string  
    The fields an Open in Kelly link may carry after #.
  - `steps` array of string · required  
    What to do, in order.
- `automation` object · required  
  Zapier, Make or n8n.
  - `apis` array of string  
    The routes to call.
  - `steps` array of string · required  
    What to do, in order.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `attribution` string · nullable  
  Attribution the source's terms require.
- `request_id` string · required · nullable  
  The request that produced this response.
- `live_topics` array of string  
  Kelly Wire topics that update this resource (API and cards only).
- `rg_line` string · nullable  
  The cost line (COMP-1, D19) on every resource and result that touches wagering: one engine-computed cost fact, or the short form, plus 21+ and the helpline. Show it with the value. Null on resources that don't touch wagering.

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

### Example
```http
GET https://api.askkelly.ai/v1/me/rule-import-ways
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "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
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00Z

Generated from Kelly API 2026-10-05.

---

Generated from Kelly API 2026-10-05

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

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