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

# Ingest record

`POST /v0/records`

## 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`
- Auth: HTTP bearer

Commit durable input, Receipt and dispatch intent before responding. Same key and canonical request returns same Receipt; changed request conflicts. A new source revision corrects the Record. All accepted/replayed submissions use 202, even when a replayed Receipt has resolved.

## Request body

- IngestCommand: Initial request shape. Same source identity creates or corrects a Record. Same external revision with different canonical content conflicts. No revision means canonical Manifest digest identity; no source position means durable acceptance order. Single and batch entry replay share route_family=ingestion. A blob content accepts a verified text/* Blob, read at acceptance, or a Blob whose media type the installation routes to an external normalizer; that normalizer runs after acceptance and its output is the published Manifest, while the Version identity still derives from the submitted Blob. When the normalizer fails, the Version is quarantined with a Diagnostic on the Version read (or, on an optional text/* route, published through the built-in text path with provenance.normalization.fallback). Other media types are rejected with unverified_blob. provenance.normalization is engine-owned and rejected on input. Extension namespaces owned by the pinned plugin are written only by its normalizer output, published on the Version; a submission writing one, top-level or on a Part, is rejected with 422 extension_namespace_owned.
  - `idempotency_key` string, required
  - `source` SourceIdentity, required
    - `corpus_id` string, required
    - `namespace` string, required
    - `record_key` string, required
  - `source_revision` string
  - `source_position` string: Optional monotonic source position, encoded as decimal text to avoid JSON numeric precision loss.
  - `content` union, required
    - TextContent
      - `kind` 'text', required
      - `text` string, required
    - BlobContent
      - `kind` 'blob', required
      - `blob_id` string, required
      - `media_type` string, required
    - ManifestContent: Unique Part keys, acyclic parent references within this Manifest, and verified same-Organization Blobs are checked before atomic publication. These semantic constraints need server validation in addition to JSON Schema.
      - `kind` 'manifest', required
      - `parts` Part[], required
        - `key` string, required
        - `parent_key` string
        - `role` string, required
        - `content` union, required
          - TextContent
            - `kind` 'text', required
            - `text` string, required
          - BlobContent
            - `kind` 'blob', required
            - `blob_id` string, required
            - `media_type` string, required
        - `extensions` Extensions: Keys are plugin namespaces. Data is validated against the installed schema version; source data is not a computed Annotation.
      - `relations` RelationInput[]
        - `type` string, required
        - `target` SourceIdentity, required
          - `corpus_id` string, required
          - `namespace` string, required
          - `record_key` string, required
        - `source_target_revision` string
  - `extensions` Extensions: Keys are plugin namespaces. Data is validated against the installed schema version; source data is not a computed Annotation.
  - `provenance` Provenance
    - `source_blob_ids` string[]
    - `producer` string
    - `producer_version` string
    - `normalization` NormalizationProvenance: Engine-owned record of the external normalizer invocation whose output a Record Version publishes. Present only on read; a submission that sets it is rejected. producer and producer_version keep naming the acquirer, and source_blob_ids keeps the input Blob.
      - `plugin_id` string, required
      - `plugin_version` string, required
      - `plugin_api` string, required: Plugin API version the engine invoked.
      - `contribution` 'normalizer', required
      - `invocation_id` string: Present when import audit detail is retained, or when it identifies a failed invocation. Omitted for successful normalization without audit detail.
      - `idempotency_key` string, required
      - `input_sha256` string, required
      - `fallback` object: Present when the route is optional and the normalizer failed: the published Manifest comes from the built-in text path, and invocation_id names the failed invocation.
        - `code` string, required
        - `message` string, required

## Response `202`

Successful response

- 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

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