> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.talqora.com/get-started/api-overview/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.talqora.com/_mcp/server. # API overview Talqora Vector has two products behind one regional index and one API key: * **Vector Storage & Retrieval** for applications that already own their embedding pipeline. Write vectors and metadata directly, then retrieve with dense, lexical, or hybrid search. * **Serverless Processing** for teams that start with files or public web content. Upload a source, receive a durable job, and Talqora extracts text, applies OCR only when needed, creates 1536-dimensional embeddings, indexes lexical text, and makes the evidence available to retrieval. Both products write to the same index contract. A result written through the Vector API and a chunk created by a processing job can be retrieved, filtered, measured, cited by Assistant RAG, replaced, or deleted through the same index. You choose the AWS region at index creation; dimensions, metric, and region remain fixed so every write and query has a predictable storage destination. ## Choose your path | If you have... | Start with | What Talqora does | | -------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application embeddings and structured records | **Vector Storage & Retrieval** | Stores regional dense vectors, indexes optional `sparse_text`, enforces metadata filters, and returns dense, sparse, or hybrid candidates. | | PDFs, Office files, images, spreadsheets, Markdown, JSON, or a public site | **Serverless Processing** | Creates a retryable job, extracts or OCRs content, preserves source provenance, chunks with overlap, embeds, and writes both retrieval paths. | | An agent that needs grounded answers | **Assistant RAG** | Retrieves when a turn needs index evidence, returns sources for grounded answers, and skips retrieval for conversational or explicitly search-disabled turns. | The two ingestion paths are complementary. For example, write product records directly from your application while asynchronously processing compliance PDFs into the same index. Use metadata such as `source`, `tenant_id`, `document_type`, or `visibility` to enforce the retrieval boundary your application needs. ## How data moves ### Vector Storage & Retrieval 1. Create an index with an AWS region, dimensions, and a distance configuration. 2. Create a scoped API key with only the indexes and read/write capabilities required by the workload. 3. Upsert vectors with optional metadata and `sparse_text`. Writes are idempotent and are recorded in the usage ledger only after durable storage succeeds. 4. Query dense, sparse, or hybrid retrieval. Apply metadata filters and a relevance threshold before returning results to an application or agent. Dense vectors and filterable metadata are stored in the index's regional vector store. Sparse text is indexed separately for BM25 retrieval. Hybrid queries execute both paths, remove stale sparse candidates, and combine valid candidates in the API. This means the API behaves consistently whether data was written directly or created by a processing job. ### Serverless Processing 1. `POST /v1/indexes/{index_id}/files` creates a file job and returns a one-time upload URL. 2. Upload bytes directly, then call `POST /v1/indexes/{index_id}/files/{job_id}/complete`. 3. A serverless worker receives the durable job. It detects the type, extracts native text or runs OCR for visual pages, and splits large sources into independently retryable work units. 4. Each unit is normalized, chunked with provenance and overlap, embedded, and written to dense and sparse retrieval. 5. Poll `GET /v1/indexes/{index_id}/files` until the job is complete. The same API supports replacement and deletion without rebuilding the rest of the index. The upload request is intentionally short. It never waits for a 500-page PDF, a spreadsheet, or a scan to finish. Job state and task totals let clients show progress while serverless processors retry only the failed work unit. See [File processing](/build-retrieval/file-processing) for supported formats, lifecycle states, and full request examples. ## API map The dashboard uses a Supabase session token. Index control-plane routes accept either that session or a Talqora API key with the required permission. `Idempotency-Key` is required for vector writes and deletes. | Method | Path | Auth | Purpose | | -------- | ------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------- | | `GET` | `/health/ready` | None | Service readiness probe. | | `POST` | `/v1/auth/bootstrap` | Session | Creates or returns the caller's default workspace. | | `GET` | `/v1/organization` | Session | Returns the active workspace. | | `GET` | `/v1/regions` | Session | Lists AWS regions available for new indexes. | | `GET` | `/v1/indexes` | Session or read API key | Lists indexes visible to the caller's scope. | | `POST` | `/v1/indexes` | Session or unscoped write API key | Creates an index with immutable dimensions, metric, and AWS region. | | `GET` | `/v1/indexes/{index_id}` | Session or read API key | Reads an index contract within the key's scope. | | `PATCH` | `/v1/indexes/{index_id}` | Session or write API key | Renames an allowed index. | | `POST` | `/v1/indexes/{index_id}/branches` | Session or write API key | Materializes a branch from an allowed index. | | `DELETE` | `/v1/indexes/{index_id}` | Session or write API key | Deletes an allowed index and its stored vectors. | | `GET` | `/v1/indexes/{index_id}/stats` | Session or read API key | Reads usage for an allowed index. | | `POST` | `/v1/api-keys` | Session | Creates a scoped data-plane API key. | | `GET` | `/v1/api-keys` | Session | Lists API keys without exposing their tokens. | | `DELETE` | `/v1/api-keys/{key_id}` | Session | Revokes an API key immediately. | | `POST` | `/v1/indexes/{index_id}/vectors` | API key + `Idempotency-Key` | Upserts up to 500 dense vectors and optional sparse text. | | `DELETE` | `/v1/indexes/{index_id}/vectors` | API key + `Idempotency-Key` | Deletes up to 500 vectors by ID. | | `POST` | `/v1/indexes/{index_id}/query` | API key | Runs dense, sparse, or hybrid retrieval with metadata filters. | | `POST` | `/v1/indexes/{index_id}/files` | Write API key | Creates a serverless file-processing job and one-time upload URL. | | `POST` | `/v1/indexes/{index_id}/files/{job_id}/complete` | Write API key | Queues an uploaded source for processing. | | `GET` | `/v1/indexes/{index_id}/files` | Read API key | Lists file jobs, progress, source provenance, and errors. | | `GET` | `/v1/indexes/{index_id}/files/{job_id}/tasks` | Read API key | Inspects page ranges, retries, chunks, vectors, and extraction errors. | | `POST` | `/v1/indexes/{index_id}/crawl-jobs` | Write API key | Queues a paid-plan public website processing job. | | `POST` | `/v1/indexes/{index_id}/browser-fetch` | Organization owner session | Renders up to ten approved public or Context-authenticated pages and returns Markdown. | ## Authentication Talqora API keys can be used for the data plane and index control plane. ```bash curl https://api.talqora.com/v1/indexes \ -H "Authorization: Bearer $TALQORA_API_KEY" ``` Keys begin with `tq_live_`. They are shown only once when created. The dashboard uses a Supabase session instead. Session endpoints accept the Supabase access token from an authenticated console user. API-key endpoints accept a token created under **API keys** in the console. API keys can be restricted to `read` or `write` operations and to a set of indexes. | Index operation | Session | API-key requirement | | ------------------------- | ------- | --------------------------------------------------------------- | | List, get, or read stats | Allowed | `read`; results are limited to `index_ids` when present. | | Create | Allowed | `write` and no `index_ids` restriction. | | Rename, branch, or delete | Allowed | `write` and the target index must be in `index_ids`, if scoped. | Use a dedicated unscoped write key only for trusted provisioning automation. Application keys should normally be scoped to the indexes they use. API-key creation, rotation, and revocation remain dashboard-session operations. ## Encoding and errors Requests and responses use JSON. Send `Content-Type: application/json` on every request with a JSON body. A missing or incompatible content type returns `415 Unsupported Media Type` before the request reaches the data plane. Errors use one stable envelope. `code`, `field`, `expected`, and `received` are present when Talqora can safely identify a client-side validation failure. `request_id` is returned on every response and should be included in support requests. ```json { "status": "error", "error": "Zero-norm vectors are not supported", "message": "Zero-norm vectors are not supported", "code": "validation_error", "field": "vectors[0].values", "expected": "a non-zero vector", "request_id": "req_..." } ``` Use `Idempotency-Key` on writes and deletes. A retry with the same key and request body returns the original result without another write or usage increment. Reusing a key with a different body is rejected. ## Request conventions * All request and response bodies are UTF-8 JSON. * Vector values are `float32` values and must match the index dimensions exactly. * Dense vectors must be finite and non-zero. IDs must be unique within one upsert batch. * Metadata filters are evaluated against filterable metadata keys. * Query responses include end-to-end `latency_ms` plus `dense_latency_ms`, `sparse_latency_ms`, and `fusion_latency_ms` when those phases run. * Dense results include a distance when `include_distance` is enabled. Sparse and hybrid results include a relevance score. * API keys are workspace-scoped. A key restricted to selected indexes cannot access other indexes in that workspace. * Request rate limits are enforced server-side per organization. Additional API keys do not multiply the plan allowance.