{
  "openapi": "3.1.0",
  "info": {
    "title": "Aperture Wallet Agent API",
    "version": "1.0.0",
    "summary": "Read-only public product knowledge for Aperture Wallet",
    "description": "A canonical, public, unauthenticated knowledge interface for agents that cannot use the Aperture MCP server. It exposes documentation only. It cannot inspect a device or wallet, read balances, accept wallet credentials, change settings, sign, authorize, broadcast, import, export, or delete anything.",
    "termsOfService": "https://aperturex.io/terms",
    "contact": {
      "name": "Aperture Support",
      "url": "https://aperturex.io/support",
      "email": "support@aperturex.io"
    },
    "license": {
      "name": "Aperture Terms of Use",
      "url": "https://aperturex.io/terms"
    }
  },
  "servers": [
    {
      "url": "https://aperturex.io",
      "description": "Canonical production origin"
    }
  ],
  "externalDocs": {
    "description": "Aperture Wallet agent index",
    "url": "https://aperturex.io/llms.txt"
  },
  "security": [],
  "tags": [
    {
      "name": "Discovery",
      "description": "API discovery and public knowledge retrieval"
    },
    {
      "name": "Product",
      "description": "Canonical, version-scoped Aperture Wallet product documentation"
    },
    {
      "name": "Journal",
      "description": "Published Aperture Journal metadata and documents"
    }
  ],
  "x-agent-safety": {
    "read_only": true,
    "public_product_data_only": true,
    "never_submit": [
      "recovery phrase",
      "private key",
      "BIP-39 passphrase",
      "app passcode",
      "backup secret",
      "complete sensitive wallet payload"
    ],
    "unsupported_effects": [
      "inspect a device or wallet",
      "read balances",
      "sign or authorize transactions",
      "broadcast transactions",
      "import or export credentials",
      "change settings",
      "delete data"
    ]
  },
  "paths": {
    "/api/agent/v1": {
      "get": {
        "operationId": "getAgentApiDiscovery",
        "summary": "Discover Aperture's public agent interfaces",
        "description": "Returns canonical REST, OpenAPI, MCP, and llms.txt locations plus the complete safety boundary.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      },
      "head": {
        "operationId": "checkAgentApiDiscovery",
        "summary": "Check API availability without a response body",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/HeadSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/search": {
      "get": {
        "operationId": "searchApertureKnowledge",
        "summary": "Search canonical Aperture product and Journal documents",
        "description": "Returns stable document IDs, titles, and canonical URLs. Fetch a selected result through the document endpoint before relying on its details.",
        "tags": ["Discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/SearchQuery"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked public knowledge results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/agent/v1/documents/{id}": {
      "get": {
        "operationId": "fetchApertureDocument",
        "summary": "Fetch one canonical public document",
        "description": "Fetches a document returned by search. Static IDs include product, features, networks, security-model, app-screens, app-entry-points, and releases. Journal IDs use article:{slug}.",
        "tags": ["Discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Canonical document with source URL and complete public text",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/v1/product": {
      "get": {
        "operationId": "getApertureProduct",
        "summary": "Get product identity, availability, fit, and boundaries",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/features": {
      "get": {
        "operationId": "listApertureFeatures",
        "summary": "List documented Aperture Wallet features",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/networks": {
      "get": {
        "operationId": "listApertureNetworks",
        "summary": "List the version-scoped mainnet catalog",
        "description": "This is a mainnet-only documentation catalog, not a guarantee that every asset or operation is available in every installed app version.",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/security": {
      "get": {
        "operationId": "getApertureSecurityModel",
        "summary": "Get Aperture's documented self-custody security model",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/screens": {
      "get": {
        "operationId": "listApertureScreens",
        "summary": "List non-secret semantic app screen documentation",
        "description": "Screen documentation never represents permission to inspect a user's device or wallet.",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/releases": {
      "get": {
        "operationId": "getApertureReleases",
        "summary": "Get the public App Store release snapshot",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/articles": {
      "get": {
        "operationId": "listApertureArticles",
        "summary": "List published Aperture Journal articles",
        "description": "Returns public metadata and canonical HTML and Markdown URLs without exposing the publishing interface.",
        "tags": ["Journal"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    },
    "/api/agent/v1/app-entry-points": {
      "get": {
        "operationId": "listApertureAppEntryPoints",
        "summary": "List safe, navigation-only Aperture app entry points",
        "description": "Every entry opens visible UI and preserves the app's existing protection. No entry point authorizes a transaction or reads wallet data.",
        "tags": ["Product"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonSuccess"
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "SearchQuery": {
        "name": "q",
        "in": "query",
        "required": true,
        "description": "A plain-language product or Journal query. Never include wallet credentials or private wallet data.",
        "schema": {
          "type": "string",
          "minLength": 2,
          "maxLength": 200,
          "examples": ["physical randomness wallet creation"]
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Maximum result count.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 10
        }
      },
      "DocumentId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "A stable ID returned by search, such as product or article:build-wallet-with-dice-coin-flips-random-digits.",
        "schema": {
          "type": "string",
          "pattern": "^(?:[a-z0-9]+(?:-[a-z0-9]+)*|article:[a-z0-9]+(?:-[a-z0-9]+)*)$"
        }
      }
    },
    "responses": {
      "JsonSuccess": {
        "description": "Canonical public Aperture data",
        "headers": {
          "Link": {
            "description": "OpenAPI service description and MCP alternate interface",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenericEnvelope"
            }
          }
        }
      },
      "HeadSuccess": {
        "description": "The API is reachable; the response has no body."
      },
      "ClientError": {
        "description": "The request method, route, or bounded input was invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "BadRequest": {
        "description": "A bounded query parameter or document ID was invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "NotFound": {
        "description": "No canonical public resource matched the route or ID",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "GenericEnvelope": {
        "type": "object",
        "required": ["api_version", "data"],
        "properties": {
          "api_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": ["id", "title", "url"],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": false
      },
      "SearchEnvelope": {
        "type": "object",
        "required": ["api_version", "data"],
        "properties": {
          "api_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "data": {
            "type": "object",
            "required": ["query", "count", "results"],
            "properties": {
              "query": {
                "type": "string"
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 20
              },
              "results": {
                "type": "array",
                "maxItems": 20,
                "items": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          }
        }
      },
      "DocumentEnvelope": {
        "type": "object",
        "required": ["api_version", "data"],
        "properties": {
          "api_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "data": {
            "type": "object",
            "required": ["id", "title", "url", "text", "metadata"],
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "text": {
                "type": "string"
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["api_version", "error"],
        "properties": {
          "api_version": {
            "type": "string",
            "const": "1.0.0"
          },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}