Inspiration actions
2 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.
Search the inspiration library
Section titled “Search the inspiration library”inspiration.search · read
Find the starting point for a post: Xholic’s library of millions of proven X posts, searched by meaning. Ranked by how far each post beat its author’s usual (timesTheirUsual), among authors near the account’s size, with each post’s shape (personal_story, networking…). Pass the post’s idea as query, a shape to narrow it, and 1–4 keywords: when the library has too few, it runs one live X search with them and saves what it finds. Free: no Xholic credits. Build from the shape, never the wording; pass the ids you build from as sourcePostIds to check_draft and show_drafts.
- MCP tool:
search_inspiration. Loaded by default in MCP clients. - REST:
GET /v1/inspiration/search - CLI:
xholic inspiration search - Scope:
read - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
query |
string ≤ 200 chars | Yes | The idea of the post you’re writing, in plain words, e.g. “haven’t written code by hand in months”. |
keywords |
array of string ≤ 60 chars (max 2) | No | 1–4 words a matching post would contain, for the live X fallback (X search matches words, not meaning), e.g. [“vs code”, “zed editor”]. |
shape |
“relatable_scene” \ | “one_liner” \ | “contrast_pair” \ |
size |
“near_me” \ | “any” \ | “lt1k” \ |
sort |
“beat_usual” \ | “relevance” \ | “top” |
timeRange |
“week” \ | “month” \ | “3months” \ |
limit |
integer 1–10 | No | Default: 8. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Explain a post’s structure
Section titled “Explain a post’s structure”inspiration.explain_structure · write
Xholic AI breaks down why an Inspiration post works: hook, structure and reusable pattern. Cached posts are free. Uses Xholic AI credits otherwise: quote first and pass confirmCredits after the user agrees. You can usually explain it yourself from get_post.
- MCP tool:
inspiration_explain_structure. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/inspiration/explain-structure - CLI:
xholic inspiration explain-structure - Scope:
write - Plan: Every plan, including the trial
- Cost: Xholic AI: up to about 1 credits (Xholic’s structure explainer). Returns a quote first; pass
confirmCreditsafter the user agrees. - Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
tweetId |
string ≤ 100 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. |
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. |
