Write vectors

Use the Vector API write path when your application already owns extraction and embedding generation. A write creates or replaces a record in one index. Each record can contain a stable ID, a dense vector, filterable metadata, and optional sparse_text for lexical and hybrid retrieval.

This is separate from Serverless Processing, where Talqora accepts a source file and generates chunks and embeddings asynchronously. Both paths produce searchable records in the same index.

Write contract

• A request accepts at most 500 vectors.
• Every values array must exactly match the index dimensions.
• Values must be finite, float32-compatible numbers with a non-zero norm. All-zero vectors return 422; they are never forwarded to storage.
• IDs must be unique within one batch. A duplicate ID in one payload returns 422 with the failing vectors[n].id field.
• Every write requires an Idempotency-Key header.
• A key has write capability and must be scoped to the target index, or be allowed for all workspace indexes.
• Reusing an existing record ID replaces its active dense, sparse, and metadata representation.

Use stable IDs from your source system. For example, use product:sku-42, ticket:INC-1842:summary, or policy:v3:page-12:chunk-2. Avoid random IDs for records that will be updated; stable IDs make replacement and deletion precise.

Upsert a batch

curl --fail-with-body https://api.talqora.com/v1/indexes/$INDEX_ID/vectors \
  -X POST \
  -H "Authorization: Bearer $TALQORA_API_KEY" \
  -H "Idempotency-Key: catalog-import-2026-08-11-001" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "id": "product:shoe-42",
        "values": [0.12, 0.18, 0.44],
        "metadata": {
          "tenant_id": "acme",
          "category": "running",
          "price": 90,
          "in_stock": true,
          "locale": "en-US"
        },
        "sparse_text": "lightweight red running shoe for trail training"
      }
    ]
  }'

In production, build the values array from the exact model used for this index. The three values above are only a compact example; a 1536-dimensional index requires 1,536 values per record.

Dense, sparse, and metadata fields

values is the dense representation used for semantic retrieval. It should be generated from the content you want to match, not from an ID or a few keywords.

sparse_text is optional but recommended when users search names, policy codes, SKUs, error messages, dates, or product language. It is indexed for BM25 search and combines with dense candidates during hybrid retrieval. Omit it only for a genuinely dense-only workload.

metadata carries structured facts for filters and for display after retrieval. Use booleans, numbers, strings, arrays, and stable source identifiers. Do not put source bodies, credentials, or unbounded arbitrary payloads in metadata.

Idempotency and retries

An Idempotency-Key makes a network retry safe. Use a unique deterministic key for one logical batch, persist it alongside the source checkpoint, and resend the exact same request if the client cannot confirm the response.

• Same key, same body: Talqora returns the original outcome without a second write or second usage increment.
• Same key, different body: Talqora rejects the request to prevent accidental data corruption.
• New key: Talqora treats the payload as a new operation. If IDs already exist, it is an intentional upsert.

Do not generate a new idempotency key immediately after a timeout. Retry the original request first. This is particularly important for worker queues and client libraries that may receive an ambiguous connection failure after the server has completed the durable write.

Input failures are actionable

Malformed JSON, a missing required field, invalid dimensions, duplicate IDs, and unsupported field types all return 422 with the same error envelope. Fix the reported field; do not retry it unchanged. Missing Content-Type: application/json returns 415. Vector-store, sparse-store, and provider failures are distinct retryable 5xx responses and include request_id.

Upserts and usage

Writing an existing ID replaces the live record. documents measures current live cardinality, while rows_written measures accepted write activity. Therefore an index with 10,000 current documents may have a much larger rows_written value after catalog refreshes.

data_written reflects accepted write payload activity. Dense storage, sparse storage, and query transfer are tracked separately in the index and organization usage views. Read Usage and limits before choosing an import batch size or refresh cadence.

Batch design

Batch up to 500 records to reduce request overhead, but keep batches small enough that your producer can retry one logical checkpoint. A common pattern is to checkpoint source offsets every 100–500 records, use one idempotency key per checkpoint, and only advance the source cursor after Talqora confirms the batch.

For a very large backfill, run bounded concurrent batches rather than an unbounded fan-out. Respect 429 responses and the RateLimit-* headers. On a retryable transport or capacity error, use exponential backoff with jitter. Do not retry malformed vectors, invalid filters, or a mismatched dimension without correcting the payload.

Updating and deleting

To change content, write the same ID with a new vector, metadata, and sparse_text. To remove records, use DELETE /v1/indexes/{index_id}/vectors with an idempotency key. Deletion makes the record unavailable to dense, sparse, and hybrid retrieval before background sparse compaction completes.

Use File processing replacement and deletion endpoints for sources created through Processing. That path knows every chunk generated from the file and removes the complete source lifecycle safely.

Validate before shipping

1. Confirm the index dimensions match the embedding model output.
2. Write a small fixture batch with realistic metadata and sparse_text.
3. Query dense, sparse, and hybrid modes with your production filters.
4. Test an upsert of the same ID and verify only the new representation is returned.
5. Test a delete and confirm no stale sparse candidate is exposed.
6. Record p50/p95 latency, error rate, transfer, and relevance before scaling the importer.