Skip to main content
GET
Get Collection

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

collection_identifier
string
required

The ID or name of the collection to retrieve

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. 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:
vector_indexes
any[]

NOT REQUIRED (auto-computed from extractor). Vector indexes for semantic search. Populated from feature_extractor.required_vector_indexes. Defines: Which embeddings are indexed, dimensions, distance metrics. Use for: Understanding search capabilities, debugging vector queries.

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

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' (Qdrant + 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

Automatic storage tiering rules (not enforced in V1).

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

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