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

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 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.

Authentication

Talqora API keys can be used for the data plane and index control plane.

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.

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.

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