{
  "openapi": "3.1.0",
  "info": {
    "title": "ProtectAfrica Initiative Public API",
    "description": "Enterprise-grade machine-readable Web3 and humanitarian telemetry API for ProtectAfrica Initiative & WeCare ($CARE) on Base Mainnet. Designed for autonomous AI agents, web crawlers, and blockchain analytics.",
    "version": "1.0.0",
    "contact": {
      "name": "ProtectAfrica Initiative Developer & Agent Relations",
      "url": "https://protectafrica.org",
      "email": "contact@protectafrica.org"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://protectafrica.org",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Agent health and API readiness check",
        "description": "Returns the operational status of ProtectAfrica APIs, confirms agent accessibility without JS, and validates structured response compatibility.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "API is operational and agent-ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/api/whitepaper": {
      "get": {
        "summary": "Retrieve official technical whitepaper specifications",
        "description": "Returns machine-readable Whitepaper v1.1.0 data including the 12% total flywheel fee breakdown, 4% ceiling per category, 48-Hour Governance Timelock, and multi-utility ecosystem matrix.",
        "operationId": "getWhitepaper",
        "responses": {
          "200": {
            "description": "Official technical whitepaper data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "title": { "type": "string" },
                    "version": { "type": "string" },
                    "tokenAsset": { "type": "string" },
                    "networkArchitecture": { "type": "string" },
                    "canonicalUrl": { "type": "string" },
                    "totalFeePercent": { "type": "number", "example": 12.0 },
                    "feeMatrix": { "type": "array" },
                    "sections": { "type": "array" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ecosystem/stats": {
      "get": {
        "summary": "Retrieve live tokenomics and verified on-chain metrics",
        "description": "Fetches current WeCare ($CARE) token parameters, Base Mainnet smart contract address, 2% charity allocation metrics, and verified treasury proofs.",
        "operationId": "getEcosystemStats",
        "responses": {
          "200": {
            "description": "Ecosystem and tokenomics metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EcosystemStats"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/charity/projects": {
      "get": {
        "summary": "List active humanitarian relief projects",
        "description": "Returns verified grassroots initiatives including solar water boreholes in Turkana, girls' STEM computer labs in Makoko, mobile pediatric healthcare in Karamoja, and drought relief.",
        "operationId": "getCharityProjects",
        "responses": {
          "200": {
            "description": "List of active humanitarian missions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectsList"
                }
              }
            }
          }
        }
      }
    },
    "/api/newsroom/posts": {
      "get": {
        "summary": "Impact Newsroom dispatches and documentary reels",
        "description": "Returns all published field dispatches, geo-locations, beneficiary metrics, and on-chain Base transaction hashes.",
        "operationId": "getNewsroomPosts",
        "responses": {
          "200": {
            "description": "List of mission dispatches",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewsroomPostsList"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/chat": {
      "post": {
        "summary": "CareAI ecosystem advisor query",
        "description": "Interactive question-answering assistant for $CARE tokenomics, humanitarian initiatives, on-chain verification, and pre-sale allocation queries.",
        "operationId": "postAiChat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI response generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid payload format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Processing error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/live-feed": {
      "post": {
        "summary": "Fetch dynamic humanitarian live updates",
        "description": "Generates verified telemetry updates and field alerts for real-time dashboard display.",
        "operationId": "postAiLiveFeed",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "category": { "type": "string", "example": "all" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Live feed items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updates": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/market-insights": {
      "post": {
        "summary": "Analyze DEX market trends and Base token analytics",
        "description": "Returns market sentiment, liquidity pool health, and burn velocity metrics.",
        "operationId": "postAiMarketInsights",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "type": "object" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Market insights report",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/api/ai/staking-analysis": {
      "post": {
        "summary": "Simulate staking yields and reflection compounding",
        "description": "Calculates APY tiers (30, 60, 90 days) and dynamic token reflections.",
        "operationId": "postAiStakingAnalysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": { "type": "number", "example": 100000 },
                  "durationDays": { "type": "integer", "example": 90 }
                },
                "required": ["amount"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Staking projection results",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/api/subscribe": {
      "post": {
        "summary": "Subscribe to mission dispatches and on-chain alerts",
        "description": "Enrolls an email address for verified field updates and token governance announcements.",
        "operationId": "postSubscribe",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "agent@example.org"
                  }
                },
                "required": ["email"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string", "example": "Subscribed successfully" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid email supplied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "required": ["code", "message", "resolution_hint"],
            "properties": {
              "code": {
                "type": "string",
                "example": "API_ROUTE_NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "The requested API endpoint does not exist."
              },
              "resolution_hint": {
                "type": "string",
                "example": "Refer to OpenAPI specification at https://protectafrica.org/openapi.json for valid endpoints."
              },
              "documentation_url": {
                "type": "string",
                "example": "https://protectafrica.org/openapi.json"
              }
            }
          }
        }
      },
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "operational" },
          "agent_ready": { "type": "boolean", "example": true },
          "version": { "type": "string", "example": "1.0.0" },
          "chain": { "type": "string", "example": "Base Mainnet (Chain ID 8453)" },
          "openapi_spec": { "type": "string", "example": "https://protectafrica.org/openapi.json" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "EcosystemStats": {
        "type": "object",
        "properties": {
          "tokenName": { "type": "string", "example": "WeCare" },
          "symbol": { "type": "string", "example": "CARE" },
          "contractAddress": { "type": "string", "example": "0x4d6bf4Da144093aDFc27eDaE30B8331629c53781" },
          "network": { "type": "string", "example": "Base Mainnet" },
          "chainId": { "type": "integer", "example": 8453 },
          "charityFeePercent": { "type": "number", "example": 2.0 },
          "reflectionFeePercent": { "type": "number", "example": 1.5 },
          "autoLiquidityFeePercent": { "type": "number", "example": 2.0 },
          "burnFeePercent": { "type": "number", "example": 1.0 },
          "basescanUrl": { "type": "string", "example": "https://basescan.org/address/0x4d6bf4Da144093aDFc27eDaE30B8331629c53781" }
        }
      },
      "ProjectsList": {
        "type": "object",
        "properties": {
          "projects": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "title": { "type": "string" },
                "category": { "type": "string" },
                "location": { "type": "string" },
                "impactMetric": { "type": "string" },
                "beneficiaries": { "type": "string" }
              }
            }
          }
        }
      },
      "NewsroomPostsList": {
        "type": "object",
        "properties": {
          "count": { "type": "integer" },
          "posts": {
            "type": "array",
            "items": { "type": "object" }
          }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["role", "content"],
              "properties": {
                "role": { "type": "string", "enum": ["user", "model", "system"] },
                "content": { "type": "string" }
              }
            }
          }
        }
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "reply": { "type": "string" },
          "isSimulated": { "type": "boolean" }
        }
      }
    }
  }
}