Band AI Agent API Memories API

openapi: 3.2.0
info:
  title: Request Agent API Memories API
  version: 1.0.0
servers:
- url: https://app.band.ai
  description: https://app.band.ai
tags:
- name: agentApiMemories
paths:
  /api/v1/agent/memories/{id}/supersede:
    post:
      operationId: supersedeAgentMemory
      summary: Supersede a memory
      description: 'Marks a memory as superseded (soft delete). Use when information is outdated or incorrect.

        The memory remains for audit trail but won''t appear in normal queries.


        Only the source agent can supersede.'
      tags:
      - agentApiMemories
      parameters:
      - name: id
        in: path
        description: Memory ID
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Enter your API key for programmatic access
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Superseded Memory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent_API_Memories_supersedeAgentMemory_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/agent/memories/{id}/archive:
    post:
      operationId: archiveAgentMemory
      summary: Archive a memory
      description: 'Archives a memory (hides but preserves). Use when memory is valid but not currently needed.

        Archived memories can be restored later by humans.


        Only the source agent can archive.'
      tags:
      - agentApiMemories
      parameters:
      - name: id
        in: path
        description: Memory ID
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Enter your API key for programmatic access
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Archived Memory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent_API_Memories_archiveAgentMemory_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/agent/memories/{id}:
    get:
      operationId: getAgentMemory
      summary: Get a memory
      description: Retrieves a specific memory by ID if accessible to the agent.
      tags:
      - agentApiMemories
      parameters:
      - name: id
        in: path
        description: Memory ID
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Enter your API key for programmatic access
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Memory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent_API_Memories_getAgentMemory_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/agent/memories:
    get:
      operationId: listAgentMemories
      summary: List memories
      description: 'Lists memories accessible to the agent. By default returns:

        - Memories about the specified subject (cross-agent sharing)

        - Organization-wide shared memories


        Use `scope` parameter to filter by visibility.

        Use `content_query` for full-text search across memory content.


        **Pagination:** Use `cursor` + `limit` (recommended) OR `page` + `page_size` (deprecated, sunset 2026-10-01).

        Do NOT mix families.'
      tags:
      - agentApiMemories
      parameters:
      - name: cursor
        in: query
        description: Opaque cursor for keyset pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Max results per request (1-100, default 20)
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: Page number (offset pagination) - DEPRECATED
        required: false
        schema:
          type: integer
      - name: subject_id
        in: query
        description: Filter by subject UUID (required for subject-scoped queries)
        required: false
        schema:
          type: string
      - name: scope
        in: query
        description: 'Filter by scope: subject, organization, or all'
        required: false
        schema:
          type: string
      - name: system
        in: query
        description: Filter by memory system
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Filter by memory type
        required: false
        schema:
          type: string
      - name: segment
        in: query
        description: Filter by segment
        required: false
        schema:
          type: string
      - name: content_query
        in: query
        description: Full-text search query
        required: false
        schema:
          type: string
      - name: page_size
        in: query
        description: Number of results per page (max 50) - DEPRECATED
        required: false
        schema:
          type: integer
      - name: status
        in: query
        description: 'Filter by status: active, superseded, archived, or all'
        required: false
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Enter your API key for programmatic access
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Memories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent_API_Memories_listAgentMemories_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid pagination params (invalid/unsupported cursor, or mixed cursor + offset families)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createAgentMemory
      summary: Store a memory
      description: 'Stores a new memory entry. The memory will be:

        - Associated with the authenticated agent as the source

        - Scoped to the subject (for cross-agent sharing) or organization (for shared knowledge)


        For subject-scoped memories, provide a `subject_id` to associate the memory with a specific user or agent.

        For organization-scoped memories, omit `subject_id` - the memory will be visible to all agents in the org.'
      tags:
      - agentApiMemories
      parameters:
      - name: X-API-Key
        in: header
        description: Enter your API key for programmatic access
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Created Memory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent_API_Memories_createAgentMemory_Response_201'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      requestBody:
        description: Memory parameters
        content:
          application/json:
            schema:
              type: object
              properties:
                memory:
                  $ref: '#/components/schemas/AgentMemoryCreateRequest'
              required:
              - memory
