Skip to content
Kellydocs
Kellydocs

artifacts

Copy page

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

On this page
MethodPathTitleAccessPriceMCP tool
GET/v1/artifactsList your artifactsread:artifacts0list_my_artifacts
POST/v1/artifactsMake an artifactwrite:artifacts0create_artifact
GET/v1/artifacts/{artifact_id}Get one of your artifactsread:artifacts0get_artifact
PATCH/v1/artifacts/{artifact_id}Change an artifactwrite:artifacts0update_artifact
POST/v1/artifacts/{artifact_id}:shareShare an artifactwrite:artifacts0share_artifact
POST/v1/artifacts:remixMake a shared artifact yourswrite:artifacts0remix_artifact
POST/v1/artifacts:replyReply to a shared artifact with yourswrite:artifacts0reply_to_artifact
GET/v1/shared-artifacts/{slug}/vs/{other}Compare two shared artifactspublic0compare_artifacts
GET/v1/shared-artifacts/{slug}/repliesList a shared artifact's repliespublic0list_artifact_replies
GET/v1/shared-artifacts/{slug}Get a shared artifactpublic0get_shared_artifact
GET/v1/artifact-templatesList the artifact templatespublic0list_artifact_templates
GET/v1/shared-artifacts/{slug}/tailGet a shared artifact's bets to tailpublic0get_artifact_tail
GET/v1/me/share-momentsYour prepared momentsread:artifacts0get_my_share_moments
PATCH/v1/me/share-momentsTurn prepared moments on or offwrite:artifacts0set_my_share_moments
GET/v1/shared-artifacts/{slug}/renderGet an artifact's picturespublic0render_artifact
POST/v1/shared-artifacts/{slug}/reportReport a shared artifactpublic0report_artifact
GET/v1/me/handleGet your public handleread:artifacts0get_my_handle
PUT/v1/me/handleSet your public handlewrite:artifacts0set_my_handle
DELETE/v1/me/handleGive up your public handlewrite:artifacts0remove_my_handle

GET /v1/artifacts

List your artifactsLink to this section

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.

ParametersLink to this section

project_idstring · query

Only this project's artifacts.

max length 64

limitinteger · query

Artifacts per page, 1 to 50.

min 1 · max 50 · default 25

cursorstring · query

The next_cursor of the page before.

max length 200

ResponseLink to this section

200 A page of your artifacts.

objectconstrequired

Always artifact_list.

Always "artifact_list".

artifactsarray of objectrequired

The artifacts, most recently changed first.

Show 15 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

project_idstringnullable

The project it belongs to, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

created_atstring

When it was made.

format date-time

updated_atstring

When it last changed.

format date-time

published_atstringnullable

When it was first shared.

format date-time

revokedboolean

Whether its owner turned its link off.

blocksinteger

How many blocks it has.

totalintegerrequired

How many artifacts you have (in this project, when asked).

next_cursorstringrequirednullable

Pass as cursor for the next page.

ErrorsLink to this section

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

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/artifacts
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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 artifactLink to this section

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.

ParametersLink to this section

Body, application/json (required):

templatestring

A template's ID (GET /v1/artifact-templates): a starter filled from your own data.

pattern ^[a-z][a-z0-9_]{1,47}$

inputsobject

With template: what it asks for, each optional; left out, it is filled from your account (your league synced last, this month).

Show 2 fields
leaguestring

One of your connected leagues (lg_…).

monthstring

A month, as YYYY-MM.

pattern ^[0-9]{4}-[0-9]{2}$

recipeobject

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_answerobject

An Ask Kelly answer of yours: its visuals become the blocks.

Show 1 field
answer_idstringrequired

The answer's ID (ans_…).

project_idstring

One of your projects.

ResponseLink to this section

201 The artifact, drawn for you.

objectconstrequired

Always artifact.

Always "artifact".

artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

recipeobjectrequired

Its recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).

versionsintegerrequired

How many versions it has.

remixobject

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

shareobject

Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (artifact, url, snapshots, images).

compare_urlstring

Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

ErrorsLink to this section

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

ExampleLink to this section

Request
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?" ] } ] } }

Response, 201
{
  "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
}
Request
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?" ] } ] } }

Response, 403
{
  "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."
}
Request
POST https://api.askkelly.ai/v1/artifacts
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

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

