> ## Documentation Index
> Fetch the complete documentation index at: https://pixelcut.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Assets & Collections

> Upload, organize, and search your media assets from MCP.

Assets are the images and videos in your Pixelcut workspace. Collections let you organize them into groups. Both are fully manageable from the MCP server.

## Assets

### MCP tools

The `assets` tool supports `list`, `search`, and `get` actions. Use the `upload` tool to import from URLs or get a one-time upload URL for local files.

| Action                  | Description                                                      |
| ----------------------- | ---------------------------------------------------------------- |
| `assets` (`list`)       | List assets, with optional filters by collection, tag, or status |
| `assets` (`search`)     | Search by keyword or semantic similarity                         |
| `assets` (`get`)        | Fetch metadata and a fresh URL for a single asset                |
| `upload` (`url`)        | Import an image from a public URL                                |
| `upload` (`upload_url`) | Get a one-time upload URL for a local file                       |

### Importing files

Ask the agent to import an image from a URL:

```
Import this product photo into my workspace: https://example.com/photo.jpg
```

The agent calls `upload` with `action: "url"` and returns the new asset ID:

```json theme={null}
{
  "id": "ast_abc123",
  "url": "https://assets.pixelcut.app/ast_abc123.png",
  "content_type": "image/png"
}
```

### Listing and filtering

```
List the assets in my "Summer Campaign" collection.
```

```
Find product photos tagged "hero" that are ready to use.
```

The agent calls `assets` with `action: "list"` and the appropriate filters (`collection_id`, `tag`, or `status`).

### Searching assets

Search uses semantic similarity — describe what you are looking for in natural language:

```
Find images of red sneakers on a white background.
```

<Info>
  Semantic search requires a Business tier subscription.
</Info>

## Collections

Collections are named groups of assets. Use them to organize uploads, target batch operations, and keep related assets together.

### MCP actions

The `collections` tool supports `list`, `search`, `get`, and `create` actions.

| Action                   | Description                |
| ------------------------ | -------------------------- |
| `collections` (`list`)   | List all collections       |
| `collections` (`search`) | Search collections by name |
| `collections` (`get`)    | Get a collection by ID     |
| `collections` (`create`) | Create a new collection    |

### Creating a collection

```
Create a new collection called "Summer Campaign" and put the images we just generated into it.
```

The agent calls `collections` (action: `create`), then references the new collection ID in subsequent operations.

## Common workflows

### Organize generated content

```
Generate 5 product shots, then save them all to a new "Q3 Hero Shots" collection.
```

The agent calls `generate_media` to produce the images, `collections` (`create`) for the new collection, and includes the `collection_id` so generated assets land directly in the right place.

### Find and process

```
Find my outdoor furniture photos and remove the background from the best one.
```

The agent calls `assets` (`search`), then `edit_image` with `action: "remove_background"` on the chosen result.

<Info>
  You cannot delete assets, collections, or share links via MCP. Use the Pixelcut web app for deletion.
</Info>