File Search API

Version: 2.0 Base URL: https://filesearchrag.usinc.ai

Quick Start

API Key

x-api-key: <YOUR_API_KEY>

Create Collection API

Endpoint: POST /v2/collections

Overview

The Create Collection API enables you to upload and process documents into organized, searchable collections for Retrieval-Augmented Generation (RAG). RAG is a technique that enhances AI model responses by retrieving relevant information from your documents before generating answers, resulting in more accurate and contextually relevant outputs.

Key Features

• OCR-based extraction using USF Vision API for accurate text parsing from any document type
• Parent-child chunking that preserves document context for better retrieval accuracy
• Hierarchical organization with collections and sub-collections
• S3 preview generation for file thumbnails in UI
• User-scoped isolation ensuring private access to your collections
• Concurrent processing of up to 3 files simultaneously
• SSE Streaming for real-time progress updates

API Endpoint

Authentication

All API requests require authentication using an API key passed in the request header.

Example API Key:

x-api-key: <YOUR_API_KEY>

⚠️ Security Note: Keep your API key secure and never expose it in client-side code or public repositories.

Request Format

Files must be sent as multipart/form-data. This is the standard HTTP format for uploading binary data.

Request Parameters

Request Behavior

• New Collection: Omit collection_id to create a brand new collection
• Append to Existing: Provide collection_id to add files as a new sub-collection within an existing collection
• Collection ID Format: Generated IDs use the format vs_* (e.g., vs_9b1fd5b2186f45bc9a35eab321c8318f)

Usage Examples

Python

Create New Collection (Single File):

import requests

url = "https://filesearchrag.usinc.ai/v2/collections"
headers = {"x-api-key": ""}

# Upload a single file to create a new collection
with open("document.pdf", "rb") as f:
    files = [("files", ("document.pdf", f, "application/pdf"))]
    data = {"name": "My Documents"}

    response = requests.post(url, headers=headers, files=files, data=data)
    result = response.json()

    print(f"Collection ID: {result['collection']['id']}")
    print(f"Sub-collections: {result['sub_collections']}")

Create New Collection (Batch Upload):

import requests

url = "https://filesearchrag.usinc.ai/v2/collections"
headers = {"x-api-key": ""}

