Workers actions
21 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.
Workers
Section titled “Workers”workers.list · read
The account’s Workers (always-on AI writers): settings, schedule and status.
- MCP tool:
get_workers. Loaded by default in MCP clients. - REST:
GET /v1/workers/list - CLI:
xholic workers list - 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. |
Worker drafts
Section titled “Worker drafts”workers.drafts · read
Drafts a Worker wrote that are waiting for review.
- MCP tool:
get_worker_drafts. Loaded by default in MCP clients. - REST:
GET /v1/workers/drafts - CLI:
xholic workers drafts - Scope:
read - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
neuronId |
string (uuid) | No | |
limit |
integer 1–30 | No | Default: 12. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Growth overview
Section titled “Growth overview”workers.overview · read
The account’s growth overview: milestones, Workers and what they produced.
- MCP tool:
workers_overview. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/workers/overview - CLI:
xholic workers overview - 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. |
Find creators for a Worker
Section titled “Find creators for a Worker”workers.find_creators · read
Find X creators whose style a Worker can learn from.
- MCP tool:
workers_find_creators. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/workers/find-creators - CLI:
xholic workers find-creators - Scope:
read - Plan: Pro plan or higher
- Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
- Rate limit bucket:
live_x
Input
| Field | Type | Required | Description |
|---|---|---|---|
query |
string ≤ 60 chars | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Create a Worker
Section titled “Create a Worker”workers.create · write
Create a Worker that writes posts on a schedule or on demand. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
create_worker. Loaded by default in MCP clients. - REST:
POST /v1/workers/create - CLI:
xholic workers create - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
name |
string ≤ 80 chars | Yes | |
status |
“ACTIVE” \ | “PAUSED” | No |
voiceMode |
“OWN” \ | “CREATOR” \ | “HYBRID” |
creatorXIds |
array of string ≤ 120 chars (max 3) | No | Creator xid values from findWorkerCreators: one for HYBRID unless the user asks for more (up to three), one to three for CREATOR, none for OWN. Default: []. |
instructions |
string ≤ 2000 chars or null | No | The worker’s brief, broad boundaries only: who it writes for, who speaks, how the account likes to write, the areas it usually writes in, when to mention products and hard bans. Never a thesis, a point of view to push or specific topics to cover. |
applyAccountRules |
boolean | No | Follow the account’s saved writing rules. Default: true. |
mirrorProvenPosts |
boolean | No | Shape posts on formats that already work in the niche. Default: true. |
topicMode |
“FOR_YOU” \ | “PRODUCT” \ | “CUSTOM_TOPIC” \ |
customTopic |
string ≤ 500 chars or null | No | CUSTOM_TOPIC: what to post about. NICHE_TRENDING: one to five comma-separated keywords. |
productIds |
array of string ≤ 120 chars (max 5) | No | PRODUCT only: saved product IDs from getAutomationSetup or getAccountContext. Default: []. |
outputCount |
8 or 12 or 24 | Yes | Posts written per run: 8, 12 or 24. |
scheduleMode |
“ON_DEMAND” \ | “DAILY” \ | “WEEKLY” |
scheduleTimeMinutes |
integer 0–1439 or null | No | DAILY or WEEKLY: minutes after midnight in the account’s timezone, e.g. 540 for 9:00. |
scheduleDayOfWeek |
integer 0–6 or null | No | WEEKLY: 0 is Sunday, 6 is Saturday. |
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. |
Edit a Worker
Section titled “Edit a Worker”workers.update · write
Change a Worker’s instructions, voice, topics, products, size or schedule. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
update_worker. Loaded by default in MCP clients. - REST:
POST /v1/workers/update - CLI:
xholic workers update - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
workerId |
string (uuid) | Yes | |
changes |
object | Yes | |
changes.name |
string ≤ 80 chars | No | |
changes.status |
“ACTIVE” \ | “PAUSED” | No |
changes.voiceMode |
“OWN” \ | “CREATOR” \ | “HYBRID” |
changes.creatorXIds |
array of string ≤ 120 chars (max 3) | No | Creator xid values from findWorkerCreators: one for HYBRID unless the user asks for more (up to three), one to three for CREATOR, none for OWN. |
changes.instructions |
string ≤ 2000 chars or null | No | The worker’s brief, broad boundaries only: who it writes for, who speaks, how the account likes to write, the areas it usually writes in, when to mention products and hard bans. Never a thesis, a point of view to push or specific topics to cover. |
changes.applyAccountRules |
boolean | No | Follow the account’s saved writing rules. |
changes.mirrorProvenPosts |
boolean | No | Shape posts on formats that already work in the niche. |
changes.topicMode |
“FOR_YOU” \ | “PRODUCT” \ | “CUSTOM_TOPIC” \ |
changes.customTopic |
string ≤ 500 chars or null | No | CUSTOM_TOPIC: what to post about. NICHE_TRENDING: one to five comma-separated keywords. |
changes.productIds |
array of string ≤ 120 chars (max 5) | No | PRODUCT only: saved product IDs from getAutomationSetup or getAccountContext. |
changes.outputCount |
8 or 12 or 24 | No | Posts written per run: 8, 12 or 24. |
changes.scheduleMode |
“ON_DEMAND” \ | “DAILY” \ | “WEEKLY” |
changes.scheduleTimeMinutes |
integer 0–1439 or null | No | DAILY or WEEKLY: minutes after midnight in the account’s timezone, e.g. 540 for 9:00. |
changes.scheduleDayOfWeek |
integer 0–6 or null | No | WEEKLY: 0 is Sunday, 6 is Saturday. |
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. |
Pause or resume a Worker
Section titled “Pause or resume a Worker”workers.set_status · write
Pause or resume a Worker.
- MCP tool:
pause_or_resume_worker. Loaded by default in MCP clients. - REST:
POST /v1/workers/set-status - CLI:
xholic workers set-status - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
workerId |
string (uuid) | Yes | |
status |
“ACTIVE” \ | “PAUSED” | 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. |
Run a Worker now
Section titled “Run a Worker now”workers.run · write
Queue a Worker to write a new batch now with Xholic’s writer. Spends Xholic AI credits per post: quote first, show it to the user, and pass confirmCredits after they agree. Returns right away; drafts arrive in get_worker_drafts.
- MCP tool:
run_worker. Loaded by default in MCP clients. - REST:
POST /v1/workers/run - CLI:
xholic workers run - Scope:
write - Plan: Pro plan or higher
- Cost: Xholic AI: up to about 120 credits (Xholic’s Worker writer, charged per post in the batch). Returns a quote first; pass
confirmCreditsafter the user agrees. - Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
neuronId |
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. |
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. |
Create the ready-made Worker
Section titled “Create the ready-made Worker”workers.create_ready_made · write
Create the preset Worker built from the account’s context (voice, creators it already has posts for, products). Fails while a ready-made Worker exists; rebuild that one instead. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_create_ready_made. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/create-ready-made - CLI:
xholic workers create-ready-made - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
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. |
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. |
Rebuild the ready-made Worker
Section titled “Rebuild the ready-made Worker”workers.rebuild_ready_made · write
Refresh the ready-made Worker’s creators and brief from the account’s current context. Name, schedule, drafts and runs stay; no run starts. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_rebuild_ready_made. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/rebuild-ready-made - CLI:
xholic workers rebuild-ready-made - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string ≤ 160 chars | Yes | Worker id from get_workers. |
keepInstructions |
boolean | No | Keep the user’s own brief and refresh only voice and creators. |
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. |
Stop a queued Worker run
Section titled “Stop a queued Worker run”workers.cancel_queued_run · write
Stop a Worker run that is queued and hasn’t started yet. Its credits are returned. A run that already started can’t be stopped.
- MCP tool:
workers_cancel_queued_run. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/cancel-queued-run - CLI:
xholic workers cancel-queued-run - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string ≤ 160 chars | Yes | Worker id from get_workers. |
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. |
Worker runs
Section titled “Worker runs”workers.runs · read
Recent Worker runs, newest first: status, trigger, credits and why a run failed or was skipped.
- MCP tool:
workers_runs. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/workers/runs - CLI:
xholic workers runs - Scope:
read - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
limit |
integer 1–100 | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Takes and expertise
Section titled “Takes and expertise”workers.voice · read
The account’s takes (opinions) and expertise areas that Workers write from, each marked as mined or added by the user.
- MCP tool:
workers_voice. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/workers/voice - CLI:
xholic workers voice - 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. |
Add a take
Section titled “Add a take”workers.add_take · write
Add an opinion the user holds, in their words, for Workers to write from. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_add_take. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/add-take - CLI:
xholic workers add-take - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
text |
string ≤ 200 chars | 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. |
Remove a take
Section titled “Remove a take”workers.remove_take · write
Remove a take so Workers stop writing from it. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_remove_take. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/remove-take - CLI:
xholic workers remove-take - 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 ≤ 64 chars | Yes | Take id from workers.voice. |
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 an expertise area
Section titled “Add an expertise area”workers.add_expertise · write
Add a subject the account teaches, so Workers write knowledge posts about it. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_add_expertise. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/add-expertise - CLI:
xholic workers add-expertise - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
name |
string ≤ 80 chars | 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. |
Remove an expertise area
Section titled “Remove an expertise area”workers.remove_expertise · write
Remove an expertise area and its insight cards. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_remove_expertise. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/remove-expertise - CLI:
xholic workers remove-expertise - 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 ≤ 64 chars | Yes | Expertise area id from workers.voice. |
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. |
Review a Worker draft
Section titled “Review a Worker draft”workers.review_draft · write
Move a Worker draft: DRAFT keeps it in the user’s drafts, DISMISSED throws it away, TO_REVIEW puts it back in review. When dismissing because it isn’t the user’s opinion, pass reason NOT_MY_OPINION so Workers learn. To post or schedule it, use schedule_post with its text. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
review_worker_draft. Loaded by default in MCP clients. - REST:
POST /v1/workers/review-draft - CLI:
xholic workers review-draft - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string ≤ 160 chars | Yes | Worker draft id from get_worker_drafts. |
status |
“TO_REVIEW” \ | “DRAFT” \ | “DISMISSED” |
reason |
“NOT_MY_OPINION” | No | Only with DISMISSED: why, when it teaches the Workers something. |
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. |
More or less like this
Section titled “More or less like this”workers.draft_feedback · write
Tell the Workers to write more or fewer drafts like this one. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_draft_feedback. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/draft-feedback - CLI:
xholic workers draft-feedback - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string ≤ 160 chars | Yes | Worker draft id from get_worker_drafts. |
action |
“MORE_LIKE_THIS” \ | “LESS_LIKE_THIS” | 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. |
Worker meme image
Section titled “Worker meme image”workers.draft_meme · write
The reaction image (GIF or meme) attached to a Worker meme draft. The first call picks one.
- MCP tool:
workers_draft_meme. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/draft-meme - CLI:
xholic workers draft-meme - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Worker draft id of a meme draft. |
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. |
Change a Worker meme image
Section titled “Change a Worker meme image”workers.set_draft_meme · write
Swap or remove the reaction image on a Worker meme draft. Pass pick null to remove it. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
workers_set_draft_meme. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/workers/set-draft-meme - CLI:
xholic workers set-draft-meme - Scope:
write - Plan: Pro plan or higher
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Worker draft id of a meme draft. |
kind |
“gifs” \ | “memes” | Yes |
pick |
object or null | Yes | A pick as returned by workers.draft_meme, or null to remove the image. |
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. |