# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/memory-stores.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/memory-stores.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Memory Stores API
  version: 1.0.0
  description: >-
    Memory stores: the named stores an agent remembers into and reads back from — the other half of
    the retrieval an agent's knowledge configuration performs, alongside the project's documents. A
    fully runtime-backed module — this spec is generated verbatim from the runtime's own, re-rooted
    under /v1/projects/{project_id}. The project in the path is authorized by naturali and enforced
    upstream by the project's scoped credential.


    This module mirrors the upstream runtime verbatim (tier A): paths are the runtime's own
    re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape
    passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by
    naturali itself (authentication, project resolution, an unreachable runtime) use naturali's.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: "{baseUrl}"
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: MemoryStores
    description: Manage memory store configurations for document retrieval
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/memory-stores:
    get:
      tags:
        - MemoryStores
      summary: List memory stores
      description: Returns a list of memory store configurations for a project
      operationId: listMemoryStores
      parameters:
        - $ref: "#/components/parameters/TagsQuery"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of memory stores
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/MemoryStore"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - MemoryStores
      summary: Create a memory store
      description: Creates a new memory store configuration in a project
      operationId: createMemoryStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Memory store name
                  example: Product Documentation
                description:
                  type: string
                  description: Optional description
                  example: Retrieves product docs for support queries
                tags:
                  description: Optional key-value tags. Scopes the memory store in knowledge search, where every
                    requested pair must match exactly.
                  allOf:
                    - $ref: "#/components/schemas/TagBag"
                duplicate_threshold:
                  type: number
                  nullable: true
                  description: "The store's dedup policy: cosine similarity at or above which an incoming fact is
                    already known and the write is skipped. `null` (the default) uses the algorithm
                    constant `0.95`. A single `POST /v1/projects/{project_id}/memories` call may
                    override it; the agent tool and the post-turn rule never can."
                  minimum: 0
                  maximum: 1
                  example: 0.95
                supersede_threshold:
                  type: number
                  nullable: true
                  description: "Cosine similarity at or above which an incoming fact restates a known one that has
                    changed: the matched memory is invalidated and replaced. `null` (the default)
                    uses the algorithm constant `0.90`. Must be lower than the effective
                    `duplicate_threshold`, or the write is rejected with `400 VALIDATION_FAILED` —
                    equal makes `superseded` unreachable and inverted swallows `skipped`."
                  minimum: 0
                  maximum: 1
                  example: 0.9
      responses:
        "201":
          description: Memory store created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryStore"
        "400":
          description: Bad request — a missing required field, a threshold outside `[0, 1]`, or a pair that is
            not `supersede_threshold < duplicate_threshold`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/memory-stores/{memory_store_id}:
    get:
      tags:
        - MemoryStores
      summary: Get a memory store
      description: Returns a single memory store configuration by ID
      operationId: getMemoryStore
      parameters:
        - name: memory_store_id
          in: path
          required: true
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: Memory store found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryStore"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    put:
      tags:
        - MemoryStores
      summary: Update a memory store
      description: Updates an existing memory store configuration
      operationId: updateMemoryStore
      parameters:
        - name: memory_store_id
          in: path
          required: true
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Memory store name
                description:
                  type: string
                  nullable: true
                  description: Optional description
                tags:
                  description: Optional key-value tags. Replaces the stored bag; `null` clears it.
                  allOf:
                    - $ref: "#/components/schemas/NullableTagBag"
                duplicate_threshold:
                  type: number
                  nullable: true
                  description: "The store's dedup policy: cosine similarity at or above which an incoming fact is
                    already known and the write is skipped. `null` (the default) uses the algorithm
                    constant `0.95`. A single `POST /v1/projects/{project_id}/memories` call may
                    override it; the agent tool and the post-turn rule never can."
                  minimum: 0
                  maximum: 1
                  example: 0.95
                supersede_threshold:
                  type: number
                  nullable: true
                  description: "Cosine similarity at or above which an incoming fact restates a known one that has
                    changed: the matched memory is invalidated and replaced. `null` (the default)
                    uses the algorithm constant `0.90`. Must be lower than the effective
                    `duplicate_threshold`, or the write is rejected with `400 VALIDATION_FAILED` —
                    equal makes `superseded` unreachable and inverted swallows `skipped`."
                  minimum: 0
                  maximum: 1
                  example: 0.9
      responses:
        "200":
          description: Memory store updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryStore"
        "400":
          description: Bad request — a threshold outside `[0, 1]`, or a pair that is not `supersede_threshold
            < duplicate_threshold` once the stored values this request does not replace are applied.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    delete:
      tags:
        - MemoryStores
      summary: Delete a memory store
      description: Deletes a memory store configuration
      operationId: deleteMemoryStore
      parameters:
        - name: memory_store_id
          in: path
          required: true
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
      responses:
        "204":
          description: Memory store deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/memory-stores/{memory_store_id}/assertions:
    get:
      tags:
        - MemoryStores
      summary: List a memory store's write assertions
      description: "Returns the store's write ledger, newest first: one row per write attempt, skips
        included. This is how \"which write path is filling this store?\" is asked — a question no
        column on a memory row could answer, because a skipped write produced no memory at all."
      operationId: listMemoryStoreAssertions
      parameters:
        - name: memory_store_id
          in: path
          required: true
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
        - name: actor_id
          in: query
          required: false
          description: Only the writes that resolved into this actor's memories. Pin it in a tool's
            `preset_parameters` as `{{context:actor_id}}` to confine it to the end user an agent
            serves.
          schema:
            type: string
            example: actor_V1StGXR8Z5jdHi6B
        - name: mechanism
          in: query
          required: false
          description: Only assertions that came through this door.
          schema:
            type: string
            enum:
              - tool
              - rule
              - api
              - formation
        - name: outcome
          in: query
          required: false
          description: Only assertions that resolved this way.
          schema:
            type: string
            enum:
              - created
              - superseded
              - skipped
              - retracted
        - name: generation_id
          in: query
          required: false
          description: Only assertions made during this generation. A generation that does not exist matches
            nothing rather than widening to the whole store.
          schema:
            type: string
            example: gen_V1StGXR8Z5jdHi6B
        - name: from
          in: query
          required: false
          description: Only assertions recorded at or after this instant (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: Only assertions recorded at or before this instant (ISO 8601).
          schema:
            type: string
            format: date-time
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of assertions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/MemoryAssertion"
        "400":
          description: An unknown `mechanism` or `outcome`, or a `from` or `to` that is not a timestamp
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/memory-stores/{memory_store_id}/export:
    get:
      tags:
        - MemoryStores
      summary: Export a memory store's memories as NDJSON
      description: Streams one store's memories as newline-delimited JSON — one memory object per line,
        oldest first. Invalidated memories (retracted or superseded) are left out unless
        `include_invalidated` asks for them, so the file holds what the store currently asserts. The
        rows are the rows the listing returns for the same caller.
      operationId: exportMemories
      x-iam-also-checked-on:
        - resource_type: memory
      x-mcp-exclude: true
      parameters:
        - name: memory_store_id
          in: path
          required: true
          description: Memory store whose memories are exported
          schema:
            type: string
            example: mem_store_V1StGXR8Z5jdHi6B
        - name: actor_id
          in: query
          required: false
          description: Only the memories that belong to this actor.
          schema:
            type: string
            example: actor_V1StGXR8Z5jdHi6B
        - name: include_invalidated
          in: query
          description: Include memories that were retracted or superseded
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/TagsQuery"
      responses:
        "200":
          description: A newline-delimited stream of memories. Each line is a JSON object with the same fields
            as `Memory`.
          content:
            application/x-ndjson:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/memory-stores/{memory_store_id}/tags:
    get:
      tags:
        - MemoryStores
      summary: Get memory store tags
      description: Returns all tags attached to the memory store
      operationId: getMemoryStoreTags
      parameters:
        - name: memory_store_id
          in: path
          required: true
          description: Memory store ID
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: Memory store tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      tags:
        - MemoryStores
      summary: Replace memory store tags
      description: Replaces all tags on the memory store with the provided tags (not merged)
      operationId: replaceMemoryStoreTags
      parameters:
        - name: memory_store_id
          in: path
          required: true
          description: Memory store ID
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Tags replaced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          description: Body is not an object of string values
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    patch:
      tags:
        - MemoryStores
      summary: Merge memory store tags
      description: Merges provided tags into the memory store's existing tags (existing tags are preserved
        unless overridden)
      operationId: mergeMemoryStoreTags
      parameters:
        - name: memory_store_id
          in: path
          required: true
          description: Memory store ID
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Tags merged
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          description: Body is not an object of string values
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Memory store not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    MemoryStore:
      type: object
      properties:
        id:
          type: string
          example: mstore_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
          example: proj_V1StGXR8Z5jdHi6B
        name:
          type: string
          example: Product Documentation
        description:
          type: string
          nullable: true
          example: Retrieves product docs for support queries
        tags:
          description: Key-value tags for filtering in knowledge search.
          allOf:
            - $ref: "#/components/schemas/TagBag"
        duplicate_threshold:
          type: number
          nullable: true
          description: "The store's duplicate cutoff, or `null` when it has never been set. Reported as `null`
            rather than as the constant it resolves to: a store with no policy must read differently
            from one pinned to today's default."
          example: 0.95
        supersede_threshold:
          type: number
          nullable: true
          description: The store's supersede cutoff, or `null` when it has never been set.
          example: 0.9
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Page:
      type: object
      description: One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: Structured error. Every error response uses this shape, so `code` can be read without
            first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              description: Machine-readable error code, UPPER_SNAKE whether naturali or the runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: What to do about it, naming the routes of this API to call. For people and agents; it
                may change, so branch on `code`.
              example: Use a credential whose scope includes this action, or ask a project `admin` or `owner` to
                act; the caller's role or key excludes it.
            meta:
              type: object
              additionalProperties: true
              description: Structured context, such as the `resource` and `limit` of a `PLAN_LIMIT_REACHED`.
    TagBag:
      type: object
      additionalProperties:
        type: string
      x-cli-flag-name: tags
      description: >-
        Key-value labels on a resource. A flat object of string values — an array, a nested object
        or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and
        stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB
        containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM
        `iam:ResourceTag/<key>` condition.


        Keys beginning `system.` are reserved: the platform writes them to record which
        conversation, actor, agent and role a row came from, and a write naming one is refused with
        `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.


        The bag is bounded, because every pair reaches the IAM context of every access check on the
        resource: at most 50 keys, each key at most 128 characters and each value at most 256. A
        write past a bound — including a merge that would grow the stored bag past the key count —
        is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys
        are the platform's and do not count against the 50.
      example:
        team: finance
        env: prod
    NullableTagBag:
      type: object
      nullable: true
      additionalProperties:
        type: string
      description: "A `TagBag` on a request field where `null` is meaningful: a full-replacement update
        that clears the bag. A record whose bag is unset leaves the field out."
      example:
        team: finance
        env: prod
    MemoryAssertion:
      type: object
      description: "One write attempt against a memory store: some principal, through some mechanism,
        claimed a fact. Append-only, and recorded whatever the outcome — including the skips, which
        left no record anywhere before."
      properties:
        id:
          type: string
          example: massert_V1StGXR8Z5jdHi6B
        memory_store_id:
          x-naturali-ref: memory-stores
          type: string
          example: mstore_V1StGXR8Z5jdHi6B
        memory_id:
          type: string
          nullable: true
          description: "The memory this assertion resolved into: the new memory for `created` and
            `superseded`, the existing memory that matched for `skipped`, the memory withdrawn for
            `retracted`. Null only once that memory has been deleted."
          example: mem_V1StGXR8Z5jdHi6B
        superseded_memory_id:
          type: string
          nullable: true
          description: The memory this assertion retired, on a `superseded` outcome; null otherwise, a
            retraction included — it retires its own memory, which `memory_id` already names. Read
            back from `memories.superseded_by_memory_id` rather than stored here, because validity
            lives on the memory — where every read filters it — and exactly one memory is superseded
            per assertion.
          example: mem_V1StGXR8Z5jdHi6B
        content:
          type: string
          description: "The text as asserted, which is not necessarily the memory's text: a `skipped`
            assertion records what was claimed, while the memory keeps what it already held."
          example: The customer prefers email communication over phone calls
        mechanism:
          type: string
          enum:
            - tool
            - rule
            - api
            - formation
          description: Which door the write came through. `tool` is the agent's `write_memory` call mid-turn;
            `rule` is a post-turn pass over the finished turn; `api` is `POST
            /v1/projects/{project_id}/memories`; `formation` is a `memory` resource in an applied
            template. It answers *how*, never *who* — the principal fields answer that. Open set —
            new mechanisms may be added in minor releases; clients must tolerate unknown values.
          example: tool
        rule_id:
          x-naturali-ref: memory-rules
          type: string
          nullable: true
          description: The memory rule whose firing wrote this, set only when `mechanism` is `rule` — the
            built-in extractor included, since that is a rule with no handler. Null once the rule
            has been deleted, and on assertions written before memory rules shipped.
          example: mrule_V1StGXR8Z5jdHi6B
        generation_id:
          x-naturali-ref: generations
          type: string
          nullable: true
          description: The turn that asserted the fact — the origin of anything an agent wrote, and the edge a
            conversation is reachable from. Null on the `api` and `formation` doors, which have no
            generation behind them.
          example: gen_V1StGXR8Z5jdHi6B
        principal_type:
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: "Who claimed the fact: `user` or `api_key` on the `api` and `formation` doors, `agent`
            on both agent doors — the extractor runs under the agent's identity."
        principal_id:
          type: string
          example: agent_V1StGXR8Z5jdHi6B
        outcome:
          type: string
          enum:
            - created
            - superseded
            - skipped
            - retracted
          description: What the write resolved to. `created` is a distinct fact, `superseded` is the same fact
            changed (the top match was invalidated and replaced), `skipped` is a fact already known,
            `retracted` is a fact that stopped holding with nothing replacing it. Open set — new
            outcomes may be added in minor releases; clients must tolerate unknown values.
          example: created
        similarity:
          type: number
          nullable: true
          description: The cosine similarity the outcome was decided against — the top match's, or the
            declared target's when `declared` is true, where it decides nothing and only records how
            far apart the two statements were. Null when there was nothing to compare against, when
            the content could not be embedded, and on a `retracted` outcome, which compares nothing.
          example: 0.97
        declared:
          type: boolean
          description: Whether the write named the memory it replaced (`supersedes` on create) instead of the
            thresholds choosing one. Always false on a `created`, `skipped` or `retracted` outcome.
          example: false
        created_at:
          type: string
          format: date-time
    PrincipalType:
      type: string
      enum:
        - user
        - api_key
        - agent
        - automation
        - approval
        - trigger
        - system
        - eval
        - decider
        - ingestion_rule
        - memory_rule
        - playbook_version
      description: What kind of principal acted. `user` and `api_key` are authenticated callers, and the
        id is the user's (`user_…`) or the key's own (`key_…`), so a record names which key acted
        rather than its owner. `agent` is an agent writing under its own identity (`agent_…`).
        `automation` is the task engine acting on a dispatch outcome and `approval` an approval
        resolution; neither carries an id. `trigger` is a trigger firing under its own `policy_ids`
        (`trg_…`). `system` is the platform itself, with an id naming the mechanism
        (`retention_sweep`, `zero_retention`). `eval`, `decider`, `ingestion_rule`, `memory_rule`
        and `playbook_version` are that resource's work running under its own `policy_ids` when
        nobody started it, the id its own.
      example: user
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    TagsQuery:
      name: tags
      in: query
      required: false
      description: >
        Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain
        colons). Repeat the parameter for several pairs; **all** must be present with exactly that
        value.
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
        - env:prod
    Limit:
      name: limit
      in: query
      required: false
      description: Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an
        integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`; omit it for the first page. A cursor this list did
        not issue is `400`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: "A connected app's OAuth access token, issued by this API's authorization server
        (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation,
        confined to the projects the user chose when approving the app."
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: "`QUOTA_EXCEEDED` — a `requests` quota on the calling API key or its project is spent
        for the window; `Retry-After` says when it reopens"
      headers:
        Retry-After:
          description: Seconds until the quota window admits a request again
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    PayloadTooLarge:
      description: "`REQUEST_REJECTED` — the request body is over the size the body parser accepts"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionUnavailable:
      description: The deployment's admission service is asked about this write and did not answer —
        `ADMISSION_UNAVAILABLE`; the write did not happen
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionRefused:
      description: The deployment's admission service refused this write — answered under the service's
        own `4xx` status, with its `code` (matching `^[A-Za-z_][A-Za-z0-9_]{0,63}$`, not necessarily
        an `ERROR_CODES` key), `message` and `meta`; the write did not happen. A status this
        operation also declares on its own is documented there
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Unexpected server error — `INTERNAL_ERROR`, with the raw message never forwarded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ProjectNotFound:
      description: The project does not exist or the caller is not a member of it (`RESOURCE_NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
