> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert Vectors > Insert new documents or update existing documents in a vector store. **Upsert Behavior:** If a document ID already exists, it will be completely replaced with the new content and metadata. The previous document's text, embedding, and all metadata fields are discarded. If the ID does not exist, a new document is created. **Document Content:** Each document supports several modes: - `content` only: text is automatically embedded using the store's configured model. - `embedding` only: pre-computed embedding vector is used directly. Dimension must match the store's configuration. - Both `content` and `embedding`: the pre-computed embedding is stored and text is kept for retrieval/search. - Neither (metadata-only): only metadata is updated on an existing document without re-embedding. If the document does not exist, it will appear as a failure in the batch response. A store created without an embedding model (dimensions-only) only accepts documents with pre-computed `embedding`. **Batch Operations:** This endpoint supports batch operations with partial success handling and mixed document types (some with raw embeddings, some with content) in the same call. **Metadata:** Supports nested metadata with string, number, boolean, object, and array types. Null values are not permitted—omit the field or use an empty string instead. ## OpenAPI ````yaml https://api.dev-sgp.scale.com/openapi-versions/v5/openapi.json post /v5/vector-stores/{vector_store_name}/upsert openapi: 3.1.0 info: title: EGP API V5 description: >- This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs. contact: name: Scale Generative AI Platform url: https://scale.com/genai-platform version: 0.1.0 servers: - url: https://api.egp.scale.com security: [] paths: /v5/vector-stores/{vector_store_name}/upsert: post: tags: - Vector Stores summary: Upsert Vectors description: >- Insert new documents or update existing documents in a vector store. **Upsert Behavior:** If a document ID already exists, it will be completely replaced with the new content and metadata. The previous document's text, embedding, and all metadata fields are discarded. If the ID does not exist, a new document is created. **Document Content:** Each document supports several modes: - `content` only: text is automatically embedded using the store's configured model. - `embedding` only: pre-computed embedding vector is used directly. Dimension must match the store's configuration. - Both `content` and `embedding`: the pre-computed embedding is stored and text is kept for retrieval/search. - Neither (metadata-only): only metadata is updated on an existing document without re-embedding. If the document does not exist, it will appear as a failure in the batch response. A store created without an embedding model (dimensions-only) only accepts documents with pre-computed `embedding`. **Batch Operations:** This endpoint supports batch operations with partial success handling and mixed document types (some with raw embeddings, some with content) in the same call. **Metadata:** Supports nested metadata with string, number, boolean, object, and array types. Null values are not permitted—omit the field or use an empty string instead. operationId: POST-V5-/v5/vector-stores/vector_store_name/upsert parameters: - name: vector_store_name in: path required: true schema: type: string description: The name of the vector store title: Vector Store Name description: The name of the vector store - name: x-selected-account-id in: header required: false schema: anyOf: - type: string - type: 'null' title: Account ID Header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertVectorsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchOperationResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: UpsertVectorsRequest: properties: vectors: items: $ref: '#/components/schemas/VectorDocumentRequest' type: array title: Vectors description: Array of documents to upsert type: object required: - vectors title: UpsertVectorsRequest description: Request to upsert documents. BatchOperationResponse: properties: success_count: type: integer title: Success Count description: Number of successfully processed documents failure_count: type: integer title: Failure Count description: Number of failed documents succeeded: items: type: string type: array title: Succeeded description: IDs of successfully processed documents failed: items: $ref: '#/components/schemas/FailedDocumentResponse' type: array title: Failed description: Failed documents with their error messages type: object required: - success_count - failure_count title: BatchOperationResponse description: Response for batch insert/upsert operations. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError VectorDocumentRequest: properties: id: type: string title: Id description: Unique document ID content: title: Content description: >- Document content to embed. Omit to perform a metadata-only update on an existing document without re-embedding. oneOf: - $ref: '#/components/schemas/TextContent' discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/TextContent' embedding: title: Embedding description: Pre-computed embedding vector items: type: number type: array metadata: additionalProperties: true type: object title: Metadata description: Key-value metadata type: object required: - id title: VectorDocumentRequest description: >- A document for upsert operations. Documents support several modes: - ``content`` only: text is embedded and all fields are replaced. - ``embedding`` only: pre-computed embedding vector is used directly. - Both ``content`` and ``embedding``: the pre-computed embedding is used and text is stored for retrieval but not re-embedded. - Neither (metadata-only): only metadata is updated on an existing document without re-embedding. Omitting both on a document that does not exist yet will return a per-item failure in the batch response. FailedDocumentResponse: properties: id: type: string title: Id description: Document ID error: type: string title: Error description: Error message describing why the document failed type: object required: - id - error title: FailedDocumentResponse description: A document that failed during a batch upsert operation. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: title: Error Type type: string input: title: Input ctx: type: object title: Context additionalProperties: true type: object required: - loc - msg - type title: ValidationError TextContent: properties: type: type: string const: text title: Type description: Content type identifier default: text text: type: string title: Text description: Text content to be embedded type: object required: - text title: TextContent description: Text content for documents. securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ````