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

# Get revision chain

> Return the revision chain for a memory.

Facts → supersede chain (oldest → newest).
Artifacts → version chain (v1 → vN).
Episodes → single-element list (episodes have no revisions today).

Full chain in one response. ``has_more`` is always ``false``;
cursor envelope kept for shape consistency.



## OpenAPI

````yaml https://api.staging.xtrace.ai/openapi.public.json get /v1/memories/{memory_id}/revisions
openapi: 3.1.0
info:
  title: XTrace Vec DB
  description: XTrace API
  version: 1.0.0
servers:
  - url: https://api.production.xtrace.ai
    description: Production
security:
  - ApiKeyHeader: []
  - BearerToken: []
paths:
  /v1/memories/{memory_id}/revisions:
    get:
      tags:
        - memories
      summary: Get revision chain
      description: |-
        Return the revision chain for a memory.

        Facts → supersede chain (oldest → newest).
        Artifacts → version chain (v1 → vN).
        Episodes → single-element list (episodes have no revisions today).

        Full chain in one response. ``has_more`` is always ``false``;
        cursor envelope kept for shape consistency.
      operationId: get_memory_revisions_v1_memories__memory_id__revisions_get
      parameters:
        - name: memory_id
          in: path
          required: true
          schema:
            type: string
            title: Memory Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnvelope'
        '401':
          description: >-
            Authentication failed. Missing / invalid API key. Body carries
            `detail.code = "unauthorized"`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: >-
            `detail.code = "memory_not_found"` — no row with that id under this
            org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Rate-limit or daily-cap exceeded. `Retry-After` and `RateLimit-*`
            response headers indicate when to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: >-
            Server-side failure. Body carries `detail.code = "server_error"`
            with a stable error code; details are in the operator log, indexed
            by the `X-Request-Id` echoed in the response header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ListEnvelope:
      properties:
        object:
          type: string
          const: list
          title: Object
          description: Constant discriminator for the resource type.
          default: list
        data:
          items:
            $ref: '#/components/schemas/Memory'
          type: array
          title: Data
          description: Page of memory rows.
        has_more:
          type: boolean
          title: Has More
          description: >-
            True if more rows exist beyond this page; use `next_cursor` to fetch
            them.
          default: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Opaque cursor for the next page. Null on the final page.
            Tenant-scoped: only usable with the same `(org, key)` that produced
            it.
      type: object
      title: ListEnvelope
      description: |-
        Stripe-style list envelope used by ``GET /v1/memories``,
        ``GET /v1/memories/{id}/revisions``, and the default search
        response.
    ErrorEnvelope:
      properties:
        detail:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - detail
      title: ErrorEnvelope
      description: |-
        Standard error body for non-2xx responses raised by the memory
        API. Pydantic field-validation failures (422) use the FastAPI-
        default ``HTTPValidationError`` shape instead, where ``detail`` is
        an array of per-field error entries — switch on the response
        status code to pick the right shape.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Memory:
      properties:
        id:
          type: string
          title: Id
          description: Stable UUID for this memory row.
        object:
          type: string
          const: memory
          title: Object
          description: Constant discriminator for the resource type.
          default: memory
        type:
          type: string
          enum:
            - fact
            - artifact
            - episode
            - lesson
            - procedure
          title: Type
          description: >-
            Memory subtype. `fact` = a single semantic claim extracted from a
            turn; `artifact` = a structured object (code, doc, image) referenced
            by the conversation; `episode` = a session-scoped summary of a
            stretch of turns; `lesson` / `procedure` = a situated directive
            recalled by the symbol tripwire (see `DirectiveDetails`).
        text:
          type: string
          title: Text
          description: >-
            Short readable preview. For facts: the claim statement. For
            artifacts: a summary or title (full body lives in
            `details.full_content`, opt-in via `include=full_content`). For
            episodes: a summary of the session.
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: User scope this row belongs to.
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Agent scope, if any.
        conv_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conv Id
          description: Conversation anchor.
        app_id:
          anyOf:
            - type: string
            - type: 'null'
          title: App Id
          description: App scope, if any.
        group_ids:
          items:
            type: string
          type: array
          title: Group Ids
          description: >-
            Group ids associated with this row — the sharing axis. Stamped at
            ingest time and editable afterward via `PATCH /v1/memories/{id}`
            (`add_group_ids` / `remove_group_ids`). Reachable as a filter axis
            via `filters: {group_ids: <id>}` or `{group_ids: {"$in": [<id>,
            ...]}}`.
        categories:
          items:
            type: string
          type: array
          title: Categories
          description: Optional category labels from the extraction pipeline.
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
          description: >-
            Vector-similarity score. Present **only** on search responses; null
            on list / get-by-id / patch / ingest result rows.
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          format: date-time
          title: Created At
          description: ISO-8601 timestamp of original ingest.
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          format: date-time
          title: Updated At
          description: ISO-8601 timestamp of the last supersede / consolidation.
        details:
          oneOf:
            - $ref: '#/components/schemas/FactDetails'
            - $ref: '#/components/schemas/ArtifactDetails'
            - $ref: '#/components/schemas/EpisodeDetails'
            - 0dc16cfe-7f7d-4424-b72b-94b908c810ef
          type: object
          title: Details
          description: >-
            Type-specific extension. Shape depends on `type` — see `FactDetails`
            / `ArtifactDetails` / `EpisodeDetails` schemas. Always an object;
            never null.
      type: object
      required:
        - id
        - type
        - text
      title: Memory
      description: |-
        Unified memory resource — facts, artifacts, episodes marshal to
        this shape. ``type`` is the discriminator; ``details`` is the
        type-specific extension.

        Invariant: ``text`` is always a short readable preview, regardless
        of type (fact statement / artifact summary / episode summary).
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable error identifier. Switch on this rather than parsing the
            message. Common values: `invalid_request`, `invalid_messages`,
            `memory_not_found`, `job_not_found`, `immutable_field`,
            `reserved_field`, `empty_text_field`, `missing_user_id`,
            `missing_conv_id`, `unsupported_include_option`, `cursor_mismatch`,
            `unauthorized`, `forbidden`, `rate_limited`, `delete_failed`,
            `search_failed`, `ingest_failed`, `server_error`.
          examples:
            - memory_not_found
        message:
          type: string
          title: Message
          description: Human-readable summary; safe to log but not safe to switch on.
          examples:
            - Memory 0fa1c0e6-... not found
      type: object
      required:
        - code
        - message
      title: ErrorDetail
      description: |-
        Inner ``detail`` block on every non-2xx response raised by a
        memory-API route handler. ``code`` is the stable identifier
        clients should switch on; ``message`` is a sanitized human-
        readable summary.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    FactDetails:
      description: |-
        Per-row fact details — sits under ``Memory.details`` when
        ``Memory.type == "fact"``.
      properties:
        fact_type:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Fact Type
        status:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Status
        supersedes:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Supersedes
        source_role:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Source Role
        episode_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Episode Id
        artifact_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Artifact Id
        artifact_ids:
          items:
            type: string
          title: Artifact Ids
          type: array
        source_event_ids:
          items:
            type: string
          title: Source Event Ids
          type: array
      title: FactDetails
      type: object
    ArtifactDetails:
      description: |-
        Per-row artifact details under ``Memory.details`` when
        ``Memory.type == "artifact"``.

        ``full_content`` is opt-in — omitted on list/search by default,
        included on ``GET /v1/memories/{id}`` and when
        ``include=["full_content"]`` is set on list/search.
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Title
        rationale:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Rationale
        version:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          title: Version
        root_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Root Id
        source_fact_ids:
          items:
            type: string
          title: Source Fact Ids
          type: array
        episode_ids:
          items:
            type: string
          title: Episode Ids
          type: array
        full_content:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Full Content
      title: ArtifactDetails
      type: object
    EpisodeDetails:
      description: |-
        Per-row episode details under ``Memory.details`` when
        ``Memory.type == "episode"``.
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Title
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Started At
        ended_at:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Ended At
        fact_ids:
          items:
            type: string
          title: Fact Ids
          type: array
        artifact_ids:
          items:
            type: string
          title: Artifact Ids
          type: array
      title: EpisodeDetails
      type: object
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Long-lived org API key. Alternative: `Authorization: Bearer <key>`.'
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: 'Long-lived API key sent as `Authorization: Bearer <api-key>`.'

````