# Upload multiple files to create a new collection
files = [
    ("files", ("report.pdf", open("report.pdf", "rb"), "application/pdf")),
    ("files", ("data.xlsx", open("data.xlsx", "rb"), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")),
    ("files", ("notes.txt", open("notes.txt", "rb"), "text/plain"))
]
data = {"name": "Q4 Financial Reports"}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

print(f"Collection: {result['collection']['name']}")
print(f"Files processed: {result['summary']['successful']}/{result['summary']['total_files']}")
print(f"Total chunks: {result['summary']['total_chunks']}")

# Don't forget to close file handles
for _, (_, f, _) in files:
    f.close()

Append to Existing Collection:

import requests

url = "https://filesearchrag.usinc.ai/v2/collections"
headers = {"x-api-key": ""}

# Append files to an existing collection
existing_collection_id = "vs_9b1fd5b2186f45bc9a35eab321c8318f"

files = [
    ("files", ("new_report.pdf", open("new_report.pdf", "rb"), "application/pdf"))
]
data = {
    "name": "Q4 Reports",
    "collection_id": existing_collection_id
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

print(f"Added to collection: {result['collection']['id']}")
print(f"New sub-collection: {result['latest_sub_collection_id']}")

JavaScript

Create New Collection (Single File):

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function createCollection() {
    const form = new FormData();
    form.append('files', fs.createReadStream('document.pdf'));
    form.append('name', 'My Documents');

    try {
        const response = await axios.post(
            'https://filesearchrag.usinc.ai/v2/collections',
            form,
            {
                headers: {
                    'x-api-key': '',
                    ...form.getHeaders()
                }
            }
        );

        console.log('Collection ID:', response.data.collection.id);
        console.log('Sub-collections:', response.data.sub_collections);
    } catch (error) {
        console.error(error.response?.data || error.message);
    }
}

createCollection();

Create New Collection (Batch Upload):

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function createBatchCollection() {
    const form = new FormData();

    // Append multiple files
    form.append('files', fs.createReadStream('report.pdf'));
    form.append('files', fs.createReadStream('data.xlsx'));
    form.append('files', fs.createReadStream('notes.txt'));
    form.append('name', 'Q4 Financial Reports');

    try {
        const response = await axios.post(
            'https://filesearchrag.usinc.ai/v2/collections',
            form,
            {
                headers: {
                    'x-api-key': '',
                    ...form.getHeaders()
                }
            }
        );

        const { data } = response;
        console.log('Collection:', data.collection.name);
        console.log('Processed:', data.summary.successful + '/' + data.summary.total_files);
        console.log('Total chunks:', data.summary.total_chunks);
    } catch (error) {
        console.error(error.response?.data || error.message);
    }
}

createBatchCollection();

cURL

Create New Collection (Single File):

curl -X POST "https://filesearchrag.usinc.ai/v2/collections" \
  -H "x-api-key: " \
  -F "files=@document.pdf" \
  -F "name=My Documents"

Create New Collection (Batch Upload):

curl -X POST "https://filesearchrag.usinc.ai/v2/collections" \
  -H "x-api-key: " \
  -F "files=@report.pdf" \
  -F "files=@data.xlsx" \
  -F "files=@notes.txt" \
  -F "name=Q4 Financial Reports"

Append to Existing Collection:

curl -X POST "https://filesearchrag.usinc.ai/v2/collections" \
  -H "x-api-key: " \
  -F "files=@new_report.pdf" \
  -F "name=Q4 Reports" \
  -F "collection_id=vs_9b1fd5b2186f45bc9a35eab321c8318f"

With S3 Preview and Summarization:

curl -X POST "https://filesearchrag.usinc.ai/v2/collections" \
  -H "x-api-key: " \
  -F "files=@document.pdf" \
  -F "name=My Documents" \
  -F "summarize=true" \
  -F "preview=1"

Response Format

The API returns a comprehensive JSON response with collection details, file information, and processing statistics.

HTTP Status Codes

Success Response (HTTP 200)

{
    "status_code": 200,
    "status": "success",
    "api_version": "v2",
    "collection": {
        "id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
        "name": "Q4 Financial Reports",
        "created_at": "2026-02-09T10:30:00.000Z",
        "sub_collections_count": 3
    },
    "sub_collections": [
        "vs_a1b2c3d4e5f6g7h8i9j0",
        "vs_b2c3d4e5f6g7h8i9j0k1",
        "vs_c3d4e5f6g7h8i9j0k1l2"
    ],
    "latest_sub_collection_id": "vs_c3d4e5f6g7h8i9j0k1l2",
    "choices": [
        {
            "id": "file-doc_abc123def456",
            "bytes": 1048576,
            "size": "1.0 MB",
            "created_at": 1707480000,
            "filename": "report.pdf",
            "status": "processed",
            "status_details": "File processed with parent-child chunking",
            "sub_collection_id": "vs_a1b2c3d4e5f6g7h8i9j0",
            "metadata_document_id": "doc_abc123def456",
            "mongo_id": "65c1a2b3c4d5e6f7890abcde",
            "chunks_count": 45,
            "total_tokens": 12500,
            "parser_used": "vision_ocr",
            "chunking_mode": "parent_child",
            "parent_child_stats": {
                "parent_chunks": 15,
                "child_chunks": 45,
                "avg_parent_tokens": 1800,
                "avg_child_tokens": 280
            },
            "performance": {
                "extraction_time": 5.2,
                "chunking_time": 0.8,
                "embedding_time": 2.1,
                "indexing_time": 1.2,
                "total_time": 9.3
            },
            "preview_enabled": true,
            "s3_key": "collections/vs_9b1fd5b2186f45bc/files/report.pdf",
            "s3_url": "https://s3.amazonaws.com/bucket/collections/vs_9b1fd5b2186f45bc/files/report.pdf",
            "content_type": "application/pdf"
        }
    ],
    "processed_files": [
        {
            "filename": "report.pdf",
            "size": "1.0 MB",
            "file_id": "file-doc_abc123def456",
            "chunks": 45
        }
    ],
    "unprocessed_files": null,
    "summary": {
        "total_files": 1,
        "successful": 1,
        "failed": 0,
        "total_chunks": 45,
        "total_size": "1.0 MB",
        "total_size_bytes": 1048576,
        "summarization_enabled": false,
        "chunking_mode": "parent_child",
        "processing_time_seconds": 12.45,
        "avg_time_per_file": 12.45,
        "chunks_per_second": 3.61
    }
}

Partial Success Response (HTTP 207)

{
    "status_code": 207,
    "status": "partial",
    "api_version": "v2",
    "collection": {
        "id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
        "name": "Q4 Financial Reports",
        "created_at": "2026-02-09T10:30:00.000Z",
        "sub_collections_count": 1
    },
    "sub_collections": ["vs_a1b2c3d4e5f6g7h8i9j0"],
    "latest_sub_collection_id": "vs_a1b2c3d4e5f6g7h8i9j0",
    "choices": [
        {
            "id": "file-doc_abc123def456",
            "bytes": 1048576,
            "size": "1.0 MB",
            "created_at": 1707480000,
            "filename": "report.pdf",
            "status": "processed",
            "status_details": "File processed with parent-child chunking",
            "sub_collection_id": "vs_a1b2c3d4e5f6g7h8i9j0",
            "chunks_count": 45
        },
        {
            "id": null,
            "bytes": 2097152,
            "size": "2.0 MB",
            "created_at": 1707480000,
            "filename": "corrupted.pdf",
            "status": "error",
            "status_details": "Failed to extract text from file",
            "sub_collection_id": null
        }
    ],
    "processed_files": [
        {"filename": "report.pdf", "size": "1.0 MB", "file_id": "file-doc_abc123def456", "chunks": 45}
    ],
    "unprocessed_files": [
        {"filename": "corrupted.pdf", "size": "2.0 MB", "error": "Failed to extract text from file"}
    ],
    "summary": {
        "total_files": 2,
        "successful": 1,
        "failed": 1,
        "total_chunks": 45,
        "total_size": "3.0 MB",
        "total_size_bytes": 3145728,
        "summarization_enabled": false,
        "chunking_mode": "parent_child",
        "processing_time_seconds": 15.32,
        "avg_time_per_file": 7.66,
        "chunks_per_second": 2.94
    }
}

Response Fields Reference

Top-Level Fields

Collection Object

Choice Object (File Details)

Summary Object

SSE Streaming Mode

When stream=true, the API returns Server-Sent Events for real-time progress updates.

SSE Stages

SSE Event Format

event: file_progress
data: {"filename": "report.pdf", "stage": "extraction", "progress": 45, "message": "Extracting text..."}

event: file_progress
data: {"filename": "report.pdf", "stage": "embedding", "progress": 80, "message": "Generating embeddings..."}

event: complete
data: {"status": "success", "collection_id": "vs_9b1fd5b2186f45bc", "total_chunks": 45}

Supported File Types

Error Handling

Error Response Format

{
    "error": {
        "message": "Error description",
        "type": "validation_error",
        "code": "ERROR_CODE",
        "status_code": 400,
        "correlation_id": "abc12345",
        "timestamp": "2026-02-09T10:30:00.000Z",
        "param": "field_name"
    }
}

Common Error Codes

Best Practices

1. Validate Files Before Upload: Check file size (up to 100 MB OR up to 5,000 pages) and extension before sending requests
2. Handle Partial Success: When status_code is 207, check both processed_files and unprocessed_files
3. Store Sub-Collection IDs: Save the returned latest_sub_collection_id for use in /v2/filesearch
4. Use Meaningful Names: Set descriptive name values for easy identification
5. Batch Related Documents: Upload related files together for logical groupings
6. Implement Retry Logic: For 5xx errors, use exponential backoff with max 3 attempts
7. Monitor Performance: Check summary.processing_time_seconds for throughput optimization
8. Use Append for Updates: Use collection_id parameter to add files to existing collections

Using Sub-Collection IDs for Search

After uploading files, use the returned sub_collection_id or latest_sub_collection_id with the /v2/filesearch endpoint:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: " \
  -H "Content-Type: application/json" \
  -d '{
    "model": "usf1-mini",
    "messages": [{"role": "user", "content": "What are the key findings?"}],
    "collection_name": "vs_9b1fd5b2186f45bc9a35eab321c8318f"
  }'

Additional Endpoints

Get Collection Details

curl -X GET "https://filesearchrag.usinc.ai/v2/collections/vs_9b1fd5b2186f45bc9a35eab321c8318f" \
  -H "x-api-key: "

Delete Collection

Delete entire collection:

curl -X DELETE "https://filesearchrag.usinc.ai/v2/collections/vs_9b1fd5b2186f45bc9a35eab321c8318f?is_sub_collection=false" \
  -H "x-api-key: "

Delete sub-collection only:

curl -X DELETE "https://filesearchrag.usinc.ai/v2/collections/vs_a1b2c3d4e5f6g7h8?is_sub_collection=true" \
  -H "x-api-key: "

FileSearch API

Endpoint: POST /v2/filesearch

Overview

The FileSearch API enables RAG-powered (Retrieval-Augmented Generation) semantic search across your document collections. It combines advanced hybrid search (BM25 keyword + semantic vector search) with LLM-generated responses that include inline citations to source documents.

Key Features

API Endpoint

Authentication

All API requests require authentication using an API key passed in the request header.

Example API Key:

x-api-key: <YOUR_API_KEY>

⚠️ Security Note: Keep your API key secure and never expose it in client-side code or public repositories.

Request Format

Requests must be sent as application/json with a JSON body.

Request Parameters

Core Parameters

Collection & File Parameters

Search Parameters

Pagination Parameters

Message Object

Request Body Schema

{
    "model": "usf1-mini",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What are the key findings in the Q4 report?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 4000,
    "stream": false,
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "conversation_id": null,
    "web_search": false,
    "file_id": null,
    "search_type": "hybrid",
    "top_k": 20,
    "limit": 10,
    "offset": 0,
    "retrieval_token": null
}

Request Behavior

Search Modes

Pagination System

How Pagination Works

1. First Request: Fresh search runs, results cached with retrieval_token
2. Subsequent Requests: Pass retrieval_token + different offset to paginate
3. Token Expiry: Retrieval tokens expire after 5 minutes (300 seconds)

Pagination Flow Example

Request 1: Fresh Search

{
    "messages": [{"role": "user", "content": "List all contracts"}],
    "collection_id": "vs_abc123",
    "limit": 10,
    "offset": 0
}

Response 1:

{
    "pagination": {
        "offset": 0,
        "limit": 10,
        "total": 25,
        "has_more": true,
        "retrieval_token": "ret_abc123def456",
        "retrieval_token_expires_in": 300
    }
}

Request 2: Paginated (No Re-Search)

{
    "messages": [{"role": "user", "content": "List all contracts"}],
    "collection_id": "vs_abc123",
    "limit": 10,
    "offset": 10,
    "retrieval_token": "ret_abc123def456"
}

Response 2:

{
    "pagination": {
        "offset": 10,
        "limit": 10,
        "total": 25,
        "has_more": true,
        "retrieval_token": "ret_abc123def456",
        "retrieval_token_expires_in": 300
    }
}

Usage Examples

Python

Basic Search:

import requests

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "What are the key findings in the Q4 report?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f"
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(f"Answer: {result['choices'][0]['message']['content']}")
print(f"Citations: {result['citations']}")
print(f"Docs used: {result['search_summary']['docs_used']}")

Multi-Turn Conversation:

import requests

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

# First message
payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "What was the total revenue in Q4?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f"
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
conversation_id = result['conversation_id']

# Follow-up message with history
payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "What was the total revenue in Q4?"},
        {"role": "assistant", "content": result['choices'][0]['message']['content']},
        {"role": "user", "content": "How does that compare to Q3?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "conversation_id": conversation_id
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(f"Answer: {result['choices'][0]['message']['content']}")

Search with File Filter:

import requests

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "Summarize the main points"}
    ],
    "file_id": "file-abc123def456"  # Search only within this file
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(f"Answer: {result['choices'][0]['message']['content']}")
print(f"File: {result['file_filter']['filename']}")

