> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-ad5578da.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Embeddings

> Upload pre-computed embeddings for advanced similarity search.

This endpoint accepts vector embeddings that you’ve generated externally,
 allowing you to integrate with custom embedding models or existing vector databases.
  The embeddings represent chunks of your content as numerical vectors.

The system stores these embeddings and makes them available for semantic search and similarity matching.
 Use this when you want to leverage specialized embedding models or have existing vector representations.
When upsert=True, existing embeddings with the same chunk_id will be updated.

export const TableOfContents = ({title = 'On this page', items, minHeadingLevel = 2, maxHeadingLevel = 3, className = '', activeClassName = 'text-primary dark:text-primary-light border-primary dark:border-primary-light hover:border-primary dark:hover:border-primary-light', inactiveClassName = 'hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-300'}) => {
  const [toc, setToc] = useState(items ?? []);
  const [activeId, setActiveId] = useState('');
  useEffect(() => {
    if (items && items.length) return;
    if (typeof document === 'undefined') return;
    const selectors = [];
    for (let lvl = minHeadingLevel; lvl <= maxHeadingLevel; lvl++) {
      selectors.push(`h${lvl}`);
    }
    const nodes = Array.from(document.querySelectorAll(selectors.join(','))).filter(el => el.id);
    const built = [];
    let currentTop = null;
    nodes.forEach(el => {
      const level = Number(el.tagName.slice(1));
      const node = {
        id: el.id,
        label: el.textContent.trim(),
        href: `#${el.id}`,
        children: []
      };
      if (level === minHeadingLevel) {
        built.push(node);
        currentTop = node;
      } else if (level > minHeadingLevel && currentTop) {
        currentTop.children.push(node);
      } else {
        built.push(node);
      }
    });
    setToc(built);
  }, [items, minHeadingLevel, maxHeadingLevel]);
  useEffect(() => {
    if (typeof document === 'undefined') return;
    const applyHash = () => {
      const h = window.location.hash.replace('#', '');
      if (h) setActiveId(h);
    };
    applyHash();
    const observer = new IntersectionObserver(entries => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          setActiveId(entry.target.id);
        }
      });
    }, {
      rootMargin: '0px 0px -70% 0px',
      threshold: 0.1
    });
    const ids = toc.flatMap(i => [i, ...i.children ?? []]).map(i => i.id);
    ids.forEach(id => {
      const el = document.getElementById(id);
      if (el) observer.observe(el);
    });
    window.addEventListener('hashchange', applyHash);
    return () => {
      window.removeEventListener('hashchange', applyHash);
      observer.disconnect();
    };
  }, [toc]);
  const Item = ({node, depth = 0}) => {
    const isActive = activeId === node.id;
    return <li className="toc-item relative ml-6" data-depth={depth}>
        <a href={node.href} className={`py-1 block font-medium ${isActive ? activeClassName : inactiveClassName}`} style={depth > 0 ? {
      marginLeft: `${depth}rem`
    } : {}} onClick={() => setActiveId(node.id)}>
          {node.label}
        </a>
        {node.children && node.children.length > 0 && <>
            {node.children.map(child => <Item node={child} depth={depth + 1} key={child.href} />)}
          </>}
      </li>;
  };
  const data = toc && toc.length ? toc : items || [];
  return <div className={`text-gray-600 text-sm leading-6 w-[18rem] pb-4 -mt-10 pt-10 hidden xl:block ${className}`} id="table-of-contents-custom">
      <ul id="table-of-contents-custom-content" className="toc">
        <li className="toc-item relative">
          <div className="text-gray-700 dark:text-gray-300 font-medium flex items-center space-x-2 py-1">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" xmlns="http://www.w3.org/2000/svg" className="h-3 w-3">
              <path d="M2.44434 12.6665H13.5554" strokeLinecap="round" strokeLinejoin="round"></path>
              <path d="M2.44434 3.3335H13.5554" strokeLinecap="round" strokeLinejoin="round"></path>
              <path d="M2.44434 8H7.33323" strokeLinecap="round" strokeLinejoin="round"></path>
            </svg>
            <span>{title}</span>
          </div>
        </li>
        {data.map(node => <Item node={node} key={node.href} />)}
      </ul>
    </div>;
};

<Panel>
  <TableOfContents />
</Panel>

<Tip> Hit the `Try it` button to try this API now in our playground. It's the best way to check the full request and response in one place, customize your parameters, and generate ready-to-use code snippets.</Tip>

### Examples

