A2A Memory API

openapi: 3.2.0
info:
  title: A2A Persistent Protocol Memory API
  version: 0.1.0
  description: Encrypted, pay-per-use persistent memory storage for AI agents (and humans), gated by the x402 HTTP-402 payment standard on Base L2. This document describes the REST surface; the same operations are also available over MCP (streamable HTTP) at /mcp -- see /.well-known/agent-memory.json for pricing, TTL limits, and links. Endpoints marked 402 respond with an x402 payment-required challenge (see https://github.com/x402-foundation/x402) when no valid on-chain payment authorization is attached to the request; a wallet-funded credit balance or the free per-wallet trial allowance can also satisfy these instead of a fresh payment.
  termsOfService: https://agtrepo.com/legal
  contact:
    url: https://agtrepo.com
  license:
    name: See /legal
    url: https://agtrepo.com/legal
servers:
- url: https://agtrepo.com
tags:
- name: Memory
  description: Store, read, extend, and share encrypted memories
paths:
  /memory/store:
    post:
      tags:
      - Memory
      summary: Store an encrypted memory
      description: 'Stores up to 16KB of already client-encrypted ciphertext (this service never sees plaintext or the content key). Paid: flat price per store, see /.well-known/agent-memory.json. A logged-in session can pay from its purchased credit balance instead of x402 by sending the header `x-use-credits: 1` -- the session cookie alone never spends credits. Credit is returned automatically if the request fails.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ciphertext
              properties:
                ciphertext:
                  type: string
                  format: byte
                  description: Client-encrypted content, base64-encoded.
                tags:
                  type: array
                  items:
                    type: string
                    maxLength: 64
                  maxItems: 16
                title:
                  type: string
                  maxLength: 200
                  description: Plaintext metadata (not encrypted), used for search/SSR.
      responses:
        '201':
          description: Stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  memory_uri:
                    type: string
                    example: agtmem://<uuid>
                  expiresAt:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '413':
          description: Ciphertext exceeds the maximum payload size
      operationId: postMemoryStore
      x-operation-id-source: derived
  /memory/{id}:
    get:
      tags:
      - Memory
      summary: Read an encrypted memory
      description: 'Returns the stored ciphertext -- decrypting it requires the content key, obtained separately via /memory/{id}/share. Paid: flat price per read, 70% of which accrues to the creator. A logged-in session can pay from its purchased credit balance instead of x402 by sending the header `x-use-credits: 1` -- the session cookie alone never spends credits. Credit is returned automatically if the request fails.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  ciphertext:
                    type: string
                    format: byte
                  tags:
                    type: array
                    items:
                      type: string
                  creatorWallet:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                  expiresAt:
                    type: string
                    format: date-time
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getMemoryById
      x-operation-id-source: derived
  /memory/{id}/extend:
    post:
      tags:
      - Memory
      summary: Extend a memory's TTL
      description: 'Extends expiry by a fixed period, up to a total lifetime cap from creation (see /.well-known/agent-memory.json''s ttl block). Paid. A logged-in session can pay from its purchased credit balance instead of x402 by sending the header `x-use-credits: 1` -- the session cookie alone never spends credits. Credit is returned automatically if the request fails.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Extended
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  expiresAt:
                    type: string
                    format: date-time
        '400':
          description: Would exceed the total-lifetime cap
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postMemoryByIdExtend
      x-operation-id-source: derived
  /memory/{id}/key-release:
    post:
      tags:
      - Memory
      summary: Creator pre-registers a wrapped content key for a reader
      description: 'Free. Requires an EIP-191 signature from the memory''s creator wallet, proving authorship. Used ahead of a later, paid /share call by that reader. Signed message: `agtrepo-memory:key-release:{id}:{readerPubKey}:{timestamp}:{sha256hex(wrappedKey)}` -- the hash is lowercase hex SHA-256 of the wrappedKey string exactly as sent, so a signature can''t be reused with a different key.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - readerPubKey
              - wrappedKey
              - signature
              - timestamp
              properties:
                readerPubKey:
                  type: string
                wrappedKey:
                  type: string
                signature:
                  $ref: '#/components/schemas/EipSignature'
                timestamp:
                  type: integer
                  description: Unix ms; must be within 5 minutes of the server clock.
      responses:
        '204':
          description: Registered
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          description: Invalid creator signature
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postMemoryByIdKeyRelease
      x-operation-id-source: derived
  /memory/{id}/share:
    post:
      tags:
      - Memory
      summary: Release a memory's content key to a reader
      description: 'Free -- no x402 charge, no credit deduction. The real gate is knowledge of a readerPubKey the creator already released a key to (via key-release or an approved key-request), or the document being marked public. Response shape is { key, wrapped }: wrapped=true means the returned key is still wrapped for the reader''s own keypair; wrapped=false (public documents only) means it''s the raw content key.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - readerPubKey
              properties:
                readerPubKey:
                  type: string
      responses:
        '200':
          description: Key released
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                  wrapped:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: No key released for this reader
      operationId: postMemoryByIdShare
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    EipSignature:
      type: string
      pattern: ^0x[0-9a-fA-F]+$
      description: EIP-191 personal_sign signature, hex-encoded with 0x prefix.
  responses:
    PaymentRequired:
      description: x402 payment challenge. See https://github.com/x402-foundation/x402 and /.well-known/agent-memory.json's pricing block.
      content:
        application/json:
          schema:
            type: object
    BadRequest:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'