# Inspiration actions

> Inspiration: 2 Xholic actions (1 read, 1 change), each with its MCP tool, REST endpoint and CLI command.

Source: https://docs.xholic.ai/actions/inspiration/

2 actions. Every field marked *Required* must be sent; `account`, `dryRun`, `idempotencyKey`, `confirmCredits` and `quoteId` are the [control fields](/api/responses/#control-fields) every surface adds.

## Search the inspiration library

`inspiration.search` · read

Search Xholic's library of proven posts by idea, with outlier scores (how far a post beat its author's normal).

- **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 |  |
| `timeRange` | "week" \\| "month" \\| "3months" \\| "year" \\| "all" | No | Default: `"year"`. |
| `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

`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 with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/inspiration/explain-structure`
- **CLI:** `xholic inspiration explain-structure`
- **Scope:** `write`
- **Plan:** Max plan or higher
- **Cost:** Xholic AI: up to about 1 credits (Xholic's structure explainer). Returns a quote first; pass `confirmCredits` after 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. |