# artifacts

Make, read, share and remix artifacts: recipes of Kelly tools that Kelly draws again for each viewer, with controls anyone can change.

| Method | Path | Title | Access | Price | MCP tool |
| --- | --- | --- | --- | --- | --- |
| GET | [`/v1/artifacts`](#list-my-artifacts) | List your artifacts | `read:artifacts` | 0 | `list_my_artifacts` |
| POST | [`/v1/artifacts`](#create-artifact) | Make an artifact | `write:artifacts` | 0 | `create_artifact` |
| GET | [`/v1/artifacts/{artifact_id}`](#get-artifact) | Get one of your artifacts | `read:artifacts` | 0 | `get_artifact` |
| PATCH | [`/v1/artifacts/{artifact_id}`](#update-artifact) | Change an artifact | `write:artifacts` | 0 | `update_artifact` |
| POST | [`/v1/artifacts/{artifact_id}:share`](#share-artifact) | Share an artifact | `write:artifacts` | 0 | `share_artifact` |
| POST | [`/v1/artifacts:remix`](#remix-artifact) | Make a shared artifact yours | `write:artifacts` | 0 | `remix_artifact` |
| POST | [`/v1/artifacts:reply`](#reply-to-artifact) | Reply to a shared artifact with yours | `write:artifacts` | 0 | `reply_to_artifact` |
| GET | [`/v1/shared-artifacts/{slug}/vs/{other}`](#compare-artifacts) | Compare two shared artifacts | public | 0 | `compare_artifacts` |
| GET | [`/v1/shared-artifacts/{slug}/replies`](#list-artifact-replies) | List a shared artifact's replies | public | 0 | `list_artifact_replies` |
| GET | [`/v1/shared-artifacts/{slug}`](#get-shared-artifact) | Get a shared artifact | public | 0 | `get_shared_artifact` |
| GET | [`/v1/artifact-templates`](#list-artifact-templates) | List the artifact templates | public | 0 | `list_artifact_templates` |
| GET | [`/v1/shared-artifacts/{slug}/tail`](#get-artifact-tail) | Get a shared artifact's bets to tail | public | 0 | `get_artifact_tail` |
| GET | [`/v1/me/share-moments`](#get-my-share-moments) | Your prepared moments | `read:artifacts` | 0 | `get_my_share_moments` |
| PATCH | [`/v1/me/share-moments`](#set-my-share-moments) | Turn prepared moments on or off | `write:artifacts` | 0 | `set_my_share_moments` |
| GET | [`/v1/shared-artifacts/{slug}/render`](#render-artifact) | Get an artifact's pictures | public | 0 | `render_artifact` |
| POST | [`/v1/shared-artifacts/{slug}/report`](#report-artifact) | Report a shared artifact | public | 0 | `report_artifact` |
| GET | [`/v1/me/handle`](#get-my-handle) | Get your public handle | `read:artifacts` | 0 | `get_my_handle` |
| PUT | [`/v1/me/handle`](#set-my-handle) | Set your public handle | `write:artifacts` | 0 | `set_my_handle` |
| DELETE | [`/v1/me/handle`](#remove-my-handle) | Give up your public handle | `write:artifacts` | 0 | `remove_my_handle` |

`GET /v1/artifacts`

## List your artifacts
scope `read:artifacts` · 0 credits, not charged during the beta · MCP tool `list_my_artifacts` · status live

Your artifacts, most recently changed first, with how many there are: each one's title, address, mode (live or frozen), who may open it, its version and how many parts it has. Filter by project.

### Parameters
- `project_id` string · query  
  Only this project's artifacts.  
  max length 64
- `limit` integer · query  
  Artifacts per page, 1 to 50.  
  min 1 · max 50 · default 25
- `cursor` string · query  
  The next_cursor of the page before.  
  max length 200

### Response
`200` A page of your artifacts.

- `object` const · required  
  Always `artifact_list`.  
  Always `"artifact_list"`.
- `artifacts` array of object · required  
  The artifacts, most recently changed first.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `project_id` string · nullable  
    The project it belongs to, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `created_at` string  
    When it was made.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `revoked` boolean  
    Whether its owner turned its link off.
  - `blocks` integer  
    How many blocks it has.
- `total` integer · required  
  How many artifacts you have (in this project, when asked).
- `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/artifacts
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "artifact_list",
  "artifacts": [
    {
      "id": "art_hre67fdbqtf9ngbejn9v",
      "slug": "p0mketm12pvqd03yc9ga",
      "title": "Reading a -110 price",
      "mode": "live",
      "visibility": "private",
      "theme": "wire",
      "version": 1,
      "template": null,
      "project_id": null,
      "remix_of": null,
      "created_at": "2026-10-04T17:30:00Z",
      "updated_at": "2026-10-04T17:30:00Z",
      "published_at": null,
      "revoked": false,
      "removed": false,
      "blocks": 3
    }
  ],
  "total": 1,
  "next_cursor": null
}
```

`POST /v1/artifacts`

## Make an artifact
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `create_artifact` · status live

Makes an artifact from a recipe (the Kelly Artifact Spec: a title, up to 6 controls and up to 12 parts, each naming a Kelly tool that reads, its arguments and what to draw) or from one of your answers' visuals, and answers it drawn for you. A recipe never holds a number; Kelly computes them when it is drawn. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

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

- `template` string  
  A template's ID (GET /v1/artifact-templates): a starter filled from your own data.  
  pattern ^[a-z][a-z0-9_]{1,47}$
- `inputs` object  
  With template: what it asks for, each optional; left out, it is filled from your account (your league synced last, this month).
  - `league` string  
    One of your connected leagues (lg_…).
  - `month` string  
    A month, as YYYY-MM.  
    pattern ^[0-9]{4}-[0-9]{2}$
- `recipe` object  
  The artifact's recipe. A Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`): a title, up to 6 controls and 1 to 12 blocks, each naming a Kelly tool that reads. It never holds a number: the engine draws each one.
- `from_answer` object  
  An Ask Kelly answer of yours: its visuals become the blocks.
  - `answer_id` string · required  
    The answer's ID (ans_…).
- `project_id` string  
  One of your projects.

### Response
`201` The artifact, drawn for you.

- `object` const · required  
  Always `artifact`.  
  Always `"artifact"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `url` string · nullable  
    Its page on askkelly.ai, with this view's controls.
  - `author` object  
    Who made it, as they chose to show it; `display` is always shown.
  - `description` string · nullable  
    Its first note, in plain words.
  - `as_of` string  
    When these blocks were drawn.  
    format date-time
  - `can_edit` boolean  
    Whether the reader may change it (its owner).
  - `actions` array of string  
    What the reader may do: remix, ask, edit, share.
  - `original` object · nullable  
    The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
  - `can_reply` boolean  
    Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
- `params` array of object · required  
  The controls a reader may change, each with its `value`, `display` and `default`.
- `query` string · required  
  This view's controls as an address query, defaults left out.
- `blocks` array of object · required  
  Its blocks, in reading order, drawn for this reader.
  - `id` string · required  
    b1, b2, …
  - `type` string · required  
    The block's type.
  - `width` integer · required  
    Columns of three it spans.  
    One of: `1`, `2`, `3` (open: new values may be added).
  - `problem` string · nullable  
    Why it isn't drawn, or null.
  - `link` string · nullable  
    on_site_only: where it is drawn.
  - `frozen` boolean  
    Kept as its owner shared it.
  - `summary` string · nullable  
    What it shows, in one sentence.
- `recipe` object · required  
  Its recipe: a Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`).
- `versions` integer · required  
  How many versions it has.
- `remix` object  
  Only on Make it yours (remix_artifact): what the copy took from the reader. `from` (the shared artifact's `id` and `slug`), `controls` (the view it opens on, as an address query), `league` (`id` and `name` of the reader's league its league parts draw, or null) and `blocks`: each own-data block's `block`, `binding`, `league`, `left_out` (arguments that named the author's own records) and `needs` (`league` when the reader has none to draw).
- `share` object  
  Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (`artifact`, `url`, `snapshots`, `images`).
- `compare_url` string  
  Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

### 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/artifacts
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "text": "The price most books hang on a side."
      },
      {
        "id": "b2",
        "type": "tiles",
        "binding": "public",
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        }
      },
      {
        "id": "b3",
        "type": "ask",
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  }
}
```

```json
{
  "object": "artifact",
  "artifact": {
    "id": "art_hre67fdbqtf9ngbejn9v",
    "slug": "p0mketm12pvqd03yc9ga",
    "url": "https://askkelly.ai/a/p0mketm12pvqd03yc9ga",
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "version": 1,
    "visibility": "private",
    "author": {
      "display": "A Kelly member"
    },
    "description": "The price most books hang on a side.",
    "published_at": null,
    "as_of": "2026-10-04T17:30:00Z",
    "remix_of": null,
    "template": null,
    "can_edit": true,
    "actions": [
      "remix",
      "ask"
    ],
    "original": null,
    "can_reply": false,
    "live": {
      "topics": [],
      "follow_gap_seconds": 3
    }
  },
  "params": [],
  "query": "",
  "blocks": [
    {
      "id": "b1",
      "type": "note",
      "width": 3,
      "text": "The price most books hang on a side."
    },
    {
      "id": "b2",
      "type": "tiles",
      "width": 3,
      "tiles": [
        {
          "label": "Summary",
          "display": "Kelly's convert odds on the person's own numbers."
        },
        {
          "label": "Last read",
          "display": "2026-10-04T17:30:00Z"
        },
        {
          "label": "Source",
          "display": "kelly"
        }
      ],
      "problem": null,
      "summary": "Kelly's convert odds on the person's own numbers.",
      "frozen": false
    },
    {
      "id": "b3",
      "type": "ask",
      "width": 3,
      "questions": [
        "What does -110 mean as a probability?"
      ]
    }
  ],
  "since": null,
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "params": [],
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "width": 3,
        "callouts": [],
        "text": "The price most books hang on a side.",
        "questions": []
      },
      {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        },
        "binding": "public",
        "callouts": [],
        "questions": []
      },
      {
        "id": "b3",
        "type": "ask",
        "width": 3,
        "callouts": [],
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  },
  "versions": 1
}
```

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

{
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "text": "Test mode."
      },
      {
        "id": "b2",
        "type": "tiles",
        "binding": "public",
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        }
      },
      {
        "id": "b3",
        "type": "ask",
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  }
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:artifacts scope.",
  "param": "write:artifacts",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_ca4f2c2b066f930794c25d1c",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

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

{
  "recipe": {
    "kas": 1,
    "title": "Empty",
    "blocks": []
  }
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "recipe.blocks: List should have at least 1 item after validation, not 0",
  "param": "recipe",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_b7d2356fe67758d15d3e69c5",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

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

{
  "recipe": {
    "kas": 1,
    "title": "Chiefs at Raiders: my card",
    "blocks": [
      {
        "id": "b1",
        "type": "card",
        "binding": "public",
        "source": {
          "tool": "get_market",
          "args": {
            "market_id": "mkt_f1sgktw2wqexfkatnd75",
            "selections": [
              "away"
            ]
          }
        }
      },
      {
        "id": "b2",
        "type": "card",
        "binding": "public",
        "source": {
          "tool": "analyze_parlay",
          "args": {
            "selection_ids": [
              "sel_prpdvg0dqppc6mqc4wns",
              "sel_jxveeh9qa7p63qv03dfe"
            ]
          }
        }
      },
      {
        "id": "b3",
        "type": "action",
        "action": "tail"
      }
    ]
  }
}
```

```json
{
  "object": "artifact",
  "artifact": {
    "id": "art_vv011xck2jc417pkgrqw",
    "slug": "wbaztybb2myg079j9ej9",
    "url": "https://askkelly.ai/a/wbaztybb2myg079j9ej9",
    "title": "Chiefs at Raiders: my card",
    "theme": "wire",
    "mode": "live",
    "version": 1,
    "visibility": "private",
    "author": {
      "display": "A Kelly member"
    },
    "description": null,
    "published_at": null,
    "as_of": "2026-10-04T17:30:00Z",
    "remix_of": null,
    "template": null,
    "can_edit": true,
    "actions": [
      "remix",
      "ask",
      "tail"
    ],
    "original": null,
    "can_reply": false,
    "live": {
      "topics": [],
      "follow_gap_seconds": 3
    }
  },
  "params": [],
  "query": "",
  "blocks": [
    {
      "id": "b1",
      "type": "card",
      "width": 3,
      "problem": "on_site_only",
      "link": "https://askkelly.ai/a/wbaztybb2myg079j9ej9",
      "frozen": false
    },
    {
      "id": "b2",
      "type": "card",
      "width": 3,
      "problem": "on_site_only",
      "link": "https://askkelly.ai/a/wbaztybb2myg079j9ej9",
      "frozen": false
    },
    {
      "id": "b3",
      "type": "action",
      "width": 3,
      "action": "tail",
      "href": "/a/wbaztybb2myg079j9ej9/tail"
    }
  ],
  "since": null,
  "recipe": {
    "kas": 1,
    "title": "Chiefs at Raiders: my card",
    "theme": "wire",
    "mode": "live",
    "params": [],
    "blocks": [
      {
        "id": "b1",
        "type": "card",
        "width": 3,
        "source": {
          "tool": "get_market",
          "args": {
            "market_id": "mkt_f1sgktw2wqexfkatnd75",
            "selections": [
              "away"
            ]
          }
        },
        "binding": "public",
        "callouts": [],
        "questions": []
      },
      {
        "id": "b2",
        "type": "card",
        "width": 3,
        "source": {
          "tool": "analyze_parlay",
          "args": {
            "selection_ids": [
              "sel_prpdvg0dqppc6mqc4wns",
              "sel_jxveeh9qa7p63qv03dfe"
            ]
          }
        },
        "binding": "public",
        "callouts": [],
        "questions": []
      },
      {
        "id": "b3",
        "type": "action",
        "width": 3,
        "callouts": [],
        "questions": [],
        "action": "tail"
      }
    ]
  },
  "versions": 1
}
```

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

{
  "template": "league_recap"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Connect a fantasy league first: paste its link or Sleeper league ID in Ask Kelly or on Connect.",
  "param": "template",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_ca632c4d44386ec722ffb61f",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

`GET /v1/artifacts/{artifact_id}`

## Get one of your artifacts
scope `read:artifacts` · 0 credits, not charged during the beta · MCP tool `get_artifact` · status live

One of your artifacts drawn for you now, with its recipe and how many versions it has. Controls go in the query by their ids. Anyone else's answers 404. Read here, a part drawn from a tool that carries book prices or links answers problem on_site_only with the page's link, and a chart keeps only the columns its rights allow.

### Parameters
- `artifact_id` string · path · required  
  The artifact's ID (art_…).  
  pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

- `controls` object · query  
  The artifact's controls by their IDs, as its page's address carries them (`player=plr_…`, `weeks=5-10`); a block's view by `b1.t=1`. Absent: each default.

### Response
`200` The artifact, drawn for you, with its recipe.

- `object` const · required  
  Always `artifact`.  
  Always `"artifact"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `url` string · nullable  
    Its page on askkelly.ai, with this view's controls.
  - `author` object  
    Who made it, as they chose to show it; `display` is always shown.
  - `description` string · nullable  
    Its first note, in plain words.
  - `as_of` string  
    When these blocks were drawn.  
    format date-time
  - `can_edit` boolean  
    Whether the reader may change it (its owner).
  - `actions` array of string  
    What the reader may do: remix, ask, edit, share.
  - `original` object · nullable  
    The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
  - `can_reply` boolean  
    Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
- `params` array of object · required  
  The controls a reader may change, each with its `value`, `display` and `default`.
- `query` string · required  
  This view's controls as an address query, defaults left out.
- `blocks` array of object · required  
  Its blocks, in reading order, drawn for this reader.
  - `id` string · required  
    b1, b2, …
  - `type` string · required  
    The block's type.
  - `width` integer · required  
    Columns of three it spans.  
    One of: `1`, `2`, `3` (open: new values may be added).
  - `problem` string · nullable  
    Why it isn't drawn, or null.
  - `link` string · nullable  
    on_site_only: where it is drawn.
  - `frozen` boolean  
    Kept as its owner shared it.
  - `summary` string · nullable  
    What it shows, in one sentence.
- `recipe` object · required  
  Its recipe: a Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`).
- `versions` integer · required  
  How many versions it has.
- `remix` object  
  Only on Make it yours (remix_artifact): what the copy took from the reader. `from` (the shared artifact's `id` and `slug`), `controls` (the view it opens on, as an address query), `league` (`id` and `name` of the reader's league its league parts draw, or null) and `blocks`: each own-data block's `block`, `binding`, `league`, `left_out` (arguments that named the author's own records) and `needs` (`league` when the reader has none to draw).
- `share` object  
  Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (`artifact`, `url`, `snapshots`, `images`).
- `compare_url` string  
  Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

### 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/artifacts/art_hre67fdbqtf9ngbejn9v
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "artifact",
  "artifact": {
    "id": "art_hre67fdbqtf9ngbejn9v",
    "slug": "p0mketm12pvqd03yc9ga",
    "url": "https://askkelly.ai/a/p0mketm12pvqd03yc9ga",
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "version": 1,
    "visibility": "private",
    "author": {
      "display": "A Kelly member"
    },
    "description": "The price most books hang on a side.",
    "published_at": null,
    "as_of": "2026-10-04T17:30:00Z",
    "remix_of": null,
    "template": null,
    "can_edit": true,
    "actions": [
      "remix",
      "ask"
    ],
    "original": null,
    "can_reply": false,
    "live": {
      "topics": [],
      "follow_gap_seconds": 3
    }
  },
  "params": [],
  "query": "",
  "blocks": [
    {
      "id": "b1",
      "type": "note",
      "width": 3,
      "text": "The price most books hang on a side."
    },
    {
      "id": "b2",
      "type": "tiles",
      "width": 3,
      "tiles": [
        {
          "label": "Summary",
          "display": "Kelly's convert odds on the person's own numbers."
        },
        {
          "label": "Last read",
          "display": "2026-10-04T17:30:00Z"
        },
        {
          "label": "Source",
          "display": "kelly"
        }
      ],
      "problem": null,
      "summary": "Kelly's convert odds on the person's own numbers.",
      "frozen": false
    },
    {
      "id": "b3",
      "type": "ask",
      "width": 3,
      "questions": [
        "What does -110 mean as a probability?"
      ]
    }
  ],
  "since": null,
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "params": [],
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "width": 3,
        "callouts": [],
        "text": "The price most books hang on a side.",
        "questions": []
      },
      {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        },
        "binding": "public",
        "callouts": [],
        "questions": []
      },
      {
        "id": "b3",
        "type": "ask",
        "width": 3,
        "callouts": [],
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  },
  "versions": 1
}
```

```http
GET https://api.askkelly.ai/v1/artifacts/art_zzzzzzzzzzzzzzzzzzzz
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No artifact with that id on your account.",
  "param": null,
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_191f4ada1860e203e0e073b5",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`PATCH /v1/artifacts/{artifact_id}`

## Change an artifact
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `update_artifact` · status live

Saves a new version of the recipe. Send base_version, the version you changed: when the artifact moved on since, it answers conflict and nothing is saved. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

### Parameters
- `artifact_id` string · path · required  
  The artifact's ID (art_…).  
  pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

Body, `application/json` (required):

- `recipe` object  
  The new recipe. A Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`): a title, up to 6 controls and 1 to 12 blocks, each naming a Kelly tool that reads. It never holds a number: the engine draws each one.
- `base_version` integer  
  The version you changed; when it is no longer the current one the change answers 409 conflict.  
  min 1

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

- `object` const · required  
  Always `artifact`.  
  Always `"artifact"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `url` string · nullable  
    Its page on askkelly.ai, with this view's controls.
  - `author` object  
    Who made it, as they chose to show it; `display` is always shown.
  - `description` string · nullable  
    Its first note, in plain words.
  - `as_of` string  
    When these blocks were drawn.  
    format date-time
  - `can_edit` boolean  
    Whether the reader may change it (its owner).
  - `actions` array of string  
    What the reader may do: remix, ask, edit, share.
  - `original` object · nullable  
    The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
  - `can_reply` boolean  
    Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
- `params` array of object · required  
  The controls a reader may change, each with its `value`, `display` and `default`.
- `query` string · required  
  This view's controls as an address query, defaults left out.
- `blocks` array of object · required  
  Its blocks, in reading order, drawn for this reader.
  - `id` string · required  
    b1, b2, …
  - `type` string · required  
    The block's type.
  - `width` integer · required  
    Columns of three it spans.  
    One of: `1`, `2`, `3` (open: new values may be added).
  - `problem` string · nullable  
    Why it isn't drawn, or null.
  - `link` string · nullable  
    on_site_only: where it is drawn.
  - `frozen` boolean  
    Kept as its owner shared it.
  - `summary` string · nullable  
    What it shows, in one sentence.
- `recipe` object · required  
  Its recipe: a Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`).
- `versions` integer · required  
  How many versions it has.
- `remix` object  
  Only on Make it yours (remix_artifact): what the copy took from the reader. `from` (the shared artifact's `id` and `slug`), `controls` (the view it opens on, as an address query), `league` (`id` and `name` of the reader's league its league parts draw, or null) and `blocks`: each own-data block's `block`, `binding`, `league`, `left_out` (arguments that named the author's own records) and `needs` (`league` when the reader has none to draw).
- `share` object  
  Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (`artifact`, `url`, `snapshots`, `images`).
- `compare_url` string  
  Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

### 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/artifacts/art_hre67fdbqtf9ngbejn9v
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "text": "Stale."
      },
      {
        "id": "b2",
        "type": "tiles",
        "binding": "public",
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        }
      },
      {
        "id": "b3",
        "type": "ask",
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  },
  "base_version": 1
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The artifact changed since version 1: it is at version 2 now. Reload it and make the change again.",
  "param": null,
  "doc_url": "https://docs.askkelly.ai/problems/conflict",
  "request_id": "req_63bc7df8352db81fbcf76377",
  "retryable": false,
  "display_message": "That's already in use."
}
```

```http
PATCH https://api.askkelly.ai/v1/artifacts/art_hre67fdbqtf9ngbejn9v
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "text": "The price most books hang on both sides of a spread."
      },
      {
        "id": "b2",
        "type": "tiles",
        "binding": "public",
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        }
      },
      {
        "id": "b3",
        "type": "ask",
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  },
  "base_version": 1
}
```

```json
{
  "object": "artifact",
  "artifact": {
    "id": "art_hre67fdbqtf9ngbejn9v",
    "slug": "p0mketm12pvqd03yc9ga",
    "url": "https://askkelly.ai/a/p0mketm12pvqd03yc9ga",
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "version": 2,
    "visibility": "private",
    "author": {
      "display": "A Kelly member"
    },
    "description": "The price most books hang on both sides of a spread.",
    "published_at": null,
    "as_of": "2026-10-04T17:30:00Z",
    "remix_of": null,
    "template": null,
    "can_edit": true,
    "actions": [
      "remix",
      "ask"
    ],
    "original": null,
    "can_reply": false,
    "live": {
      "topics": [],
      "follow_gap_seconds": 3
    }
  },
  "params": [],
  "query": "",
  "blocks": [
    {
      "id": "b1",
      "type": "note",
      "width": 3,
      "text": "The price most books hang on both sides of a spread."
    },
    {
      "id": "b2",
      "type": "tiles",
      "width": 3,
      "tiles": [
        {
          "label": "Summary",
          "display": "Kelly's convert odds on the person's own numbers."
        },
        {
          "label": "Last read",
          "display": "2026-10-04T17:30:00Z"
        },
        {
          "label": "Source",
          "display": "kelly"
        }
      ],
      "problem": null,
      "summary": "Kelly's convert odds on the person's own numbers.",
      "frozen": false
    },
    {
      "id": "b3",
      "type": "ask",
      "width": 3,
      "questions": [
        "What does -110 mean as a probability?"
      ]
    }
  ],
  "since": null,
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "params": [],
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "width": 3,
        "callouts": [],
        "text": "The price most books hang on both sides of a spread.",
        "questions": []
      },
      {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        },
        "binding": "public",
        "callouts": [],
        "questions": []
      },
      {
        "id": "b3",
        "type": "ask",
        "width": 3,
        "callouts": [],
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  },
  "versions": 2
}
```

`POST /v1/artifacts/{artifact_id}:share`

## Share an artifact
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `share_artifact` · status live

Sets who may open it: link (anyone with the address) or public. The parts drawn from your own data are kept as they are now, and that is what others see; your live data never runs for them. Returns the address and its pictures. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

### Parameters
- `artifact_id` string · path · required  
  The artifact's ID (art_…).  
  pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

Body, `application/json` (required):

- `visibility` string  
  link (anyone with the link; the default) or public (listed). people, project and league open to you only for now.  
  One of: `link`, `public`, `people`, `project`, `league` (open: new values may be added).  
  default "link"
- `show_author` boolean  
  Show your Kelly name on it.

### Response
`200` Its link, and the blocks kept as they are now.

- `object` const · required  
  Always `artifact_share`.  
  Always `"artifact_share"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `project_id` string · nullable  
    The project it belongs to, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `created_at` string  
    When it was made.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `revoked` boolean  
    Whether its owner turned its link off.
- `url` string · required  
  Its link on askkelly.ai.
- `snapshots` array of string · required  
  The blocks kept as they are now, by ID: your own data, or every block when it is frozen.
- `images` object  
  Its pictures by format: link (1200×630), square (1080×1080), story (1080×1920).
  - `link` object  
    One picture.
    - `url` string  
      The PNG's address.
    - `width` integer  
      Pixels wide.
    - `height` integer  
      Pixels high.
  - `square` object  
    One picture.
    - `url` string  
      The PNG's address.
    - `width` integer  
      Pixels wide.
    - `height` integer  
      Pixels high.
  - `story` object  
    One picture.
    - `url` string  
      The PNG's address.
    - `width` integer  
      Pixels wide.
    - `height` integer  
      Pixels high.
- `text_url` string  
  Its plain text, for a reader that can't see pictures.

### 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/artifacts/art_hre67fdbqtf9ngbejn9v:share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "visibility": "link"
}
```

```json
{
  "object": "artifact_share",
  "artifact": {
    "id": "art_hre67fdbqtf9ngbejn9v",
    "slug": "addc7rz7brr5s5x7k66w",
    "title": "Reading a -110 price",
    "mode": "live",
    "visibility": "link",
    "theme": "wire",
    "version": 2,
    "template": null,
    "project_id": null,
    "remix_of": null,
    "created_at": "2026-10-04T17:30:00Z",
    "updated_at": "2026-10-04T17:30:00Z",
    "published_at": "2026-10-04T17:30:00Z",
    "revoked": false,
    "removed": false
  },
  "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w",
  "snapshots": [],
  "images": {
    "images": {
      "link": {
        "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/image/link",
        "width": 1200,
        "height": 630
      },
      "square": {
        "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/image/square",
        "width": 1080,
        "height": 1080
      },
      "story": {
        "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/image/story",
        "width": 1080,
        "height": 1920
      }
    },
    "text_url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/text"
  }
}
```

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

{
  "visibility": "link"
}
```

```json
{
  "object": "artifact_share",
  "artifact": {
    "id": "art_vv011xck2jc417pkgrqw",
    "slug": "6j60fp1ywvnwpbp5nrjf",
    "title": "Chiefs at Raiders: my card",
    "mode": "live",
    "visibility": "link",
    "theme": "wire",
    "version": 1,
    "template": null,
    "project_id": null,
    "remix_of": null,
    "created_at": "2026-10-04T17:30:00Z",
    "updated_at": "2026-10-04T17:30:00Z",
    "published_at": "2026-10-04T17:30:00Z",
    "revoked": false,
    "removed": false
  },
  "url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf",
  "snapshots": [],
  "images": {
    "images": {
      "link": {
        "url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf/image/link",
        "width": 1200,
        "height": 630
      },
      "square": {
        "url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf/image/square",
        "width": 1080,
        "height": 1080
      },
      "story": {
        "url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf/image/story",
        "width": 1080,
        "height": 1920
      }
    },
    "text_url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf/text"
  }
}
```

`POST /v1/artifacts:remix`

## Make a shared artifact yours
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `remix_artifact` · status live

Copies a shared artifact (by its slug) to your account; its parts that read the owner's own data now read yours. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

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

- `slug` string  
  Its address (askkelly.ai/a/{slug}).  
  min length 12 · max length 100
- `controls` object  
  The view to open your copy on, as its page's address carries it: controls by their IDs (`weeks`: `5-10`) and block views (`b1.t`: `1`). Absent: as it was shared.
- `league_id` string  
  Which of your leagues its league parts draw (lg_…). Absent: your league closest to the author's.  
  max length 40

### Response
`201` Your copy, drawn for you.

- `object` const · required  
  Always `artifact`.  
  Always `"artifact"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `url` string · nullable  
    Its page on askkelly.ai, with this view's controls.
  - `author` object  
    Who made it, as they chose to show it; `display` is always shown.
  - `description` string · nullable  
    Its first note, in plain words.
  - `as_of` string  
    When these blocks were drawn.  
    format date-time
  - `can_edit` boolean  
    Whether the reader may change it (its owner).
  - `actions` array of string  
    What the reader may do: remix, ask, edit, share.
  - `original` object · nullable  
    The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
  - `can_reply` boolean  
    Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
- `params` array of object · required  
  The controls a reader may change, each with its `value`, `display` and `default`.
- `query` string · required  
  This view's controls as an address query, defaults left out.
- `blocks` array of object · required  
  Its blocks, in reading order, drawn for this reader.
  - `id` string · required  
    b1, b2, …
  - `type` string · required  
    The block's type.
  - `width` integer · required  
    Columns of three it spans.  
    One of: `1`, `2`, `3` (open: new values may be added).
  - `problem` string · nullable  
    Why it isn't drawn, or null.
  - `link` string · nullable  
    on_site_only: where it is drawn.
  - `frozen` boolean  
    Kept as its owner shared it.
  - `summary` string · nullable  
    What it shows, in one sentence.
- `recipe` object · required  
  Its recipe: a Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`).
- `versions` integer · required  
  How many versions it has.
- `remix` object  
  Only on Make it yours (remix_artifact): what the copy took from the reader. `from` (the shared artifact's `id` and `slug`), `controls` (the view it opens on, as an address query), `league` (`id` and `name` of the reader's league its league parts draw, or null) and `blocks`: each own-data block's `block`, `binding`, `league`, `left_out` (arguments that named the author's own records) and `needs` (`league` when the reader has none to draw).
- `share` object  
  Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (`artifact`, `url`, `snapshots`, `images`).
- `compare_url` string  
  Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

### 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) · [`artifact_revoked`](/problems/artifact_revoked)

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

{
  "slug": "addc7rz7brr5s5x7k66w"
}
```

```json
{
  "object": "artifact",
  "artifact": {
    "id": "art_zqby83rgre58mgpz19s8",
    "slug": "133vgzvn3n1k63hx2752",
    "url": "https://askkelly.ai/a/133vgzvn3n1k63hx2752",
    "title": "Reading a -110 price (mine)",
    "theme": "wire",
    "mode": "live",
    "version": 1,
    "visibility": "private",
    "author": {
      "display": "A Kelly member"
    },
    "description": "The price most books hang on both sides of a spread.",
    "published_at": null,
    "as_of": "2026-10-04T17:30:00Z",
    "remix_of": "art_hre67fdbqtf9ngbejn9v",
    "template": null,
    "can_edit": true,
    "actions": [
      "remix",
      "ask"
    ],
    "original": {
      "slug": "addc7rz7brr5s5x7k66w",
      "title": "Reading a -110 price",
      "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w"
    },
    "can_reply": false,
    "live": {
      "topics": [],
      "follow_gap_seconds": 3
    }
  },
  "params": [],
  "query": "",
  "blocks": [
    {
      "id": "b1",
      "type": "note",
      "width": 3,
      "text": "The price most books hang on both sides of a spread."
    },
    {
      "id": "b2",
      "type": "tiles",
      "width": 3,
      "tiles": [
        {
          "label": "Summary",
          "display": "Kelly's convert odds on the person's own numbers."
        },
        {
          "label": "Last read",
          "display": "2026-10-04T17:30:00Z"
        },
        {
          "label": "Source",
          "display": "kelly"
        }
      ],
      "problem": null,
      "summary": "Kelly's convert odds on the person's own numbers.",
      "frozen": false
    },
    {
      "id": "b3",
      "type": "ask",
      "width": 3,
      "questions": [
        "What does -110 mean as a probability?"
      ]
    }
  ],
  "since": null,
  "recipe": {
    "kas": 1,
    "title": "Reading a -110 price (mine)",
    "theme": "wire",
    "mode": "live",
    "params": [],
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "width": 3,
        "callouts": [],
        "text": "The price most books hang on both sides of a spread.",
        "questions": []
      },
      {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "source": {
          "tool": "calculate_odds",
          "args": {
            "calc": "convert_odds",
            "prices": [
              "-110"
            ]
          }
        },
        "binding": "public",
        "callouts": [],
        "questions": []
      },
      {
        "id": "b3",
        "type": "ask",
        "width": 3,
        "callouts": [],
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ]
  },
  "versions": 1,
  "remix": {
    "from": {
      "id": "art_hre67fdbqtf9ngbejn9v",
      "slug": "addc7rz7brr5s5x7k66w"
    },
    "controls": "",
    "league": null,
    "blocks": []
  }
}
```

`POST /v1/artifacts:reply`

## Reply to a shared artifact with yours
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `reply_to_artifact` · status live

Answers a shared artifact (by its slug) with your own: a copy on your account opened on the view you send, its parts that read the owner's own data now reading yours, shared at once as a link (or public, listed under the original). Returns it with its link and compare_url, the original and yours side by side. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

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

- `slug` string  
  The original's address (askkelly.ai/a/{slug}).  
  min length 12 · max length 100
- `controls` object  
  The view your reply opens on, as the original's address carries it. Absent: as it was shared.
- `league_id` string  
  Which of your leagues its league parts draw (lg_…).  
  max length 40
- `visibility` string  
  link (only people you send it to; the default) or public (also listed under the original).  
  One of: `link`, `public` (open: new values may be added).  
  default "link"
- `show_author` boolean  
  Show your Kelly name on it.

### Response
`201` Your reply, drawn for you, with its share and the side-by-side link.

- `object` const · required  
  Always `artifact`.  
  Always `"artifact"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `url` string · nullable  
    Its page on askkelly.ai, with this view's controls.
  - `author` object  
    Who made it, as they chose to show it; `display` is always shown.
  - `description` string · nullable  
    Its first note, in plain words.
  - `as_of` string  
    When these blocks were drawn.  
    format date-time
  - `can_edit` boolean  
    Whether the reader may change it (its owner).
  - `actions` array of string  
    What the reader may do: remix, ask, edit, share.
  - `original` object · nullable  
    The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
  - `can_reply` boolean  
    Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
- `params` array of object · required  
  The controls a reader may change, each with its `value`, `display` and `default`.
- `query` string · required  
  This view's controls as an address query, defaults left out.
- `blocks` array of object · required  
  Its blocks, in reading order, drawn for this reader.
  - `id` string · required  
    b1, b2, …
  - `type` string · required  
    The block's type.
  - `width` integer · required  
    Columns of three it spans.  
    One of: `1`, `2`, `3` (open: new values may be added).
  - `problem` string · nullable  
    Why it isn't drawn, or null.
  - `link` string · nullable  
    on_site_only: where it is drawn.
  - `frozen` boolean  
    Kept as its owner shared it.
  - `summary` string · nullable  
    What it shows, in one sentence.
- `recipe` object · required  
  Its recipe: a Kelly Artifact Spec (KAS 1, `registry/contracts/artifacts/kas.schema.json`).
- `versions` integer · required  
  How many versions it has.
- `remix` object  
  Only on Make it yours (remix_artifact): what the copy took from the reader. `from` (the shared artifact's `id` and `slug`), `controls` (the view it opens on, as an address query), `league` (`id` and `name` of the reader's league its league parts draw, or null) and `blocks`: each own-data block's `block`, `binding`, `league`, `left_out` (arguments that named the author's own records) and `needs` (`league` when the reader has none to draw).
- `share` object  
  Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (`artifact`, `url`, `snapshots`, `images`).
- `compare_url` string  
  Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

### 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) · [`artifact_revoked`](/problems/artifact_revoked)

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

{
  "slug": "addc7rz7brr5s5x7k66w"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "That artifact is yours: change it in Kelly, or share it.",
  "param": "slug",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_12b306db86646851f35ad69a",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

`GET /v1/shared-artifacts/{slug}/vs/{other}`

## Compare two shared artifacts
public, no key needed · 0 credits, not charged during the beta · MCP tool `compare_artifacts` · status live

A reply and its original (or two replies to one artifact) drawn side by side, each as its own page draws it, their parts paired. No key needed. Two artifacts that aren't a reply and its original answer not_found. Read here, a part drawn from a tool that carries book prices or links answers problem on_site_only with the page's link, and a chart keeps only the columns its rights allow.

### Parameters
- `slug` string · path · required  
  Its address (askkelly.ai/a/{slug}).  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100
- `other` string · path · required  
  The other artifact's address: a reply to it, its original, or another reply to the same original.  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

### Response
`200` The two, side by side.

- `object` const · required  
  Always `artifact_compare`.  
  Always `"artifact_compare"`.
- `url` string · required  
  The side-by-side page on askkelly.ai.
- `left` object · required  
  A shared artifact drawn for whoever reads it: public blocks drawn now, the owner's own blocks as they shared them, never whose data it is beyond what they chose to show.
  - `artifact` object · required  
    The artifact.
    - `id` string  
      Its ID (art_…).
    - `slug` string · nullable  
      Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
    - `title` string  
      Its title, the person's own words.
    - `mode` string  
      live: drawn now each time it opens; frozen: kept as it was when shared.  
      One of: `live`, `frozen` (open: new values may be added).
    - `visibility` string  
      Who may open its link.  
      One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
    - `theme` string  
      Its look.  
      One of: `wire`, `vellum` (open: new values may be added).
    - `version` integer  
      Its current version, from 1.
    - `template` string · nullable  
      The template it was made from, if any.
    - `remix_of` string · nullable  
      The artifact it was remixed from, if any.
    - `published_at` string · nullable  
      When it was first shared.  
      format date-time
    - `url` string · nullable  
      Its page on askkelly.ai, with this view's controls.
    - `author` object  
      Who made it, as they chose to show it; `display` is always shown.
    - `description` string · nullable  
      Its first note, in plain words.
    - `as_of` string  
      When these blocks were drawn.  
      format date-time
    - `can_edit` boolean  
      Whether the reader may change it (its owner).
    - `actions` array of string  
      What the reader may do: remix, ask, edit, share.
    - `original` object · nullable  
      The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
    - `can_reply` boolean  
      Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
  - `params` array of object · required  
    The controls a reader may change, each with its `value`, `display` and `default`.
  - `query` string · required  
    This view's controls as an address query, defaults left out.
  - `blocks` array of object · required  
    Its blocks, in reading order, drawn for this reader.
    - `id` string · required  
      b1, b2, …
    - `type` string · required  
      The block's type.
    - `width` integer · required  
      Columns of three it spans.  
      One of: `1`, `2`, `3` (open: new values may be added).
    - `problem` string · nullable  
      Why it isn't drawn, or null.
    - `link` string · nullable  
      on_site_only: where it is drawn.
    - `frozen` boolean  
      Kept as its owner shared it.
    - `summary` string · nullable  
      What it shows, in one sentence.
- `right` object · required  
  A shared artifact drawn for whoever reads it: public blocks drawn now, the owner's own blocks as they shared them, never whose data it is beyond what they chose to show.
  - `artifact` object · required  
    The artifact.
    - `id` string  
      Its ID (art_…).
    - `slug` string · nullable  
      Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
    - `title` string  
      Its title, the person's own words.
    - `mode` string  
      live: drawn now each time it opens; frozen: kept as it was when shared.  
      One of: `live`, `frozen` (open: new values may be added).
    - `visibility` string  
      Who may open its link.  
      One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
    - `theme` string  
      Its look.  
      One of: `wire`, `vellum` (open: new values may be added).
    - `version` integer  
      Its current version, from 1.
    - `template` string · nullable  
      The template it was made from, if any.
    - `remix_of` string · nullable  
      The artifact it was remixed from, if any.
    - `published_at` string · nullable  
      When it was first shared.  
      format date-time
    - `url` string · nullable  
      Its page on askkelly.ai, with this view's controls.
    - `author` object  
      Who made it, as they chose to show it; `display` is always shown.
    - `description` string · nullable  
      Its first note, in plain words.
    - `as_of` string  
      When these blocks were drawn.  
      format date-time
    - `can_edit` boolean  
      Whether the reader may change it (its owner).
    - `actions` array of string  
      What the reader may do: remix, ask, edit, share.
    - `original` object · nullable  
      The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
    - `can_reply` boolean  
      Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
  - `params` array of object · required  
    The controls a reader may change, each with its `value`, `display` and `default`.
  - `query` string · required  
    This view's controls as an address query, defaults left out.
  - `blocks` array of object · required  
    Its blocks, in reading order, drawn for this reader.
    - `id` string · required  
      b1, b2, …
    - `type` string · required  
      The block's type.
    - `width` integer · required  
      Columns of three it spans.  
      One of: `1`, `2`, `3` (open: new values may be added).
    - `problem` string · nullable  
      Why it isn't drawn, or null.
    - `link` string · nullable  
      on_site_only: where it is drawn.
    - `frozen` boolean  
      Kept as its owner shared it.
    - `summary` string · nullable  
      What it shows, in one sentence.
- `pairs` array of object · required  
  The blocks paired, in reading order (buttons left out).
  - `id` string  
    The block's ID (b1, b2, …).
  - `type` string  
    The block's type.
  - `title` string · nullable  
    Its title.
  - `left` object · nullable  
    The left artifact's block, drawn; null when it has none.
  - `right` object · nullable  
    The right artifact's block, drawn; null when it has none.

### 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) · [`artifact_revoked`](/problems/artifact_revoked)

### Example
```http
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/vs/no-such-artifact-here
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No artifact at that address.",
  "param": null,
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_dcfff17dd02c074ab1face34",
  "retryable": false,
  "display_message": "That could not be found."
}
```

```http
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/vs/133vgzvn3n1k63hx2752
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "artifact_compare",
  "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/vs/133vgzvn3n1k63hx2752",
  "left": {
    "artifact": {
      "id": "art_hre67fdbqtf9ngbejn9v",
      "slug": "addc7rz7brr5s5x7k66w",
      "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w",
      "title": "Reading a -110 price",
      "theme": "wire",
      "mode": "live",
      "version": 2,
      "visibility": "link",
      "author": {
        "display": "A Kelly member"
      },
      "description": "The price most books hang on both sides of a spread.",
      "published_at": "2026-10-04T17:30:00Z",
      "as_of": "2026-10-04T17:30:00Z",
      "remix_of": null,
      "template": null,
      "can_edit": true,
      "actions": [
        "remix",
        "ask"
      ],
      "original": null,
      "can_reply": false,
      "live": {
        "topics": [],
        "follow_gap_seconds": 3
      }
    },
    "params": [],
    "query": "",
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "width": 3,
        "text": "The price most books hang on both sides of a spread."
      },
      {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "tiles": [
          {
            "label": "Summary",
            "display": "Kelly's convert odds on the person's own numbers."
          },
          {
            "label": "Last read",
            "display": "2026-10-04T17:30:00Z"
          },
          {
            "label": "Source",
            "display": "kelly"
          }
        ],
        "problem": null,
        "summary": "Kelly's convert odds on the person's own numbers.",
        "frozen": false
      },
      {
        "id": "b3",
        "type": "ask",
        "width": 3,
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ],
    "since": {
      "shared_at": "2026-10-04T17:30:00Z",
      "changes": []
    }
  },
  "right": {
    "artifact": {
      "id": "art_zqby83rgre58mgpz19s8",
      "slug": "133vgzvn3n1k63hx2752",
      "url": "https://askkelly.ai/a/133vgzvn3n1k63hx2752",
      "title": "Reading a -110 price (mine)",
      "theme": "wire",
      "mode": "live",
      "version": 1,
      "visibility": "private",
      "author": {
        "display": "A Kelly member"
      },
      "description": "The price most books hang on both sides of a spread.",
      "published_at": null,
      "as_of": "2026-10-04T17:30:00Z",
      "remix_of": "art_hre67fdbqtf9ngbejn9v",
      "template": null,
      "can_edit": true,
      "actions": [
        "remix",
        "ask"
      ],
      "original": {
        "slug": "addc7rz7brr5s5x7k66w",
        "title": "Reading a -110 price",
        "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w"
      },
      "can_reply": false,
      "live": {
        "topics": [],
        "follow_gap_seconds": 3
      }
    },
    "params": [],
    "query": "",
    "blocks": [
      {
        "id": "b1",
        "type": "note",
        "width": 3,
        "text": "The price most books hang on both sides of a spread."
      },
      {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "tiles": [
          {
            "label": "Summary",
            "display": "Kelly's convert odds on the person's own numbers."
          },
          {
            "label": "Last read",
            "display": "2026-10-04T17:30:00Z"
          },
          {
            "label": "Source",
            "display": "kelly"
          }
        ],
        "problem": null,
        "summary": "Kelly's convert odds on the person's own numbers.",
        "frozen": false
      },
      {
        "id": "b3",
        "type": "ask",
        "width": 3,
        "questions": [
          "What does -110 mean as a probability?"
        ]
      }
    ],
    "since": null
  },
  "pairs": [
    {
      "id": "b1",
      "type": "note",
      "title": null,
      "left": {
        "id": "b1",
        "type": "note",
        "width": 3,
        "text": "The price most books hang on both sides of a spread."
      },
      "right": {
        "id": "b1",
        "type": "note",
        "width": 3,
        "text": "The price most books hang on both sides of a spread."
      }
    },
    {
      "id": "b2",
      "type": "tiles",
      "title": null,
      "left": {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "tiles": [
          {
            "label": "Summary",
            "display": "Kelly's convert odds on the person's own numbers."
          },
          {
            "label": "Last read",
            "display": "2026-10-04T17:30:00Z"
          },
          {
            "label": "Source",
            "display": "kelly"
          }
        ],
        "problem": null,
        "summary": "Kelly's convert odds on the person's own numbers.",
        "frozen": false
      },
      "right": {
        "id": "b2",
        "type": "tiles",
        "width": 3,
        "tiles": [
          {
            "label": "Summary",
            "display": "Kelly's convert odds on the person's own numbers."
          },
          {
            "label": "Last read",
            "display": "2026-10-04T17:30:00Z"
          },
          {
            "label": "Source",
            "display": "kelly"
          }
        ],
        "problem": null,
        "summary": "Kelly's convert odds on the person's own numbers.",
        "frozen": false
      }
    }
  ]
}
```

`GET /v1/shared-artifacts/{slug}/replies`

## List a shared artifact's replies
public, no key needed · 0 credits, not charged during the beta · MCP tool `list_artifact_replies` · status live

A shared artifact's public replies, newest first: each one's title, address, author as they chose to show it and side-by-side address. Replies shared by link only are never listed. No key needed.

### Parameters
- `slug` string · path · required  
  Its address (askkelly.ai/a/{slug}).  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

- `limit` integer · query  
  Replies per page, 1 to 50.  
  min 1 · max 50 · default 20
- `cursor` string · query  
  The next_cursor of the page before.  
  max length 80

### Response
`200` Its public replies.

- `object` const · required  
  Always `artifact_reply_list`.  
  Always `"artifact_reply_list"`.
- `slug` string · required  
  The original's address.
- `replies` array of object · required  
  The replies.
  - `slug` string  
    Its address.
  - `title` string  
    Its title.
  - `url` string  
    Its page on askkelly.ai.
  - `author` object  
    Who made it, as they chose to show it.
  - `published_at` string  
    When it was shared.  
    format date-time
  - `compare_url` string  
    It and the original, side by side.
- `total` integer · required  
  How many public replies it has.
- `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) · [`not_found`](/problems/not_found) · [`artifact_revoked`](/problems/artifact_revoked)

### Example
```http
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/replies
```

```json
{
  "object": "artifact_reply_list",
  "slug": "addc7rz7brr5s5x7k66w",
  "replies": [],
  "total": 0,
  "next_cursor": null
}
```

`GET /v1/shared-artifacts/{slug}`

## Get a shared artifact
public, no key needed · 0 credits, not charged during the beta · MCP tool `get_shared_artifact` · status live

A shared artifact by its address, drawn now: its controls (set them in the query by their ids), each part's chart, table, tiles or card, and the owner's parts as they shared them. No key needed. A link its owner turned off answers artifact_revoked. Read here, a part drawn from a tool that carries book prices or links answers problem on_site_only with the page's link, and a chart keeps only the columns its rights allow.

### Parameters
- `slug` string · path · required  
  Its address (askkelly.ai/a/{slug}).  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

- `controls` object · query  
  The artifact's controls by their IDs, as its page's address carries them (`player=plr_…`, `weeks=5-10`); a block's view by `b1.t=1`. Absent: each default.

### Response
`200` The artifact, drawn for whoever asks.

- `object` const · required  
  Always `artifact`.  
  Always `"artifact"`.
- `artifact` object · required  
  The artifact.
  - `id` string  
    Its ID (art_…).
  - `slug` string · nullable  
    Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
  - `title` string  
    Its title, the person's own words.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `visibility` string  
    Who may open its link.  
    One of: `private`, `link`, `public`, `people`, `project`, `league` (open: new values may be added).
  - `theme` string  
    Its look.  
    One of: `wire`, `vellum` (open: new values may be added).
  - `version` integer  
    Its current version, from 1.
  - `template` string · nullable  
    The template it was made from, if any.
  - `remix_of` string · nullable  
    The artifact it was remixed from, if any.
  - `published_at` string · nullable  
    When it was first shared.  
    format date-time
  - `url` string · nullable  
    Its page on askkelly.ai, with this view's controls.
  - `author` object  
    Who made it, as they chose to show it; `display` is always shown.
  - `description` string · nullable  
    Its first note, in plain words.
  - `as_of` string  
    When these blocks were drawn.  
    format date-time
  - `can_edit` boolean  
    Whether the reader may change it (its owner).
  - `actions` array of string  
    What the reader may do: remix, ask, edit, share.
  - `original` object · nullable  
    The shared artifact this one was made from (`slug`, `title`, `url`), when anyone may open it; else null (C4, ADR-K899).
  - `can_reply` boolean  
    Whether a reader may answer it with their own (reply_to_artifact): it is shared and has a control or its owner's own data.
- `params` array of object · required  
  The controls a reader may change, each with its `value`, `display` and `default`.
- `query` string · required  
  This view's controls as an address query, defaults left out.
- `blocks` array of object · required  
  Its blocks, in reading order, drawn for this reader.
  - `id` string · required  
    b1, b2, …
  - `type` string · required  
    The block's type.
  - `width` integer · required  
    Columns of three it spans.  
    One of: `1`, `2`, `3` (open: new values may be added).
  - `problem` string · nullable  
    Why it isn't drawn, or null.
  - `link` string · nullable  
    on_site_only: where it is drawn.
  - `frozen` boolean  
    Kept as its owner shared it.
  - `summary` string · nullable  
    What it shows, in one sentence.

### 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) · [`artifact_revoked`](/problems/artifact_revoked)

### Example
```http
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w
```

```json
{
  "object": "artifact",
  "artifact": {
    "id": "art_hre67fdbqtf9ngbejn9v",
    "slug": "addc7rz7brr5s5x7k66w",
    "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w",
    "title": "Reading a -110 price",
    "theme": "wire",
    "mode": "live",
    "version": 2,
    "visibility": "link",
    "author": {
      "display": "A Kelly member"
    },
    "description": "The price most books hang on both sides of a spread.",
    "published_at": "2026-10-04T17:30:00Z",
    "as_of": "2026-10-04T17:30:00Z",
    "remix_of": null,
    "template": null,
    "can_edit": false,
    "actions": [
      "remix",
      "ask"
    ],
    "original": null,
    "can_reply": false,
    "live": {
      "topics": [],
      "follow_gap_seconds": 15
    }
  },
  "params": [],
  "query": "",
  "blocks": [
    {
      "id": "b1",
      "type": "note",
      "width": 3,
      "text": "The price most books hang on both sides of a spread."
    },
    {
      "id": "b2",
      "type": "tiles",
      "width": 3,
      "tiles": [
        {
          "label": "Summary",
          "display": "Kelly's convert odds on the person's own numbers."
        },
        {
          "label": "Last read",
          "display": "2026-10-04T17:30:00Z"
        },
        {
          "label": "Source",
          "display": "kelly"
        }
      ],
      "problem": null,
      "summary": "Kelly's convert odds on the person's own numbers.",
      "frozen": false
    },
    {
      "id": "b3",
      "type": "ask",
      "width": 3,
      "questions": [
        "What does -110 mean as a probability?"
      ]
    }
  ],
  "since": {
    "shared_at": "2026-10-04T17:30:00Z",
    "changes": []
  }
}
```

```http
GET https://api.askkelly.ai/v1/shared-artifacts/no-such-artifact-here
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No artifact at that address.",
  "param": null,
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_1a23d671347a4b8c8d790a06",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`GET /v1/artifact-templates`

## List the artifact templates
public, no key needed · 0 credits, not charged during the beta · MCP tool `list_artifact_templates` · status live

Kelly's artifact templates (a weekly league recap with awards, a league's playoff and title odds, a monthly betting Wrapped): what each holds and whether it is live or frozen. With your key, each says whether it can open for you now (else why) and the choices its inputs take (your leagues); make one with POST /v1/artifacts and template. No key needed.

### Response
`200` The templates; with your key, which open now and your choices.

- `object` const · required  
  Always `artifact_template_list`.  
  Always `"artifact_template_list"`.
- `templates` array of object · required  
  The templates.
  - `id` string  
    Its ID, for `template`.
  - `name` string  
    Its name.
  - `group` string  
    fantasy or general.  
    One of: `fantasy`, `general` (open: new values may be added).
  - `about` string  
    What it shows.
  - `mode` string  
    live: drawn now each time it opens; frozen: kept as it was when shared.  
    One of: `live`, `frozen` (open: new values may be added).
  - `parts` array of string  
    What it holds, in reading order.
  - `needs` string · nullable  
    What of yours it draws: league, bets or nothing.  
    One of: `league`, `bets` (open: new values may be added).
  - `ready` boolean  
    Whether it can open for you now.
  - `problem` string · nullable  
    Why not, in words, when it can't.
  - `inputs` array of object  
    What it asks for; each is optional.
    - `id` string  
      Its key in `inputs`.
    - `type` string  
      What it is.  
      One of: `league`, `team`, `month` (open: new values may be added).
    - `label` string  
      Its name.
    - `about` string  
      What it does.
    - `choices` array of object  
      Your choices (signed in), when it takes one of a list.
      - `value` string  
        What to send (lg_… for a league).
      - `label` string  
        Its name.
- `total` integer · required  
  How many there are.

### 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/artifact-templates
```

```json
{
  "object": "artifact_template_list",
  "templates": [
    {
      "id": "league_recap",
      "name": "Weekly league recap",
      "group": "fantasy",
      "about": "The week in your league: every game with its top starters, the week's awards, the table after it, the season's awards so far and the playoff race. Frozen when you share it, so it stays that week's recap.",
      "mode": "frozen",
      "parts": [
        "The week's games and awards",
        "Season awards so far",
        "The playoff race",
        "Questions to ask",
        "Claim your team"
      ],
      "needs": "league",
      "ready": false,
      "problem": "Sign in to make it with your own data.",
      "inputs": [
        {
          "id": "league",
          "type": "league",
          "label": "League",
          "about": "One of your connected leagues (lg_…); default the one synced last."
        }
      ]
    },
    {
      "id": "playoff_odds",
      "name": "Playoff and title odds",
      "group": "fantasy",
      "about": "Your league's playoff race from 10,000 simulated rest-of-seasons: your chances of the playoffs, a bye and the title, each seed, odds by week, who to root for, then everyone's odds and the power ratings. Live: it redraws each time it opens.",
      "mode": "live",
      "parts": [
        "Playoff and title odds",
        "Power ratings",
        "Questions to ask",
        "Claim your team"
      ],
      "needs": "league",
      "ready": false,
      "problem": "Sign in to make it with your own data.",
      "inputs": [
        {
          "id": "league",
          "type": "league",
          "label": "League",
          "about": "One of your connected leagues (lg_…); default the one synced last."
        }
      ]
    },
    {
      "id": "monthly_wrapped",
      "name": "Monthly Wrapped",
      "group": "general",
      "about": "One month of your betting in units, never money: the record, profit over the month, the rolling return and how each sport went. Frozen when you share it.",
      "mode": "frozen",
      "parts": [
        "The month in units",
        "Profit over the month",
        "Rolling return",
        "By sport",
        "Questions to ask"
      ],
      "needs": "bets",
      "ready": false,
      "problem": "Sign in to make it with your own data.",
      "inputs": [
        {
          "id": "month",
          "type": "month",
          "label": "Month",
          "about": "A month as YYYY-MM; default this month (last month in a month's first week)."
        }
      ]
    }
  ],
  "total": 3
}
```

`GET /v1/shared-artifacts/{slug}/tail`

## Get a shared artifact's bets to tail
public, no key needed · 0 credits, not charged during the beta · MCP tool `get_artifact_tail` · status live

The bets a shared artifact offers to tail: the sharer's open bets as they shared them and the bets its public parts name, leg by leg, at Kelly's consensus price and line with the no-vig chance and the fair price. College player props are never tailed. The prices at your own books and the bet links are on its askkelly.ai Tail page (tail_url). No key needed. A link its owner turned off answers artifact_revoked; an artifact with no Tail answers not_found.

### Parameters
- `slug` string · path · required  
  Its address (askkelly.ai/a/{slug}).  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

### Response
`200` Its bets to tail, at Kelly's consensus.

- `object` const · required  
  Always `artifact_tail`.  
  Always `"artifact_tail"`.
- `artifact` object · required  
  The artifact: `id`, `slug`, `title`, `url`, `version`.
- `tail_url` string · required  
  Its Tail page on askkelly.ai.
- `next` string · nullable  
  What the reader does next: `tail_page` off askkelly.ai.
- `priced` boolean  
  Whether book prices are in this read (never off askkelly.ai).
- `kept_at` string · nullable  
  When the sharer's bets were kept (at share).  
  format date-time
- `viewer` object  
  Who is reading: `signed_in`, `attested`, `books_set`.
- `bets` array of object · required  
  The bets, the sharer's first, at most 10.
  - `key` string  
    t1, t2, …
  - `kind` string  
    single or parlay.
  - `source` string  
    shared or public.  
    One of: `shared`, `public` (open: new values may be added).
  - `shared_price` object · nullable  
    A price: `american` and `decimal`.
    - `american` number  
      American odds.
    - `decimal` number  
      Decimal odds.
  - `tailable` boolean  
    Whether every leg can be tailed now.
  - `legs` array of object  
    Its legs, in order.
    - `label` string · nullable  
      What the leg is on.
    - `market_id` string · nullable  
      Kelly's market (mkt_…).
    - `selection_id` string · nullable  
      Kelly's selection (sel_…).
    - `line` number · nullable  
      The leg's line.
    - `consensus_price` number · nullable  
      Kelly's consensus decimal price.
    - `consensus_point` number · nullable  
      The consensus line for this side.
    - `no_vig_prob` number · nullable  
      The no-vig chance at the leg's line.
    - `fair_price` object · nullable  
      A price: `american` and `decimal`.
      - `american` number  
        American odds.
      - `decimal` number  
        Decimal odds.
    - `shared_price` object · nullable  
      A price: `american` and `decimal`.
      - `american` number  
        American odds.
      - `decimal` number  
        Decimal odds.
    - `starts_at` string · nullable  
      When its game starts.  
      format date-time
    - `problem` string · nullable  
      Why it can't be tailed, or null.  
      One of: `college_prop`, `no_market`, `closed`, `unpriced` (open: new values may be added).
    - `problem_detail` string · nullable  
      The problem in words.
  - `combined` object · nullable  
    A parlay's legs together at the consensus (`markets.bet_slip`), or null.
- `helpline` object · nullable  
  On askkelly.ai only; null here.
- `as_of` string  
  When this was read.  
  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) · [`not_found`](/problems/not_found) · [`artifact_revoked`](/problems/artifact_revoked)

### Example
```http
GET https://api.askkelly.ai/v1/shared-artifacts/6j60fp1ywvnwpbp5nrjf/tail
```

```json
{
  "object": "artifact_tail",
  "artifact": {
    "id": "art_vv011xck2jc417pkgrqw",
    "slug": "6j60fp1ywvnwpbp5nrjf",
    "title": "Chiefs at Raiders: my card",
    "url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf",
    "version": 1
  },
  "tail_url": "https://askkelly.ai/a/6j60fp1ywvnwpbp5nrjf/tail",
  "viewer": {
    "signed_in": false,
    "attested": false,
    "books_set": false
  },
  "next": "tail_page",
  "priced": false,
  "kept_at": "2026-10-04T17:30:00Z",
  "bets": [
    {
      "key": "t1",
      "kind": "single",
      "source": "public",
      "block": "b1",
      "shared_price": null,
      "placed_at": null,
      "tailable": false,
      "legs": [
        {
          "label": null,
          "starts_at": null,
          "shared_price": null,
          "problem": "closed",
          "problem_detail": "This market is closed or no longer offered."
        }
      ],
      "combined": null,
      "slip": null
    },
    {
      "key": "t2",
      "kind": "parlay",
      "source": "public",
      "block": "b2",
      "shared_price": null,
      "placed_at": null,
      "tailable": false,
      "legs": [
        {
          "label": null,
          "starts_at": null,
          "shared_price": null,
          "problem": "no_market",
          "problem_detail": "This leg was logged in words only, so Kelly can't price it."
        },
        {
          "label": null,
          "starts_at": null,
          "shared_price": null,
          "problem": "no_market",
          "problem_detail": "This leg was logged in words only, so Kelly can't price it."
        }
      ],
      "combined": null,
      "slip": null
    }
  ],
  "helpline": null,
  "as_of": "2026-10-04T17:30:00Z"
}
```

```http
GET https://api.askkelly.ai/v1/shared-artifacts/no-such-artifact-here/tail
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No artifact at that address.",
  "param": null,
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_f44fbe0a76cf7f66a1971853",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`GET /v1/me/share-moments`

## Your prepared moments
scope `read:artifacts` · 0 credits, not charged during the beta · MCP tool `get_my_share_moments` · status live

The artifacts Kelly drafted for you at moments worth sharing, newest first: what happened, the draft's ID and its link on askkelly.ai, whether it was e-mailed or waved away; how many are waiting; and the switch per kind: bet_graded (a bet of yours won), bad_beat (one lost narrowly), weekly_recap (Tuesday's recap of each league you connected) and trade_accepted (a trade of yours went through). Every kind is on until you turn it off.

### Parameters
- `limit` integer · query  
  Moments, 1 to 50.  
  min 1 · max 50 · default 20

### Response
`200` Your prepared moments and switches.

- `object` const · required  
  Always `share_moments`.  
  Always `"share_moments"`.
- `moments` array of object · required  
  Newest first.
  - `object` const  
    Always `share_moment`.  
    Always `"share_moment"`.
  - `id` string  
    Its ID (smo_…).
  - `kind` string  
    What happened.  
    One of: `bet_graded`, `bad_beat`, `weekly_recap`, `trade_accepted` (open: new values may be added).
  - `label` string  
    The kind in words.
  - `state` string  
    offered, or dismissed when you waved it away.  
    One of: `offered`, `dismissed` (open: new values may be added).
  - `words` string · nullable  
    What happened, in a sentence; never a price, a stake or an edge.
  - `artifact_id` string · nullable  
    The draft (art_…), private until you share it; null if deleted.
  - `path` string · nullable  
    Where the draft opens on askkelly.ai.
  - `made_at` string  
    When Kelly made it.  
    format date-time
  - `emailed` boolean  
    Whether it was e-mailed to you.
  - `dismissed_at` string · nullable  
    When you waved it away.  
    format date-time
- `waiting` integer · required  
  How many offered drafts you haven't waved away.
- `switches` array of object · required  
  Every kind, on or off.
  - `kind` string  
    The kind.  
    One of: `bet_graded`, `bad_beat`, `weekly_recap`, `trade_accepted` (open: new values may be added).
  - `label` string  
    It in words.
  - `on` boolean  
    Whether Kelly drafts and offers 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/me/share-moments
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "share_moments",
  "moments": [],
  "waiting": 0,
  "switches": [
    {
      "kind": "bet_graded",
      "label": "A bet of yours wins",
      "on": true
    },
    {
      "kind": "bad_beat",
      "label": "A bad beat",
      "on": true
    },
    {
      "kind": "weekly_recap",
      "label": "Tuesday's league recap",
      "on": true
    },
    {
      "kind": "trade_accepted",
      "label": "A trade of yours goes through",
      "on": true
    }
  ]
}
```

`PATCH /v1/me/share-moments`

## Turn prepared moments on or off
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `set_my_share_moments` · status live

Turns kinds of prepared moments on or off: switches maps a kind to true or false (bet_graded (a bet of yours won), bad_beat (one lost narrowly), weekly_recap (Tuesday's recap of each league you connected) and trade_accepted (a trade of yours went through)). Answers as the read does. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

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

- `switches` object  
  A kind and true or false.
  - `bet_graded` boolean  
    A bet of yours won.
  - `bad_beat` boolean  
    A bet of yours lost narrowly.
  - `weekly_recap` boolean  
    Tuesday's recap of each league you connected.
  - `trade_accepted` boolean  
    A trade of yours went through.

### Response
`200` Your prepared moments and switches after the change.

- `object` const · required  
  Always `share_moments`.  
  Always `"share_moments"`.
- `moments` array of object · required  
  Newest first.
  - `object` const  
    Always `share_moment`.  
    Always `"share_moment"`.
  - `id` string  
    Its ID (smo_…).
  - `kind` string  
    What happened.  
    One of: `bet_graded`, `bad_beat`, `weekly_recap`, `trade_accepted` (open: new values may be added).
  - `label` string  
    The kind in words.
  - `state` string  
    offered, or dismissed when you waved it away.  
    One of: `offered`, `dismissed` (open: new values may be added).
  - `words` string · nullable  
    What happened, in a sentence; never a price, a stake or an edge.
  - `artifact_id` string · nullable  
    The draft (art_…), private until you share it; null if deleted.
  - `path` string · nullable  
    Where the draft opens on askkelly.ai.
  - `made_at` string  
    When Kelly made it.  
    format date-time
  - `emailed` boolean  
    Whether it was e-mailed to you.
  - `dismissed_at` string · nullable  
    When you waved it away.  
    format date-time
- `waiting` integer · required  
  How many offered drafts you haven't waved away.
- `switches` array of object · required  
  Every kind, on or off.
  - `kind` string  
    The kind.  
    One of: `bet_graded`, `bad_beat`, `weekly_recap`, `trade_accepted` (open: new values may be added).
  - `label` string  
    It in words.
  - `on` boolean  
    Whether Kelly drafts and offers 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) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found)

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

{
  "switches": {
    "bad_beat": false
  }
}
```

```json
{
  "object": "share_moments",
  "moments": [],
  "waiting": 0,
  "switches": [
    {
      "kind": "bet_graded",
      "label": "A bet of yours wins",
      "on": true
    },
    {
      "kind": "bad_beat",
      "label": "A bad beat",
      "on": false
    },
    {
      "kind": "weekly_recap",
      "label": "Tuesday's league recap",
      "on": true
    },
    {
      "kind": "trade_accepted",
      "label": "A trade of yours goes through",
      "on": true
    }
  ]
}
```

```http
PATCH https://api.askkelly.ai/v1/me/share-moments
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "switches": {
    "big_win": true
  }
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "big_win: one of bet_graded, bad_beat, weekly_recap, trade_accepted.",
  "param": "big_win",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_b847b6948211e1461d317341",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

`GET /v1/shared-artifacts/{slug}/render`

## Get an artifact's pictures
public, no key needed · 0 credits, not charged during the beta · MCP tool `render_artifact` · status live

The addresses of a shared artifact's pictures for this view (link 1200x630, square 1080, story 1080x1920) and of its plain text, ready to post. No key needed.

### Parameters
- `slug` string · path · required  
  Its address (askkelly.ai/a/{slug}).  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

- `controls` object · query  
  The artifact's controls by their IDs, as its page's address carries them (`player=plr_…`, `weeks=5-10`); a block's view by `b1.t=1`. Absent: each default.

### Response
`200` Its pictures and text for this view.

- `object` const · required  
  Always `artifact_render`.  
  Always `"artifact_render"`.
- `slug` string · required  
  Its address.
- `url` string · required  
  Its page on askkelly.ai, with this view.
- `images` object · required  
  Its pictures by format: link (1200×630), square (1080×1080), story (1080×1920).
  - `link` object  
    One picture.
    - `url` string  
      The PNG's address.
    - `width` integer  
      Pixels wide.
    - `height` integer  
      Pixels high.
  - `square` object  
    One picture.
    - `url` string  
      The PNG's address.
    - `width` integer  
      Pixels wide.
    - `height` integer  
      Pixels high.
  - `story` object  
    One picture.
    - `url` string  
      The PNG's address.
    - `width` integer  
      Pixels wide.
    - `height` integer  
      Pixels high.
- `text_url` string · required  
  Its plain text, for a reader that can't see pictures.

### 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) · [`artifact_revoked`](/problems/artifact_revoked)

### Example
```http
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/render
```

```json
{
  "object": "artifact_render",
  "slug": "addc7rz7brr5s5x7k66w",
  "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w",
  "images": {
    "link": {
      "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/image/link",
      "width": 1200,
      "height": 630
    },
    "square": {
      "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/image/square",
      "width": 1080,
      "height": 1080
    },
    "story": {
      "url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/image/story",
      "width": 1080,
      "height": 1920
    }
  },
  "text_url": "https://askkelly.ai/a/addc7rz7brr5s5x7k66w/text"
}
```

`POST /v1/shared-artifacts/{slug}/report`

## Report a shared artifact
public, no key needed · 0 credits, not charged during the beta · MCP tool `report_artifact` · status live

Tells Kelly a shared artifact breaks the rules: reason spam, abuse, private_info, wrong, illegal or other, and an optional note up to 500 characters. Kelly's staff read every report; once enough separate people report one, it is held until they look. No key needed; 10 reports a day from one address.

### Parameters
- `slug` string · path · required  
  Its address (askkelly.ai/a/{slug}).  
  pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

Body, `application/json` (required):

- `reason` string  
  What is wrong with it.  
  One of: `spam`, `abuse`, `private_info`, `wrong`, `illegal`, `other` (open: new values may be added).
- `note` string  
  Anything staff should know.  
  min length 1 · max length 500

### Response
`200` Kelly has your report.

- `object` const · required  
  Always `artifact_report`.  
  Always `"artifact_report"`.
- `slug` string · required  
  The artifact you reported.
- `received` 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) · [`not_found`](/problems/not_found) · [`payload_too_large`](/problems/payload_too_large) · [`artifact_revoked`](/problems/artifact_revoked) · [`artifact_removed`](/problems/artifact_removed)

### Example
```http
POST https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/report
Content-Type: application/json

{
  "reason": "boring"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "reason: one of spam, abuse, private_info, wrong, illegal, other.",
  "param": "reason",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_25eb15a8fc8cf460a73c4f86",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

```http
POST https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/report
Content-Type: application/json

{
  "reason": "spam",
  "note": "Posted the same page ten times."
}
```

```json
{
  "object": "artifact_report",
  "slug": "addc7rz7brr5s5x7k66w",
  "received": true
}
```

`GET /v1/me/handle`

## Get your public handle
scope `read:artifacts` · 0 credits, not charged during the beta · MCP tool `get_my_handle` · status live

The public name your shared artifacts are signed with (@handle, and a display name), or null; when Kelly's staff cleared your handle, which one. Without a handle, or when a share doesn't show its author, the artifact reads "A Kelly member".

### Response
`200` Your public handle, or null.

- `object` const · required  
  Always `public_handle`.  
  Always `"public_handle"`.
- `handle` object · required · nullable  
  Your handle, or null when you have none (your artifacts read "A Kelly member").
  - `handle` string  
    The handle without its @: 3 to 20 of a-z, 0-9 and _.  
    pattern ^[a-z0-9_]{3,20}$
  - `display` string  
    The name a reader sees: your display name, else @handle.
  - `display_name` string · nullable  
    Your display name, if you set one.
  - `created_at` string  
    When you took it.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `cleared` string · required · nullable  
  A handle Kelly's staff took from you, if they did.
- `hold_days` integer · required  
  Days a handle you give up stays yours to take back.

### 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/me/handle
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "public_handle",
  "handle": {
    "handle": "sharp_side",
    "display": "Sharp Side",
    "display_name": "Sharp Side",
    "created_at": "2026-10-04T17:30:00Z",
    "updated_at": "2026-10-04T17:30:00Z"
  },
  "cleared": null,
  "hold_days": 30
}
```

```http
GET https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "public_handle",
  "handle": null,
  "cleared": null,
  "hold_days": 30
}
```

`PUT /v1/me/handle`

## Set your public handle
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `set_my_handle` · status live

Takes or changes your public handle: 3 to 20 of a-z, 0-9 and _, never one that names Kelly, staff, a book, a league or a platform, plus an optional display name up to 40 characters. A handle someone else has, or gave up in the last 30 days, answers conflict. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

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

- `handle` string  
  3 to 20 of a-z, 0-9 and _ (a leading @ is dropped; kept lower case).  
  min length 3 · max length 21
- `display` string · nullable  
  The name readers see, up to 40 characters; null or absent shows @handle.  
  max length 40

### Response
`200` Your public handle as it now is.

- `object` const · required  
  Always `public_handle`.  
  Always `"public_handle"`.
- `handle` object · required · nullable  
  Your handle, or null when you have none (your artifacts read "A Kelly member").
  - `handle` string  
    The handle without its @: 3 to 20 of a-z, 0-9 and _.  
    pattern ^[a-z0-9_]{3,20}$
  - `display` string  
    The name a reader sees: your display name, else @handle.
  - `display_name` string · nullable  
    Your display name, if you set one.
  - `created_at` string  
    When you took it.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `cleared` string · required · nullable  
  A handle Kelly's staff took from you, if they did.
- `hold_days` integer · required  
  Days a handle you give up stays yours to take back.

### 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
PUT https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "handle": "kelly_official"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "That handle is kept for Kelly or a name people would mistake for an official one.",
  "param": "handle",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_1207c34fdcf1a2a1ad88783b",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

```http
PUT https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "handle": "sharp_side",
  "display": "Sharp Side"
}
```

```json
{
  "object": "public_handle",
  "handle": {
    "handle": "sharp_side",
    "display": "Sharp Side",
    "display_name": "Sharp Side",
    "created_at": "2026-10-04T17:30:00Z",
    "updated_at": "2026-10-04T17:30:00Z"
  },
  "cleared": null,
  "hold_days": 30
}
```

`DELETE /v1/me/handle`

## Give up your public handle
scope `write:artifacts` · 0 credits, not charged during the beta · MCP tool `remove_my_handle` · status live

Drops your public handle: every artifact you shared then reads "A Kelly member". Only you can take it back in the next 30 days. Needs your own live API key with write:artifacts; an AI app makes and changes artifacts through Kelly MCP.

### Response
`200` No handle: your artifacts read "A Kelly member".

- `object` const · required  
  Always `public_handle`.  
  Always `"public_handle"`.
- `handle` object · required · nullable  
  Your handle, or null when you have none (your artifacts read "A Kelly member").
  - `handle` string  
    The handle without its @: 3 to 20 of a-z, 0-9 and _.  
    pattern ^[a-z0-9_]{3,20}$
  - `display` string  
    The name a reader sees: your display name, else @handle.
  - `display_name` string · nullable  
    Your display name, if you set one.
  - `created_at` string  
    When you took it.  
    format date-time
  - `updated_at` string  
    When it last changed.  
    format date-time
- `cleared` string · required · nullable  
  A handle Kelly's staff took from you, if they did.
- `hold_days` integer · required  
  Days a handle you give up stays yours to take back.

### 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
DELETE https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "public_handle",
  "handle": null,
  "cleared": null,
  "hold_days": 30
}
```

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
