Quickstart

This walkthrough creates a regional index, creates a data-plane key in the console, and shows both Talqora products:

1. Vector Storage & Retrieval: write records and vectors your application already has.
2. Serverless Processing: upload a document and let Talqora extract, OCR when needed, embed, and index it asynchronously.

Index region, dimensions, and metric are immutable after creation. File processing requires 1536 dimensions because Talqora owns the embedding step for that product.

1. Create an index

Use your authenticated console session token to create the control-plane resource. Request GET /v1/regions first if you need the regions enabled for your workspace.

curl https://api.talqora.com/v1/indexes \
  -X POST \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"products","dimensions":3,"distance_metric":"cosine","aws_region":"us-east-1"}'

Then create an API key in the console and write vectors through the data-plane endpoint.

2. Create a scoped API key

Create an API key with read and write permission scoped to the new index in Console → API keys, then save it as TALQORA_API_KEY. Keep it server-side. The key is shown once only.

3. Write vectors directly

Use direct writes when your application already creates embeddings or owns its data transformation pipeline. The idempotency key makes this request safe to retry.

curl https://api.talqora.com/v1/indexes/$INDEX_ID/vectors \
  -X POST \
  -H "Authorization: Bearer $TALQORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalog-import-001" \
  -d '{
    "vectors": [
      {
        "id": "shoe-001",
        "values": [0.12, 0.84, 0.21],
        "metadata": {"category": "running", "in_stock": true},
        "sparse_text": "lightweight red running shoe"
      }
    ]
  }'

The number of values must equal your index dimensions.

4. Query the index

Use dense retrieval when your application already creates embeddings. Use hybrid to combine the vector with lexical terms in sparse_query.

curl https://api.talqora.com/v1/indexes/$INDEX_ID/query \
  -X POST \
  -H "Authorization: Bearer $TALQORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_type": "hybrid",
    "vector": [0.11, 0.82, 0.20],
    "sparse_query": "red running shoe",
    "top_k": 10,
    "filter": {"in_stock": true}
  }'

Dense retrieval uses the supplied vector. Sparse retrieval uses sparse_query. Hybrid retrieval uses both and returns one ranked result set. Add a metadata filter whenever records within an index have different access or product boundaries.

5. Process a file serverlessly

Use processing when the source starts as an unstructured document rather than an embedding. This path is asynchronous: the create request allocates the source and returns immediately. It does not wait for extraction, OCR, chunking, embedding, or indexing.

Create the job:

JOB=$(curl -sS -X POST "https://api.talqora.com/v1/indexes/$INDEX_ID/files" \
  -H "Authorization: Bearer $TALQORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"security-policy.pdf","content_type":"application/pdf"}')
JOB_ID=$(echo "$JOB" | jq -r .id)
UPLOAD_URL=$(echo "$JOB" | jq -r .upload_url)
UPLOAD_CONTENT_TYPE=$(echo "$JOB" | jq -r '.upload_headers["Content-Type"]')
UPLOAD_IF_NONE_MATCH=$(echo "$JOB" | jq -r '.upload_headers["If-None-Match"]')

Upload the original file directly to the one-time URL, then enqueue it:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $UPLOAD_CONTENT_TYPE" \
  -H "If-None-Match: $UPLOAD_IF_NONE_MATCH" \
  --upload-file security-policy.pdf
curl --fail-with-body -X POST \
  "https://api.talqora.com/v1/indexes/$INDEX_ID/files/$JOB_ID/complete" \
  -H "Authorization: Bearer $TALQORA_API_KEY"

Always send every entry in upload_headers with the PUT. Those headers are part of the S3 signature; omitting or changing one causes 403 Forbidden.

Talqora records one durable job for the source, then schedules independently retryable work units. Native text is extracted directly; scanned pages and images use the OCR path. Content is normalized and chunked with source, page, sheet, or row provenance. Every chunk becomes a 1536-dimensional dense record plus lexical text for hybrid retrieval. A completed source is immediately available to the query endpoint and Assistant RAG.

Poll status without holding an application request open:

curl --fail-with-body "https://api.talqora.com/v1/indexes/$INDEX_ID/files" \
  -H "Authorization: Bearer $TALQORA_API_KEY"

Jobs move from uploading to queued, processing, and completed, or to failed with an error. The response reports total_tasks, completed_tasks, and vectors_written. Replacing or deleting one file removes only that source’s retrieval records; it does not rebuild unrelated vectors in the index. See File processing for DOCX, spreadsheets, images, website crawls, replacement, deletion, and retry behavior.

6. Inspect usage

The console and GET /v1/indexes/$INDEX_ID/stats report current document count, storage, rows written, data written, queries, and queried transfer. The API overview contains the complete path map; the Write vectors guide covers batching and idempotency details.