Upsert documents with BYO vectors

Upsert documents with user-provided vectors directly into a namespace. This bypasses the collection/batch/extractor pipeline entirely. Documents go directly to the vector store. Maximum 1000 documents per call.

POST /v1/namespaces/{namespace_id}/documents/upsert

Upsert documents with BYO vectors

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    {
      "document_id": "<string>",
      "vectors": {},
      "payload": {},
      "metadata": {},
      "acl": {
        "read": [
          "<string>"
        ],
        "write": [
          "<string>"
        ],
        "public": true
      },
      "root_object_id": "<string>",
      "root_bucket_id": "<string>",
      "source_object_id": "<string>",
      "source_document_id": "<string>",
      "source_collection_id": "<string>",
      "lineage_path": "<string>",
      "lineage_chain": [
        {}
      ],
      "content_hash": "<string>"
    }
  ],
  "collection_id": "<string>",
  "options": {
    "write_token": false,
    "idempotency_key": "<string>"
  }
}
'

200

{
  "inserted": 123,
  "document_ids": [
    "<string>"
  ],
  "write_token": "<string>",
  "dropped_payload_fields": {},
  "unsearchable_document_ids": [
    "<string>"
  ],
  "consistency": {
    "retriever_visible": "<string>",
    "recommended_header": "<string>",
    "write_token_available": false,
    "expected_visible_within_ms": 123,
    "poll": {},
    "next_actions": [
      {}
    ]
  },
  "warnings": [
    "<string>"
  ]
}

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.

Path Parameters

namespace_id · string · required

The namespace to upsert documents into.

Example:

"ns_abc123def456"

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request body for BYO document upsert.

documents · BYODocument · object[] · required

Documents to upsert. Maximum 1000 per call.

Maximum array length: 1000

Show child attributes

collection_id · string | null

Target collection. Documents are tagged with this collection_id so they appear in collection-scoped queries, list, and clustering. When omitted a namespace-level default collection is used.

options · UpsertOptions · object | null

Optional upsert behavior flags.

Show child attributes

Response

200

application/json

Successful Response

Response from a BYO document upsert.

inserted · integer · required

Number of documents upserted.

document_ids · string[] · required

IDs of all upserted documents.

write_token · string | null

Opaque token for read-your-writes consistency (only when requested).

dropped_payload_fields · Dropped Payload Fields · object

document_id -> payload field names that were REMOVED before storage because they collide with reserved internal field names. Their values are not stored anywhere and are not readable back. Rename the field (e.g. 'source_type' -> 'my_source_type') or nest it under 'metadata' to keep the value. Empty when nothing was dropped.

Show child attributes

unsearchable_document_ids · string[]

document_ids that were stored but carry no vector for the collection's declared index, so a retriever search will not return them until you provide a vector for that index or run the collection's extractor. The documents are readable by list and get; they are only absent from search. Empty when every document is searchable.

consistency · WriteConsistency · object

How and when this write becomes visible to retriever reads.

Show child attributes

warnings · string[]

Advisories about this write that did not fail it: today, that the idempotency replay entry could not be stored, so a retry with the same idempotency_key would write again.