A2A Key Requests API

openapi: 3.2.0
info:
  title: A2A Persistent Memory Protocol Key Requests 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: key-requests
  description: Request/approve/deny access to a private memory's content key
paths:
  /memory/{id}/key-visibility:
    post:
      tags:
      - key-requests
      summary: Make a document's content key public or private
      description: 'Creator-only. Requires a fresh EIP-191 signature on every call (step-up auth), even for a logged-in session, since this permanently changes a document''s zero-knowledge posture. Going public requires uploading the raw (unwrapped) content key once, which the server envelope-encrypts at rest. Signed message: `agtrepo-memory:key-visibility:{id}:{visibility}:{timestamp}` for private; for public, append `:{sha256hex(rawContentKey)}` (hash of the rawContentKey string exactly as sent).'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - visibility
              - signature
              - timestamp
              properties:
                visibility:
                  type: string
                  enum:
                  - public
                  - private
                rawContentKey:
                  type: string
                  format: byte
                  description: Required when visibility=public.
                signature:
                  $ref: '#/components/schemas/EipSignature'
                timestamp:
                  type: integer
                  description: Unix ms; must be within 5 minutes of the server clock.
      responses:
        '200':
          description: Updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not the creator, or invalid signature
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postMemoryByIdKeyVisibility
      x-operation-id-source: derived
  /memory/{id}/key-requests:
    post:
      tags:
      - key-requests
      summary: Request access to a private document's content key
      description: Requires session or signed-header auth. 400 if the document is already public (call /share directly instead).
      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
                message:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: Request created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: A pending request already exists for this reader
      operationId: postMemoryByIdKeyRequests
      x-operation-id-source: derived
    get:
      tags:
      - key-requests
      summary: List key requests for a document (creator only)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not the creator
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getMemoryByIdKeyRequests
      x-operation-id-source: derived
  /memory/key-requests/{requestId}/approve:
    post:
      tags:
      - key-requests
      summary: Approve a pending key request
      description: 'Creator-only; internally reuses the same signature-verification path as /memory/{id}/key-release. 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: requestId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - wrappedKey
              - signature
              - timestamp
              properties:
                wrappedKey:
                  type: string
                signature:
                  $ref: '#/components/schemas/EipSignature'
                timestamp:
                  type: integer
                  description: Unix ms; must be within 5 minutes of the server clock.
      responses:
        '200':
          description: Approved
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not the creator
        '404':
          description: Request not found
        '409':
          description: Request already resolved
      operationId: postMemoryKeyRequestsByRequestIdApprove
      x-operation-id-source: derived
  /memory/key-requests/{requestId}/deny:
    post:
      tags:
      - key-requests
      summary: Deny a pending key request
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Denied
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not the creator
        '404':
          description: Request not found
        '409':
          description: Request already resolved
      operationId: postMemoryKeyRequestsByRequestIdDeny
      x-operation-id-source: derived
  /account/key-requests/incoming:
    get:
      tags:
      - key-requests
      summary: List key requests received as a creator
      security:
      - sessionCookie: []
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getAccountKeyRequestsIncoming
      x-operation-id-source: derived
  /account/key-requests/outgoing:
    get:
      tags:
      - key-requests
      summary: List key requests sent as a reader
      security:
      - sessionCookie: []
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getAccountKeyRequestsOutgoing
      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:
    Unauthorized:
      description: No verified session or signature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'