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

# Assets Overview

> Manage media files including images, videos, and documents through the Metabind API

Assets represent media files (images, videos, documents, etc.) stored on the CDN and managed through Metabind. Assets referenced by Packages are preserved to maintain package integrity.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Package Integration" icon="box">
    Assets referenced by packages are immutable. Package references prevent deletion, and new versions can be created while maintaining package integrity.
  </Card>

  <Card title="Status Management" icon="toggle-on">
    Assets can be active or deleted. Deletion is prevented if referenced. Soft-delete preserves history.
  </Card>

  <Card title="CDN Integration" icon="cloud">
    All assets are served through CDN with versioned URLs, cache control headers, and geographic distribution.
  </Card>

  <Card title="Optimization" icon="wand-magic-sparkles">
    On-demand transformations including format conversion, size optimization, and quality adjustments.
  </Card>
</CardGroup>

## Asset Object

The Asset object contains all metadata and references for a media file.

### Fields

| Field         | Type      | Description                                         |
| ------------- | --------- | --------------------------------------------------- |
| `id`          | string    | Unique identifier (UUID)                            |
| `name`        | string    | Display name                                        |
| `description` | string    | Structured markdown description for semantic search |
| `type`        | string    | MIME type (e.g., `image/jpeg`, `video/mp4`)         |
| `url`         | string    | CDN URL                                             |
| `status`      | string    | Status: `active` or `deleted`                       |
| `size`        | number    | File size in bytes                                  |
| `tags`        | string\[] | Asset categories                                    |
| `createdAt`   | string    | Creation timestamp (ISO format)                     |
| `updatedAt`   | string    | Last update timestamp (ISO format)                  |

### Metadata Object

| Field                       | Type      | Description                               |
| --------------------------- | --------- | ----------------------------------------- |
| `metadata.width`            | number    | Image width in pixels (if applicable)     |
| `metadata.height`           | number    | Image height in pixels (if applicable)    |
| `metadata.duration`         | number    | Media duration in seconds (if applicable) |
| `metadata.format`           | string    | File format                               |
| `metadata.usage.components` | string\[] | Components referencing this asset         |
| `metadata.usage.packages`   | string\[] | Packages containing this asset            |
| `metadata.usage.content`    | string\[] | Content items using this asset            |

### Example

```json theme={null}
{
  "id": "asset123",
  "name": "hero-image.jpg",
  "description": "Hero banner image for homepage header. High-resolution landscape image showcasing product features.\n\n**Usage:** Homepage hero section, marketing campaigns\n**Dimensions:** 1920x1080\n**Format:** JPEG (optimized for web)\n**Subject:** Product showcase with lifestyle elements",
  "type": "image/jpeg",
  "status": "active",
  "url": "https://cdn.metabind.ai/images/hero-image.jpg",
  "size": 2048576,
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "jpeg",
    "usage": {
      "components": ["comp123"],
      "packages": ["1.0.0", "1.1.0"],
      "content": ["cont123"]
    }
  },
  "tags": ["hero", "article"],
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}
```

## Description Field Standards

The asset description field follows a structured markdown format optimized for semantic search and LLM understanding.

### Template

```markdown theme={null}
[Brief description of the asset]. [Additional context about usage or content].

**Usage:** [Where/how this asset is typically used]
**Dimensions:** [Width x Height for images]
**Duration:** [Length for video/audio]
**Format:** [File format and optimization details]
**Subject:** [What the asset depicts or contains]
```

<Note>
  Aim for 200-300 characters. Maximum 400 characters.
</Note>

### Examples

<Tabs>
  <Tab title="Image">
    ```markdown theme={null}
    Hero banner image for homepage header. High-resolution landscape image showcasing product features.

    **Usage:** Homepage hero section, marketing campaigns
    **Dimensions:** 1920x1080
    **Format:** JPEG (optimized for web)
    **Subject:** Product showcase with lifestyle elements
    ```
  </Tab>

  <Tab title="Video">
    ```markdown theme={null}
    Product demonstration video showing key features. Professional studio recording with voiceover.

    **Usage:** Product pages, onboarding flows
    **Duration:** 2:34
    **Format:** MP4 (H.264, 1080p)
    **Subject:** Step-by-step product usage guide
    ```
  </Tab>

  <Tab title="Document">
    ```markdown theme={null}
    Product specification sheet with technical details. Comprehensive PDF document for B2B customers.

    **Usage:** Sales materials, customer support
    **Pages:** 12
    **Format:** PDF (searchable, print-ready)
    **Subject:** Technical specifications and compliance data
    ```
  </Tab>
</Tabs>