API Reference

Complete REST API reference for RAG DB — authentication, index management, search queries, and monitoring

The RAG DB API is the control plane and query gateway for the indexing platform. It handles authentication, index lifecycle management, four distinct search modes, file tracking, run orchestration, and monitoring.

Base URL

https://your-ragdb-instance.azurecontainerapps.io

All endpoints are at the root level — there is no /api/v1/ prefix.

Authentication

RAG DB supports two authentication methods:

HTTP-only cookie — Set automatically after login via Auth0
x-api-key header — Pass one of your API keys directly in the request header

Authenticate with Auth0 credentials. On success, sets an HTTP-only secure cookie.

{
  "client_id": "your-auth0-client-id",
  "client_secret": "your-auth0-client-secret"
}

Response: 200 OK with Set-Cookie header.

POST `/logout`

Clears the access token cookie.

Response: 200 OK

GET `/validate`

Check whether the current session is authenticated.

Response: 200 OK if valid, 401 Unauthorized otherwise.

API Keys

Manage the API keys used for x-api-key authentication.

GET `/apiKeys`

Returns the current API keys for the authenticated account.

Response:

{
  "key1": "rdb_k1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key2": "rdb_k2_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

POST `/apiKeys/regenerate/{keyType}`

Regenerate a specific API key. The keyType path parameter must be key1 or key2.

Response: 200 OK with the new key value.

{
  "key1": "rdb_k1_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

Index Management

POST `/indexes`

Create a new index. RAG DB provisions a Cosmos DB container, a Service Bus subscription, and an Index Processor container app.

Request body (IndexCreate):

{
  "name": "financial-reports",
  "storageAccount": "myteamstorage",
  "blobContainer": "documents",
  "blobFolder": "finance/2025"
}

Response: 201 Created

{
  "id": "idx_a1b2c3d4e5f6",
  "name": "financial-reports",
  "storageAccount": "myteamstorage",
  "blobContainer": "documents",
  "blobFolder": "finance/2025",
  "queue": "financial-reports-queue",
  "createdAt": "2026-03-05T10:30:00Z",
  "modifiedAt": "2026-03-05T10:30:00Z",
  "status": "provisioning",
  "activeRunId": null
}

GET `/indexes`

List all indexes. Optionally filter by name.

Query Parameter	Type	Description
`name`	string	Filter indexes by name

Response: 200 OK

[
  {
    "id": "idx_a1b2c3d4e5f6",
    "name": "financial-reports",
    "storageAccount": "myteamstorage",
    "blobContainer": "documents",
    "blobFolder": "finance/2025",
    "queue": "financial-reports-queue",
    "createdAt": "2026-03-05T10:30:00Z",
    "modifiedAt": "2026-03-05T12:00:00Z",
    "status": "ready",
    "activeRunId": null
  }
]

GET `/indexes/{indexId}`

Get a single index by ID. Optional query parameters enrich the response.

Query Parameter	Type	Description
`includeActiveRun`	boolean	Include the full active run object
`includeFilesSummary`	boolean	Include a file count breakdown by status

Response: 200 OK

{
  "id": "idx_a1b2c3d4e5f6",
  "name": "financial-reports",
  "storageAccount": "myteamstorage",
  "blobContainer": "documents",
  "blobFolder": "finance/2025",
  "queue": "financial-reports-queue",
  "createdAt": "2026-03-05T10:30:00Z",
  "modifiedAt": "2026-03-05T14:00:00Z",
  "status": "ready",
  "activeRunId": "run_x7y8z9",
  "activeRun": {
    "id": "run_x7y8z9",
    "indexId": "idx_a1b2c3d4e5f6",
    "startTime": "2026-03-05T13:00:00Z",
    "lastUpdated": "2026-03-05T14:00:00Z",
    "endTime": null,
    "documentsIndexed": 42,
    "documentsFailed": 1
  },
  "filesSummary": {
    "indexed": 42,
    "failed": 1,
    "pending": 7,
    "processing": 3
  }
}

DELETE `/indexes/{indexId}`

Delete an index and all associated resources (Cosmos DB container, processor, queue). This is an asynchronous operation.

Response: 202 Accepted

POST `/indexes/updateImage`

Update the Docker image for all Index Processor container apps. Use this after publishing a new processor image.

Response: 202 Accepted

POST `/indexes/{indexId}/updateImage`

Update the Docker image for a specific Index Processor.

Response: 202 Accepted

Search / Query

RAG DB exposes four search modes, each optimized for different use cases. All search endpoints return results with auto-generated SAS tokens injected into file location URLs.

Response Headers

All search endpoints return these custom headers:

Header	Description
`x-request-charge`	Cosmos DB Request Unit (RU) consumption
`x-index-metrics`	Index performance metrics (JSON)
`x-query-metrics`	Query execution metrics (JSON)

SAS Token Injection

Every location field in search results includes an auto-generated Azure Blob Storage SAS token. These are container-level user delegation tokens, read-only, with a 7-day default expiry. You can use the URL directly to fetch the source file.

POST `/indexes/{indexId}/query/semantic`

Semantic search — the recommended default. Provide a natural language query; RAG DB auto-generates the embedding and optionally rewrites the query using AI for better recall.

Request body (SemanticQuery):

{
  "query": "What were the Q3 revenue figures?",
  "top_k": 5
}

Response: 200 OK

[
  {
    "id": "chunk_9f8e7d6c",
    "parentKey": "file_abc123",
    "chunkIndex": 12,
    "name": "quarterly-report.pdf",
    "location": "https://myteamstorage.blob.core.windows.net/documents/finance/2025/quarterly-report.pdf?sv=2024-11-04&st=2026-03-05&se=2026-03-12&sr=c&sp=r&sig=aBcDeFgH...",
    "chunk": "Q3 2025 revenue reached $4.2B, a 15% increase year-over-year driven by growth in cloud services and enterprise subscriptions.",
    "vector": null,
    "score": 0.937
  },
  {
    "id": "chunk_1a2b3c4d",
    "parentKey": "file_def456",
    "chunkIndex": 3,
    "name": "earnings-summary.docx",
    "location": "https://myteamstorage.blob.core.windows.net/documents/finance/2025/earnings-summary.docx?sv=2024-11-04&st=2026-03-05&se=2026-03-12&sr=c&sp=r&sig=xYzWvU...",
    "chunk": "Total revenue for the third quarter was $4.2 billion with an operating margin of 38%.",
    "vector": null,
    "score": 0.891
  }
]

Scoring: priority — blends best_sim, avg_sim, and an original query boost.

POST `/indexes/{indexId}/query/vector`

Vector similarity search — provide a pre-computed embedding vector directly.

Request body (VectorQuery):

{
  "embedding": [0.0123, -0.0456, 0.0789, "... (1536 dimensions)"],
  "top_k": 10
}

Response: 200 OK — same shape as semantic search results.

Scoring: 1 - VectorDistance() (cosine similarity). A score of 1.0 is a perfect match; 0.0 is orthogonal.

POST `/indexes/{indexId}/query/hybrid`

Hybrid search — combines vector similarity with full-text BM25 using Reciprocal Rank Fusion (RRF). Provide both a text query and an embedding vector.

Request body (HybridQuery):

{
  "query_text": "quarterly revenue growth",
  "query_vector": [0.0123, -0.0456, 0.0789, "... (1536 dimensions)"],
  "top_k": 10
}

Response: 200 OK — same shape as semantic search results.

Scoring: 1 / (rank + 60) — RRF formula. The rank from both the vector and full-text sub-queries are fused. Higher scores indicate agreement across both retrieval methods.

POST `/indexes/{indexId}/query/fulltext`

Full-text BM25 search — classic keyword search without vectors.

Request body (FullTextQuery):

{
  "search_text": "revenue Q3 2025",
  "top_k": 10
}

Response: 200 OK — same shape as semantic search results.

Scoring: 1 / (rank + 60) — RRF over BM25 ranking.

File Chunks

Retrieve specific chunks by file location or file ID.

POST `/indexes/{indexId}/files/chunks`

Get chunks for a file by its blob storage location. Optionally narrow to a specific chunk and its surrounding context.

Request body:

{
  "location": "https://myteamstorage.blob.core.windows.net/documents/finance/2025/report.pdf",
  "chunkIndex": 5,
  "margin": 2
}

Field	Type	Required	Description
`location`	string	yes	The blob storage URL of the source file
`chunkIndex`	integer	no	Return a specific chunk by index
`margin`	integer	no	Number of surrounding chunks to include (context window)

Response: 200 OK — array of DocumentChunk objects.

POST `/indexes/{indexId}/files/{fileId}/chunks`

Get all chunks for a file by its internal file ID.

Response: 200 OK — array of DocumentChunk objects.

Index Files

GET `/indexes/{indexId}/files`

List files tracked by an index.

Query Parameter	Type	Description
`status`	string	Filter by status: `indexed`, `pending`, `processing`, `failed`

Response: 200 OK

[
  {
    "id": "file_abc123",
    "indexId": "idx_a1b2c3d4e5f6",
    "name": "quarterly-report.pdf",
    "location": "https://myteamstorage.blob.core.windows.net/documents/finance/2025/quarterly-report.pdf",
    "status": "indexed",
    "statusMessage": null,
    "createdAt": "2026-03-05T10:35:00Z",
    "modifiedAt": "2026-03-05T10:42:00Z",
    "failureCount": 0
  }
]

GET `/indexes/{indexId}/files/summary`

Get a count of files grouped by status.

Response: 200 OK

{
  "indexed": 42,
  "pending": 7,
  "processing": 3,
  "failed": 1
}

Index Runs

A run represents a processing session where files are indexed.

GET `/indexes/{indexId}/runs`

List all runs for an index.

Response: 200 OK

[
  {
    "id": "run_x7y8z9",
    "indexId": "idx_a1b2c3d4e5f6",
    "startTime": "2026-03-05T13:00:00Z",
    "lastUpdated": "2026-03-05T14:00:00Z",
    "endTime": "2026-03-05T14:05:00Z",
    "documentsIndexed": 42,
    "documentsFailed": 1
  }
]

GET `/indexes/{indexId}/runs/{runId}`

Get details for a specific run.

Response: 200 OK — a single IndexRun object.

POST `/indexes/{indexId}/run`

Start a new indexing run.

Query Parameter	Type	Description
`full`	boolean	If `true`, reindex all files (not just changes)

Response: 200 OK

Field	Type	Required	Description
`name`	string	yes	Human-readable index name
`storageAccount`	string	yes	Azure Storage account name
`blobContainer`	string	yes	Blob container name
`blobFolder`	string	yes	Folder path within the container

`Index`

The full index object returned by the API.

Field	Type	Description
`id`	string	Unique index identifier
`name`	string	Human-readable name
`storageAccount`	string	Azure Storage account name
`blobContainer`	string	Blob container name
`blobFolder`	string	Folder path within the container
`queue`	string	Service Bus queue name
`createdAt`	datetime	When the index was created
`modifiedAt`	datetime	When the index was last modified
`status`	string	Current status: `provisioning`, `ready`, `deleting`, `error`
`activeRunId`	string/null	ID of the currently active run, if any

`IndexFile`

A file tracked within an index.

Field	Type	Description
`id`	string	Unique file identifier
`indexId`	string	Parent index ID
`name`	string	File name
`location`	string	Full blob storage URL
`status`	string	`pending`, `processing`, `indexed`, `failed`
`statusMessage`	string/null	Error message if status is `failed`
`createdAt`	datetime	When the file was first detected
`modifiedAt`	datetime	When the file status last changed
`failureCount`	integer	Number of failed processing attempts

`DocumentChunk`

A searchable chunk of content with its vector embedding.

Field	Type	Description
`id`	string	Unique chunk identifier
`parentKey`	string	Parent file ID
`chunkIndex`	integer	Position of this chunk within the source file
`name`	string	Source file name
`location`	string	Blob URL (includes SAS token in search responses)
`chunk`	string	The text content of this chunk
`vector`	float[]/null	Embedding vector (1536 dimensions, null in responses to reduce payload)

`IndexRun`

A processing session for an index.

Field	Type	Description
`id`	string	Unique run identifier
`indexId`	string	Parent index ID
`startTime`	datetime	When the run started
`lastUpdated`	datetime	Last progress update
`endTime`	datetime/null	When the run completed (null if active)
`documentsIndexed`	integer	Count of successfully indexed files
`documentsFailed`	integer	Count of files that failed

Query Scoring Reference

Each search mode uses a different scoring strategy. All scores are normalized so that higher values indicate better matches.

Search Mode	Scoring Formula	Range	Notes
Vector	`1 - VectorDistance()` (cosine)	0.0–1.0	1.0 = perfect match, 0.0 = orthogonal
Hybrid	`1 / (rank + 60)` (RRF)	0.0–1.0	Fuses vector and BM25 ranks
Full-text	`1 / (rank + 60)` (RRF)	0.0–1.0	BM25 ranking with RRF normalization
Semantic	`priority`	0.0–1.0	Blends best_sim, avg_sim, and query boost

API Reference

On this page