Response, 400
{
  "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."
}
Request
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" } ] } }

Response, 201
{
  "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
}
Request
POST https://api.askkelly.ai/v1/artifacts
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{ "template": "league_recap" }

Response, 400
{
  "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 artifactsLink to this section

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.

ParametersLink to this section

artifact_idstring · pathrequired

The artifact's ID (art_…).

pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

controlsobject · 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.

ResponseLink to this section

200 The artifact, drawn for you, with its recipe.

objectconstrequired

Always artifact.

Always "artifact".

artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

recipeobjectrequired

Its recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).

versionsintegerrequired

How many versions it has.

remixobject

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

shareobject

Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (artifact, url, snapshots, images).

compare_urlstring

Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

ErrorsLink to this section

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

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/artifacts/art_hre67fdbqtf9ngbejn9v
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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
}
Request
GET https://api.askkelly.ai/v1/artifacts/art_zzzzzzzzzzzzzzzzzzzz
Authorization: Bearer $KELLY_API_KEY
Response, 404
{
  "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 artifactLink to this section

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.

ParametersLink to this section

artifact_idstring · pathrequired

The artifact's ID (art_…).

pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

Body, application/json (required):

recipeobject

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_versioninteger

The version you changed; when it is no longer the current one the change answers 409 conflict.

min 1

ResponseLink to this section

200 The artifact as it now is.

objectconstrequired

Always artifact.

Always "artifact".

artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

recipeobjectrequired

Its recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).

versionsintegerrequired

How many versions it has.

remixobject

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

shareobject

Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (artifact, url, snapshots, images).

compare_urlstring

Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

ErrorsLink to this section

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

ExampleLink to this section

Request
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 }

Response, 409
{
  "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."
}
Request
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 }

Response, 200
{
  "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 artifactLink to this section

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.

ParametersLink to this section

artifact_idstring · pathrequired

The artifact's ID (art_…).

pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

Body, application/json (required):

visibilitystring

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_authorboolean

Show your Kelly name on it.

ResponseLink to this section

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

objectconstrequired

Always artifact_share.

Always "artifact_share".

artifactobjectrequired

The artifact.

Show 14 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

project_idstringnullable

The project it belongs to, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

created_atstring

When it was made.

format date-time

updated_atstring

When it last changed.

format date-time

published_atstringnullable

When it was first shared.

format date-time

revokedboolean

Whether its owner turned its link off.

urlstringrequired

Its link on askkelly.ai.

snapshotsarray of stringrequired

The blocks kept as they are now, by ID: your own data, or every block when it is frozen.

imagesobject

Its pictures by format: link (1200×630), square (1080×1080), story (1080×1920).

Show 3 fields
squareobject

One picture.

Show 3 fields
urlstring

The PNG's address.

widthinteger

Pixels wide.

heightinteger

Pixels high.

storyobject

One picture.

Show 3 fields
urlstring

The PNG's address.

widthinteger

Pixels wide.

heightinteger

Pixels high.

text_urlstring

Its plain text, for a reader that can't see pictures.

ErrorsLink to this section

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

ExampleLink to this section

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

{ "visibility": "link" }

Response, 200
{
  "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"
  }
}
Request
POST https://api.askkelly.ai/v1/artifacts/art_vv011xck2jc417pkgrqw:share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{ "visibility": "link" }

Response, 200
{
  "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 yoursLink to this section

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.

ParametersLink to this section

Body, application/json (required):

slugstring

Its address (askkelly.ai/a/{slug}).

min length 12 · max length 100

controlsobject

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_idstring

Which of your leagues its league parts draw (lg_…). Absent: your league closest to the author's.

max length 40

ResponseLink to this section

201 Your copy, drawn for you.

objectconstrequired

Always artifact.

Always "artifact".

artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

recipeobjectrequired

Its recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).

versionsintegerrequired

How many versions it has.

remixobject

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

shareobject

Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (artifact, url, snapshots, images).

compare_urlstring

Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

ErrorsLink to this section

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

ExampleLink to this section

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

{ "slug": "addc7rz7brr5s5x7k66w" }

