# Collections actions

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

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

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

## Collections

`collections.list` · read

The user's saved-post collections with counts.

- **MCP tool:** `collections_list`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/collections/list`
- **CLI:** `xholic collections list`
- **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 a collection

`collections.create` · write

Create a collection for saved posts. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string ≤ 100 chars | Yes |  |
| `emoji` | string ≤ 10 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. |

## Hooks collection

`collections.hooks` · write

Get the user's Hooks collection (for saved hook ideas), creating it if it doesn't exist.

- **MCP tool:** `collections_hooks`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/collections/hooks`
- **CLI:** `xholic collections hooks`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **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. |

## Move a saved post

`collections.move` · write

Put a saved post in a collection, or take it out with collectionId null.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tweetId` | string ≤ 100 chars | Yes |  |
| `collectionId` | string ≤ 100 chars or null | Yes | Collection id from collections.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. |

## Reorder collections

`collections.reorder` · write

Set the display order of collections, by id.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `orderedCollectionIds` | array of 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. |

## Rename a collection

`collections.rename` · write

Rename a collection or change its emoji (null removes it). Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string ≤ 100 chars | Yes | Collection id from collections.list. |
| `name` | string ≤ 100 chars | Yes |  |
| `emoji` | string ≤ 10 chars or null | 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. |

## Delete a collection

`collections.delete` · write

Delete a collection. Its posts stay saved, uncategorized. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `collections_delete`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/collections/delete`
- **CLI:** `xholic collections delete`
- **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 |
| --- | --- | --- | --- |
| `id` | string ≤ 100 chars | Yes | Collection id from collections.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. |