{
  "openapi": "3.0.0",
  "info": {
    "title": "Smart Contract Permission Explainer API",
    "version": "1.0.0",
    "description": "Explain smart contract approvals, admin controls, upgrade functions, role permissions, and ABI fragments in plain English using self-contained rules."
  },
  "servers": [
    {
      "url": "https://smart-contract-permission-explainer.vercel.app"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "List available endpoints",
        "description": "Return all routes and example request bodies for the Smart Contract Permission Explainer API.",
        "responses": {
          "200": {
            "description": "Endpoint directory"
          }
        }
      }
    },
    "/openapi": {
      "get": {
        "summary": "Return OpenAPI 3.0 spec",
        "description": "Return a valid OpenAPI 3.0 JSON specification for Orbis and AI agent tool import.",
        "responses": {
          "200": {
            "description": "OpenAPI specification"
          }
        }
      }
    },
    "/permission-catalog": {
      "get": {
        "summary": "Return permission dictionary",
        "description": "Return hardcoded smart contract permission patterns with plain-English meanings, user risks, and safe practices.",
        "responses": {
          "200": {
            "description": "Permission catalog"
          }
        }
      }
    },
    "/roles": {
      "get": {
        "summary": "Return role dictionary",
        "description": "Return hardcoded role labels such as DEFAULT_ADMIN_ROLE, MINTER_ROLE, PAUSER_ROLE, and UPGRADER_ROLE with plain-English meanings.",
        "responses": {
          "200": {
            "description": "Role dictionary"
          }
        }
      }
    },
    "/explain": {
      "post": {
        "summary": "Explain a contract function",
        "description": "Explain a smart contract function name, signature, modifiers, or description using hardcoded permission patterns and role dictionaries.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "setApprovalForAll(address,bool)"
                  },
                  "modifiers": {
                    "type": "string",
                    "example": "onlyOwner"
                  },
                  "description": {
                    "type": "string",
                    "example": "Allows an operator to manage every NFT for an owner."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Function permission explanation"
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/summarize-abi": {
      "post": {
        "summary": "Summarize ABI permissions",
        "description": "Summarize pasted ABI fragments and identify permission-like functions, admin controls, approvals, upgrades, minting, burning, and fund movement patterns.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "abi": {
                    "type": "array",
                    "items": {
                      "oneOf": [
                        {
                          "type": "string",
                          "example": "upgradeTo(address)"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "example": "function"
                            },
                            "name": {
                              "type": "string",
                              "example": "mint"
                            },
                            "inputs": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "example": "address"
                                  },
                                  "name": {
                                    "type": "string",
                                    "example": "to"
                                  }
                                }
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                },
                "required": [
                  "abi"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ABI permission summary"
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/explain-transaction": {
      "post": {
        "summary": "Explain transaction permission risk",
        "description": "Explain a transaction method and params in plain English, including approval, upgrade, role, and fund movement warnings.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "example": "approve(address,uint256)"
                  },
                  "params": {
                    "type": "object",
                    "example": {
                      "spender": "0xSpender",
                      "amount": "max"
                    }
                  }
                },
                "required": [
                  "method"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction permission explanation"
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    }
  }
}