---
title: "Ingest batch"
method: POST
path: "/v0/records/batch"
tags: ["Records"]
---

# Ingest batch

`POST /v0/records/batch`

## Request

- Base URL: `https://docs.quivr.thevibecompany.co` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.quivr.thevibecompany.co/v0/records/batch`
- Auth: HTTP bearer

Initial bound: 100 entries (413 batch_too_large), envelope 10 MiB (413 request_too_large). Validate envelope structure/size first, then each entry independently against IngestCommand, including wrong types or missing fields. Each raw entry is also held to the 1 MiB single-request bound (entry error entry_too_large), so the same entry bytes are never refused for size alone. HTTP 200 carries Receipt or Error per entry, with the same error codes as single submission. Same ingestion family/key as single submission. Each entry has a fresh 5-second acceptance budget, bounded by an 8-second deadline for the whole batch, including envelope decoding and validation. Caller cancellation or an earlier caller deadline also applies. An entry that times out, and every remaining entry after the batch deadline, returns retryable content_unavailable. Retry with the same entry keys to recover the original Receipts. If the envelope cannot be read before the deadline, HTTP 503 returns retryable content_unavailable without attempting entries. Reuse entry keys after unknown transport outcomes.

## Request body

- BatchRequest: Envelope validation checks items array and batch/body limits only. Each raw entry is independently validated as IngestCommand; even a missing required field or wrong JSON type returns an entry error. SDK convenience builders may type valid entries as IngestCommand, but server envelope validation must not reject the entire batch for an invalid entry.
  - `items` unknown[], required
    - unknown

## Response `200`

Successful response

- BatchResult
  - `items` BatchItem[], required
    - `index` integer, required
    - `receipt` Receipt: Durable acceptance outcome, not workflow state. Availability is a separate authorized live read view; omitted before a linked version exists. Infrastructure retry never resolves a Receipt as failed.
      - `receipt_id` string, required
      - `state` 'pending' | 'resolved', required
      - `outcome` 'created' | 'duplicate' | 'withdrawal_applied' | 'conflict'
      - `record_id` string
      - `version_id` string
      - `availability` Availability
        - `state` 'materialized' | 'building_baseline' | 'retrieval_ready' | 'quarantined', required
        - `is_current` boolean, required
        - `searchable` boolean, required
      - `diagnostics` Error[], required
        - `request_id` string: Bounded caller X-Request-ID, or an engine-generated correlation ID.
        - `trace_id` string: W3C trace ID when a trace context is present.
        - `span_id` string: W3C span ID of the API handler when a trace context is present.
        - `code` string, required
        - `message` string, required
        - `retryable` boolean, required
        - `field` string: JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands).
        - `resync_url` string, uri-reference
      - `source` SourceIdentity, required
        - `corpus_id` string, required
        - `namespace` string, required
        - `record_key` string, required
      - `processing` ProcessingSummary, required: Live read view, not a Receipt lifecycle or public workflow identifier. blocked means an outstanding contribution needs intervention; diagnostics describe why. idle means no work currently pending, not a promise of final enrichment. Phase is omitted when idle; required and optional progress do not override Version Availability.
        - `state` 'queued' | 'running' | 'retrying' | 'blocked' | 'idle', required
        - `phase` 'materialization' | 'baseline' | 'enrichment'
        - `message` string
    - `error` Error
      - `request_id` string: Bounded caller X-Request-ID, or an engine-generated correlation ID.
      - `trace_id` string: W3C trace ID when a trace context is present.
      - `span_id` string: W3C span ID of the API handler when a trace context is present.
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
      - `field` string: JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands).
      - `resync_url` string, uri-reference

## Other responses

- `default`: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

---

[API](https://skmtc.dev/thevibecompany/apis/quivr-http-api.md) - [All operations](https://skmtc.dev/thevibecompany/apis/quivr-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thevibecompany/apis/quivr-http-api/revisions/4f4e30ba8f4e?raw)