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

# Packages Overview

> Packages create immutable snapshots of all components for versioned distribution

# Packages

Packages enable version control and dependency management at the project level by creating immutable snapshots of all components and their bound assets at a specific point in time. Each package uses semantic versioning and can be referenced by other projects.

## Key Concepts

| Concept | Description |
| - | - |
| **Immutable Snapshots** | Packages cannot be modified after creation |
| **Semantic Versioning** | Uses MAJOR.MINOR.PATCH format (e.g., `1.0.0`) |
| **Auto-Publishing** | Creating a package publishes all draft/modified components |
| **Asset Bundling** | All component-bound assets are included |
| **Dependency Resolution** | Project dependencies are snapshotted |

## What Happens When You Create a Package

1. **Draft components** (never published) → `published` status with version 1
2. **Modified components** → `published` status with incremented version
3. **Published components** (unchanged) → included at current version
4. **Collection structure** is flattened (not preserved in packages)
5. **All bound assets** are captured and included

## Package Object

### Fields

| Field | Type | Description |
| - | - | - |
| `version` | string | Semantic version (e.g., `1.0.0`) |
| `components` | object\[] | Array of component snapshots |
| `components[].id` | string | Component ID |
| `components[].version` | number | Component version at time of capture |
| `components[].hash` | string | SHA-256 hash of the component's code |
| `components[].status` | string | Component status at time of capture |
| `assets` | object\[] | Array of bundled assets |
| `assets[].id` | string | Asset ID |
| `assets[].name` | string | Asset friendly name |
| `assets[].url` | string | CDN URL |
| `assets[].componentId` | string | Owning component ID |
| `dependencies` | object\[] | Snapshotted project dependencies |
| `metadata` | object | Package metadata |
| `metadata.author` | string | Creator |
| `metadata.description` | string | Package description |
| `metadata.tags` | string\[] | Categories |
| `createdAt` | string | Creation timestamp |
| `updatedAt` | string | Last update timestamp |

### Example Package

```json theme={null}
{
  "version": "1.0.0",
  "components": [
    {
      "id": "comp123",
      "version": 5,
      "hash": "sha256:b064acd1b548604fd6253fd69e32b9d60f7f5f75aff8094fa96b76cefdadb079",
      "status": "published"
    },
    {
      "id": "comp124",
      "version": 2,
      "hash": "sha256:22fbe0367fb61ec8aa439296baa45dbc2664d3af0d8c9d59c397e08063dec3df",
      "status": "published"
    }
  ],
  "assets": [
    {
      "id": "asset123",
      "name": "logo-primary",
      "url": "https://cdn.metabind.ai/assets/logo-2x.png",
      "componentId": "comp123"
    }
  ],
  "dependencies": [
    {
      "projectId": "proj456",
      "version": "2.0.0"
    }
  ],
  "metadata": {
    "author": "jane.doe@metabind.ai",
    "description": "Core UI components v1",
    "tags": ["ui", "core"]
  },
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}
```

## Package Creation Process

```mermaid theme={null}
graph TD
    A[Create Package Request] --> B[Identify Changed Components]
    B --> C[Assign New Version Numbers]
    C --> D[Update Component Status to Published]
    D --> E[Capture Bound Assets]
    E --> F[Snapshot Dependencies]
    F --> G[Create Immutable Package]
```

### Version Assignment

| Previous Status | New Status | Version Change |
| - | - | - |
| `draft` (never published) | `published` | `null` → `1` |
| `modified` | `published` | `n` → `n+1` |
| `published` (unchanged) | `published` | No change |

## Base URL

All package endpoints use this base path:

```
/app/v1/organizations/:organizationId/projects/:projectId/packages
```


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