<Tabs>
  <Tab title="API Request">
    ```bash expandable theme={null}
    curl -X 'POST' \
    'https://api.usecortex.ai/embeddings/insert-raw-embeddings' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "tenant_id": "string",
    "sub_tenant_id": "",
    "embeddings": [
    {
      "tenant_id": "string",
      "sub_tenant_id": "string",
      "source_id": "string",
      "metadata": {
        "additionalProp1": {}
      },
      "embeddings": [
        {
          "chunk_id": "string",
          "embedding": [
            0
          ]
        }
      ]
    }
    ],
    "upsert": false
    }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const result = await client.upload.uploadEmbeddings({
      tenant_id: "tenant_1234",
      sub_tenant_id: "sub_tenant_4567",
      embeddings: [
        [0.123413, 0.655367, 0.987654, 0.123456, 0.789012],
        [0.123413, 0.655367, 0.987654, 0.123456, 0.789012]
      ],
      file_id: "CortexDoc1234"
    });
    ```
  </Tab>

  <Tab title="Python (Sync)">
    ```python theme={null}
    # Async usage is similar, just use async_client and await
    result = client.upload.upload_embeddings(
        tenant_id="tenant_1234",
        sub_tenant_id="sub_tenant_4567",
        embeddings=[
            [0.123413, 0.655367, 0.987654, 0.123456, 0.789012],
            [0.123413, 0.655367, 0.987654, 0.123456, 0.789012]
        ],
        file_id="CortexDoc1234"
    )
    ```
  </Tab>
</Tabs>

Upload pre-computed embedding vectors directly to your tenant's knowledge base. This is useful when you have your own embedding model or want to use embeddings from external sources.

## Embedding Processing Pipeline

When you upload pre-computed embeddings, they go through a streamlined processing pipeline optimized for vector data:

### 1. **Immediate Upload & Validation**

* Your embedding vectors are immediately accepted and validated
* Dimensional consistency is checked across all vectors
* Format validation ensures proper numeric array structure
* You receive a confirmation response with a `file_id` for tracking

### 2. **Vector Processing Phase**

Our system automatically handles:

* **Dimensional Validation**: Ensuring all vectors have consistent dimensions
* **Data Type Normalization**: Converting to optimal numeric formats
* **Vector Quality Assessment**: Checking for valid numeric ranges and patterns
* **Batch ID Generation**: Creating unique chunk IDs for each embedding vector

### 3. **Chunk ID Assignment**

* Each embedding vector receives a unique chunk ID in format `{batch_id}_{index}`
* These IDs serve as references for retrieval and linking to original content
* Example: `[0.1, 0.2, 0.3, 0.4, 0.5]` becomes `CortexEmbeddings123_0`
* You can use these chunk IDs to link back to your original text content

### 4. **Direct Indexing**

* Embeddings are directly stored in our vector database (no embedding generation needed)
* Full-text search indexes are created for associated metadata
* Metadata is indexed for filtering and faceted search
* Cross-references are established for related embedding batches

### 5. **Quality Assurance**

* Automated quality checks ensure vector integrity
* Dimensional consistency validation across the tenant
* Vector range and format validation
* Database storage verification

<Note>
  **Processing Time**: Pre-computed embeddings are typically processed and searchable within 30 seconds to 2 minutes. Large embedding batches (1000+ vectors) may take up to 5 minutes. You can check processing status using the document ID returned in the response.
</Note>

<Note>
  **Default Sub-Tenant Behavior**: If you don't specify a `sub_tenant_id`, the embeddings will be uploaded to the default sub-tenant created when your tenant was set up. This is perfect for organization-wide embeddings that should be accessible across all departments.
</Note>

### Requirements

* **Maximum dimensions**: 2000 rows × 3024 columns; i.e, 2000 chunks with the dimensions, not more than 3024
* **Format**: 2D array of numeric values (int or float)
* **Consistency**: All embedding vectors must have the same dimension
* **Content**: Embeddings array cannot be empty
* **Processing**: Generates unique chunk IDs in format `{batch_id}_{index} for each row`.
  * Consider them as references of that particular embeddings vector. You will get back these `chunk_ids`, when you query something.
  * In the example on your right, the reference to `[0.1, 0.2, 0.3, 0.4, 0.5]` is `CortexEmbeddings123_0`
  * You can use these chunk IDs to link the original text which is being embedded
* **Dimensional consistency per tenant**: All embedding vectors within a tenant must have identical dimensions. Different dimensional vectors require separate tenants

> **File ID Management**: When you provide a `file_id` as a key in the `document_metadata` object, that specific ID will be used to identify your content. If no `file_id` is provided in the `document_metadata`, the system will automatically generate a unique identifier for you. This allows you to maintain consistent references to your content across your application while ensuring every piece of content has a unique identifier.

### **Duplicate File ID Behavior**

When you upload embeddings with a `file_id` that already exists in your tenant:

* **Overwrite Behavior**: The existing embeddings with the same `file_id` will be **completely replaced** with the new embeddings
* **Processing**: The new embeddings will go through validation and direct indexing (no embedding generation needed)
* **Search Results**: Previous search results and vector data from the old embeddings will be replaced with the new embeddings
* **Idempotency**: Uploading the same embeddings with the same `file_id` multiple times is safe and will result in the same final state

<Warning>
  **Important**: When overwriting existing embeddings, all previous vector data, chunk IDs, and search indexes associated with that `file_id` will be permanently removed and replaced. This action cannot be undone.
</Warning>

**Example Success Response for Duplicate File ID:**

```json theme={null}
{
  "message": "Embeddings uploaded successfully. Existing embeddings with file_id 'emb_123456' have been overwritten.",
  "file_id": "emb_123456",
  "status": "success"
}
```

## Error Responses

All endpoints return consistent error responses following the standard format. For detailed error information, see our [Error Responses](/api-reference/error-responses) documentation.


## OpenAPI

````yaml POST /embeddings/insert-raw-embeddings
openapi: 3.1.0
info:
  title: Cortex SDK API
  description: REST APIs for Cortex AI retrieval engine
  version: 0.0.1
servers:
  - url: /
    description: Local
    x-fern-server-name: cortex-backend-local
  - url: https://api.usecortex.ai
    description: Production
    x-fern-server-name: cortex-prod
    x-fern-audiences:
      - public
  - url: https://preprod.usecortex.ai
    description: Staging
    x-fern-server-name: cortex-staging
security: []
paths:
  /embeddings/insert-raw-embeddings:
    post:
      tags:
        - embeddings
      summary: Insert Raw Embeddings Endpoint
      description: >-
        Upload pre-computed embeddings for advanced similarity search.


        This endpoint accepts vector embeddings that you’ve generated
        externally,
         allowing you to integrate with custom embedding models or existing vector databases.
          The embeddings represent chunks of your content as numerical vectors.

        The system stores these embeddings and makes them available for semantic
        search and similarity matching.
         Use this when you want to leverage specialized embedding models or have existing vector representations.
        When upsert=True, existing embeddings with the same chunk_id will be
        updated.
      operationId: insert_raw_embeddings_endpoint_embeddings_insert_raw_embeddings_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/Body_insert_raw_embeddings_endpoint_embeddings_insert_raw_embeddings_post
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertResult'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '422':
          description: Unprocessable Entity - Validation failed
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
      security:
        - HTTPBearer: []
components:
  schemas:
    Body_insert_raw_embeddings_endpoint_embeddings_insert_raw_embeddings_post:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Unique identifier for the tenant/organization
          example: tenant_1234
        sub_tenant_id:
          type: string
          title: Sub Tenant Id
          description: >-
            Optional sub-tenant identifier used to organize data within a
            tenant. If omitted, the default sub-tenant created during tenant
            setup will be used.
          default: ''
          example: sub_tenant_4567
        embeddings:
          items:
            $ref: '#/components/schemas/RawEmbeddingDocument'
          type: array
          title: Embeddings
          description: List of raw embedding documents to insert
          example:
            - - 0.123413
              - 0.655367
              - 0.987654
              - 0.123456
              - 0.789012
            - - 0.123413
              - 0.655367
              - 0.987654
              - 0.123456
              - 0.789012
        upsert:
          type: boolean
          title: Upsert
          description: If True, update existing embeddings; if False, insert only
          default: false
          example: true
      type: object
      required:
        - tenant_id
        - embeddings
      title: >-
        Body_insert_raw_embeddings_endpoint_embeddings_insert_raw_embeddings_post
    InsertResult:
      properties:
        insert_count:
          type: integer
          title: Insert Count
          description: Number of entities inserted
          example: 1
        ids:
          items:
            type: string
          type: array
          title: Ids
          description: Inserted entity IDs
          example: []
        success:
          type: boolean
          title: Success
          description: Whether insert succeeded
          default: true
          example: true
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
      type: object
      required:
        - insert_count
      title: InsertResult
      description: Result of an insert operation.
    cortex__models__response__commons__ActualErrorResponse:
      properties:
        detail:
          $ref: >-
            #/components/schemas/cortex__models__response__commons__ErrorResponse
      type: object
      required:
        - detail
      title: ActualErrorResponse
    RawEmbeddingDocument:
      properties:
        source_id:
          type: string
          title: Source Id
          description: Source identifier for the embedding
          example: CortexDoc1234
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Metadata to store
        embeddings:
          items:
            $ref: '#/components/schemas/RawEmbeddingVector'
          type: array
          title: Embeddings
          description: Embedding payloads containing ids and vectors
          example:
            - - 0.123413
              - 0.655367
              - 0.987654
              - 0.123456
              - 0.789012
            - - 0.123413
              - 0.655367
              - 0.987654
              - 0.123456
              - 0.789012
      type: object
      required:
        - source_id
        - embeddings
      title: RawEmbeddingDocument
      description: A raw embedding document for direct insert/upsert operations.
    cortex__models__response__commons__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: false
          example: true
        message:
          type: string
          title: Message
          default: Error occurred
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
      type: object
      title: ErrorResponse
    RawEmbeddingVector:
      properties:
        chunk_id:
          type: string
          title: Chunk Id
          description: Primary key / chunk identifier
          example: <chunk_id>
        embedding:
          items:
            type: number
          type: array
          title: Embedding
          description: Embedding vector
          example: []
      type: object
      required:
        - chunk_id
        - embedding
      title: RawEmbeddingVector
      description: Embedding payload containing the chunk identifier and vector.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````