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.

POST /embeddings/insert-raw-embeddings

Error

A valid request URL is required to generate request examples

200

{
  "insert_count": 1,
  "ids": [],
  "success": true,
  "error": "<string>"
}

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.

Examples

API Request

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
}'

TypeScript

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"
});

Python (Sync)

# 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"
)

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

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.

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.

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

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.

Example Success Response for Duplicate File ID:

{
  "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 documentation.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

tenant_id · string · required

Unique identifier for the tenant/organization

Example:

"tenant_1234"

embeddings · RawEmbeddingDocument · object[] · required

List of raw embedding documents to insert

Show child attributes

Example:

[
  [
    0.123413,
    0.655367,
    0.987654,
    0.123456,
    0.789012
  ],
  [
    0.123413,
    0.655367,
    0.987654,
    0.123456,
    0.789012
  ]
]

sub_tenant_id · string · default: ""

Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.

Example:

"sub_tenant_4567"

upsert · boolean · default: false

If True, update existing embeddings; if False, insert only

Example:

true

Response

200

application/json

Successful Response

Result of an insert operation.

insert_count · integer · required

Number of entities inserted

Example:

1

ids · string[]

Inserted entity IDs

Example:

[]

success · boolean · default: true

Whether insert succeeded

Example:

true

error · string | null

Error message if failed