Pagination:

import requests

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

# First request - get first page
payload = {
    "messages": [{"role": "user", "content": "List all contracts"}],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "limit": 5,
    "offset": 0
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(f"Page 1: {result['search_summary']['docs_used']} of {result['pagination']['total']} docs")

# Get next page using retrieval_token (no re-search)
if result['pagination']['has_more']:
    payload = {
        "messages": [{"role": "user", "content": "List all contracts"}],
        "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
        "limit": 5,
        "offset": 5,
        "retrieval_token": result['pagination']['retrieval_token']
    }

    response = requests.post(url, headers=headers, json=payload)
    result = response.json()
    print(f"Page 2: {result['search_summary']['docs_used']} more docs")

Streaming Response:

import requests
import json

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "What are the key findings?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "stream": True
}

response = requests.post(url, headers=headers, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data_str = line_str[6:]
            if data_str.strip() == '[DONE]':
                break
            try:
                chunk = json.loads(data_str)
                if 'choices' in chunk and chunk['choices']:
                    delta = chunk['choices'][0].get('delta', {})
                    content = delta.get('content', '')
                    if content:
                        print(content, end='', flush=True)
            except json.JSONDecodeError:
                continue

With Web Search Augmentation:

import requests

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "What are the latest industry trends?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "web_search": True  # Combine document search with web results
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(f"Answer: {result['choices'][0]['message']['content']}")
if 'executable_data' in result:
    print(f"Web sources: {len(result['executable_data'][0]['data'])} results")

Search with Specific Mode:

import requests

url = "https://filesearchrag.usinc.ai/v2/filesearch"
headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

# Semantic-only search (meaning-based)
payload = {
    "model": "usf1-mini",
    "messages": [
        {"role": "user", "content": "What are the financial risks?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "search_type": "semantic",
    "top_k": 15
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(f"Search type: {result['search_summary']['search_type']}")
print(f"Answer: {result['choices'][0]['message']['content']}")

JavaScript

Basic Search:

const axios = require('axios');

async function searchDocuments() {
    try {
        const response = await axios.post(
            'https://filesearchrag.usinc.ai/v2/filesearch',
            {
                model: 'usf1-mini',
                messages: [
                    { role: 'user', content: 'What are the key findings in the Q4 report?' }
                ],
                collection_id: 'vs_9b1fd5b2186f45bc9a35eab321c8318f'
            },
            {
                headers: {
                    'x-api-key': '<YOUR_API_KEY>',
                    'Content-Type': 'application/json'
                }
            }
        );

        console.log('Answer:', response.data.choices[0].message.content);
        console.log('Citations:', response.data.citations);
        console.log('Sources:', response.data.sources.length);
    } catch (error) {
        console.error(error.response?.data || error.message);
    }
}

searchDocuments();

Streaming Response:

const axios = require('axios');

async function streamSearch() {
    const response = await axios.post(
        'https://filesearchrag.usinc.ai/v2/filesearch',
        {
            model: 'usf1-mini',
            messages: [
                { role: 'user', content: 'What are the key findings?' }
            ],
            collection_id: 'vs_9b1fd5b2186f45bc9a35eab321c8318f',
            stream: true
        },
        {
            headers: {
                'x-api-key': '<YOUR_API_KEY>',
                'Content-Type': 'application/json'
            },
            responseType: 'stream'
        }
    );

    response.data.on('data', (chunk) => {
        const lines = chunk.toString().split('\n');
        for (const line of lines) {
            if (line.startsWith('data: ')) {
                const dataStr = line.slice(6);
                if (dataStr.trim() === '[DONE]') return;
                try {
                    const data = JSON.parse(dataStr);
                    const content = data.choices?.[0]?.delta?.content;
                    if (content) process.stdout.write(content);
                } catch (e) {}
            }
        }
    });
}

streamSearch();

cURL

Basic Search:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "usf1-mini",
    "messages": [{"role": "user", "content": "What are the key findings?"}],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f"
  }'

With Custom System Prompt:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "usf1-mini",
    "messages": [
      {"role": "system", "content": "You are a financial analyst. Provide concise, data-driven answers."},
      {"role": "user", "content": "What was the revenue growth rate?"}
    ],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "temperature": 0.3
  }'

Streaming Response:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "usf1-mini",
    "messages": [{"role": "user", "content": "What are the key findings?"}],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "stream": true
  }'

Search Multiple Collections:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "usf1-mini",
    "messages": [{"role": "user", "content": "Compare the Q3 and Q4 results"}],
    "collection_id": "vs_abc123,vs_def456"
  }'

