Sign in
Collections

Get Collection

This endpoint allows you to retrieve a collection by ID or name.

get/v1/collections/{collection_identifier}

Path parameters

collection_identifierstring required

The ID or name of the collection to retrieve

The ID or name of the collection to retrieve

Response

Successful Response

collection_idstring

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.

collection_namestring 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'.

descriptionstring nullable

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.

source_bucket_schemasobject nullable

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

embedding_taskstring nullable

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.

enabledboolean

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.

metadataobject nullable

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.

trigger_idstring nullable

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

created_atstring date-time nullable

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

updated_atstring date-time nullable

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

lifecycle_statestring

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

s3_vector_indexstring nullable

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

last_lifecycle_transitionstring date-time nullable

Timestamp of the most recent lifecycle state change.

document_countinteger nullable

Number of documents in the collection

schema_versioninteger

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_syncstring date-time nullable

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

schema_sync_enabledboolean

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_schemaobject nullable

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

schema_validation'strict' | 'warn' | '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).

vector_countinteger nullable

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_countinteger nullable

Number of taxonomies connected to this collection

retriever_countinteger nullable

Number of retrievers connected to this collection

warningsstring[] nullable

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.

Example response

{
  "collection_id": "col_a1b2c3d4e5",
  "collection_name": "article_embeddings",
  "description": "Simple text collection: News articles with text embeddings from bucket source",
  "enabled": true,
  "feature_extractor": {
    "feature_extractor_name": "text_extractor",
    "field_passthrough": [
      {
        "source_path": "title"
      }
    ],
    "input_mappings": {
      "text": "content"
    },
    "version": "v1"
  },
  "input_schema": {
    "properties": {
      "title": {
        "type": "string"
      },
      "content": {
        "type": "text"
      }
    }
  },
  "output_schema": {
    "properties": {
      "title": {
        "type": "string"
      },
      "text_extractor_v1_embedding": {
        "type": "array"
      }
    }
  },
  "source": {
    "bucket_id": "bkt_articles",
    "type": "bucket"
  }
}

Changes

Changed in 7 of the 34 revisions of this API.23810

  • 8ef32f2ad1a61See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 7dc0581791b223See the full diff
    • ▲

      response property feature_extractor/parameters/anyOf[subschema #6: MultimodalExtractorParams]/transcription_language list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property source_lineage/items/feature_extractor/parameters/anyOf[subschema #6: MultimodalExtractorParams]/transcription_language list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      the response's property default value en was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value en was removed for the status

      response-property-default-value-removed

  • b8d3cdf035a03See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added to the / response property anyOf list for the response status

      response-property-any-of-added

    • ○

      added to the /// response property anyOf list for the response status

      response-property-any-of-added

  • a712e239102b2See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property /// to the response with the status

      response-optional-property-added

  • 1c7f318214242See the full diff
    • ●

      added the new signals enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new signals enum value to the /// response property for the response status

      response-property-enum-value-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 7cb05153331136See the full diff
    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_bounding_box enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_polygon enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the /////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new geo_radius enum value to the ///////// response property for the response status

      response-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog