> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quiva.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Correct a past version's stored values

> Amends one put version without changing the record: `data` is materialised against the target's folded snapshot, validated against the current schema, and published as an amendment the fold applies on every future read. Refuses the record's current version (edit the record itself instead) and a hidden version. A merge that leaves the snapshot byte-identical is a no-op — 200 with the existing entry, nothing published.



## OpenAPI

````yaml /api-reference/endpoint/records/openapi.json post /records/{config_id}/{id}/history/{version}/amend
openapi: 3.1.0
info:
  title: Records API
  version: 1.1.0
  description: >-
    Record configurations (schemas, views, versions) and the records that
    conform to them. Record IDs are server-generated, config IDs are
    client-supplied (`^[a-zA-Z0-9_-]+$`). Configs and records are updated with
    PUT: a config update applies only the fields sent, a record update merges
    `data`. Editing a config schema does not retroactively re-validate existing
    records. Publish a config version to snapshot the stored config; list and
    read versions to see its history.
servers:
  - url: https://api.quiva.ai
    description: Production API server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Record Configs
    description: >-
      Manage record configuration schemas. Each configuration defines the
      structure (fields, types, validation rules) that records must conform to.
  - name: Records
    description: >-
      Manage individual data records. Each record belongs to exactly one
      configuration and its data is validated against that configuration's
      schema.
  - name: Record Config Collections
    description: Groups of record configs.
  - name: Record Config Versions
    description: Published snapshots of a record config.
  - name: Record History
    description: The change history of a record.
  - name: Record Assessment
  - name: Strategy and Simulation
  - name: Record Metrics
paths:
  /records/{config_id}/{id}/history/{version}/amend:
    post:
      tags:
        - Record History
      summary: Correct a past version's stored values
      description: >-
        Amends one put version without changing the record: `data` is
        materialised against the target's folded snapshot, validated against the
        current schema, and published as an amendment the fold applies on every
        future read. Refuses the record's current version (edit the record
        itself instead) and a hidden version. A merge that leaves the snapshot
        byte-identical is a no-op — 200 with the existing entry, nothing
        published.
      operationId: amendRecordHistory
      parameters:
        - name: config_id
          in: path
          required: true
          description: ID of the record configuration that the record belongs to
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: Record ID
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: >-
            The put event's version to act on. A deletion cannot be amended,
            hidden, erased or restored (400 history_target_not_put).
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordHistoryAmendRequest'
      responses:
        '200':
          description: >-
            The folded entry as it now reads (the amended snapshot, or the
            unchanged existing entry when nothing changed).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response'
                  - properties:
                      body:
                        $ref: '#/components/schemas/RecordHistoryEntry'
        '400':
          description: >-
            Missing/invalid config_id, id or version; a malformed body;
            `{"code":"schema_validation_failed"}` when the merged data fails the
            current schema; `{"code":"history_target_not_put"}` — a delete event
            cannot be amended; `{"code":"history_reason_required"}` /
            `{"code":"history_reason_too_long"}` for `reason`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No caller identity on the request token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            `{"code":"history_forbidden"}` — the caller's role is not in the
            config's `history.edit_roles` (default root and admin).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Record configuration not found, or
            `{"code":"history_version_not_found"}` — no event at this version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `{"code":"history_target_is_current"}` — this is the record's
            current version; edit the record instead.
            `{"code":"history_target_hidden"}` — the version is hidden; restore
            it first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            `{"code":"history_read_failed"}` — could not read the version or its
            amendments. `{"code":"history_write_failed"}` — the amendment (or
            its series bucket recompute, on a timeseries config) could not be
            written; nothing changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RecordHistoryAmendRequest:
      type: object
      required:
        - data
        - reason
      description: >-
        Body of POST .../amend. `data` is merged onto the target version's
        folded snapshot data exactly as a record update merges (`replace: true`
        replaces `data` wholesale instead). `folder`, `parent_folder`,
        `space_id` and `completed` are not amendable.
      properties:
        data:
          type: object
          additionalProperties: true
          description: Corrected field values, merged into the target version's data.
        replace:
          type: boolean
          default: false
          description: Replace `data` wholesale instead of merging.
        validate:
          type: boolean
          default: true
          description: >-
            Validate the merged result against the current schema. false skips
            validation.
        hidden_fields:
          type: array
          items:
            type: string
          description: Schema fields to exclude from validation, as on a record update.
        reason:
          type: string
          maxLength: 500
          description: >-
            Required, 1-500 characters after trimming. 400
            history_reason_required when empty, history_reason_too_long over
            500.
      example:
        data:
          close: 12.5
        reason: Wrong close copied from the sheet
    Response:
      type: object
      properties:
        status_code:
          type: integer
          description: HTTP status code echoed in the response body.
        body:
          type: object
          description: Response payload.
    RecordHistoryEntry:
      type: object
      description: One event on a record's history.
      properties:
        sequence:
          type: integer
          description: Stream sequence number of this event.
        time:
          type: string
          format: date-time
          description: >-
            When the event was written (the stream message's own timestamp,
            RFC3339Nano).
        config_id:
          type: string
        record_id:
          type: string
        version:
          type: integer
          description: >-
            The record's version at this event. A delete event carries the
            record's version at the time of delete, plus one.
        op:
          type: string
          enum:
            - put
            - delete
        mode:
          type: string
          enum:
            - audit
            - timeseries
          description: The config's history mode at write time.
        actor:
          type: string
          description: >-
            User id from the write's own token; empty when the write carried
            none.
        effective_at:
          type: string
          format: date-time
          description: The time this value is about. Defaults to write time.
        config_updated_at:
          type: string
          description: >-
            The config's updated_at at write time, for detecting schema drift
            against a snapshot. Empty for events written before this field
            existed.
        snapshot:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            mode "audit": the full stored record, version included. mode
            "timeseries": {"<field>": <number>, ...} for series.fields only,
            omitting fields that were missing or non-numeric. null on a delete
            event, a hidden version or an erased version.
        reconstructed:
          type: boolean
          description: >-
            Always false in v1. Reserved for a future repair sweeper that
            re-derives a missed event from the record's stored version.
        restored_from:
          type: integer
          description: >-
            Present only on a put that restored an earlier version: the version
            its snapshot was copied from.
        hidden:
          type: boolean
          description: True once any redact targets this version.
        erased:
          type: boolean
          description: >-
            True once a redact with erased:true targets this version; its stored
            bytes are gone and snapshot is synthesised from the redact stub.
        hidden_by:
          type: string
          description: >-
            Actor of the redact with the highest sequence targeting this
            version. Present when hidden.
        hidden_at:
          type: string
          format: date-time
          description: That redact's write time. Present when hidden.
        hidden_reason:
          type: string
          description: That redact's reason. Present when hidden.
        amended_by:
          type: string
          description: >-
            Actor of the amend with the highest sequence targeting this version.
            Present only when edited and not hidden.
        amended_at:
          type: string
          format: date-time
          description: That amend's write time. Present only when edited and not hidden.
        amend_reason:
          type: string
          description: That amend's reason. Present only when edited and not hidden.
        original_snapshot:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            The put's own snapshot before the winning amend replaced it. Present
            only when edited and not hidden.
    ErrorResponse:
      type: object
      properties:
        status_code:
          type: integer
        body:
          type: object
          properties:
            error:
              type: string
              description: Human-readable error message.
      example:
        status_code: 400
        body:
          error: field 'rating' is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.