With Pagination:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "usf1-mini",
    "messages": [{"role": "user", "content": "List all contracts"}],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "limit": 10,
    "offset": 0
  }'

With Search Type:

curl -X POST "https://filesearchrag.usinc.ai/v2/filesearch" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "usf1-mini",
    "messages": [{"role": "user", "content": "Find exact term: indemnification clause"}],
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "search_type": "keyword",
    "top_k": 20
  }'

Response Format

Success Response (HTTP 200)

{
    "id": "chatcmpl-abc123def456",
    "object": "filesearch.completion",
    "created": 1707480000,
    "model": "usf1-mini",
    "api_version": "v2",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Based on the Q4 report, total revenue increased by 25% to $331.7M [[1]], driven primarily by market expansion in the APAC region [[2]]. Customer acquisition costs decreased by 12% [[1]], while the net promoter score improved to 27 [[3]]."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 2500,
        "completion_tokens": 150,
        "total_tokens": 2650
    },
    "conversation_id": "abc123def456",
    "history_source": "messages",
    "citations": [
        {
            "index": 1,
            "filename": "Q4_Report.pdf",
            "page": 5,
            "snippet": "Total revenue for Q4 2025 reached $331.7M, representing a 25% increase...",
            "confidence": 0.95
        },
        {
            "index": 2,
            "filename": "Q4_Report.pdf",
            "page": 12,
            "snippet": "APAC region contributed 45% of new customer acquisitions...",
            "confidence": 0.89
        },
        {
            "index": 3,
            "filename": "Q4_Report.pdf",
            "page": 8,
            "snippet": "Net Promoter Score improved from 21 to 27...",
            "confidence": 0.92
        }
    ],
    "sources": [
        {
            "document": "Full parent chunk text with complete context...",
            "filename": "Q4_Report.pdf",
            "score": 0.95,
            "chunk_type": "parent",
            "page": 5,
            "collection_name": "vs_9b1fd5b2186f45bc9a35eab321c8318f"
        }
    ],
    "search_summary": {
        "search_type": "hybrid",
        "context_tokens": 4500,
        "response_path": "direct",
        "docs_used": 3,
        "docs_found": 8,
        "bm25_count": 5,
        "bm25_matches": [
            {
                "rank": 1,
                "score": 0.92,
                "page": 5,
                "filename": "Q4_Report.pdf",
                "snippet": "Total revenue for Q4 2025..."
            }
        ],
        "semantic_count": 6,
        "semantic_matches": [
            {
                "rank": 1,
                "score": 0.89,
                "page": 12,
                "filename": "Q4_Report.pdf",
                "snippet": "APAC region contributed..."
            }
        ],
        "merged_results": 8,
        "rrf_k": 60,
        "top_sources": [
            {
                "document_id": "file-abc123",
                "filename": "Q4_Report.pdf",
                "page": 5,
                "relevance_score": 0.95,
                "match_type": "both",
                "bm25_rank": 1,
                "semantic_rank": 2,
                "collection_name": "vs_9b1fd5b2186f45bc9a35eab321c8318f"
            }
        ],
        "all_retrieved_files": ["Q4_Report.pdf", "Q3_Report.pdf", "Annual_Summary.pdf"],
        "all_retrieved_count": 3
    },
    "pagination": {
        "offset": 0,
        "limit": 10,
        "total": 8,
        "has_more": false,
        "retrieval_token": "ret_abc123def456",
        "retrieval_token_expires_in": 300
    },
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "context_overflow": false,
    "search_notice": null,
    "suggested_questions": null,
    "history": [],
    "file_filter": null
}

