Vector Upsert

Upsert documents into vector stores for retrieval-augmented generation

Overview

The Vector Upsert API allows you to add or update documents in vector stores that are used for retrieval-augmented generation (RAG). This enables you to keep your knowledge base up-to-date programmatically.

Vector upsert endpoints require API key authentication when the chatflow has an apikeyid configured.

Upsert Vector

Add or update documents in a vector store.

POST /api/v1/vector/upsert/:id

curl -X POST http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Flowise is an open-source low-code tool for developers to build customized LLM orchestration flows and AI agents.",
    "metadata": {
      "source": "documentation",
      "category": "introduction"
    }
  }'

Path Parameters

id · string · required

The unique identifier of the chatflow containing the vector store

Request Body

text · string

Text content to upsert into the vector store

metadata · object

Metadata to attach to the document for filtering and retrieval

{
  "source": "documentation",
  "category": "api",
  "author": "John Doe",
  "date": "2024-03-15"
}

files · file[]

Array of files to process and upsert (sent as multipart/form-data)

overrideConfig · object

Override vector store configuration for this request

{
  "chunkSize": 1000,
  "chunkOverlap": 200
}

Response

{
  "status": "success",
  "message": "Document upserted successfully",
  "numAdded": 5,
  "addedDocs": [
    {
      "id": "doc-uuid-1",
      "text": "Chunk 1 of the document...",
      "metadata": {
        "source": "documentation",
        "category": "introduction"
      }
    }
  ]
}

status · string

Status of the operation: success or error

message · string

Human-readable message about the operation

numAdded · number

Number of document chunks added to the vector store

addedDocs · array

Array of documents that were added with their IDs and metadata

Upsert Files

Upload and process files to upsert into a vector store.

POST /api/v1/vector/upsert/:id (with files)

curl -X POST http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/path/to/document.pdf" \
  -F "files=@/path/to/article.txt" \
  -F "metadata={\"source\":\"upload\",\"batch\":\"2024-03\"}" 

Supported File Types

Flowise supports various file types depending on your chatflow configuration:

• Documents: PDF, DOCX, TXT, MD
• Data: CSV, JSON, XLSX
• Code: JS, TS, PY, JAVA, CPP
• Web: HTML, XML

File processing uses the document loaders configured in your chatflow. Ensure appropriate loaders are set up for your file types.

Internal Upsert

The internal upsert endpoint is used for administrative operations and internal workflows:

POST /api/v1/vector/internal-upsert/:id

curl -X POST http://localhost:3000/api/v1/vector/internal-upsert/CHATFLOW_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Internal document",
    "metadata": {"internal": true}
  }'

Internal endpoints require JWT authentication and are typically used by the Flowise UI or automated workflows.

Chunking Strategy

Documents are automatically split into chunks before embedding. You can configure the chunking strategy:

const response = await fetch(
  'http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: 'Long document content...',
      overrideConfig: {
        chunkSize: 1000,
        chunkOverlap: 200,
        separators: ['\n\n', '\n', ' ']
      }
    })
  }
).then(res => res.json());

Metadata Filtering

Metadata enables powerful filtering during retrieval. Use descriptive metadata to improve search accuracy:

JavaScript

// Upsert with rich metadata
await fetch('http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Q1 2024 financial report shows 20% growth...',
    metadata: {
      type: 'financial_report',
      quarter: 'Q1',
      year: 2024,
      department: 'finance',
      confidential: false,
      tags: ['growth', 'quarterly', 'revenue']
    }
  })
});

Batch Upserts

For large-scale updates, batch multiple documents in a single request:

const documents = [
  {
    text: 'Document 1 content...',
    metadata: { id: 'doc1', type: 'article' }
  },
  {
    text: 'Document 2 content...',
    metadata: { id: 'doc2', type: 'article' }
  },
  {
    text: 'Document 3 content...',
    metadata: { id: 'doc3', type: 'guide' }
  }
];

for (const doc of documents) {
  await fetch('http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(doc)
  });
  
  // Add delay to avoid rate limiting
  await new Promise(resolve => setTimeout(resolve, 100));
}

File Upload Example

Upload multiple files with custom metadata:

const formData = new FormData();

// Add multiple files
formData.append('files', fileInput1.files[0]);
formData.append('files', fileInput2.files[0]);

// Add metadata as JSON string
formData.append('metadata', JSON.stringify({
  source: 'user_upload',
  uploadedBy: '[e-mail]',
  timestamp: new Date().toISOString()
}));

const response = await fetch(
  'http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
  }
).then(res => res.json());

console.log(`Uploaded ${response.numAdded} chunks`);

Rate Limiting

Vector upsert operations may be rate-limited to prevent abuse:

Implement retry logic with exponential backoff:

async function upsertWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        'http://localhost:3000/api/v1/vector/upsert/CHATFLOW_ID',
        {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(data)
        }
      );
      
      if (response.status === 429) {
        // Rate limited, wait and retry
        const waitTime = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Vector Store Requirements

Chatflow Must Have Vector Store

The chatflow must be configured with a vector store node (e.g., Pinecone, Qdrant, Chroma) to accept upsert requests.

If the chatflow doesn’t have a vector store, you’ll receive an error.

Document Loaders Required for Files

To upsert files, the chatflow must have appropriate document loader nodes configured.

For example, to process PDFs, include a PDF loader node in your flow.

Text Splitters

Text splitter nodes determine how documents are chunked before embedding.

Configure chunk size and overlap based on your use case:

• Technical docs: 500-1000 tokens, 100-200 overlap
• Articles: 1000-2000 tokens, 200-400 overlap
• Short Q&A: 200-500 tokens, 50-100 overlap

Error Handling

401 Unauthorized

Missing or invalid API key.

Solution: Include a valid API key in the Authorization header.

404 Not Found

Chatflow doesn’t exist.

Solution: Verify the chatflow ID is correct.

500 Internal Server Error

Vector store operation failed.

Possible causes:

• Vector store credentials are invalid
• Network connectivity issues
• Vector store quota exceeded

Solution: Check chatflow logs and vector store status.