# Library actions

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

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

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

## Saved posts

`library.saved` · read

The account's X bookmarks and likes mirrored by Xholic, plus saved posts. Bookmarks show taste.

- **MCP tool:** `get_saved_posts`. Loaded by default in MCP clients.
- **REST:** `GET /v1/library/saved`
- **CLI:** `xholic library saved`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string ≤ 120 chars | No | Words to look for in the saved posts; omit for the newest. |
| `kind` | "bookmarks" \\| "likes" \\| "all" | No | Default: `"all"`. |
| `questionsOnly` | boolean | No | Only posts that ask a question. Default: `false`. |
| `limit` | integer 1–20 | No | Default: `10`. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Save a post

`library.save` · write

Save an X post to the user's library by its id. Use library.save_by_url for a URL.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tweetId` | string | Yes | X post id (digits). |
| `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. |

## Save a post by URL

`library.save_by_url` · write

Save an X post to the user's library from its URL.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string ≤ 2048 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 saved post

`library.unsave` · write

Remove a post from the user's library. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tweetId` | string | Yes | X post id (digits). |
| `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. |