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

# Search Assets

> Search for media assets using filters or semantic search

Search for assets using standard filters or semantic search.

<Note>
  Assets must be uploaded through the Metabind interface before they can be referenced in content. The MCP tools provide discovery and search capabilities, not upload functionality.
</Note>

## Input Schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Project ID (optional, uses session default if not provided)"
    },
    "query": {
      "type": "string",
      "description": "Natural language query for semantic search. When provided, results are ranked by relevance."
    },
    "type": {
      "type": "string",
      "description": "Filter by MIME type or category (image/*, video/*, etc.)"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Filter by tags. Accepts tag names or IDs."
    },
    "page": {
      "type": "number",
      "default": 1,
      "description": "Page number for paginated results (1-based indexing)"
    },
    "limit": {
      "type": "number",
      "default": 20,
      "maximum": 100,
      "description": "Maximum items to return per page"
    }
  }
}
```

## Parameters

| Parameter   | Type      | Default         | Description                                         |
| ----------- | --------- | --------------- | --------------------------------------------------- |
| `projectId` | string    | session default | Project to search in                                |
| `query`     | string    | -               | Natural language semantic search query              |
| `type`      | string    | -               | Filter by MIME type (e.g., `image/jpeg`, `image/*`) |
| `tags`      | string\[] | -               | Filter by tags                                      |
| `page`      | number    | 1               | Page number                                         |
| `limit`     | number    | 20              | Items per page (max 100)                            |

## Response

| Field                       | Type      | Description                                 |
| --------------------------- | --------- | ------------------------------------------- |
| `items`                     | array     | Array of asset objects                      |
| `items[].id`                | string    | Unique asset identifier                     |
| `items[].name`              | string    | Display name for the asset                  |
| `items[].description`       | string    | Asset description or metadata               |
| `items[].type`              | string    | MIME type of the asset                      |
| `items[].url`               | string    | CDN URL for accessing the asset             |
| `items[].dimensions`        | object    | Asset dimensions (for images/videos)        |
| `items[].dimensions.width`  | number    | Width in pixels                             |
| `items[].dimensions.height` | number    | Height in pixels                            |
| `items[].size`              | number    | File size in bytes                          |
| `items[].tags`              | string\[] | Categorization tags                         |
| `items[].similarity`        | number    | Similarity score 0-1 (when `query` is used) |
| `total`                     | number    | Total number of matching items              |

## Examples

### Semantic Search

Search for assets using natural language:

```json theme={null}
{
  "query": "team collaboration workspace"
}
```

Response:

```json theme={null}
{
  "items": [
    {
      "id": "asset-workspace-001",
      "name": "Workspace Collaboration",
      "description": "The Acme design team collaborating on the new unified component library at their San Francisco headquarters.",
      "type": "image/jpeg",
      "url": "https://cdn.metabind.ai/org123/proj123/assets/workspace-collaboration.jpg",
      "dimensions": {
        "width": 2048,
        "height": 1366
      },
      "size": 524288,
      "tags": ["team", "collaboration", "design-system"],
      "similarity": 0.95
    }
  ],
  "total": 1
}
```

### Filter by Type

Find all JPEG images:

```json theme={null}
{
  "type": "image/jpeg"
}
```

### Filter by Tags

Find assets with specific tags:

```json theme={null}
{
  "tags": ["hero", "banner"]
}
```

### Combined Filters

Search for hero images using semantic search:

```json theme={null}
{
  "query": "professional office environment",
  "type": "image/*",
  "tags": ["hero"]
}
```

## Common MIME Types

| Type              | Description   |
| ----------------- | ------------- |
| `image/jpeg`      | JPEG images   |
| `image/png`       | PNG images    |
| `image/gif`       | GIF images    |
| `image/webp`      | WebP images   |
| `image/svg+xml`   | SVG graphics  |
| `video/mp4`       | MP4 videos    |
| `video/webm`      | WebM videos   |
| `application/pdf` | PDF documents |

Use `image/*` or `video/*` to match all images or videos respectively.

## Using Assets in Content

When creating content, reference assets by their ID:

```json theme={null}
{
  "asset": {
    "id": "asset-workspace-001"
  }
}
```

The full asset details (URL, dimensions, etc.) are resolved automatically when the content is rendered.

<Warning>
  Always verify asset IDs exist before referencing them in content. Use `search_assets` to find valid asset IDs. Non-existent asset references will cause validation errors during content creation.
</Warning>