# Ask Xholic actions

> Ask Xholic: 8 Xholic actions (4 read, 4 change), each with its MCP tool, REST endpoint and CLI command.

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

8 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.

## Hand a job to Xholic

`ask.start` · write

Hand a long job to Xholic's own agent, e.g. 'find 30 leads, research each and draft DMs'. Uses Xholic AI credits: quote first, show it to the user, pass confirmCredits after they agree. Returns a task id; read progress with ask.task.

- **MCP tool:** `ask_xholic`. Loaded by default in MCP clients.
- **REST:** `POST /v1/ask/start`
- **CLI:** `xholic ask start`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Xholic AI: up to about 25 credits (Ask Xholic, charged for what the job uses up to this amount). Returns a quote first; pass `confirmCredits` after the user agrees.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `task` | string ≤ 8000 chars | Yes | The job, in the user's words. |
| `model` | "luna" \\| "sol" \\| "sonnet" \\| "astra" \\| "opus" \\| "fable" | No | Ask model. Defaults to sonnet. Advanced models need Max. |
| `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. |

## Ask job status

`ask.task` · read

Status and answer of a job started with ask_xholic or draft_with_xholic.

- **MCP tool:** `ask_task`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/ask/task`
- **CLI:** `xholic ask task`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `taskId` | string ≤ 120 chars | Yes |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Ask conversations

`ask.conversations` · read

The user's past Ask conversations, newest first, with search and paging.

- **MCP tool:** `ask_conversations`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/ask/conversations`
- **CLI:** `xholic ask conversations`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string ≤ 120 chars | No |  |
| `cursor` | string (uuid) | No | Cursor from the previous page. |
| `limit` | integer 1–50 | No |  |
| `status` | "ACTIVE" \\| "ARCHIVED" | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Ask conversation

`ask.conversation` · read

One Ask conversation with its messages and drafts.

- **MCP tool:** `ask_conversation`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/ask/conversation`
- **CLI:** `xholic ask conversation`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Conversation id from ask.conversations. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Ask models and skills

`ask.catalog` · read

Ask's models the plan can use, its built-in skills (playbooks) and the user's custom skills.

- **MCP tool:** `ask_catalog`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/ask/catalog`
- **CLI:** `xholic ask catalog`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **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. |

## Create an Ask skill

`ask.create_skill` · write

Save a reusable Ask skill: a named prompt the user can run again. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `ask_create_skill`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/ask/create-skill`
- **CLI:** `xholic ask create-skill`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`
- **Undo:** from the activity log, which runs `ask.delete_skill`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string ≤ 80 chars | Yes |  |
| `description` | string ≤ 200 chars or null | No |  |
| `prompt` | string ≤ 4000 chars | Yes | What Ask should do when the skill runs, in the user's words. |
| `model` | "luna" \\| "sol" \\| "sonnet" \\| "opus" \\| "astra" \\| "fable" or null | No | Ask model the skill runs on; leave out for the user's default. |
| `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 an Ask skill

`ask.update_skill` · write

Replace a custom Ask skill's title, description, prompt and model. Send every field: this is a full replace. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `ask_update_skill`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/ask/update-skill`
- **CLI:** `xholic ask update-skill`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `skillId` | string (uuid) | Yes | Custom skill id from ask.catalog. |
| `title` | string ≤ 80 chars | Yes |  |
| `description` | string ≤ 200 chars or null | No |  |
| `prompt` | string ≤ 4000 chars | Yes | What Ask should do when the skill runs, in the user's words. |
| `model` | "luna" \\| "sol" \\| "sonnet" \\| "opus" \\| "astra" \\| "fable" or null | No | Ask model the skill runs on; leave out for the user's default. |
| `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 Ask skill

`ask.delete_skill` · write

Delete a custom Ask skill. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `ask_delete_skill`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/ask/delete-skill`
- **CLI:** `xholic ask delete-skill`
- **Scope:** `write`. Destructive: it can't be taken back
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `skillId` | string (uuid) | Yes | Custom skill id from ask.catalog. |
| `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. |