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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.