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/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
      operationId: postAiLiveFeed
      responses:
        '200':
          description: Live feed items
  /api/ai/market-insights:
    post:
      summary: Analyze DEX market trends and Base token analytics
      operationId: postAiMarketInsights
      responses:
        '200':
          description: Market insights report
  /api/ai/staking-analysis:
    post:
      summary: Simulate staking yields and reflection compounding
      operationId: postAiStakingAnalysis
      responses:
        '200':
          description: Staking projection results
  /api/subscribe:
    post:
      summary: Subscribe to mission dispatches and on-chain alerts
      operationId: postSubscribe
      responses:
        '200':
          description: Subscription confirmed
        '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
        basescanUrl:
          type: string
          example: https://basescan.org/address/0x4d6bf4Da144093aDFc27eDaE30B8331629c53781
    ProjectsList:
      type: object
      properties:
        projects:
          type: array
          items:
            type: object
    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