Skip to main content
POST
Create Collection

Authorizations

​
Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

​
X-Namespace
string
header
required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Body

application/json

Keys this body does not declare are ignored, and the response's warnings name them, until 2026-11-02; from 2026-11-02 they are refused with 422 extra_forbidden naming the accepted keys.

Request model for creating a new collection.

Collections process data from buckets or other collections using a single feature extractor.

KEY ARCHITECTURAL CHANGE: Each collection has EXACTLY ONE feature extractor.

  • Use field_passthrough to include additional source fields in output documents
  • Multiple extractors = multiple collections
  • This simplifies processing and makes output schema deterministic

CRITICAL: To use input_mappings:

  1. Your source bucket MUST have a bucket_schema defined
  2. The input_mappings reference fields from that bucket_schema
  3. The system validates that mapped fields exist in the source schema

Example workflow:

  1. Create bucket with schema: { "properties": { "image": {"type": "image"}, "title": {"type": "string"} } }
  2. Upload objects conforming to that schema
  3. Create collection with:
    • input_mappings: { "image": "image" }
    • field_passthrough: [{"source_path": "title"}]
  4. Output documents will have both extractor outputs AND passthrough fields

Schema Computation:

  • output_schema is computed IMMEDIATELY when collection is created
  • output_schema = field_passthrough fields + extractor output fields
  • No waiting for documents to be processed!
​
collection_name
string
required

Name of the collection to create

Examples:

"video_frames"

"product_embeddings"

​
source
SourceConfig · object
required

Source configuration (bucket or collection) for this collection

Examples:
​
description
string | null

Description of the collection

​
input_schema
BucketSchema · object | null

Input schema for the collection. If not provided, inferred from source bucket's bucket_schema or source collection's output_schema. REQUIRED for input_mappings to work - defines what fields can be mapped to feature extractors.

​
feature_extractor
FeatureExtractorConfig · object | null

Single feature extractor for this collection. Use field_passthrough within the extractor config to include additional source fields. For multiple extractors, create multiple collections and use collection-to-collection pipelines. DEPRECATED for direct use: prefer features: [...] (contract v2 §6.2, D9) — extractor names are internal implementation. MUTUALLY EXCLUSIVE with retriever_transform (provide exactly one).

Example:
​
features
string[] | null

What you want to search by: feature keys from GET /v1/collections/features (e.g. ['faces'] or ['custom:']). Resolved to the processing pipeline server-side — the preferred alternative to feature_extractor. Provide one or the other.

​
enabled
boolean
default:true

Whether the collection is enabled

​
metadata
Metadata · object | null

Additional metadata for the collection

​
schedule
CollectionScheduleConfig · object | null

Optional schedule for automatic re-processing. Creates a COLLECTION_TRIGGER trigger behind the scenes. Supports cron and interval schedules.

​
taxonomy_applications
TaxonomyApplicationConfig · object[] | null

Optional taxonomy applications to automatically enrich documents in this collection. Each taxonomy will classify/enrich documents based on configured retriever matches.

​
cluster_applications
ClusterApplicationConfig · object[] | null

Optional cluster applications to automatically execute when batch processing completes. Each cluster enriches documents with cluster assignments (cluster_id, cluster_label, etc.).

​
alert_applications
AlertApplicationConfig · object[] | null

Optional alert applications to automatically execute when documents are ingested. Each alert runs a retriever against new documents and sends notifications if matches are found. Supports both ON_INGEST (triggered per batch) and SCHEDULED (periodic) execution modes.

​
retriever_enrichments
RetrieverEnrichmentConfig · object[] | null

Optional retriever enrichments to run on documents during post-processing. Each enrichment executes a retriever pipeline and writes selected result fields back to the document. Use for: LLM classification, cross-collection joins, multi-stage enrichment at ingestion time.

​
retriever_transform
RetrieverTransformConfig · object | null

