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
- List your artifacts
- Parameters
- Response
- Errors
- Example
- Make an artifact
- Parameters
- Response
- Errors
- Example
- Get one of your artifacts
- Parameters
- Response
- Errors
- Example
- Change an artifact
- Parameters
- Response
- Errors
- Example
- Share an artifact
- Parameters
- Response
- Errors
- Example
- Make a shared artifact yours
- Parameters
- Response
- Errors
- Example
- Reply to a shared artifact with yours
- Parameters
- Response
- Errors
- Example
- Compare two shared artifacts
- Parameters
- Response
- Errors
- Example
- List a shared artifact's replies
- Parameters
- Response
- Errors
- Example
- Get a shared artifact
- Parameters
- Response
- Errors
- Example
- List the artifact templates
- Response
- Errors
- Example
- Get a shared artifact's bets to tail
- Parameters
- Response
- Errors
- Example
- Your prepared moments
- Parameters
- Response
- Errors
- Example
- Turn prepared moments on or off
- Parameters
- Response
- Errors
- Example
- Get an artifact's pictures
- Parameters
- Response
- Errors
- Example
- Report a shared artifact
- Parameters
- Response
- Errors
- Example
- Get your public handle
- Response
- Errors
- Example
- Set your public handle
- Parameters
- Response
- Errors
- Example
- Give up your public handle
- Response
- Errors
- Example
| Method | Path | Title | Access | Price | MCP tool |
|---|---|---|---|---|---|
| GET | /v1/artifacts | List your artifacts | read:artifacts | 0 | list_my_artifacts |
| POST | /v1/artifacts | Make an artifact | write:artifacts | 0 | create_artifact |
| GET | /v1/artifacts/{artifact_id} | Get one of your artifacts | read:artifacts | 0 | get_artifact |
| PATCH | /v1/artifacts/{artifact_id} | Change an artifact | write:artifacts | 0 | update_artifact |
| POST | /v1/artifacts/{artifact_id}:share | Share an artifact | write:artifacts | 0 | share_artifact |
| POST | /v1/artifacts:remix | Make a shared artifact yours | write:artifacts | 0 | remix_artifact |
| POST | /v1/artifacts:reply | Reply to a shared artifact with yours | write:artifacts | 0 | reply_to_artifact |
| GET | /v1/shared-artifacts/{slug}/vs/{other} | Compare two shared artifacts | public | 0 | compare_artifacts |
| GET | /v1/shared-artifacts/{slug}/replies | List a shared artifact's replies | public | 0 | list_artifact_replies |
| GET | /v1/shared-artifacts/{slug} | Get a shared artifact | public | 0 | get_shared_artifact |
| GET | /v1/artifact-templates | List the artifact templates | public | 0 | list_artifact_templates |
| GET | /v1/shared-artifacts/{slug}/tail | Get a shared artifact's bets to tail | public | 0 | get_artifact_tail |
| GET | /v1/me/share-moments | Your prepared moments | read:artifacts | 0 | get_my_share_moments |
| PATCH | /v1/me/share-moments | Turn prepared moments on or off | write:artifacts | 0 | set_my_share_moments |
| GET | /v1/shared-artifacts/{slug}/render | Get an artifact's pictures | public | 0 | render_artifact |
| POST | /v1/shared-artifacts/{slug}/report | Report a shared artifact | public | 0 | report_artifact |
| GET | /v1/me/handle | Get your public handle | read:artifacts | 0 | get_my_handle |
| PUT | /v1/me/handle | Set your public handle | write:artifacts | 0 | set_my_handle |
| DELETE | /v1/me/handle | Give up your public handle | write:artifacts | 0 | remove_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 · queryOnly this project's artifacts.
max length 64
limitinteger · queryArtifacts per page, 1 to 50.
min 1 · max 50 · default 25
cursorstring · queryThe next_cursor of the page before.
max length 200
ResponseLink to this section
200 A page of your artifacts.
objectconstrequiredAlways artifact_list.
Always "artifact_list".
artifactsarray of objectrequiredThe artifacts, most recently changed first.
Show 15 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
project_idstringnullableThe project it belongs to, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
created_atstringWhen it was made.
format date-time
updated_atstringWhen it last changed.
format date-time
published_atstringnullableWhen it was first shared.
format date-time
revokedbooleanWhether its owner turned its link off.
blocksintegerHow many blocks it has.
totalintegerrequiredHow many artifacts you have (in this project, when asked).
next_cursorstringrequirednullablePass as cursor for the next page.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled
ExampleLink to this section
GET https://api.askkelly.ai/v1/artifacts
Authorization: Bearer $KELLY_API_KEY{
"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):
templatestringA template's ID (GET /v1/artifact-templates): a starter filled from your own data.
pattern ^[a-z][a-z0-9_]{1,47}$
inputsobjectWith template: what it asks for, each optional; left out, it is filled from your account (your league synced last, this month).
Show 2 fields
leaguestringOne of your connected leagues (lg_…).
monthstringA month, as YYYY-MM.
pattern ^[0-9]{4}-[0-9]{2}$
recipeobjectThe 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_answerobjectAn Ask Kelly answer of yours: its visuals become the blocks.
Show 1 field
answer_idstringrequiredThe answer's ID (ans_…).
project_idstringOne of your projects.
ResponseLink to this section
201 The artifact, drawn for you.
objectconstrequiredAlways artifact.
Always "artifact".
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
recipeobjectrequiredIts recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).
versionsintegerrequiredHow many versions it has.
remixobjectOnly 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).
compare_urlstringOnly 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
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?"
]
}
]
}
}
{
"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
}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?"
]
}
]
}
}
{
"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."
}POST https://api.askkelly.ai/v1/artifacts
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"recipe": {
"kas": 1,
"title": "Empty",
"blocks": []
}
}
{
"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."
}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"
}
]
}
}
{
"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
}POST https://api.askkelly.ai/v1/artifacts
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"template": "league_recap"
}
{
"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 · pathrequiredThe artifact's ID (art_…).
pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
controlsobject · queryThe 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.
objectconstrequiredAlways artifact.
Always "artifact".
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
recipeobjectrequiredIts recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).
versionsintegerrequiredHow many versions it has.
remixobjectOnly 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).
compare_urlstringOnly 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
GET https://api.askkelly.ai/v1/artifacts/art_hre67fdbqtf9ngbejn9v
Authorization: Bearer $KELLY_API_KEY{
"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
}GET https://api.askkelly.ai/v1/artifacts/art_zzzzzzzzzzzzzzzzzzzz
Authorization: Bearer $KELLY_API_KEY{
"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 · pathrequiredThe artifact's ID (art_…).
pattern ^art_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
Body, application/json (required):
recipeobjectThe 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_versionintegerThe 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.
objectconstrequiredAlways artifact.
Always "artifact".
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
recipeobjectrequiredIts recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).
versionsintegerrequiredHow many versions it has.
remixobjectOnly 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).
compare_urlstringOnly 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
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
}
{
"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."
}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
}
{
"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
Body, application/json (required):
ResponseLink to this section
200 Its link, and the blocks kept as they are now.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled · payload_too_large · not_found
ExampleLink to this section
POST https://api.askkelly.ai/v1/artifacts/art_hre67fdbqtf9ngbejn9v:share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"visibility": "link"
}
{
"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"
}
}POST https://api.askkelly.ai/v1/artifacts/art_vv011xck2jc417pkgrqw:share
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"visibility": "link"
}
{
"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):
slugstringIts address (askkelly.ai/a/{slug}).
min length 12 · max length 100
controlsobjectThe 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_idstringWhich 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.
objectconstrequiredAlways artifact.
Always "artifact".
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
recipeobjectrequiredIts recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).
versionsintegerrequiredHow many versions it has.
remixobjectOnly 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).
compare_urlstringOnly 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
POST https://api.askkelly.ai/v1/artifacts:remix
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"slug": "addc7rz7brr5s5x7k66w"
}
{
"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):
slugstringThe original's address (askkelly.ai/a/{slug}).
min length 12 · max length 100
controlsobjectThe view your reply opens on, as the original's address carries it. Absent: as it was shared.
league_idstringWhich of your leagues its league parts draw (lg_…).
max length 40
visibilitystringlink (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_authorbooleanShow your Kelly name on it.
ResponseLink to this section
201 Your reply, drawn for you, with its share and the side-by-side link.
objectconstrequiredAlways artifact.
Always "artifact".
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
recipeobjectrequiredIts recipe: a Kelly Artifact Spec (KAS 1, registry/contracts/artifacts/kas.schema.json).
versionsintegerrequiredHow many versions it has.
remixobjectOnly 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).
compare_urlstringOnly 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
POST https://api.askkelly.ai/v1/artifacts:reply
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"slug": "addc7rz7brr5s5x7k66w"
}
{
"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 · pathrequiredIts address (askkelly.ai/a/{slug}).
pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100
otherstring · pathrequiredThe 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.
objectconstrequiredAlways artifact_compare.
Always "artifact_compare".
urlstringrequiredThe side-by-side page on askkelly.ai.
leftobjectrequiredA 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
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
rightobjectrequiredA 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
artifactobjectrequiredThe artifact.
Show 18 fields
idstringIts ID (art_…).
slugstringnullableIts address on askkelly.ai (askkelly.ai/a/{slug}); null until shared.
titlestringIts title, the person's own words.
modestringlive: drawn now each time it opens; frozen: kept as it was when shared.
One of: live, frozen (open: new values may be added).
visibilitystringWho may open its link.
One of: private, link, public, people, project, league (open: new values may be added).
themestringIts look.
One of: wire, vellum (open: new values may be added).
versionintegerIts current version, from 1.
templatestringnullableThe template it was made from, if any.
remix_ofstringnullableThe artifact it was remixed from, if any.
published_atstringnullableWhen it was first shared.
format date-time
urlstringnullableIts page on askkelly.ai, with this view's controls.
authorobjectWho made it, as they chose to show it; display is always shown.
descriptionstringnullableIts first note, in plain words.
as_ofstringWhen these blocks were drawn.
format date-time
can_editbooleanWhether the reader may change it (its owner).
actionsarray of stringWhat the reader may do: remix, ask, edit, share.
originalobjectnullableThe shared artifact this one was made from (slug, title, url), when anyone may open it; else null (C4, ADR-K899).
can_replybooleanWhether 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 objectrequiredThe controls a reader may change, each with its value, display and default.
querystringrequiredThis view's controls as an address query, defaults left out.
blocksarray of objectrequiredIts blocks, in reading order, drawn for this reader.
Show 7 fields
idstringrequiredb1, b2, …
typestringrequiredThe block's type.
widthintegerrequiredColumns of three it spans.
One of: 1, 2, 3 (open: new values may be added).
problemstringnullableWhy it isn't drawn, or null.
linkstringnullableon_site_only: where it is drawn.
frozenbooleanKept as its owner shared it.
summarystringnullableWhat it shows, in one sentence.
pairsarray of objectrequiredThe blocks paired, in reading order (buttons left out).
Show 5 fields
idstringThe block's ID (b1, b2, …).
typestringThe block's type.
titlestringnullableIts title.
leftobjectnullableThe left artifact's block, drawn; null when it has none.
rightobjectnullableThe 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
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/vs/no-such-artifact-here{
"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."
}GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/vs/133vgzvn3n1k63hx2752
Authorization: Bearer $KELLY_API_KEY{
"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 · pathrequiredIts address (askkelly.ai/a/{slug}).
pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100
limitinteger · queryReplies per page, 1 to 50.
min 1 · max 50 · default 20
cursorstring · queryThe next_cursor of the page before.
max length 80
ResponseLink to this section
200 Its public replies.
objectconstrequiredAlways artifact_reply_list.
Always "artifact_reply_list".
slugstringrequiredThe original's address.
repliesarray of objectrequiredThe replies.
Show 6 fields
slugstringIts address.
titlestringIts title.
urlstringIts page on askkelly.ai.
authorobjectWho made it, as they chose to show it.
published_atstringWhen it was shared.
format date-time
compare_urlstringIt and the original, side by side.
totalintegerrequiredHow many public replies it has.
next_cursorstringrequirednullablePass as cursor for the next page.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · not_found · artifact_revoked
ExampleLink to this section
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/replies{
"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
ResponseLink to this section
200 The artifact, drawn for whoever asks.
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
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w{
"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": []
}
}GET https://api.askkelly.ai/v1/shared-artifacts/no-such-artifact-here{
"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.
objectconstrequiredAlways artifact_template_list.
Always "artifact_template_list".
templatesarray of objectrequiredThe templates.
Show 10 fields
idstringIts ID, for template.
namestringIts name.
groupstringfantasy or general.
One of: fantasy, general (open: new values may be added).
aboutstringWhat it shows.
modestringlive: 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 stringWhat it holds, in reading order.
needsstringnullableWhat of yours it draws: league, bets or nothing.
One of: league, bets (open: new values may be added).
readybooleanWhether it can open for you now.
problemstringnullableWhy not, in words, when it can't.
inputsarray of objectWhat it asks for; each is optional.
Show 5 fields
idstringIts key in inputs.
typestringWhat it is.
One of: league, team, month (open: new values may be added).
labelstringIts name.
aboutstringWhat it does.
choicesarray of objectYour choices (signed in), when it takes one of a list.
Show 2 fields
valuestringWhat to send (lg_… for a league).
labelstringIts name.
totalintegerrequiredHow 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
GET https://api.askkelly.ai/v1/artifact-templates{
"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 · pathrequiredIts 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.
objectconstrequiredAlways artifact_tail.
Always "artifact_tail".
artifactobjectrequiredThe artifact: id, slug, title, url, version.
tail_urlstringrequiredIts Tail page on askkelly.ai.
nextstringnullableWhat the reader does next: tail_page off askkelly.ai.
pricedbooleanWhether book prices are in this read (never off askkelly.ai).
kept_atstringnullableWhen the sharer's bets were kept (at share).
format date-time
viewerobjectWho is reading: signed_in, attested, books_set.
betsarray of objectrequiredThe bets, the sharer's first, at most 10.
Show 7 fields
keystringt1, t2, …
kindstringsingle or parlay.
sourcestringshared or public.
One of: shared, public (open: new values may be added).
tailablebooleanWhether every leg can be tailed now.
legsarray of objectIts legs, in order.
Show 12 fields
labelstringnullableWhat the leg is on.
market_idstringnullableKelly's market (mkt_…).
selection_idstringnullableKelly's selection (sel_…).
linenumbernullableThe leg's line.
consensus_pricenumbernullableKelly's consensus decimal price.
consensus_pointnumbernullableThe consensus line for this side.
no_vig_probnumbernullableThe no-vig chance at the leg's line.
fair_priceobjectnullableA price: american and decimal.
Show 2 fields
americannumberAmerican odds.
decimalnumberDecimal odds.
starts_atstringnullableWhen its game starts.
format date-time
problemstringnullableWhy it can't be tailed, or null.
One of: college_prop, no_market, closed, unpriced (open: new values may be added).
problem_detailstringnullableThe problem in words.
combinedobjectnullableA parlay's legs together at the consensus (markets.bet_slip), or null.
helplineobjectnullableOn askkelly.ai only; null here.
as_ofstringWhen 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
GET https://api.askkelly.ai/v1/shared-artifacts/6j60fp1ywvnwpbp5nrjf/tail{
"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"
}GET https://api.askkelly.ai/v1/shared-artifacts/no-such-artifact-here/tail{
"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
ResponseLink to this section
200 Your prepared moments and switches.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled · not_found
ExampleLink to this section
GET https://api.askkelly.ai/v1/me/share-moments
Authorization: Bearer $KELLY_API_KEY{
"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):
ResponseLink to this section
200 Your prepared moments and switches after the change.
ErrorsLink to this section
invalid_request · credential_in_url · unsupported_api_version · unauthenticated · method_not_allowed · rate_limited · internal_error · service_unavailable · quota_exhausted · insufficient_scope · not_entitled · payload_too_large · not_found
ExampleLink to this section
PATCH https://api.askkelly.ai/v1/me/share-moments
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"switches": {
"bad_beat": false
}
}
{
"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
}
]
}PATCH https://api.askkelly.ai/v1/me/share-moments
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"switches": {
"big_win": true
}
}
{
"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 · pathrequiredIts address (askkelly.ai/a/{slug}).
pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100
controlsobject · queryThe 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.
objectconstrequiredAlways artifact_render.
Always "artifact_render".
slugstringrequiredIts address.
urlstringrequiredIts page on askkelly.ai, with this view.
imagesobjectrequiredIts pictures by format: link (1200×630), square (1080×1080), story (1080×1920).
Show 3 fields
linkobjectOne picture.
Show 3 fields
urlstringThe PNG's address.
widthintegerPixels wide.
heightintegerPixels high.
squareobjectOne picture.
Show 3 fields
urlstringThe PNG's address.
widthintegerPixels wide.
heightintegerPixels high.
storyobjectOne picture.
Show 3 fields
urlstringThe PNG's address.
widthintegerPixels wide.
heightintegerPixels high.
text_urlstringrequiredIts 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
GET https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/render{
"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 · pathrequiredIts address (askkelly.ai/a/{slug}).
pattern ^[a-z0-9]+(-[a-z0-9]+)*$ · min length 12 · max length 100
Body, application/json (required):
reasonstringWhat is wrong with it.
One of: spam, abuse, private_info, wrong, illegal, other (open: new values may be added).
notestringAnything staff should know.
min length 1 · max length 500
ResponseLink to this section
200 Kelly has your report.
objectconstrequiredAlways artifact_report.
Always "artifact_report".
slugstringrequiredThe artifact you reported.
receivedconstrequiredAlways 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
POST https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/report
Content-Type: application/json{
"reason": "boring"
}
{
"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."
}POST https://api.askkelly.ai/v1/shared-artifacts/addc7rz7brr5s5x7k66w/report
Content-Type: application/json{
"reason": "spam",
"note": "Posted the same page ten times."
}
{
"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.
objectconstrequiredAlways public_handle.
Always "public_handle".
handleobjectrequirednullableYour handle, or null when you have none (your artifacts read "A Kelly member").
Show 5 fields
handlestringThe handle without its @: 3 to 20 of a-z, 0-9 and _.
pattern ^[a-z0-9_]{3,20}$
displaystringThe name a reader sees: your display name, else @handle.
display_namestringnullableYour display name, if you set one.
created_atstringWhen you took it.
format date-time
updated_atstringWhen it last changed.
format date-time
clearedstringrequirednullableA handle Kelly's staff took from you, if they did.
hold_daysintegerrequiredDays 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
GET https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY{
"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
}GET https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY{
"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):
handlestring3 to 20 of a-z, 0-9 and _ (a leading @ is dropped; kept lower case).
min length 3 · max length 21
displaystringnullableThe 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.
objectconstrequiredAlways public_handle.
Always "public_handle".
handleobjectrequirednullableYour handle, or null when you have none (your artifacts read "A Kelly member").
Show 5 fields
handlestringThe handle without its @: 3 to 20 of a-z, 0-9 and _.
pattern ^[a-z0-9_]{3,20}$
displaystringThe name a reader sees: your display name, else @handle.
display_namestringnullableYour display name, if you set one.
created_atstringWhen you took it.
format date-time
updated_atstringWhen it last changed.
format date-time
clearedstringrequirednullableA handle Kelly's staff took from you, if they did.
hold_daysintegerrequiredDays 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
PUT https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"handle": "kelly_official"
}
{
"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."
}PUT https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json{
"handle": "sharp_side",
"display": "Sharp Side"
}
{
"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".
objectconstrequiredAlways public_handle.
Always "public_handle".
handleobjectrequirednullableYour handle, or null when you have none (your artifacts read "A Kelly member").
Show 5 fields
handlestringThe handle without its @: 3 to 20 of a-z, 0-9 and _.
pattern ^[a-z0-9_]{3,20}$
displaystringThe name a reader sees: your display name, else @handle.
display_namestringnullableYour display name, if you set one.
created_atstringWhen you took it.
format date-time
updated_atstringWhen it last changed.
format date-time
clearedstringrequirednullableA handle Kelly's staff took from you, if they did.
hold_daysintegerrequiredDays 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
DELETE https://api.askkelly.ai/v1/me/handle
Authorization: Bearer $KELLY_API_KEY{
"object": "public_handle",
"handle": null,
"cleared": null,
"hold_days": 30
}Generated from Kelly API 2026-10-05.