openapi: 3.0.3
info:
  title: SOAT Memory Rules API
  version: 1.0.0
  description: >-
    API for managing memory rules — a memory store's ingestion policy. A rule
    subscribes to a completed turn, runs a handler (the built-in extractor, an
    agent, or a tool) and writes what it proposes through the store's own write
    algorithm.
  contact:
    name: SOAT Team
    url: https://github.com/ttoss/soat
servers:
  - url: '{baseUrl}'
    description: Base URL of your SOAT deployment (e.g. https://your-soat.com or http://localhost:5047)
    variables:
      baseUrl:
        description: The base URL of your SOAT deployment
        default: http://localhost:5047
tags:
  - name: Memory Rules
    description: What a memory store accepts from completed agent turns
security:
  - bearerAuth: []
paths:
  /api/v1/memory-rules:
    get:
      tags:
        - Memory Rules
      summary: List memory rules
      description: >-
        Returns memory rules, newest first. Narrow to one store with
        `memory_store_id` — that form is authorized against the store itself, so
        it answers "what feeds this store?" in one call.
      operationId: listMemoryRules
      x-iam-action: memories:ListMemoryRules
      parameters:
        - name: memory_store_id
          in: query
          description: Only the rules of this memory store
          schema:
            type: string
            example: mstore_V1StGXR8Z5jdHi6B
        - name: project_id
          in: query
          description: Project ID (required if not using project key auth)
          schema:
            type: string
            example: proj_V1StGXR8Z5jdHi6B
        - $ref: './pagination.yaml#/components/parameters/Limit'
        - $ref: './pagination.yaml#/components/parameters/Offset'
      responses:
        '200':
          description: List of memory rules
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - total
                  - limit
                  - offset
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MemoryRule'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
    post:
      tags:
        - Memory Rules
      summary: Create a memory rule
      description: >-
        Creates an ingestion rule on a memory store. With neither `agent_id` nor
        `tool_id` the built-in extractor runs, configurable through `prompt`,
        `ai_provider_id` and `model`.
      operationId: createMemoryRule
      x-soat-resource:
        kind: memory_store
        from: memory_store_id
      x-iam-action: memories:CreateMemoryRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - memory_store_id
                - on
              additionalProperties: false
              properties:
                memory_store_id:
                  x-soat-ref: memory-stores
                  type: string
                  description: The destination store, and the rule's owning scope
                  example: mstore_V1StGXR8Z5jdHi6B
                on:
                  $ref: '#/components/schemas/MemoryRuleEvent'
                source_agent_ids:
                  type: array
                  nullable: true
                  description: >-
                    Agents whose turns this rule reads. Omit or send `null` for
                    every agent in the store's project.
                  items:
                    x-soat-ref: agents
                    type: string
                  example: ['agent_V1StGXR8Z5jdHi6B']
                agent_id:
                  x-soat-ref: agents
                  type: string
                  nullable: true
                  description: Handler agent (mutually exclusive with tool_id)
                tool_id:
                  x-soat-ref: tools
                  type: string
                  nullable: true
                  description: Handler tool (mutually exclusive with agent_id)
                action:
                  type: string
                  nullable: true
                  description: Operation id, for a tool handler
                preset_parameters:
                  type: object
                  nullable: true
                  description: >-
                    Merged into a tool handler's input before invocation. The
                    turn's own fields are reserved and win.
                prompt:
                  type: string
                  nullable: true
                  description: >-
                    Replaces the built-in extractor's task instructions. The
                    JSON response contract and the transcript are always
                    appended. Not valid with a handler.
                ai_provider_id:
                  x-soat-ref: ai-providers
                  type: string
                  nullable: true
                  description: >-
                    Provider override for the built-in extractor's completion.
                    Not valid with a handler.
                model:
                  type: string
                  nullable: true
                  description: >-
                    Model override for the built-in extractor's completion. Not
                    valid with a handler.
                enabled:
                  type: boolean
                  default: true
                  description: A disabled rule is kept and never fires
      responses:
        '201':
          description: Memory rule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryRule'
        '400':
          description: Validation failed (e.g. agent_id and tool_id both set, or an extractor override combined with a handler)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Memory store not found
        '500':
          description: Internal server error
  /api/v1/memory-rules/{memory_rule_id}:
    get:
      tags:
        - Memory Rules
      summary: Get a memory rule
      description: Returns a specific memory rule
      operationId: getMemoryRule
      x-soat-resource:
        kind: memory_rule
        from: memory_rule_id
      x-iam-action: memories:GetMemoryRule
      parameters:
        - name: memory_rule_id
          in: path
          required: true
          description: Memory rule ID
          schema:
            type: string
            example: mrule_V1StGXR8Z5jdHi6B
      responses:
        '200':
          description: Memory rule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryRule'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Memory rule not found
    patch:
      tags:
        - Memory Rules
      summary: Update a memory rule
      description: >-
        Updates a memory rule. Validation runs against the rule as it would
        stand after the change, so a one-field update cannot pair a handler with
        a stored extractor override from the side.
      operationId: updateMemoryRule
      x-soat-resource:
        kind: memory_rule
        from: memory_rule_id
      x-iam-action: memories:UpdateMemoryRule
      parameters:
        - name: memory_rule_id
          in: path
          required: true
          description: Memory rule ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                on:
                  $ref: '#/components/schemas/MemoryRuleEvent'
                source_agent_ids:
                  type: array
                  nullable: true
                  description: Send `null` to widen the rule to every agent in the project
                  items:
                    x-soat-ref: agents
                    type: string
                agent_id:
                  x-soat-ref: agents
                  type: string
                  nullable: true
                tool_id:
                  x-soat-ref: tools
                  type: string
                  nullable: true
                action:
                  type: string
                  nullable: true
                preset_parameters:
                  type: object
                  nullable: true
                prompt:
                  type: string
                  nullable: true
                ai_provider_id:
                  x-soat-ref: ai-providers
                  type: string
                  nullable: true
                model:
                  type: string
                  nullable: true
                enabled:
                  type: boolean
      responses:
        '200':
          description: Memory rule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryRule'
        '400':
          description: Validation failed
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Memory rule not found
    delete:
      tags:
        - Memory Rules
      summary: Delete a memory rule
      description: >-
        Deletes a memory rule. The assertions it wrote are kept; their `rule_id`
        becomes null.
      operationId: deleteMemoryRule
      x-soat-resource:
        kind: memory_rule
        from: memory_rule_id
      x-iam-action: memories:DeleteMemoryRule
      parameters:
        - name: memory_rule_id
          in: path
          required: true
          description: Memory rule ID
          schema:
            type: string
      responses:
        '204':
          description: Memory rule deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Memory rule not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token or sk_ api key
  schemas:
    MemoryRuleEvent:
      type: string
      enum:
        - generations.completed
        - conversation_messages.generated
      description: >-
        The event a firing reads. `generations.completed` fires once per
        completed turn whatever the transport, and is the only event the
        built-in extractor may bind to. `conversation_messages.generated` fires
        per persisted assistant reply and is conversation-backed, so it is for
        custom handlers.
      example: generations.completed
    MemoryRule:
      type: object
      properties:
        id:
          type: string
          example: mrule_V1StGXR8Z5jdHi6B
        memory_store_id:
          x-soat-ref: memory-stores
          type: string
        project_id:
          x-soat-ref: projects
          type: string
        on:
          $ref: '#/components/schemas/MemoryRuleEvent'
        source_agent_ids:
          type: array
          nullable: true
          items:
            x-soat-ref: agents
            type: string
        agent_id:
          x-soat-ref: agents
          type: string
          nullable: true
        tool_id:
          x-soat-ref: tools
          type: string
          nullable: true
        action:
          type: string
          nullable: true
        preset_parameters:
          type: object
          nullable: true
        prompt:
          type: string
          nullable: true
        ai_provider_id:
          x-soat-ref: ai-providers
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time