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

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

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

Applying over resources that already exist

apply takes a mode query parameter. It defaults to create_only, which fails if any resource in the manifest already exists, because the manifest is treated as a closed world: a reference to a bucket that exists but is not declared is a validation error. Use create_missing to add to a namespace that already has resources. It creates what is missing, leaves what exists alone, and resolves references against the resources already in the namespace.

# Add these collections over buckets that are already there
curl -X POST "https://api.mixpeek.com/v1/manifest/apply?mode=create_missing" \
  -H "Authorization: Bearer $API_KEY" \
  -F "manifest_file=@collections.yaml"

dry_run=true validates without creating anything. If a resource fails partway through, apply rolls back the ones it already created.

Core Operations

Operation	Description
Apply	Create all resources defined in the manifest. `mode=create_only` (default) fails if anything exists; `mode=create_missing` fills the gaps
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:

Namespaces - Isolation boundaries with feature extractors
Buckets - Object storage with schemas
Collections - Document stores with indexing
Taxonomies - Classification hierarchies
Clusters - Grouping configurations
Retrievers - Search pipelines

Secret References

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

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

# 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

# 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

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

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Quick Start

Applying over resources that already exist

Core Operations

Resource Types

Secret References

Dependency Resolution

Workflows

Environment Replication

Pre-deployment Validation

CI/CD Integration

References

​Quick Start

​Applying over resources that already exist

​Core Operations

​Resource Types

​Secret References

​Dependency Resolution

​Workflows

​Environment Replication

​Pre-deployment Validation

​CI/CD Integration

​References

Quick Start

Applying over resources that already exist

Core Operations

Resource Types

Secret References

Dependency Resolution

Workflows

Environment Replication

Pre-deployment Validation

CI/CD Integration

References