Response, 201
{
  "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 yoursLink to this section

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.

ParametersLink to this section

Body, application/json (required):

slugstring

The original's address (askkelly.ai/a/{slug}).

min length 12 · max length 100

controlsobject

The view your reply opens on, as the original's address carries it. Absent: as it was shared.

league_idstring

Which of your leagues its league parts draw (lg_…).

max length 40

visibilitystring

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_authorboolean

Show your Kelly name on it.

ResponseLink to this section

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

objectconstrequired

Always artifact.

Always "artifact".

artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

recipeobjectrequired

Its recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).

versionsintegerrequired

How many versions it has.

remixobject

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

shareobject

Only on Reply with yours (reply_to_artifact): the reply's share, as share_artifact answers it (artifact, url, snapshots, images).

compare_urlstring

Only on Reply with yours: the side-by-side page of the original and the reply on askkelly.ai, the address to send back.

ErrorsLink to this section

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

ExampleLink to this section

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

{ "slug": "addc7rz7brr5s5x7k66w" }

Response, 400
{
  "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 artifactsLink to this section

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.

ParametersLink to this section

slugstring · pathrequired

Its address (askkelly.ai/a/{slug}).

pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

otherstring · pathrequired

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

ResponseLink to this section

200 The two, side by side.

objectconstrequired

Always artifact_compare.

Always "artifact_compare".

urlstringrequired

The side-by-side page on askkelly.ai.

leftobjectrequired

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.

Show 4 fields
artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

rightobjectrequired

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.

Show 4 fields
artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

pairsarray of objectrequired

The blocks paired, in reading order (buttons left out).

Show 5 fields
idstring

The block's ID (b1, b2, …).

typestring

The block's type.

titlestringnullable

Its title.

leftobjectnullable

The left artifact's block, drawn; null when it has none.

rightobjectnullable

The right artifact's block, drawn; null when it has none.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · artifact_revoked

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/vs/no-such-artifact-here
Response, 404
{
  "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."
}
Request
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/vs/133vgzvn3n1k63hx2752
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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 repliesLink to this section

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.

ParametersLink to this section

slugstring · pathrequired

Its address (askkelly.ai/a/{slug}).

pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

limitinteger · query

Replies per page, 1 to 50.

min 1 · max 50 · default 20

cursorstring · query

The next_cursor of the page before.

max length 80

ResponseLink to this section

200 Its public replies.

objectconstrequired

Always artifact_reply_list.

Always "artifact_reply_list".

slugstringrequired

The original's address.

repliesarray of objectrequired

The replies.

Show 6 fields
slugstring

Its address.

titlestring

Its title.

urlstring

Its page on askkelly.ai.

authorobject

Who made it, as they chose to show it.

published_atstring

When it was shared.

format date-time

compare_urlstring

It and the original, side by side.

totalintegerrequired

How many public replies it has.

next_cursorstringrequirednullable

Pass as cursor for the next page.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · artifact_revoked

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/replies
Response, 200
{
  "object": "artifact_reply_list",
  "slug": "addc7rz7brr5s5x7k66w",
  "replies": [],
  "total": 0,
  "next_cursor": null
}

GET /v1/shared-artifacts/{slug}

Get a shared artifactLink to this section

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.

ParametersLink to this section

slugstring · pathrequired

Its address (askkelly.ai/a/{slug}).

pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

controlsobject · 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.

ResponseLink to this section

200 The artifact, drawn for whoever asks.

objectconstrequired

Always artifact.

Always "artifact".

artifactobjectrequired

The artifact.

Show 18 fields
idstring

Its ID (art_…).

slugstringnullable

Its address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.

titlestring

Its title, the person's own words.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

visibilitystring

Who may open its link.

One of: private, link, public, people, project, league (open: new values may be added).

themestring

Its look.

One of: wire, vellum (open: new values may be added).

versioninteger

Its current version, from 1.

templatestringnullable

The template it was made from, if any.

remix_ofstringnullable

The artifact it was remixed from, if any.

published_atstringnullable

When it was first shared.

format date-time

urlstringnullable

Its page on askkelly.ai, with this view's controls.

authorobject

Who made it, as they chose to show it; display is always shown.

descriptionstringnullable

Its first note, in plain words.

as_ofstring

When these blocks were drawn.

format date-time

can_editboolean

Whether the reader may change it (its owner).

actionsarray of string

What the reader may do: remix, ask, edit, share.

originalobjectnullable

The shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).

can_replyboolean

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.

paramsarray of objectrequired

The controls a reader may change, each with its value, display and default.

