Sign in
Collection Documents

Create a document.

Create a document by ID.

post/v1/collections/{collection_identifier}/documents

Path parameters

collection_identifierstring required

The ID of the collection.

The ID 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 vector index names (e.g. 'text_extractor_v1_embedding'), values are float arrays matching the index dimensions.

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.

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

Changed in 4 of the 34 revisions of this API.15

  • 1c7f3182142411See the full diff
    • ●

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

      response-property-enum-value-added

    • ○

      added the new signal enum value to the request property /

      request-property-enum-value-added

  • 64c58b6341921See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • 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

  • 7cb0515333112See the full diff
    • ○

      the request property became optional

      request-property-became-optional

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

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