(#11): define this collection's BUILD STEP as an inline retriever pipeline run over its source (a materialized view). MUTUALLY EXCLUSIVE with feature_extractor/features — a collection is EITHER extractor-based OR transform-based. The source may be a collection or a bucket; a bucket is read through its system collection, one document per object, scoped to the objects in each batch. Distinct from retriever_enrichments (per-document post-processing referencing an existing retriever_id).

​
embedding_task
string | null

Override the embedding task hint for instruction-aware models (E5, Gemini). Defaults to 'retrieval_document' for indexing pipelines. Values: retrieval_document, retrieval_query, semantic_similarity, classification, clustering. Only change this if your primary use case is not retrieval (e.g., clustering or classification). Applied to all task-aware embedding models in this collection's extractor pipeline.

Response

Successful Response

Response model for collection endpoints.

​
collection_name
string
required

REQUIRED. Human-readable name for the collection. Must be unique within the namespace. Used for: Display, lookups (can query by name or ID), organization. Format: Alphanumeric with underscores/hyphens, 3-100 characters. Examples: 'product_embeddings', 'video_frames', 'customer_documents'.

Required string length: 3 - 100
Examples:

"video_frames"

"product_embeddings"

"customer_documents"

​
feature_extractor
FeatureExtractorConfig · object
required

REQUIRED. Single feature extractor configuration for this collection. For a transform-based collection (retriever_transform set) this is a placeholder sentinel; the retriever_transform defines the actual build. Defines: extractor name/version, input_mappings, field_passthrough, parameters. Task 9 change: ONE extractor per collection (previously supported multiple). For multiple extractors: Create multiple collections and use collection-to-collection pipelines. Use field_passthrough to include additional source fields beyond extractor outputs.

Example:
​
source
SourceConfig · object
required

REQUIRED. Source configuration defining where data comes from. Type 'bucket': Process objects from one or more buckets (tier 1). Type 'collection': Process documents from upstream collection(s) (tier 2+). For multi-bucket sources, all buckets must have compatible schemas. For multi-collection sources, all collections must have compatible schemas. Determines input_schema and enables decomposition trees.

Examples:
​
collection_id
string

NOT REQUIRED (auto-generated). Unique identifier for this collection. Used for: API paths, document queries, pipeline references. Format: 'col_' prefix + 10 random alphanumeric characters. Stable after creation - use for all collection references.

Examples:

"col_a1b2c3d4e5"

"col_xyz789abc"

"col_video_frames"

​
description
string | null

NOT REQUIRED. Human-readable description of the collection's purpose. Use for: Documentation, team communication, UI display. Common pattern: Describe what the collection contains and what processing is applied.

Example:

"Video frames extracted at 1 FPS with CLIP embeddings"

​
input_schema
BucketSchema · object | null

Auto-computed from source. Input schema defining fields available to the feature extractor. Source: bucket.bucket_schema (if source.type='bucket') OR upstream_collection.output_schema (if source.type='collection'). Determines: Which fields can be used in input_mappings and field_passthrough. This is the 'left side' of the transformation - what data goes IN. Format: BucketSchema with properties dict. Use for: Validating input_mappings, configuring field_passthrough.

Example:
​
output_schema
BucketSchema · object | null

Auto-computed at creation. Output schema defining fields in final documents. Computed as: field_passthrough fields + extractor output fields (deterministic). Known IMMEDIATELY when collection is created - no waiting for documents! This is the 'right side' of the transformation - what data comes OUT. Use for: Understanding document structure, building queries, schema validation. Example: {title (passthrough), embedding (extractor output)} = output_schema.

Example:
​
source_bucket_schemas
Source Bucket Schemas · object | null

NOT REQUIRED (auto-computed). Snapshot of bucket schemas at collection creation. Only populated for multi-bucket collections (source.type='bucket' with multiple bucket_ids). Key: bucket_id, Value: BucketSchema at time of collection creation. Used for: Schema compatibility validation, document lineage, debugging. Schema snapshot is immutable - bucket schema changes after collection creation do not affect this. Single-bucket collections may omit this field (schema in input_schema is sufficient).

Example:

null

​
source_lineage
SingleLineageEntry · object[]

NOT REQUIRED (auto-computed). Lineage chain showing complete processing history. Each entry contains: source_config, feature_extractor, output_schema for one tier. Length indicates processing depth (1 = tier 1, 2 = tier 2, etc.). Use for: Understanding multi-tier pipelines, visualizing decomposition trees.

Examples:
​
index_map
Index Map · object | null

Which feature URI answers each URI a search names, for a collection that opted into feature URIs as its version contract. Null (the default) means not opted in: a search uses the URI it names. Each key is one of the collection's own feature URIs; each value is a URI the collection holds vectors for, listed in vector_indexes (its own, or one a completed reembed.target_feature_uri added). Switching to a new embedding model and rolling back are both PATCH /v1/collections/{collection_id} with a new map; neither rewrites a vector. Every search result reports the URI that scored it in feature_uri.

Example:
​
vector_indexes
CollectionVectorIndex · object[]

NOT REQUIRED (auto-computed). Vector indexes for semantic search. Populated from feature_extractor.required_vector_indexes on extractor-backed collections, and from the namespace vector config on promoted or direct-upsert (BYO) collections, where each entry carries source='namespace_vector_config'. Defines which embeddings are indexed, their dimensions and distance metric. Use for understanding search capabilities and debugging vector queries. An entry's source distinguishes a namespace-declared index from an extractor-derived one; extractor-derived entries omit it. The nested index object carries the storage name, dimensions, distance and inference_name.

Examples:
​
payload_indexes
any[]

NOT REQUIRED (auto-computed from extractor + namespace). Payload indexes for filtering. Enables efficient filtering on metadata fields, timestamps, IDs. Populated from: extractor requirements + namespace defaults. Use for: Understanding which fields support fast filtering.

Examples:
​
embedding_task
string | null

Override the embedding task hint for instruction-aware models (E5, Gemini). Defaults to 'retrieval_document' for indexing pipelines. Values: retrieval_document, retrieval_query, semantic_similarity, classification, clustering. Applied to all task-aware embedding models in this collection's extractor pipeline.

​
enabled
boolean
default:true

NOT REQUIRED (defaults to True). Whether the collection accepts new documents. False: Collection exists but won't process new objects. True: Active and processing. Use for: Temporarily disabling collections without deletion.

Examples:

true

false

​
disabled_reason
CollectionDisabledReason · object | null

Set when the platform disabled this collection, saying why; null when it is enabled or was disabled by a caller. A collection whose source collection was deleted reads code 'source_collection_deleted' with the deleted collection's id and name. Cleared when the collection is enabled again.

​
metadata
Metadata · object | null

NOT REQUIRED. Additional user-defined metadata for the collection. Arbitrary key-value pairs for custom organization, tracking, configuration. Not used by the platform - purely for user purposes. Common uses: team ownership, project tags, deployment environment.

Example:
​
schedule
CollectionScheduleConfig · object | null

NOT REQUIRED. Schedule configuration for automatic re-processing. When set, a COLLECTION_TRIGGER trigger is created and linked to this collection.

​
trigger_id
string | null

NOT REQUIRED. ID of the linked trigger for scheduled re-processing. Automatically set when a schedule is configured.

​
created_at
string<date-time> | null

Timestamp when the collection was created. Automatically set by the system when the collection is first saved to the database.

​
updated_at
string<date-time> | null

Timestamp when the collection was last updated. Automatically updated by the system whenever the collection is modified.

​
lifecycle_state
string
default:active

Storage lifecycle state: 'active' (vector store + S3), 'cold' (S3 only), 'archived' (metadata only). Managed via lifecycle API.

​
s3_vector_index
string | null

S3 Vectors index name for this collection (e.g. 'col_{collection_id}').

​
last_lifecycle_transition
string<date-time> | null

Timestamp of the most recent lifecycle state change.

​
tiering_rules
TieringRule · object[] | null

Retired: stored and never enforced. Writes are refused; set tiering instead. Kept on reads so existing records still parse.

​
tiering
TieringOverride · object | null

This collection's override of the platform's collection tiering: enabled, idle_days ({cold, frozen}) and exempt with the reason. Unset parts inherit from the namespace, then from the platform default.

​
document_count
integer | null

Number of documents in the collection

​
schema_version
integer
default:1

Version number for the output_schema. Increments automatically when schema is updated via document sampling. Used to track schema evolution and trigger downstream collection schema updates.

​
last_schema_sync
string<date-time> | null

Timestamp of last automatic schema sync from document sampling. Used to debounce schema updates (prevents thrashing).

​
schema_sync_enabled
boolean
default:true

Whether automatic schema discovery and sync is enabled for this collection. When True, schema is periodically updated by sampling documents. When False, schema remains fixed at creation time.

​
document_schema
Document Schema · object | null

NOT REQUIRED. JSON Schema for validating documents on create/update. When set with schema_validation='strict', non-conforming documents are rejected (422). When set with schema_validation='warn', violations are recorded but document is accepted. Schema follows JSON Schema draft-07 format. Only validates user-defined fields (system fields like _internal, collection_id, document_id are excluded from validation).

Example:

null

​
schema_validation
enum<string>
default:off

Document schema validation mode. 'strict': reject non-conforming documents with 422. 'warn': accept but attach _schema_violations field to the document. 'off': no validation (default, preserves current behavior).

Available options:
strict,
warn,
off
Examples:

"off"

"strict"

"warn"

​
taxonomy_applications
TaxonomyApplicationConfig · object[] | null

NOT REQUIRED. List of taxonomies to apply to documents in this collection. Each entry specifies: taxonomy_id, optional target_collection_id, optional filters. Enrichments are materialized (persisted to documents) during ingestion. Empty/null if no taxonomies attached. Use for: Categorization, hierarchical classification.

Example:

null

​
cluster_applications
ClusterApplicationConfig · object[] | null

NOT REQUIRED. List of clusters to automatically execute when batch processing completes. Each entry specifies: cluster_id, auto_execute_on_batch, min_document_threshold, cooldown_seconds. Clusters enrich source documents with cluster assignments (cluster_id, cluster_label, etc.). Empty/null if no clusters attached. Use for: Segmentation, grouping, pattern discovery.

Example:

null

​
alert_applications
AlertApplicationConfig · object[] | null

NOT REQUIRED. List of alerts to automatically execute when documents are ingested. Each entry specifies: alert_id, execution_mode, input_mappings, execution_phase, priority. Alerts run retrievers on ingested documents and send notifications when matches are found. Empty/null if no alerts attached. Use for: Content monitoring, safety detection, compliance alerts.

Example:

null

​
retriever_enrichments
RetrieverEnrichmentConfig · object[] | null

NOT REQUIRED. List of retriever enrichments to run on documents during post-processing. Each entry specifies: retriever_id, input_mappings, write_back_fields, execution_phase, priority. Retriever enrichments execute a retriever pipeline and write selected result fields back to documents. Empty/null if no enrichments attached. Use for: LLM classification, cross-collection joins, enrichment.

Example:

null

​
retriever_transform
RetrieverTransformConfig · object | null

NOT REQUIRED. Set for a transform-based collection: the inline retriever pipeline (over an upstream collection) that defines this collection's documents. Mutually exclusive with feature_extractor. None for extractor-based collections.

​
vector_count
integer | null

Total number of vector entries across all documents in this collection. Computed as document_count * number_of_vector_indexes. Each document stores one vector per configured vector index (e.g. a collection with 1 embedding produces 1 vector per document).

​
taxonomy_count
integer | null

Number of taxonomies connected to this collection

​
retriever_count
integer | null

Number of retrievers connected to this collection

​
indexing_status
string | null

Whether every vector the vector store has accepted for this collection's namespace is searchable now. This is separate from the collection's own RUNNING/COMPLETED status: a collection can be COMPLETED while this reads 'indexing'. One of: 'quiesced' (everything the store has accepted for this namespace is searchable; documents still moving through extraction have not reached the store yet, so compare document_count with what you sent if you need completeness), 'indexing' (some accepted vectors are waiting to become searchable and will be shortly; a search run now may miss them), 'blocked' (indexing cannot proceed without intervention, and waiting will not resolve it), 'unknown' (the signal is unavailable, for example an older store build or a transient error; treat it as not confirmed ready). Null when this endpoint did not compute it, for example a list request whose store reading took too long.

Example:

"quiesced"

​
indexing_status_scoped
boolean | null

True when indexing_status describes this collection's namespace alone. False when the store could only report the whole shard, which several namespaces can share, so an 'indexing' or 'blocked' value may come from another namespace's backlog. A 'quiesced' reading is always scoped.

​
warnings
string[] | null

NOT REQUIRED. Non-fatal problems detected while creating the collection. The collection WAS created; these describe things that will make it produce nothing at run time. The case this exists for: input_mappings can name a field that is valid in the bucket SCHEMA and absent from the bucket's OBJECTS, because a sync with no schema_mapping writes its blob to the default property instead. Schema validation passes, the batch then finds nothing, and the batch error arrives long after the decision was made. A warning here reaches the caller while they can still change it.