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

# Versioning & Status

> Understanding the versioning and status management system in Metabind

Metabind uses a consistent versioning and status management system across Components, Content Types, and Content. All entities follow the same lifecycle pattern with minor variations in how they are published.

## Entity Status States

All entities can exist in one of five status states:

### Draft

Initial status for entities that have never been published.

* Version is `null` (no version number yet)
* `lastPublishedVersion` is `null`
* Working status where changes can be made freely
* Updates overwrite previous changes without creating versions
* Remains in draft until first publication

```json theme={null}
{
  "status": "draft",
  "version": null,
  "lastPublishedVersion": null
}
```

### Modified

Status for published entities with unpublished changes.

* Version is `null` (working copy)
* `lastPublishedVersion` contains the last published version number
* Original published version remains unchanged and available
* Can discard changes to revert to published version
* Changes get new version number when published

```json theme={null}
{
  "status": "modified",
  "version": null,
  "lastPublishedVersion": 3
}
```

### Published

Entities that have been published and are immutable.

* Has a version number (sequential integers: 1, 2, 3, etc.)
* Content is **immutable** and cannot be changed
* Must create a working copy to make changes (status becomes 'modified')
* Referenced by other entities or packages

```json theme={null}
{
  "status": "published",
  "version": 3,
  "lastPublishedVersion": 3
}
```

### Unpublished

Previously published entities made unavailable.

<Note>
  Only available for Content Types and Content (not Components).
</Note>

* Version number remains unchanged
* Not available for new usage but existing references maintained
* Can be re-published or edited (creates 'modified' working copy)

```json theme={null}
{
  "status": "unpublished",
  "version": 3,
  "lastPublishedVersion": 3
}
```

### Deleted

Soft-deleted entities.

* Preserves complete version history
* Maintains availability in existing packages/references
* Can be restored to draft or modified status
* Prevents inclusion in new packages or usage

```json theme={null}
{
  "status": "deleted",
  "version": 3,
  "lastPublishedVersion": 3
}
```

## Version Management Rules

| Rule               | Description                              |
| ------------------ | ---------------------------------------- |
| Version Numbers    | Sequential integers starting at 1        |
| Draft Entities     | Have `null` version (no version number)  |
| Published Versions | Are immutable and permanent              |
| Version Creation   | Only occurs during publication           |
| Version History    | All versions are preserved permanently   |
| Package References | Components in packages cannot be deleted |

## Publishing Flow

### Creating a New Entity

```mermaid theme={null}
graph LR
    A[Create] -->|status: draft| B[Edit freely]
    B --> B
    B -->|Publish| C[status: published, version: 1]
```

1. Starts in **draft** status with version `null`
2. Can be modified freely without versioning
3. First publication assigns **version 1**

### Editing a Published Entity

```mermaid theme={null}
graph LR
    A[Published v1] -->|Edit| B[Modified, working copy]
    B -->|Publish| C[Published v2]
    B -->|Discard| A
```

1. Creates working copy with status **modified**
2. Working copy has version `null`
3. Original published version remains available
4. Next publication creates **new version**

### Discarding Changes

* Only works for **modified** status (not draft)
* Reverts to last published version
* Cancels all unpublished changes

### Rollback Process

```mermaid theme={null}
graph LR
    A[Published v3] -->|Rollback to v1| B[Modified, content from v1]
    B -->|Publish| C[Published v4]
```

1. Creates new working copy from any previous version
2. Does **not** modify existing versions
3. New version created when published
4. Preserves complete version history

## Key Differences by Entity Type

| Entity            | How Published           | Can Be Unpublished | Version Trigger   |
| ----------------- | ----------------------- | ------------------ | ----------------- |
| **Components**    | Via Package creation    | No                 | Package inclusion |
| **Content Types** | Explicit publish action | Yes                | Publish action    |
| **Content**       | Explicit publish action | Yes                | Publish action    |

### Components

Components are published **automatically** when included in a Package:

```mermaid theme={null}
graph LR
    A[Draft Component] -->|Create Package| B[Published Component v1]
    C[Modified Component] -->|Create Package| D[Published Component v2]
```

* No explicit "publish component" action
* Version assigned when package is created
* All draft/modified components in project are published together

### Content Types & Content

Content Types and Content are published **explicitly**:

```http theme={null}
POST /app/v1/organizations/:orgId/projects/:projId/content-types/:id/publish
POST /app/v1/organizations/:orgId/projects/:projId/content/:id/publish
```

* Requires explicit publish action
* Can be unpublished later
* Version assigned immediately on publish

## Version History

All entities maintain complete version history:

```http theme={null}
GET /app/v1/organizations/:orgId/projects/:projId/components/:id/versions
GET /app/v1/organizations/:orgId/projects/:projId/content-types/:id/versions
GET /app/v1/organizations/:orgId/projects/:projId/content/:id/versions
```

Response:

```json theme={null}
{
  "data": [
    {
      "version": 3,
      "status": "published",
      "content": "...",
      "createdAt": "2024-03-20T10:00:00Z",
      "createdBy": "user123"
    },
    {
      "version": 2,
      "status": "published",
      "content": "...",
      "createdAt": "2024-03-15T10:00:00Z",
      "createdBy": "user123"
    }
  ]
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use draft status for iteration">
    Keep entities in draft status while actively developing. This allows unlimited changes without creating version history clutter.
  </Accordion>

  <Accordion title="Create packages at logical milestones">
    Since packages publish all components, create them at meaningful milestones rather than after every small change.
  </Accordion>

  <Accordion title="Use rollback for reverting content">
    Instead of manually recreating old content, use the rollback endpoint to create a working copy from any previous version.
  </Accordion>

  <Accordion title="Don't delete components in use">
    Components referenced by packages cannot be deleted. Use the deleted status to prevent future use while maintaining existing references.
  </Accordion>
</AccordionGroup>