{
  "app": {
    "name": "Benefithub",
    "environment": "development",
    "api_version": "v1"
  },
  "api": {
    "base_url": "https://benefithubapp.cloudtevent.com/api",
    "timeout_seconds": 30,
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json"
    }
  },
  "authentication": {
    "type": "bearer",
    "token_storage_key": "benefithub_access_token",
    "endpoints": {
      "register": {
        "method": "POST",
        "path": "/auth/register"
      },
      "login": {
        "method": "POST",
        "path": "/auth/login"
      },
      "current_user": {
        "method": "GET",
        "path": "/auth/me",
        "auth_required": true
      },
      "logout": {
        "method": "POST",
        "path": "/auth/logout",
        "auth_required": true
      }
    }
  },
  "endpoints": {
    "health": {
      "method": "GET",
      "path": "/health",
      "auth_required": false,
      "sample_response": {
        "success": true,
        "status": "ok",
        "message": "Benefithub API is running"
      }
    },
    "dashboard": {
      "method": "GET",
      "path": "/dashboard",
      "auth_required": true,
      "sample_response": {
        "success": true,
        "data": {
          "eligible_programs": 18,
          "saved_programs": 6,
          "applications_in_progress": 3,
          "submitted_applications": 2,
          "estimated_benefit_value": 12400
        }
      }
    },
    "programs": {
      "list": {
        "method": "GET",
        "path": "/programs",
        "auth_required": true,
        "query_parameters": [
          "page",
          "limit",
          "category",
          "state",
          "search"
        ],
        "sample_response": {
          "success": true,
          "data": [
            {
              "id": 101,
              "title": "Housing Assistance Program",
              "category": "Housing",
              "provider": "State Housing Department",
              "description": "Financial assistance for eligible households.",
              "estimated_value": 2500,
              "deadline": "2026-08-31",
              "application_url": "https://example.gov/apply",
              "is_saved": false
            }
          ],
          "pagination": {
            "current_page": 1,
            "last_page": 1,
            "per_page": 20,
            "total": 1
          }
        }
      },
      "details": {
        "method": "GET",
        "path": "/programs/{program_id}",
        "auth_required": true
      }
    },
    "eligibility": {
      "check": {
        "method": "POST",
        "path": "/eligibility/check",
        "auth_required": true,
        "sample_request": {
          "age": 35,
          "country": "United States",
          "state": "California",
          "household_size": 4,
          "annual_income": 42000,
          "employment_status": "employed",
          "housing_status": "renting",
          "has_children": true
        },
        "sample_response": {
          "success": true,
          "data": {
            "match_count": 1,
            "matches": [
              {
                "program_id": 101,
                "title": "Housing Assistance Program",
                "match_score": 92,
                "estimated_value": 2500,
                "eligibility_status": "likely_eligible",
                "reason": "Example eligibility result"
              }
            ]
          }
        }
      }
    },
    "saved_programs": {
      "save": {
        "method": "POST",
        "path": "/saved-programs",
        "auth_required": true
      },
      "remove": {
        "method": "DELETE",
        "path": "/saved-programs/{program_id}",
        "auth_required": true
      }
    },
    "applications": {
      "list": {
        "method": "GET",
        "path": "/applications",
        "auth_required": true
      },
      "create": {
        "method": "POST",
        "path": "/applications",
        "auth_required": true
      },
      "update": {
        "method": "PATCH",
        "path": "/applications/{application_id}",
        "auth_required": true
      }
    },
    "ocr": {
      "scan": {
        "method": "POST",
        "path": "/ocr/scan",
        "auth_required": true,
        "content_type": "multipart/form-data",
        "file_field": "document"
      }
    },
    "ai": {
      "application_help": {
        "method": "POST",
        "path": "/ai/application-help",
        "auth_required": true
      }
    }
  },
  "standard_errors": {
    "401": {
      "success": false,
      "message": "Unauthenticated"
    },
    "404": {
      "success": false,
      "message": "Resource not found"
    },
    "422": {
      "success": false,
      "message": "Validation failed",
      "errors": {}
    },
    "500": {
      "success": false,
      "message": "An unexpected server error occurred"
    }
  },
  "security": {
    "include_api_keys_in_flutter": false,
    "include_database_credentials_in_flutter": false,
    "notes": [
      "Keep OpenAI, Anthropic and database credentials only on the backend.",
      "Do not expose or publish the .env file.",
      "Replace placeholder endpoint paths after the backend API is finalized."
    ]
  }
}