Context Overflow Response

When retrieved context exceeds 15,000 tokens, the API returns suggested questions instead of attempting to process all content:

{
    "id": "chatcmpl-abc123def456",
    "object": "filesearch.completion",
    "created": 1707480000,
    "model": "usf1-mini",
    "api_version": "v2",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "I found 25 relevant sections across your documents about 'financial performance'. To provide the most accurate answer, please narrow your search by selecting one of the suggested questions below."
            },
            "finish_reason": "context_overflow"
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    },
    "conversation_id": "abc123def456",
    "context_overflow": true,
    "found_results": 25,
    "suggested_questions": [
        {
            "text": "What are the details in Table 15.1.3?",
            "reason": "Found 8 matches on pages 12, 13, 14",
            "match_count": 8,
            "pages": [12, 13, 14]
        },
        {
            "text": "Tell me about Revenue Analysis",
            "reason": "Found 6 matches on pages 5, 6, 7",
            "match_count": 6,
            "pages": [5, 6, 7]
        }
    ],
    "available_topics": [
        {
            "topic": "Revenue Analysis",
            "matches": 6,
            "pages": [5, 6, 7]
        },
        {
            "topic": "Cost Structure",
            "matches": 4,
            "pages": [15, 16]
        }
    ],
    "search_summary": {
        "search_type": "hybrid",
        "context_tokens": 18500,
        "response_path": "suggested_questions",
        "bm25_count": 12,
        "semantic_count": 15,
        "merged_results": 25,
        "top_sources": [...]
    },
    "pagination": {
        "offset": 0,
        "limit": 10,
        "total": 25,
        "has_more": true,
        "retrieval_token": "ret_abc123def456",
        "retrieval_token_expires_in": 300
    }
}

