H2O.ai Memory Blocks API

openapi: 3.2.0
info:
  title: h2oGPTe REST Memory Blocks API
  description: '# Overview


    Users can easily interact with the h2oGPTe API through its REST API, allowing HTTP requests from any programming language.'
  version: v1.0.0
servers:
- url: https://h2ogpte.genai.h2o.ai/api/v1
security:
- bearerAuth: []
tags:
- name: Memory Blocks
paths:
  /users/current/default_memory_blocks:
    get:
      operationId: get_default_memory_blocks
      summary: Get default memory blocks
      description: Returns the user's default memory blocks for LLM and agent scopes. The two scopes are independent with no cascade.
      tags:
      - Memory Blocks
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultMemoryBlocksResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: set_default_memory_block
      summary: Set a default memory block
      description: Sets a default memory block for a given scope (llm or agent). Pass memory_block_id as null to clear.
      tags:
      - Memory Blocks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetDefaultMemoryBlockRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetDefaultMemoryBlockResponse'
        '400':
          description: Invalid request - scope must be llm or agent.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks:
    post:
      operationId: create_memory_block
      summary: Create a Memory Block
      description: Creates a new memory block for persistent agent memory. Memory blocks are cross-collection and per-user.
      tags:
      - Memory Blocks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryBlockCreateRequest'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryBlock'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_memory_blocks
      summary: List memory blocks
      description: List memory blocks accessible to the current user (owned, shared, or public).
      tags:
      - Memory Blocks
      parameters:
      - name: offset
        in: query
        description: How many memory blocks to skip.
        required: false
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: How many memory blocks to return.
        required: false
        schema:
          type: integer
      - name: name_filter
        in: query
        description: Filter memory blocks by name (case-insensitive substring match).
        required: false
        schema:
          type: string
      - name: updated_after
        in: query
        description: Only return memory blocks updated at or after this timestamp (ISO 8601).
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - total
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/MemoryBlock'
                  total:
                    type: integer
                    description: Total number of accessible memory blocks matching the filters.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}:
    get:
      operationId: get_memory_block
      summary: Get a memory block by ID
      description: Returns a specific memory block by its ID.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryBlock'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: update_memory_block
      summary: Update a memory block
      description: Updates the name, content, and/or system prompt amendment of a memory block.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryBlockUpdateRequest'
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_memory_block
      summary: Delete a memory block
      description: Deletes a memory block. Only the owner can delete.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}/permissions:
    get:
      operationId: list_memory_block_permissions
      summary: List user share permissions for a memory block
      description: Returns the list of users with explicit (direct) share grants on the memory block. Does not include cascade access derived from collection sharing.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SharePermission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}/group_permissions:
    get:
      operationId: list_memory_block_group_permissions
      summary: List group share permissions for a memory block
      description: Returns the list of groups with explicit (direct) share grants on the memory block. Does not include cascade access derived from collection sharing.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupSharePermission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}/group_permissions/{group_id}:
    put:
      operationId: share_memory_block_with_group
      summary: Share a memory block with a group
      description: Shares a memory block with a group, granting read and/or edit permissions.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      - name: group_id
        in: path
        description: Id of the group that will obtain access to the memory block.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareMemoryBlockRequest'
      responses:
        '204':
          description: Successful operation
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: unshare_memory_block_from_group
      summary: Remove sharing of a memory block from a group
      description: Removes sharing of a memory block from a group.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      - name: group_id
        in: path
        description: Id of the group that will lose access to the memory block.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successful operation
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}/permissions/{username}:
    put:
      operationId: share_memory_block
      summary: Share a memory block with a user
      description: Shares a memory block with a user, granting read and/or edit permissions.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      - name: username
        in: path
        description: Username to share with.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareMemoryBlockRequest'
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: unshare_memory_block
      summary: Remove sharing of a memory block from a user
      description: Removes sharing of a memory block from a user.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      - name: username
        in: path
        description: Username to unshare from.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}/public_permissions:
    get:
      operationId: list_public_memory_block_permissions
      summary: Returns the public permissions for a memory block
      description: Returns the list of public permissions for a memory block. Returns an empty array if the memory block is not public or has no permissions. Read access is implicit for public memory blocks; an empty array on a public block means public read-only, while ['h2ogpte/memory_block/edit'] means public read + edit. Never raises 404 — unknown memory block ids also return an empty array (mirrors the collection endpoint).
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation. Returns list of permissions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /memory_blocks/{memory_block_id}/privacy:
    put:
      operationId: set_memory_block_privacy
      summary: Set memory block public or private
      description: Toggle whether a memory block is publicly accessible.
      tags:
      - Memory Blocks
      parameters:
      - name: memory_block_id
        in: path
        description: Id of the memory block.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryBlockPrivacyRequest'
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
components:
  schemas:
    SetDefaultMemoryBlockResponse:
      type: object
      properties:
        scope:
          type: string
          enum:
          - llm
          - agent
        memory_block:
          allOf:
          - $ref: '#/components/schemas/MemoryBlock'
    MemoryBlockPrivacyRequest:
      type: object
      required:
      - is_public
      properties:
        is_public:
          type: boolean
          description: Whether the memory block should be public.
        permissions:
          description: Public permission levels to grant when is_public is true (e.g. 'h2ogpte/memory_block/edit'). Read access is always granted to a public memory block. Ignored when is_public is false. When omitted, edit access is granted by default; pass an explicit empty array to make the block public read-only.
          type: array
          items:
            type: string
    SharePermission:
      required:
      - username
      type: object
      properties:
        username:
          type: string
        permissions:
          type: array
          items:
            type: string
    EndpointError:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
    DefaultMemoryBlocksResponse:
      type: object
      properties:
        defaults:
          $ref: '#/components/schemas/DefaultMemoryBlocksByScope'
    SetDefaultMemoryBlockRequest:
      type: object
      required:
      - scope
      properties:
        scope:
          type: string
          description: Which scope to set.
          enum:
          - llm
          - agent
        memory_block_id:
          type:
          - string
          - 'null'
          description: UUID of the memory block to set as default, or null to clear.
    MemoryBlockCreateRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the memory block.
        content:
          type: string
          description: Initial content of the memory block.
        system_prompt_amendment:
          type: string
          description: System prompt amendment for agent mode that drives changes to the memory block.
        injection_mode:
          type: string
          description: Where memory content is injected. 'system_prompt' (default) adds it to the LLM system prompt; 'user_instruction' prepends it to the user message; 'agent_file' makes it only available as AGENTS.md in agent mode; 'agent_tool' exposes content lazily via the read_memory_block / update_memory_block tools (no pre-injection).
          enum:
          - system_prompt
          - user_instruction
          - agent_file
          - agent_tool
        access_mode:
          type: string
          description: Controls whether the LLM/agent can read the memory, write to it, or both.
          enum:
          - read
          - write
          - read_write
        max_content_length:
          type: integer
          default: 10000
          description: Maximum number of characters allowed in memory content. Set to 0 for unlimited. In LLM mode, new memories are appended and oldest content is trimmed when this limit is exceeded.
    DefaultMemoryBlocksByScope:
      type: object
      properties:
        llm:
          allOf:
          - $ref: '#/components/schemas/MemoryBlock'
        agent:
          allOf:
          - $ref: '#/components/schemas/MemoryBlock'
    GroupSharePermission:
      required:
      - group_id
      type: object
      properties:
        group_id:
          type: string
        permissions:
          type: array
          items:
            type: string
    MemoryBlockUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: New name for the memory block.
        content:
          type: string
          description: Updated content of the memory block.
        system_prompt_amendment:
          type: string
          description: Updated system prompt amendment.
        injection_mode:
          type: string
          description: Where memory content is injected. 'system_prompt' adds it to the LLM system prompt; 'user_instruction' prepends it to the user message; 'agent_file' makes it only available as AGENTS.md in agent mode; 'agent_tool' exposes content lazily via the read_memory_block / update_memory_block tools (no pre-injection).
          enum:
          - system_prompt
          - user_instruction
          - agent_file
          - agent_tool
        access_mode:
          type: string
          description: Controls whether the LLM/agent can read the memory, write to it, or both.
          enum:
          - read
          - write
          - read_write
        max_content_length:
          type: integer
          description: Maximum number of characters allowed in memory content. Set to 0 for unlimited.
    ShareMemoryBlockRequest:
      type: object
      properties:
        permissions:
          description: Individual permission levels for the memory block.
          type: array
          items:
            type: string
    MemoryBlock:
      type: object
      required:
      - id
      - name
      - content
      - system_prompt_amendment
      - injection_mode
      - access_mode
      - user_id
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier of the memory block.
        name:
          type: string
          description: Name of the memory block.
        content:
          type: string
          description: Text content of the memory block.
        system_prompt_amendment:
          type: string
          description: System prompt amendment for agent mode.
        injection_mode:
          type: string
          description: Where memory content is injected. 'system_prompt' adds it to the LLM system prompt; 'user_instruction' prepends it to the user message; 'agent_file' makes it only available as AGENTS.md in agent mode; 'agent_tool' exposes content lazily via the read_memory_block / update_memory_block tools (no pre-injection).
          enum:
          - system_prompt
          - user_instruction
          - agent_file
          - agent_tool
        access_mode:
          type: string
          description: Controls whether the LLM/agent can read the memory, write to it, or both.
          enum:
          - read
          - write
          - read_write
        user_id:
          type: string
          description: ID of the user who owns the memory block.
        username:
          type: string
          description: Username of the owner.
        created_at:
          type: string
          format: date-time
          description: When the memory block was created.
        updated_at:
          type: string
          format: date-time
          description: When the memory block was last updated.
        is_public:
          type: boolean
          description: Whether the memory block is publicly accessible.
        is_owner:
          type: boolean
          description: Whether the current user is the owner.
        max_content_length:
          type: integer
          description: Maximum number of characters allowed in memory content. 0 means unlimited.
        is_auto:
          type: boolean
          description: Whether this memory block was auto-created by the system for an AI assistant or chat session.
        user_count:
          type: integer
          description: The number of users the memory block has been directly shared with (excludes the owner).
        group_count:
          type: integer
          description: The number of groups the memory block has been shared with.
  responses:
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unexpected:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Using an API key generated by H2OGPTe