Articles actions
16 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.
Articles
Section titled “Articles”articles.list · read
The account’s X Articles (drafts, scheduled, published), newest first.
- MCP tool:
articles_list. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/articles/list - CLI:
xholic articles list - Scope:
read - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
status |
“ALL” or “DRAFT” \ | “SCHEDULED” \ | “PUBLISHING” \ |
search |
string ≤ 120 chars | No | |
limit |
integer 1–100 | No | |
cursor |
string (uuid) | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Create an article
Section titled “Create an article”articles.create · write
Start a new X Article draft with a title. Then write its body yourself and save it with update_article. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
create_article. Loaded by default in MCP clients. - REST:
POST /v1/articles/create - CLI:
xholic articles create - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write - Undo: from the activity log, which runs
articles.delete
Input
| Field | Type | Required | Description |
|---|---|---|---|
title |
string ≤ 200 chars | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Can this account publish articles
Section titled “Can this account publish articles”articles.eligibility · read
Whether the X account can publish Articles (X requires Premium) and why not.
- MCP tool:
articles_eligibility. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/articles/eligibility - CLI:
xholic articles eligibility - Scope:
read - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
AI cover allowance
Section titled “AI cover allowance”articles.cover_usage · read
How many AI article covers are left today and this period.
- MCP tool:
articles_cover_usage. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/articles/cover-usage - CLI:
xholic articles cover-usage - Scope:
read - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Get an article
Section titled “Get an article”articles.get · read
One article with its title, subtitle, document, assets, status and version.
- MCP tool:
articles_get. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/articles/get - CLI:
xholic articles get - Scope:
read - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Edit an article
Section titled “Edit an article”articles.update · write
Save an article’s title, subtitle or body. Pass the current version from articles.get; it returns the new version. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
update_article. Loaded by default in MCP clients. - REST:
POST /v1/articles/update - CLI:
xholic articles update - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
title |
string ≤ 200 chars | No | |
subtitle |
string ≤ 280 chars or null | No | |
document |
object | No | The whole body as a Tiptap/ProseMirror JSON document: {type:“doc”,content:[paragraph, heading, bulletList, image… nodes]}. See docs.xholic.ai/api/articles. |
document.type |
“doc” | Yes | |
version |
integer 1–9007199254740991 | Yes | The article’s current version, from articles.get. A stale version is refused so edits never overwrite each other. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Delete an article
Section titled “Delete an article”articles.delete · write
Delete an article from Xholic. It does not delete one already published on X. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
articles_delete. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/delete - CLI:
xholic articles delete - Scope:
write. Destructive: it can’t be taken back - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Duplicate an article
Section titled “Duplicate an article”articles.duplicate · write
Copy an article into a new draft.
- MCP tool:
articles_duplicate. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/duplicate - CLI:
xholic articles duplicate - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Article AI
Section titled “Article AI”articles.ai_run · write
Only when the user explicitly asks for Xholic’s article AI. Queues an outline, full draft, selection rewrite/expand/shorten, titles, conclusion, teaser post or thread, or an AI cover image. Price depends on kind and model. Uses Xholic AI credits: quote first and pass confirmCredits after the user agrees. Read the result with articles.get. Otherwise write the text yourself.
- MCP tool:
articles_ai_run. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/ai-run - CLI:
xholic articles ai-run - Scope:
write - Plan: Pro plan or higher
- Cost: Xholic AI: up to about 150 credits (Xholic’s article AI; the quote shows the price for the chosen kind and model). Returns a quote first; pass
confirmCreditsafter the user agrees. - Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
kind |
“OUTLINE” \ | “FULL_ARTICLE” \ | “REWRITE_SELECTION” \ |
model |
“luna” \ | “terra” \ | “sol” |
instructions |
string ≤ 4000 chars | No | |
selectedText |
string ≤ 20000 chars | No | Required for REWRITE_SELECTION, EXPAND_SELECTION and SHORTEN_SELECTION. |
coverStyle |
“surprise_me” \ | “editorial” \ | “minimal” \ |
sourceAssetId |
string (uuid) | No | Required for COVER_EDIT: the cover to edit. |
idempotencyKey |
string ≤ 120 chars | Yes | A unique key for this run so a retry never queues it twice. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
confirmCredits |
number 0–100000 | No | Xholic AI credits the user agreed to spend. Call first without it to get the quote, show the quote to the user, and pass the amount only after they say yes. |
quoteId |
string ≤ 100 chars | No | The quoteId from the quote the user agreed to. Send it with confirmCredits. |
Upload an article image
Section titled “Upload an article image”articles.create_asset_upload · write
Start an image upload for an article cover or inline image. Returns an assetId and upload URL; PUT the bytes there, then call articles.finalize_asset.
- MCP tool:
articles_create_asset_upload. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/create-asset-upload - CLI:
xholic articles create-asset-upload - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
kind |
“COVER” \ | “INLINE” | Yes |
filename |
string ≤ 255 chars | Yes | |
mimeType |
“image/jpeg” \ | “image/png” \ | “image/webp” \ |
byteSize |
integer 1–5242880 | Yes | |
width |
integer 1–16384 | No | |
height |
integer 1–16384 | No | |
altText |
string ≤ 1000 chars | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Finish an article image upload
Section titled “Finish an article image upload”articles.finalize_asset · write
Mark an article image upload finished after the bytes were PUT to the upload URL.
- MCP tool:
articles_finalize_asset. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/finalize-asset - CLI:
xholic articles finalize-asset - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
assetId |
string (uuid) | Yes | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Add a GIF or meme to an article
Section titled “Add a GIF or meme to an article”articles.import_klipy · write
Copy a KLIPY GIF or meme (from media.browse_klipy) into an article as its cover or an inline image.
- MCP tool:
articles_import_klipy. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/import-klipy - CLI:
xholic articles import-klipy - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
kind |
“COVER” \ | “INLINE” | Yes |
type |
“gifs” \ | “memes” | Yes |
slug |
string ≤ 200 chars | Yes | The item’s slug from media.browse_klipy. |
altText |
string ≤ 1000 chars | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Remove an article image
Section titled “Remove an article image”articles.delete_asset · write
Remove an image from an article. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
articles_delete_asset. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/delete-asset - CLI:
xholic articles delete-asset - Scope:
write. Destructive: it can’t be taken back - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
assetId |
string (uuid) | Yes | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Schedule an article
Section titled “Schedule an article”articles.schedule · publish
Schedule an article to publish on X at a time. Pass the current version from articles.get. Call it only when the user asked for this in the conversation; never on your own initiative. Spends a post credit when it goes live.
- MCP tool:
schedule_article. Loaded by default in MCP clients. - REST:
POST /v1/articles/schedule - CLI:
xholic articles schedule - Scope:
publish - Plan: Pro plan or higher
- Cost: Spends a post credit when the post goes live.
- Rate limit bucket:
write - Undo: from the activity log, which runs
articles.cancel_schedule
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
scheduledAt |
string ≤ 40 chars | Yes | When to publish, as an ISO time with offset such as 2026-10-25T10:00:00-04:00. |
timezone |
string ≤ 100 chars | Yes | IANA timezone such as America/New_York. Use the user’s timezone. |
version |
integer 1–9007199254740991 | Yes | The article’s current version, from articles.get. A stale version is refused so edits never overwrite each other. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Publish an article now
Section titled “Publish an article now”articles.publish · publish
Publish an article to X now. Pass the current version from articles.get. Call it only when the user asked for this in the conversation; never on your own initiative. Spends a post credit.
- MCP tool:
publish_article. Loaded by default in MCP clients. - REST:
POST /v1/articles/publish - CLI:
xholic articles publish - Scope:
publish. Destructive: it can’t be taken back - Plan: Pro plan or higher
- Cost: Spends a post credit when the post goes live.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
version |
integer 1–9007199254740991 | Yes | The article’s current version, from articles.get. A stale version is refused so edits never overwrite each other. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Unschedule an article
Section titled “Unschedule an article”articles.cancel_schedule · write
Take a scheduled article out of the queue; it stays a draft.
- MCP tool:
articles_cancel_schedule. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/articles/cancel-schedule - CLI:
xholic articles cancel-schedule - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Article id from articles.list. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |