Collection Documents

Create a document.

Changed on

Create a document in a collection addressed by ID or name.

post/v1/collections/{collection_identifier}/documents

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/collections/{collection_identifier}/documents
  • Auth: HTTP bearer and API key in header X-Namespace

Path parameters

collection_identifierstring required

The ID or name of the collection.

Request body

collection_idstring nullable

ID of the collection the document belongs to. Optional on POST /v1/collections/{collection_id}/documents — the collection is already identified by the URL path, so an omitted body collection_id is filled from the path (a mismatch is still rejected). Required when the request is not path-scoped.

root_object_idstring nullable

Optional denormalized root object identifier provided during creation.

root_bucket_idstring nullable

Optional denormalized bucket identifier provided during creation.

source_type'bucket' | 'collection' | 'direct_upsert' | 'signal' nullable

Optional immediate parent type for the document.

source_collection_idstring nullable

Optional parent collection identifier when sourced from a collection.

source_document_idstring nullable

Optional parent document identifier when sourced from a collection.

source_object_idstring nullable

Optional parent object identifier when sourced directly from a bucket.

lineage_pathstring nullable

Optional materialized lineage path to set during creation.

content_hashstring nullable

Optional SHA256 content hash of the source object. Supplying it on a lineage-preserving import lets a later heal/reprocess recognise the cached derivation potency and skip recompute instead of re-spending GPU. Stored at _internal.content_hash.

document_schema_versionstring nullable

Optional document schema version (v1 or v2). If not provided, uses system default.

metadataobject

Optional metadata dictionary for user-defined fields and custom attributes.

vectorsobject nullable

Optional pre-computed vectors to store with the document. Keys are the names of the collection's vector indexes. A key is either the last segment of the index feature_uri (multilingual_e5_large_instruct_v1 for mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1) or the full index name (text_extractor_v1_embedding). Either way the vector is stored under the full index name. Values are float arrays with the index dimensions. A key the collection does not have returns a 422 that lists the available index names and dimensions. Read the names from vector_indexes on GET /v1/collections/{collection_id}.

Example request

{
  "collection_id": "collection_123",
  "lineage_chain": [
    {
      "collection_id": "col_video_frames",
      "document_id": "doc_frame123",
      "feature_extractor_id": "multimodal_extractor_v1",
      "timestamp": "2025-10-18T10:30:00Z"
    }
  ]
}

Response

Successful Response

document_idstring required

REQUIRED. Unique identifier for the document. Format: 'doc_' prefix + alphanumeric characters. Use for: API queries, references, filtering.

collection_idstring required

REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering.

vector_hydration_incompleteboolean nullable

OPTIONAL. Present only when return_vectors/return_vector_names was requested on this read. True means this read did not return a vector the store holds: fetching errored or timed out, its partition was not paged in, or the store keeps it only as quantized codes. An empty or absent vector on THIS response is UNCERTAIN, not a confirmed absence, and should not be treated as proof the vector does not exist. False means hydration ran to completion (present or genuinely absent). On a large/BYO collection with evicted partitions, hydration can time out on most reads before a background page-in warms the index; retrying the same read later, once warm, is the correct response to True here, not re-deriving the vector from source.

searchable_atstring nullable

When the document's latest write became searchable on the shard that served this read (ISO 8601, UTC, to the write batch). Null means stored and not searchable yet: the write is acknowledged but this shard has not applied it, or a recovery replay still covers the namespace. A read after the apply returns the time. Computed when the document is read from the shard that serves it, and not stored on the document, so it cannot be used in filters, sorts or facets.

Example response

{
  "_internal": {
    "collection_id": "col_articles",
    "created_at": "2025-10-31T10:00:00Z",
    "document_id": "doc_f8966ff29c18e20c6b45e053",
    "internal_id": "org_abc123",
    "lineage": {
      "chain": [
        {
          "collection_id": "col_articles",
          "feature_extractor_id": "text_extractor_v1",
          "timestamp": "2025-10-31T10:00:00Z"
        }
      ],
      "path": "bkt_content/col_articles",
      "root_bucket_id": "bkt_content",
      "root_object_id": "obj_article_001",
      "source_object_id": "obj_article_001",
      "source_type": "bucket"
    },
    "metadata": {
      "ingestion_status": "COMPLETED"
    },
    "modality": "text",
    "namespace_id": "ns_xyz789",
    "source_blobs": [
      {
        "blob_id": "blob_text_001",
        "blob_property": "content",
        "blob_type": "text"
      }
    ],
    "updated_at": "2025-10-31T10:00:00Z"
  },
  "author": "Dr. Smith",
  "collection_id": "col_articles",
  "description": "Text document with _internal structure",
  "document_id": "doc_f8966ff29c18e20c6b45e053",
  "title": "AI in Healthcare"
}

Changes

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • b75474e978ffRevision changes
    • info

      added the optional property to the response with the status