{"openapi":"3.1.1","info":{"title":"BMDPat Memory API","version":"1.0.0","description":"Store JSON by namespace and key. Recall reads exact keys or lists up to 100 entries, newest update first. There is no semantic search or pagination.\n\nUse a provisioned x-api-key or an authorized x402 payment. A nonempty API key takes precedence. This API does not issue keys. API-key and wallet identities have separate storage scopes; keep wallet address casing consistent.\n\nPayment needs a funded wallet and a client that can sign the requested authorization. Read the 402 PAYMENT-REQUIRED header (base64 JSON), inspect the amount, network, asset and recipient, then send PAYMENT-SIGNATURE. X-PAYMENT is a legacy alias for the same V2 payload. Do not send conflicting aliases.\n\nPayment settles before the operation runs. PAYMENT-RESPONSE is a payment receipt, not proof that memory was stored or returned. Confirmation time varies. A server error can occur after payment; automatic fulfillment recovery and refunds are not provided by this API.\n\nOn 409, do not submit another payment. Keep the transaction and network fields when present, check the transaction outcome, and contact pat@bmdpat.com if it remains unknown. A missing explorer result does not prove failure. Do not automatically repay after a timeout or 500 either.\n\nNamespace accepts 1 to 128 UTF-16 code units. A required key accepts 1 to 256. A stored value can be any JSON value, including null, up to 10240 UTF-8 bytes after JSON.stringify. Extra properties are ignored.\n\nFor recall, omit key to list entries. An empty or non-string key also selects listing for compatibility. A missing exact key returns memory: null with HTTP 200.\n\nFor forget, use namespace and key query parameters. Legacy JSON bodies also work when neither query parameter is present. If either query parameter is present, both must be valid; values are not filled from the body. Deleting a missing key still returns forgotten: true.\n\nThese handlers do not enforce a published requests-per-minute allowance. No rate-limit headers or 429 contract are promised. Limit your own concurrency and stop payment retries when the outcome is unknown."},"servers":[{"url":"https://bmdpat.com"}],"externalDocs":{"url":"https://bmdpat.com/memory.md","description":"Usage, limits and payment recovery guidance"},"security":[{"ApiKey":[]},{"X402":[]},{"LegacyX402":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Provisioned API key. Takes precedence over payment headers."},"X402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"Base64 JSON x402 V2 payment payload, signed by an authorized wallet."},"LegacyX402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"Legacy header alias for a V2 payment payload."}}},"paths":{"/api/memory/store":{"post":{"operationId":"memoryStore","summary":"Store or update a memory entry by namespace + key","description":"Store or update a memory entry by namespace + key","x-payment":{"atomicAmount":"1000","token":"USDC","network":"eip155:8453"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"description":"Maximum 128 UTF-16 code units.","x-max-utf16-code-units":128},"key":{"type":"string","minLength":1,"description":"Maximum 256 UTF-16 code units.","x-max-utf16-code-units":256},"value":{"description":"Any JSON value. JSON.stringify(value) must fit 10240 UTF-8 bytes.","x-max-json-utf8-bytes":10240}},"required":["namespace","key","value"]}}}},"responses":{"200":{"description":"Operation result.","content":{"application/json":{"schema":{"type":"object","properties":{"stored":{"const":true},"namespace":{"type":"string","minLength":1,"description":"Maximum 128 UTF-16 code units.","x-max-utf16-code-units":128},"key":{"type":"string","minLength":1,"description":"Maximum 256 UTF-16 code units.","x-max-utf16-code-units":256}},"required":["stored","namespace","key"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"400":{"description":"Invalid input, malformed payment or conflicting payment aliases.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Handler credentials rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Payment required or rejected. Read the returned requirements before authorizing payment.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"405":{"description":"Wrong method. Allow is supplied on the payment path.","headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"On 409, do not submit another payment. Keep the transaction and network fields when present, check the transaction outcome, and contact pat@bmdpat.com if it remains unknown. A missing explorer result does not prove failure. Do not automatically repay after a timeout or 500 either.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"const":"payment_settlement_uncertain"},"retryable":{"const":false},"transaction":{"type":["string","null"]},"network":{"type":["string","null"]},"message":{"type":"string"}},"required":["error","code","retryable","transaction","network","message"]}}}},"500":{"description":"Infrastructure or fulfillment failure. Payment may already have settled. Do not automatically repay.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}}}}},"/api/memory/recall":{"post":{"operationId":"memoryRecall","summary":"Recall a specific key or up to 100 entries, newest update first","description":"For recall, omit key to list entries. An empty or non-string key also selects listing for compatibility. A missing exact key returns memory: null with HTTP 200.","x-payment":{"atomicAmount":"1000","token":"USDC","network":"eip155:8453"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"description":"Maximum 128 UTF-16 code units.","x-max-utf16-code-units":128},"key":{"description":"Nonempty string selects one key (maximum 256 UTF-16 code units). Missing, empty or non-string selects up to 100 entries."}},"required":["namespace"]}}}},"responses":{"200":{"description":"Operation result.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"memory":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"value":{},"updated_at":{"type":"string","format":"date-time"}},"required":["key","value","updated_at"]},{"type":"null"}]}},"required":["memory"]},{"type":"object","properties":{"memories":{"type":"array","maxItems":100,"items":{"type":"object","properties":{"key":{"type":"string"},"value":{},"updated_at":{"type":"string","format":"date-time"}},"required":["key","value","updated_at"]}}},"required":["memories"]}]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"400":{"description":"Invalid input, malformed payment or conflicting payment aliases.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Handler credentials rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Payment required or rejected. Read the returned requirements before authorizing payment.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"405":{"description":"Wrong method. Allow is supplied on the payment path.","headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"On 409, do not submit another payment. Keep the transaction and network fields when present, check the transaction outcome, and contact pat@bmdpat.com if it remains unknown. A missing explorer result does not prove failure. Do not automatically repay after a timeout or 500 either.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"const":"payment_settlement_uncertain"},"retryable":{"const":false},"transaction":{"type":["string","null"]},"network":{"type":["string","null"]},"message":{"type":"string"}},"required":["error","code","retryable","transaction","network","message"]}}}},"500":{"description":"Infrastructure or fulfillment failure. Payment may already have settled. Do not automatically repay.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}}}}},"/api/memory/forget":{"delete":{"operationId":"memoryForget","summary":"Delete a specific memory entry","description":"For forget, use namespace and key query parameters. Legacy JSON bodies also work when neither query parameter is present. If either query parameter is present, both must be valid; values are not filled from the body. Deleting a missing key still returns forgotten: true.","x-payment":{"atomicAmount":"1000","token":"USDC","network":"eip155:8453"},"requestBody":{"required":false,"description":"Legacy alternative when neither query parameter is present. If either query parameter is present, both query values are required and this body is ignored.","content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"description":"Maximum 128 UTF-16 code units.","x-max-utf16-code-units":128},"key":{"type":"string","minLength":1,"description":"Maximum 256 UTF-16 code units.","x-max-utf16-code-units":256}},"required":["namespace","key"]}}}},"parameters":[{"name":"namespace","in":"query","required":false,"description":"Required together when either query parameter is present. Otherwise use the legacy JSON body.","schema":{"type":"string","minLength":1,"description":"Maximum 128 UTF-16 code units.","x-max-utf16-code-units":128}},{"name":"key","in":"query","required":false,"description":"Required together when either query parameter is present. Otherwise use the legacy JSON body.","schema":{"type":"string","minLength":1,"description":"Maximum 256 UTF-16 code units.","x-max-utf16-code-units":256}}],"responses":{"200":{"description":"Operation result.","content":{"application/json":{"schema":{"type":"object","properties":{"forgotten":{"const":true},"namespace":{"type":"string","minLength":1,"description":"Maximum 128 UTF-16 code units.","x-max-utf16-code-units":128},"key":{"type":"string","minLength":1,"description":"Maximum 256 UTF-16 code units.","x-max-utf16-code-units":256}},"required":["forgotten","namespace","key"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"400":{"description":"Invalid input, malformed payment or conflicting payment aliases.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Handler credentials rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Payment required or rejected. Read the returned requirements before authorizing payment.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"405":{"description":"Wrong method. Allow is supplied on the payment path.","headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"On 409, do not submit another payment. Keep the transaction and network fields when present, check the transaction outcome, and contact pat@bmdpat.com if it remains unknown. A missing explorer result does not prove failure. Do not automatically repay after a timeout or 500 either.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"const":"payment_settlement_uncertain"},"retryable":{"const":false},"transaction":{"type":["string","null"]},"network":{"type":["string","null"]},"message":{"type":"string"}},"required":["error","code","retryable","transaction","network","message"]}}}},"500":{"description":"Infrastructure or fulfillment failure. Payment may already have settled. Do not automatically repay.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}}}}},"/api/memory/stats":{"get":{"operationId":"memoryStats","summary":"Get total memory count and active namespaces","description":"Get total memory count and active namespaces","x-payment":{"atomicAmount":"1000","token":"USDC","network":"eip155:8453"},"responses":{"200":{"description":"Operation result.","content":{"application/json":{"schema":{"type":"object","properties":{"total_memories":{"type":"integer","minimum":0},"namespaces":{"type":"array","items":{"type":"string"}},"namespace_count":{"type":"integer","minimum":0}},"required":["total_memories","namespaces","namespace_count"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"400":{"description":"Invalid input, malformed payment or conflicting payment aliases.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Handler credentials rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Payment required or rejected. Read the returned requirements before authorizing payment.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}},"405":{"description":"Wrong method. Allow is supplied on the payment path.","headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"On 409, do not submit another payment. Keep the transaction and network fields when present, check the transaction outcome, and contact pat@bmdpat.com if it remains unknown. A missing explorer result does not prove failure. Do not automatically repay after a timeout or 500 either.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"const":"payment_settlement_uncertain"},"retryable":{"const":false},"transaction":{"type":["string","null"]},"network":{"type":["string","null"]},"message":{"type":"string"}},"required":["error","code","retryable","transaction","network","message"]}}}},"500":{"description":"Infrastructure or fulfillment failure. Payment may already have settled. Do not automatically repay.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 JSON settlement receipt on paid requests. Does not prove operation fulfillment.","schema":{"type":"string"}}}}}}}}}