> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml post /v1/namespaces/{namespace_id}/documents/upsert openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/namespaces/{namespace_id}/documents/upsert: post: tags: - BYO Documents summary: Upsert documents with BYO vectors description: >- 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. operationId: upsert_documents_byo_v1_namespaces__namespace_id__documents_upsert_post parameters: - name: namespace_id in: path required: true schema: type: string description: The namespace to upsert documents into. examples: - ns_abc123def456 title: Namespace Id description: The namespace to upsert documents into. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BYOUpsertRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BYOUpsertResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: BYOUpsertRequest: properties: collection_id: anyOf: - type: string - type: 'null' title: Collection Id description: >- 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. documents: items: $ref: '#/components/schemas/BYODocument' type: array maxItems: 1000 title: Documents description: Documents to upsert. Maximum 1000 per call. options: anyOf: - $ref: '#/components/schemas/UpsertOptions' - type: 'null' description: Optional upsert behavior flags. type: object required: - documents title: BYOUpsertRequest description: Request body for BYO document upsert. BYOUpsertResponse: properties: inserted: type: integer title: Inserted description: Number of documents upserted. document_ids: items: type: string type: array title: Document Ids description: IDs of all upserted documents. write_token: anyOf: - type: string - type: 'null' title: Write Token description: Opaque token for read-your-writes consistency (only when requested). dropped_payload_fields: additionalProperties: items: type: string type: array type: object title: Dropped Payload Fields description: >- 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. consistency: $ref: '#/components/schemas/WriteConsistency' description: How and when this write becomes visible to retriever reads. type: object required: - inserted - document_ids title: BYOUpsertResponse description: Response from a BYO document upsert. ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BYODocument: properties: document_id: type: string title: Document Id description: >- Unique document identifier. Upserting with an existing ID replaces the document. vectors: additionalProperties: items: type: number type: array type: object title: Vectors description: >- Named vectors as a map of vector_name -> embedding values. Example: {"text-embedding": [0.1, 0.2, ...], "image-embedding": [0.3, ...]} payload: additionalProperties: true type: object title: Payload description: Arbitrary JSON payload stored alongside the vectors. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: >- Document metadata stored in _internal.metadata. Filterable via attribute queries. source_type: anyOf: - type: string enum: - bucket - collection - direct_upsert - signal - type: 'null' title: Source Type description: >- Immediate-parent type. Defaults to 'direct_upsert' when omitted. Set 'bucket'/'collection' to import a document carrying real lineage. root_object_id: anyOf: - type: string - type: 'null' title: Root Object Id description: >- Root object id (decomposition-tree root). All documents derived from the same source object share it. root_bucket_id: anyOf: - type: string - type: 'null' title: Root Bucket Id description: Bucket id holding the root object. source_object_id: anyOf: - type: string - type: 'null' title: Source Object Id description: Immediate parent object id when source_type='bucket'. source_document_id: anyOf: - type: string - type: 'null' title: Source Document Id description: Immediate parent document id when source_type='collection'. source_collection_id: anyOf: - type: string - type: 'null' title: Source Collection Id description: Immediate parent collection id when source_type='collection'. lineage_path: anyOf: - type: string - type: 'null' title: Lineage Path description: Materialized lineage path (e.g. 'bkt_123/col_456/col_789'). lineage_chain: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Lineage Chain description: >- Ordered processing steps from root object to this document; each step carries collection_id, feature_extractor_id, document_id, timestamp. content_hash: anyOf: - type: string - type: 'null' title: Content Hash description: >- SHA256 content hash of the source object. Supplying it lets a later heal/reprocess recognise the cached derivation potency and skip recompute. Stored at _internal.content_hash. type: object required: - document_id - vectors title: BYODocument description: A single document with user-provided vectors and payload. UpsertOptions: properties: write_token: type: boolean title: Write Token description: Return a WriteToken for read-your-writes consistency. default: false idempotency_key: anyOf: - type: string - type: 'null' title: Idempotency Key description: >- Deduplication key. A repeated call with the same key and an identical body returns the original cached response; the same key with a different body returns 409 Conflict. type: object title: UpsertOptions description: Options controlling the upsert behavior. WriteConsistency: properties: retriever_visible: type: string title: Retriever Visible description: >- Visibility model: 'eventual' (BYOV direct upsert — indexed within seconds) or 'after_processing' (managed ingestion — visible after a collection batch processes the object). recommended_header: anyOf: - type: string - type: 'null' title: Recommended Header description: >- Header to send on retriever execute for read-your-writes (BYOV). Set only when a write_token was actually issued; null when no token was minted (visibility is then automatic within expected_visible_within_ms). write_token_available: type: boolean title: Write Token Available description: Whether a write_token was issued for read-your-writes. default: false expected_visible_within_ms: anyOf: - type: integer - type: 'null' title: Expected Visible Within Ms description: >- Typical upper bound for visibility (BYOV indexing). Null when visibility depends on asynchronous processing (managed ingestion). poll: anyOf: - additionalProperties: true type: object - type: 'null' title: Poll description: >- How to poll for visibility when it depends on async processing: {endpoint, field, ready_when}. next_actions: items: additionalProperties: true type: object type: array title: Next Actions description: Actionable next steps to reach retriever visibility. type: object required: - retriever_visible title: WriteConsistency description: How and when a write becomes visible to retriever reads. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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 header returns 403; an invalid or revoked key returns 401. ````