> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.talqora.com/get-started/quickstart/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.talqora.com/_mcp/server.

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

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

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

```bash
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:

```bash
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:

```bash
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:

```bash
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](/build-retrieval/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.