Response Fields Reference

Top-Level Fields

Choice Object

Message Object

Citation Object

Source Object

Search Summary Object

BM25/Semantic Match Object

Top Source Object

Pagination Object

Usage Object

File Filter Object

SSE Streaming Format

When stream: true, the API returns Server-Sent Events (SSE) with real-time progress updates.

Progress Events

data: {"event": "progress", "data": {"status": "searching", "detail": "Running hybrid search (BM25 + Semantic)"}}

data: {"event": "progress", "data": {"status": "reranked", "detail": "Found 8 relevant documents"}}

data: {"event": "progress", "data": {"status": "generating", "detail": "Starting LLM response generation"}}

Content Chunks

data: {"id": "chatcmpl-abc123", "object": "chat.completion.chunk", "created": 1707480000, "model": "usf1-mini", "api_version": "v2", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "Based on the Q4 report, "}, "finish_reason": null}]}

data: {"id": "chatcmpl-abc123", "object": "chat.completion.chunk", "created": 1707480000, "model": "usf1-mini", "api_version": "v2", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "total revenue increased by 25% [[1]]. "}, "finish_reason": null}]}

Final Chunk

data: {"id": "chatcmpl-abc123", "object": "filesearch.completion", "created": 1707480000, "model": "usf1-mini", "api_version": "v2", "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 2500, "completion_tokens": 150, "total_tokens": 2650}, "citations": [...], "sources": [...]}

data: {"event": "progress", "data": {"status": "complete", "detail": "Response generation finished"}}

data: [DONE]

Progress Status Values

Error Handling

Error Response Format

{
    "error": {
        "message": "Error description",
        "type": "validation_error",
        "code": "ERROR_CODE",
        "status_code": 400,
        "correlation_id": "abc12345",
        "timestamp": "2026-02-09T10:30:00.000Z",
        "param": "field_name"
    }
}

Common Error Codes

Retry Logic

The API implements automatic retry for transient failures:

Retryable Status Codes: 502, 503, 504, Timeout

Best Practices

Technical Configuration

Configuration Constants

List Collections API

Endpoint: GET /v2/collections

Overview

Retrieves all collections belonging to the authenticated user with file details, sub-collections, and processing status.

API Endpoint

Authentication

Usage Examples

Python

import requests

url = "https://filesearchrag.usinc.ai/v2/collections"
headers = {"x-api-key": ""}

response = requests.get(url, headers=headers)
result = response.json()

print(f"Total collections: {result['total']}")
for collection in result['data']:
    print(f"Collection: {collection['collection']['name']} - {collection['summary']['total_files']} files")

JavaScript

const axios = require('axios');

const response = await axios.get(
    'https://filesearchrag.usinc.ai/v2/collections',
    { headers: { 'x-api-key': '' } }
);

console.log('Total:', response.data.total);

cURL

curl -X GET "https://filesearchrag.usinc.ai/v2/collections" \
  -H "x-api-key: "

Response Format

{
    "status_code": 200,
    "status": "success",
    "api_version": "v2",
    "data": [
        {
            "collection": {
                "id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
                "name": "Q4 Financial Reports",
                "created_at": "2026-02-09T10:30:00.000Z",
                "sub_collections_count": 3,
                "processing_status": {
                    "status": "completed",
                    "progress_percent": 100,
                    "total_files": 5,
                    "processed_files": 5,
                    "failed_files": 0
                }
            },
            "sub_collections": ["vs_a1b2c3d4e5f6g7h8i9j0"],
            "latest_sub_collection_id": "vs_a1b2c3d4e5f6g7h8i9j0",
            "choices": [
                {
                    "id": "file-doc_abc123def456",
                    "filename": "report.pdf",
                    "size": "1.0 MB",
                    "chunks_count": 45,
                    "status": "processed",
                    "sub_collection_id": "vs_a1b2c3d4e5f6g7h8i9j0"
                }
            ],
            "summary": {
                "total_files": 1,
                "successful": 1,
                "failed": 0,
                "total_chunks": 45,
                "total_size": "1.0 MB"
            }
        }
    ],
    "total": 1
}

Response Fields

Error Handling

{
    "error": {
        "message": "Error description",
        "type": "internal_error",
        "code": "internal_error",
        "status_code": 500
    }
}

Delete Collection API

Endpoint: DELETE /v2/collections/{col_id}

Overview

Delete a collection or sub-collection by ID. Supports two deletion modes:

• Full Delete: Remove entire collection with all sub-collections and files
• Sub-Collection Delete: Remove only a specific sub-collection

Deletion pipeline:

1. Find collection/sub-collection in MongoDB
2. Delete vectors from Qdrant
3. Delete file metadata from MongoDB DocData
4. Delete/update collection record

API Endpoint

Authentication

Path Parameters

Query Parameters

Usage Examples

Python

Delete Entire Collection (default behavior):

import requests

# Use collection_id (parent collection ID)
collection_id = "vs_9b1fd5b2186f45bc9a35eab321c8318f"
url = f"https://filesearchrag.usinc.ai/v2/collections/{collection_id}"
headers = {"x-api-key": ""}

# No params needed - defaults to deleting entire collection
response = requests.delete(url, headers=headers)
result = response.json()

print(f"Deleted: {result['collection_name']}")
print(f"Sub-collections removed: {result['summary']['sub_collections_removed']}")
print(f"Documents removed: {result['summary']['total_docs_removed']}")

Delete Sub-Collection Only:

import requests

# Use sub_collection_id (child sub-collection ID from collection's sub_collections array)
sub_collection_id = "vs_4f14ee1a-46c7-4b49-a683-6a44e18b4d56"
url = f"https://filesearchrag.usinc.ai/v2/collections/{sub_collection_id}"
headers = {"x-api-key": ""}

# is_sub_collection=true - deletes only this sub-collection
response = requests.delete(url, headers=headers, params={"is_sub_collection": True})
result = response.json()

print(f"Deleted sub-collection: {result['sub_collection_id']}")
print(f"Parent collection: {result['parent_collection_id']}")
print(f"Documents removed: {result['docs_deleted']}")

JavaScript

Delete Entire Collection (default behavior):

const axios = require('axios');

// Use collection_id (parent collection ID)
const collectionId = 'vs_9b1fd5b2186f45bc9a35eab321c8318f';

const response = await axios.delete(
    `https://filesearchrag.usinc.ai/v2/collections/${collectionId}`,
    { headers: { 'x-api-key': '' } }
);

console.log('Deleted:', response.data.collection_name);
console.log('Sub-collections removed:', response.data.summary.sub_collections_removed);

Delete Sub-Collection Only:

const axios = require('axios');

// Use sub_collection_id (child sub-collection ID)
const subCollectionId = 'vs_4f14ee1a-46c7-4b49-a683-6a44e18b4d28';

const response = await axios.delete(
    `https://filesearchrag.usinc.ai/v2/collections/${subCollectionId}`,
    {
        headers: { 'x-api-key': '' },
        params: { is_sub_collection: true }
    }
);

console.log('Deleted sub-collection:', response.data.sub_collection_id);

cURL

Delete Entire Collection (pass collection_id):

# collection_id = parent collection ID
curl -X DELETE "https://filesearchrag.usinc.ai/v2/collections/vs_9b1fd5b2186f45bc9a35eab321c8318f" \
  -H "x-api-key: "

Delete Sub-Collection Only (pass sub_collection_id):

# sub_collection_id = child sub-collection ID from sub_collections array
curl -X DELETE "https://filesearchrag.usinc.ai/v2/collections/vs_4f14ee1a-46c7-4b49-a683-6a44e18b4d28?is_sub_collection=true" \
  -H "x-api-key: "

Response Format

Delete Entire Collection (is_sub_collection=false)

{
    "status_code": 200,
    "status": "success",
    "api_version": "v2",
    "message": "Collection 'Q4 Financial Reports' and all sub-collections deleted successfully",
    "collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "collection_name": "Q4 Financial Reports",
    "deleted_at": 1707480000,
    "sub_collections_deleted": [
        "vs_a1b2c3d4e5f6g7h8i9j0",
        "vs_b2c3d4e5f6g7h8i9j0k1"
    ],
    "docs_deleted": 15,
    "summary": {
        "sub_collections_removed": 2,
        "total_docs_removed": 15,
        "processing_time_seconds": 1.25
    }
}

Delete Sub-Collection Only (is_sub_collection=true)

{
    "status_code": 200,
    "status": "success",
    "api_version": "v2",
    "message": "Sub-collection 'Upload 2026-02-09' deleted successfully",
    "sub_collection_id": "vs_a1b2c3d4e5f6g7h8i9j0",
    "sub_collection_name": "Upload 2026-02-09",
    "parent_collection_id": "vs_9b1fd5b2186f45bc9a35eab321c8318f",
    "deleted_at": 1707480000,
    "qdrant_deleted": true,
    "docs_deleted": 5,
    "parent_updated": true,
    "summary": {
        "processing_time_seconds": 0.85
    }
}

Response Fields

Full Collection Delete Response

Sub-Collection Delete Response

Error Handling

Error Response Format

{
    "error": {
        "message": "Collection 'vs_xyz' not found",
        "type": "not_found",
        "code": "collection_not_found",
        "status_code": 404,
        "param": "col_id"
    }
}

Common Error Codes

FileSearchRAG API • Version 2.0 Base URL: https://filesearchrag.usinc.ai