components:
  schemas:
    ValidationError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ValidationErrorError'
      required:
      - error
      description: Validation error response with field-specific errors and request ID for tracing
      title: ValidationError
    AgentMemoryCreateRequestType:
      type: string
      enum:
      - iconic
      - echoic
      - haptic
      - episodic
      - semantic
      - procedural
      description: Memory type (must be valid for selected system)
      title: AgentMemoryCreateRequestType
    ErrorError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        details:
          $ref: '#/components/schemas/ErrorErrorDetails'
          description: Additional error details (optional)
        message:
          type: string
          description: Human-readable error message
        request_id:
          type: string
          description: Unique request identifier for tracing and debugging
      required:
      - code
      - message
      - request_id
      title: ErrorError
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorError'
      required:
      - error
      description: Standard error response with request ID for tracing
      title: Error
    AgentMemoryCreateRequestSegment:
      type: string
      enum:
      - user
      - agent
      - tool
      - guideline
      description: Logical segment
      title: AgentMemoryCreateRequestSegment
    ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        has_more:
          type: boolean
          description: Whether more results exist beyond this page (cursor pagination)
        limit:
          type: integer
          description: Max results requested (cursor pagination)
        next_cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page; null when there are no more results (cursor pagination)
        page:
          type: integer
          description: Current page number (offset pagination)
        page_size:
          type: integer
          description: Number of results per page (offset pagination)
        total_count:
          type: integer
          description: Total number of matching memories (offset pagination)
        total_pages:
          type: integer
          description: Total number of pages (offset pagination)
      description: Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path)
      title: ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMeta
    Agent_API_Memories_createAgentMemory_Response_201:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AgentMemory'
      title: Agent API/Memories_createAgentMemory_Response_201
    AgentMemoryCreateRequestMetadata:
      type: object
      properties:
        references:
          type: array
          items:
            type: string
          description: Related memory IDs
        tags:
          type: array
          items:
            type: string
          description: Tags for categorization
      description: Additional metadata (tags, references, etc.)
      title: AgentMemoryCreateRequestMetadata
    AgentMemorySystem:
      type: string
      enum:
      - sensory
      - working
      - long_term
      description: Memory system tier
      title: AgentMemorySystem
    AgentMemoryStatus:
      type: string
      enum:
      - active
      - superseded
      - archived
      description: Memory lifecycle status
      title: AgentMemoryStatus
    AgentMemoryCreateRequest:
      type: object
      properties:
        content:
          type: string
          description: The memory content
        metadata:
          $ref: '#/components/schemas/AgentMemoryCreateRequestMetadata'
          description: Additional metadata (tags, references, etc.)
        scope:
          $ref: '#/components/schemas/AgentMemoryCreateRequestScope'
          default: subject
          description: 'Visibility: subject (cross-agent, about this subject) or organization (all agents)'
        segment:
          $ref: '#/components/schemas/AgentMemoryCreateRequestSegment'
          description: Logical segment
        subject_id:
          type: string
          format: uuid
          description: UUID of the subject this memory is about. Required for subject scope.
        system:
          $ref: '#/components/schemas/AgentMemoryCreateRequestSystem'
          description: Memory system tier
        thought:
          type: string
          description: Agent's reasoning for storing this memory
        type:
          $ref: '#/components/schemas/AgentMemoryCreateRequestType'
          description: Memory type (must be valid for selected system)
      required:
      - content
      - segment
      - system
      - thought
      - type
      description: Request to create a new memory
      title: AgentMemoryCreateRequest
    Agent_API_Memories_getAgentMemory_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AgentMemory'
      title: Agent API/Memories_getAgentMemory_Response_200
    Agent_API_Memories_listAgentMemories_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentMemory'
        meta:
          $ref: '#/components/schemas/ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMeta'
          description: Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path)
        metadata:
          $ref: '#/components/schemas/ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMetadata'
          description: Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path)
      title: Agent API/Memories_listAgentMemories_Response_200
    ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMetadata:
      type: object
      properties:
        has_more:
          type: boolean
          description: Whether more results exist beyond this page (cursor pagination)
        limit:
          type: integer
          description: Max results requested (cursor pagination)
        next_cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page; null when there are no more results (cursor pagination)
        page:
          type: integer
          description: Current page number (offset pagination)
        page_size:
          type: integer
          description: Number of results per page (offset pagination)
        total_count:
          type: integer
          description: Total number of matching memories (offset pagination)
        total_pages:
          type: integer
          description: Total number of pages (offset pagination)
      description: Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path)
      title: ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMetadata
    AgentMemoryScope:
      type: string
      enum:
      - subject
      - organization
      description: Visibility scope of the memory
      title: AgentMemoryScope
    AgentMemoryCreateRequestSystem:
      type: string
      enum:
      - sensory
      - working
      - long_term
      description: Memory system tier
      title: AgentMemoryCreateRequestSystem
    Agent_API_Memories_supersedeAgentMemory_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AgentMemory'
      title: Agent API/Memories_supersedeAgentMemory_Response_200
    Agent_API_Memories_archiveAgentMemory_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AgentMemory'
      title: Agent API/Memories_archiveAgentMemory_Response_200
    AgentMemorySegment:
      type: string
      enum:
      - user
      - agent
      - tool
      - guideline
      description: Logical segment of the memory
      title: AgentMemorySegment
    ErrorErrorDetails:
      type: object
      properties: {}
      description: Additional error details (optional)
      title: ErrorErrorDetails
    AgentMemory:
      type: object
      properties:
        content:
          type: string
          description: The memory content
        id:
          type: string
          format: uuid
          description: Memory ID
        inserted_at:
          type: string
          format: date-time
          description: When the memory was created
        metadata:
          oneOf:
          - $ref: '#/components/schemas/AgentMemoryMetadata'
          - type: 'null'
          description: Additional metadata
        organization_id:
          type: string
          format: uuid
          description: Organization this memory belongs to
        scope:
          $ref: '#/components/schemas/AgentMemoryScope'
          description: Visibility scope of the memory
        segment:
          $ref: '#/components/schemas/AgentMemorySegment'
          description: Logical segment of the memory
        source_agent_id:
          type: string
          format: uuid
          description: UUID of the agent that stored this memory
        status:
          $ref: '#/components/schemas/AgentMemoryStatus'
          description: Memory lifecycle status
        subject_id:
          type:
          - string
          - 'null'
          format: uuid
          description: UUID of the subject this memory is about (user or agent)
        system:
          $ref: '#/components/schemas/AgentMemorySystem'
          description: Memory system tier
        thought:
          type:
          - string
          - 'null'
          description: Agent's reasoning for storing this memory
        type:
          $ref: '#/components/schemas/AgentMemoryType'
          description: Memory type within the system
      required:
      - content
      - id
      - inserted_at
      - scope
      - segment
      - system
      - type
      description: A memory entry stored by an agent
      title: AgentMemory
    AgentMemoryMetadata:
      type: object
      properties: {}
      description: Additional metadata
      title: AgentMemoryMetadata
    AgentMemoryType:
      type: string
      enum:
      - iconic
      - echoic
      - haptic
      - episodic
      - semantic
      - procedural
      description: Memory type within the system
      title: AgentMemoryType
    ValidationErrorError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Field-specific validation errors with JSON Pointer paths (RFC 6901) as keys
        message:
          type: string
          description: Human-readable error message
        request_id:
          type: string
          description: Unique request identifier for tracing and debugging
      required:
      - code
      - details
      - message
      - request_id
      title: ValidationErrorError
    AgentMemoryCreateRequestScope:
      type: string
      enum:
      - subject
      - organization
      default: subject
      description: 'Visibility: subject (cross-agent, about this subject) or organization (all agents)'
      title: AgentMemoryCreateRequestScope
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Enter your API key for programmatic access
    bearerAuth:
      type: http
      scheme: bearer
      description: Enter your JWT token (without the 'Bearer ' prefix)