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

# Manifests

> Declarative resource configuration with YAML manifests

Manifests let you define Mixpeek resources in YAML files and apply them in a single operation. This enables version-controlled, reproducible infrastructure across environments.

## Quick Start

```yaml theme={null}
# mixpeek.yaml — a complete pipeline: ingest → index → search
version: "1.0"
metadata:
  name: "video-search-env"

namespaces:
  - name: video_search
    feature_extractors:
      - name: multimodal_extractor
        version: v1

buckets:
  - name: raw_videos
    namespace: video_search
    schema:
      properties:
        video: { type: video }

collections:
  - name: video_index
    namespace: video_search
    source:
      type: bucket
      bucket: raw_videos
    feature_extractor:
      feature_extractor_name: multimodal_extractor
      version: v1

retrievers:
  - name: video_search_tool
    namespace: video_search
    collections: [video_index]
    input_schema:
      query:
        type: text
        required: true
    stages:
      - stage_name: search
        stage_type: filter
        config:
          stage_id: feature_search
          parameters:
            searches:
              - collection_identifiers: [video_index]
                query:
                  input_mode: text
                  text: "{{INPUT.query}}"
                feature_uri: "mixpeek://multimodal_extractor@v1/embedding"
                top_k: 10
            final_top_k: 10
```

Every collection needs a `source` and a `feature_extractor`; every retriever needs `namespace`, `collections`, and its `stages` pipeline. `validate` names any missing field, warns on unknown top-level keys (a typo like `retreivers:` won't silently drop your search pipeline), and checks that references (`namespace`, `bucket`, collection names) resolve within the manifest.

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/manifest/apply \
  -H "Authorization: Bearer $API_KEY" \
  -F "manifest_file=@mixpeek.yaml"
```

## Core Operations

| Operation    | Description                                          |
| ------------ | ---------------------------------------------------- |
| **Apply**    | Create all resources defined in the manifest         |
| **Validate** | Check syntax, schema, and references without changes |
| **Export**   | Generate a manifest from existing resources          |
| **Diff**     | Compare manifest against current state               |

## Resource Types

Manifests support these resource types, applied in dependency order:

1. **Namespaces** - Isolation boundaries with feature extractors
2. **Buckets** - Object storage with schemas
3. **Collections** - Document stores with indexing
4. **Taxonomies** - Classification hierarchies
5. **Clusters** - Grouping configurations
6. **Retrievers** - Search pipelines

## Secret References

Use `${{ secrets.NAME }}` to reference organization secrets:

```yaml theme={null}
buckets:
  - name: external_data
    namespace: my_namespace
    sync:
      connection_id: ${{ secrets.S3_CONNECTION_ID }}
```

Secrets must exist before applying. Use the validate endpoint to check for missing secrets.

## Dependency Resolution

Resources are created in topological order. The manifest engine:

* Resolves cross-resource references automatically
* Detects circular dependencies
* Rolls back all changes if any creation fails

## Workflows

### Environment Replication

```bash theme={null}
# Export from production
curl https://api.mixpeek.com/v1/manifest/export \
  -H "Authorization: Bearer $PROD_KEY" \
  -o prod-manifest.yaml

# Apply to staging
curl -X POST https://api.mixpeek.com/v1/manifest/apply \
  -H "Authorization: Bearer $STAGING_KEY" \
  -F "manifest_file=@prod-manifest.yaml"
```

### Pre-deployment Validation

```bash theme={null}
# Validate without applying
curl -X POST https://api.mixpeek.com/v1/manifest/validate \
  -H "Authorization: Bearer $API_KEY" \
  -F "manifest_file=@mixpeek.yaml"

# Check what would change
curl -X POST https://api.mixpeek.com/v1/manifest/diff \
  -H "Authorization: Bearer $API_KEY" \
  -F "manifest_file=@mixpeek.yaml"
```

### CI/CD Integration

```yaml theme={null}
# GitHub Actions example
- name: Deploy Mixpeek Resources
  run: |
    curl -X POST https://api.mixpeek.com/v1/manifest/apply \
      -H "Authorization: Bearer ${{ secrets.MIXPEEK_API_KEY }}" \
      -F "manifest_file=@mixpeek.yaml"
```

## References

* [Apply Manifest](/docs/api-reference/manifest/apply-manifest)
* [Validate Manifest](/docs/api-reference/manifest/validate-manifest)
* [Export Manifest](/docs/api-reference/manifest/export-manifest)
* [Diff Manifest](/docs/api-reference/manifest/diff-manifest)