querystringrequired

This view's controls as an address query, defaults left out.

blocksarray of objectrequired

Its blocks, in reading order, drawn for this reader.

Show 7 fields
idstringrequired

b1, b2, …

typestringrequired

The block's type.

widthintegerrequired

Columns of three it spans.

One of: 1, 2, 3 (open: new values may be added).

problemstringnullable

Why it isn't drawn, or null.

frozenboolean

Kept as its owner shared it.

summarystringnullable

What it shows, in one sentence.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · artifact_revoked

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w
Response, 200
{
  "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": []
  }
}
Request
GET https://api.askkelly.ai/v1/shared-artifacts/no-such-artifact-here
Response, 404
{
  "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 templatesLink to this section

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.

ResponseLink to this section

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

objectconstrequired

Always artifact_template_list.

Always "artifact_template_list".

templatesarray of objectrequired

The templates.

Show 10 fields
idstring

Its ID, for template.

namestring

Its name.

groupstring

fantasy or general.

One of: fantasy, general (open: new values may be added).

aboutstring

What it shows.

modestring

live: drawn now each time it opens; frozen: kept as it was when shared.

One of: live, frozen (open: new values may be added).

partsarray of string

What it holds, in reading order.

needsstringnullable

What of yours it draws: league, bets or nothing.

One of: league, bets (open: new values may be added).

readyboolean

Whether it can open for you now.

problemstringnullable

Why not, in words, when it can't.

inputsarray of object

What it asks for; each is optional.

Show 5 fields
idstring

Its key in inputs.

typestring

What it is.

One of: league, team, month (open: new values may be added).

labelstring

Its name.

aboutstring

What it does.

choicesarray of object

Your choices (signed in), when it takes one of a list.

Show 2 fields
valuestring

What to send (lg_… for a league).

labelstring

Its name.

totalintegerrequired

How many there are.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/artifact-templates
Response, 200
{
  "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 tailLink to this section

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.

ParametersLink to this section

slugstring · pathrequired

Its address (askkelly.ai/a/{slug}).

pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

ResponseLink to this section

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

objectconstrequired

Always artifact_tail.

Always "artifact_tail".

artifactobjectrequired

The artifact: id, slug, title, url, version.

tail_urlstringrequired

Its Tail page on askkelly.ai.

nextstringnullable

What the reader does next: tail_page off askkelly.ai.

pricedboolean

Whether book prices are in this read (never off askkelly.ai).

kept_atstringnullable

When the sharer's bets were kept (at share).

format date-time

viewerobject

Who is reading: signed_in, attested, books_set.

betsarray of objectrequired

The bets, the sharer's first, at most 10.

Show 7 fields
keystring

t1, t2, …

kindstring

single or parlay.

sourcestring

shared or public.

One of: shared, public (open: new values may be added).

shared_priceobjectnullable

A price: american and decimal.

Show 2 fields
americannumber

American odds.

decimalnumber

Decimal odds.

tailableboolean

Whether every leg can be tailed now.

legsarray of object

Its legs, in order.

Show 12 fields
labelstringnullable

What the leg is on.

market_idstringnullable

Kelly's market (mkt_…).

selection_idstringnullable

Kelly's selection (sel_…).

linenumbernullable

The leg's line.

consensus_pricenumbernullable

Kelly's consensus decimal price.

consensus_pointnumbernullable

The consensus line for this side.

no_vig_probnumbernullable

The no-vig chance at the leg's line.

fair_priceobjectnullable

A price: american and decimal.

Show 2 fields
americannumber

American odds.

decimalnumber

Decimal odds.

shared_priceobjectnullable

A price: american and decimal.

Show 2 fields
americannumber

American odds.

decimalnumber

Decimal odds.

starts_atstringnullable

When its game starts.

format date-time

problemstringnullable

Why it can't be tailed, or null.

One of: college_prop, no_market, closed, unpriced (open: new values may be added).

problem_detailstringnullable

The problem in words.

combinedobjectnullable

A parlay's legs together at the consensus (markets.bet_slip), or null.

helplineobjectnullable

On askkelly.ai only; null here.

as_ofstring

When this was read.

format date-time

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · artifact_revoked

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/shared-artifacts/6j60fp1ywvnwpbp5nrjf/tail
Response, 200
{
  "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"
}
Request
GET https://api.askkelly.ai/v1/shared-artifacts/no-such-artifact-here/tail
Response, 404
{
  "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 momentsLink to this section

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.

ParametersLink to this section

limitinteger · query

Moments, 1 to 50.

min 1 · max 50 · default 20

ResponseLink to this section

200 Your prepared moments and switches.

objectconstrequired

Always share_moments.

Always "share_moments".

momentsarray of objectrequired

Newest first.

Show 11 fields
objectconst

Always share_moment.

Always "share_moment".

idstring

Its ID (smo_…).

kindstring

What happened.

One of: bet_graded, bad_beat, weekly_recap, trade_accepted (open: new values may be added).

labelstring

The kind in words.

statestring

offered, or dismissed when you waved it away.

One of: offered, dismissed (open: new values may be added).

wordsstringnullable

What happened, in a sentence; never a price, a stake or an edge.

artifact_idstringnullable

The draft (art_…), private until you share it; null if deleted.

pathstringnullable

Where the draft opens on askkelly.ai.

made_atstring

When Kelly made it.

format date-time

emailedboolean

Whether it was e-mailed to you.

dismissed_atstringnullable

When you waved it away.

format date-time

waitingintegerrequired

How many offered drafts you haven't waved away.

switchesarray of objectrequired

Every kind, on or off.

Show 3 fields
kindstring

The kind.

One of: bet_graded, bad_beat, weekly_recap, trade_accepted (open: new values may be added).

labelstring

It in words.

onboolean

Whether Kelly drafts and offers it.

ErrorsLink to this section

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

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/me/share-moments
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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 offLink to this section

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.

ParametersLink to this section

Body, application/json (required):

switchesobject

A kind and true or false.

Show 4 fields
bet_gradedboolean

A bet of yours won.

bad_beatboolean

A bet of yours lost narrowly.

weekly_recapboolean

Tuesday's recap of each league you connected.

trade_acceptedboolean

A trade of yours went through.

ResponseLink to this section

200 Your prepared moments and switches after the change.

objectconstrequired

Always share_moments.

Always "share_moments".

momentsarray of objectrequired

Newest first.

Show 11 fields
objectconst

Always share_moment.

Always "share_moment".

idstring

Its ID (smo_…).

kindstring

What happened.

One of: bet_graded, bad_beat, weekly_recap, trade_accepted (open: new values may be added).

labelstring

The kind in words.

statestring

offered, or dismissed when you waved it away.

One of: offered, dismissed (open: new values may be added).

wordsstringnullable

What happened, in a sentence; never a price, a stake or an edge.

artifact_idstringnullable

The draft (art_…), private until you share it; null if deleted.

pathstringnullable

Where the draft opens on askkelly.ai.

made_atstring

When Kelly made it.

format date-time

emailedboolean

Whether it was e-mailed to you.

dismissed_atstringnullable

When you waved it away.

format date-time

waitingintegerrequired

How many offered drafts you haven't waved away.

switchesarray of objectrequired

Every kind, on or off.

Show 3 fields
kindstring

The kind.

One of: bet_graded, bad_beat, weekly_recap, trade_accepted (open: new values may be added).

labelstring

It in words.

onboolean

Whether Kelly drafts and offers it.

ErrorsLink to this section

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

ExampleLink to this section

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

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

Response, 200
{
  "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
    }
  ]
}
Request
PATCH https://api.askkelly.ai/v1/me/share-moments
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

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

Response, 400
{
  "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 picturesLink to this section

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.

ParametersLink to this section

slugstring · pathrequired

Its address (askkelly.ai/a/{slug}).

pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

controlsobject · 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.

ResponseLink to this section

200 Its pictures and text for this view.

objectconstrequired

Always artifact_render.

Always "artifact_render".

slugstringrequired

Its address.

urlstringrequired

Its page on askkelly.ai, with this view.

imagesobjectrequired

Its pictures by format: link (1200×630), square (1080×1080), story (1080×1920).

Show 3 fields
squareobject

One picture.

Show 3 fields
urlstring

The PNG's address.

widthinteger

Pixels wide.

heightinteger

Pixels high.

storyobject

One picture.

Show 3 fields
urlstring

The PNG's address.

widthinteger

Pixels wide.

heightinteger

Pixels high.

text_urlstringrequired

Its plain text, for a reader that can't see pictures.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · artifact_revoked

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/render
Response, 200
{
  "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 artifactLink to this section

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.

ParametersLink to this section

slugstring · pathrequired

Its address (askkelly.ai/a/{slug}).

pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100

Body, application/json (required):

reasonstring

What is wrong with it.

One of: spam, abuse, private_info, wrong, illegal, other (open: new values may be added).

notestring

Anything staff should know.

min length 1 · max length 500

ResponseLink to this section

200 Kelly has your report.

objectconstrequired

Always artifact_report.

Always "artifact_report".

slugstringrequired

The artifact you reported.

receivedconstrequired

Always true.

Always true.

ErrorsLink to this section

invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · payload_too_large · artifact_revoked · artifact_removed

ExampleLink to this section

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

{ "reason": "boring" }

Response, 400
{
  "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."
}
Request
POST https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/report
Content-Type: application/json

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

Response, 200
{
  "object": "artifact_report",
  "slug": "addc7rz7brr5s5x7k66w",
  "received": true
}

GET /v1/me/handle

Get your public handleLink to this section

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

ResponseLink to this section

200 Your public handle, or null.

objectconstrequired

Always public_handle.

Always "public_handle".

handleobjectrequirednullable

Your handle, or null when you have none (your artifacts read "A Kelly member").

Show 5 fields
handlestring

The handle without its @: 3 to 20 of a-z, 0-9 and _.

pattern ^[a-z0-9_]{3,20}$

displaystring

The name a reader sees: your display name, else @handle.

display_namestringnullable

Your display name, if you set one.

created_atstring

When you took it.

format date-time

updated_atstring

When it last changed.

format date-time

clearedstringrequirednullable

A handle Kelly's staff took from you, if they did.

hold_daysintegerrequired

Days a handle you give up stays yours to take back.

ErrorsLink to this section

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

ExampleLink to this section

Request
GET https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "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
}
Request
GET https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "object": "public_handle",
  "handle": null,
  "cleared": null,
  "hold_days": 30
}

PUT /v1/me/handle

Set your public handleLink to this section

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.

ParametersLink to this section

Body, application/json (required):

handlestring

3 to 20 of a-z, 0-9 and _ (a leading @ is dropped; kept lower case).

min length 3 · max length 21

displaystringnullable

The name readers see, up to 40 characters; null or absent shows @handle.

max length 40

ResponseLink to this section

200 Your public handle as it now is.

objectconstrequired

Always public_handle.

Always "public_handle".

handleobjectrequirednullable

Your handle, or null when you have none (your artifacts read "A Kelly member").

Show 5 fields
handlestring

The handle without its @: 3 to 20 of a-z, 0-9 and _.

pattern ^[a-z0-9_]{3,20}$

displaystring

The name a reader sees: your display name, else @handle.

display_namestringnullable

Your display name, if you set one.

created_atstring

When you took it.

format date-time

updated_atstring

When it last changed.

format date-time

clearedstringrequirednullable

A handle Kelly's staff took from you, if they did.

hold_daysintegerrequired

Days a handle you give up stays yours to take back.

ErrorsLink to this section

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

ExampleLink to this section

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

{ "handle": "kelly_official" }

Response, 400
{
  "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."
}
Request
PUT https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

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

Response, 200
{
  "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 handleLink to this section

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.

ResponseLink to this section

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

objectconstrequired

Always public_handle.

Always "public_handle".

handleobjectrequirednullable

Your handle, or null when you have none (your artifacts read "A Kelly member").

Show 5 fields
handlestring

The handle without its @: 3 to 20 of a-z, 0-9 and _.

pattern ^[a-z0-9_]{3,20}$

displaystring

The name a reader sees: your display name, else @handle.

display_namestringnullable

Your display name, if you set one.

created_atstring

When you took it.

format date-time

updated_atstring

When it last changed.

format date-time

clearedstringrequirednullable

A handle Kelly's staff took from you, if they did.

hold_daysintegerrequired

Days a handle you give up stays yours to take back.

ErrorsLink to this section

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

ExampleLink to this section

Request
DELETE https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Response, 200
{
  "object": "public_handle",
  "handle": null,
  "cleared": null,
  "hold_days": 30
}

Generated from Kelly API 2026-10-05.

Support: support@askkelly.ai · Security and disclosure