{
  "openapi": "3.0.3",
  "info": {
    "title": "Warriors Fund Veterans Resource API",
    "description": "Free, open API providing access to 20,000+ verified veteran resources across all 50 US states and territories. Includes VA hospitals, clinics, vet centers, benefits offices, mental health services, housing assistance, employment services, and veterans service organizations. Built by Warriors Fund, a 501(c)(3) nonprofit (EIN: 86-1336741).",
    "version": "2.0.0",
    "contact": {
      "name": "Warriors Fund",
      "email": "info@warriorsfund.org",
      "url": "https://warriorsfund.org"
    },
    "license": {
      "name": "Open Data",
      "url": "https://warriorsfund.org/about"
    }
  },
  "servers": [
    {
      "url": "https://warriors-fund-api.emperormew.workers.dev",
      "description": "Production API"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health check",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string"
                    },
                    "service": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/resources/search": {
      "get": {
        "summary": "Search veteran resources by ZIP code",
        "description": "Find VA hospitals, clinics, benefits offices, mental health services, housing, employment, and VSO resources near a US ZIP code. Returns up to 100 resources within a configurable radius (default 50 miles, max 200 miles). Includes distance from search location.",
        "operationId": "searchResources",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "5-digit US ZIP code",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$",
              "example": "77380"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by resource type",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "va_hospital",
                "va_clinic",
                "vet_center",
                "benefits_office",
                "mental_health",
                "housing",
                "employment",
                "vso",
                "other"
              ],
              "default": "all"
            }
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "description": "Search radius in miles (default 50, max 200)",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results to return (default 20, max 100)",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results with resources sorted by distance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ZIP code"
          },
          "503": {
            "description": "Service unavailable"
          }
        }
      }
    },
    "/api/resources/nearby": {
      "get": {
        "summary": "Search resources by GPS coordinates or ZIP",
        "description": "Find resources near GPS coordinates or a ZIP code. Accepts lat/lng OR zip parameter. Resolves to nearest ZIP code and searches within 50 miles.",
        "operationId": "nearbyResources",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Latitude (required if no zip)",
            "schema": {
              "type": "number",
              "example": 30.1365
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "description": "Longitude (required if no zip)",
            "schema": {
              "type": "number",
              "example": -95.4686
            }
          },
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "description": "5-digit US ZIP code (alternative to lat/lng)",
            "schema": {
              "type": "string",
              "example": "77380"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Nearby resources",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/resources/city": {
      "get": {
        "summary": "Search resources by city name",
        "description": "Find veteran resources near a city. Resolves city to its most populous ZIP code and searches within 50 miles.",
        "operationId": "citySearch",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "City name",
            "schema": {
              "type": "string",
              "example": "Houston"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "2-letter state code to narrow results",
            "schema": {
              "type": "string",
              "example": "TX"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resources near the city",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "404": {
            "description": "City not found"
          }
        }
      }
    },
    "/api/resources/name": {
      "get": {
        "summary": "Search resources by name",
        "description": "Find veteran resources by name keyword. Case-insensitive partial match. Max query length 100 characters.",
        "operationId": "nameSearch",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query (min 2, max 100 chars)",
            "schema": {
              "type": "string",
              "example": "Houston VA"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results (default 20, max 100)",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching resources",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "query": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "resources": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Resource"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Query too short or too long"
          }
        }
      }
    },
    "/api/resources/state/{state}": {
      "get": {
        "summary": "Get all resources for a state",
        "description": "Returns paginated resources for a specific US state or territory.",
        "operationId": "stateResources",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "2-letter state code",
            "schema": {
              "type": "string",
              "example": "TX"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by resource type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "State resources"
          }
        }
      }
    },
    "/api/chat": {
      "post": {
        "summary": "AI chat with crisis detection",
        "description": "Send a message about veteran needs. Detects crisis language (returns 988 hotline immediately). Extracts ZIP codes and intent (medical, benefits, housing, mental_health) to return relevant resources.",
        "operationId": "chat",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "User message about veteran needs",
                    "example": "I need help finding a VA hospital near 77380"
                  }
                },
                "required": [
                  "message"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat response with intent detection and optional resources",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "intent": {
                      "type": "string",
                      "enum": [
                        "crisis",
                        "medical",
                        "benefits",
                        "mental_health",
                        "housing",
                        "general"
                      ]
                    },
                    "isCrisis": {
                      "type": "boolean"
                    },
                    "resources": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Resource"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/feedback": {
      "post": {
        "summary": "Submit resource feedback",
        "description": "Report outdated, incorrect, or helpful resource information.",
        "operationId": "submitFeedback",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resource_id": {
                    "type": "integer",
                    "description": "ID of the resource"
                  },
                  "feedback_type": {
                    "type": "string",
                    "enum": [
                      "helpful",
                      "outdated",
                      "incorrect",
                      "closed",
                      "other"
                    ]
                  },
                  "rating": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "comment": {
                    "type": "string",
                    "maxLength": 1000
                  }
                },
                "required": [
                  "resource_id",
                  "feedback_type"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback recorded"
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "summary": "Database statistics",
        "description": "Returns live counts of resources by type, state, and total coverage statistics. Useful for AI agents to understand data scope before querying.",
        "operationId": "getStats",
        "responses": {
          "200": {
            "description": "Database statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/resources/types": {
      "get": {
        "summary": "List all resource types with counts",
        "operationId": "getResourceTypes",
        "responses": {
          "200": {
            "description": "Resource type breakdown"
          }
        }
      }
    },
    "/api/resources/states": {
      "get": {
        "summary": "List all states with resource counts",
        "operationId": "getResourceStates",
        "responses": {
          "200": {
            "description": "State-by-state resource counts"
          }
        }
      }
    },
    "/api/resources/bulk": {
      "get": {
        "summary": "Bulk export all resources",
        "description": "Paginated export of the full resource database. Use for data mirroring, analysis, or building derivative tools. Returns JSON by default, CSV with format=csv.",
        "operationId": "bulkExport",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 500,
              "maximum": 1000
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Filter by state abbreviation",
            "schema": {
              "type": "string",
              "example": "TX"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by resource type",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated resource data"
          }
        }
      }
    },
    "/api/benefits/calculate": {
      "post": {
        "summary": "Calculate VA benefits estimates",
        "description": "Estimate monthly VA disability compensation or GI Bill benefits based on rating and service years.",
        "operationId": "calculateBenefits",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "disability",
                      "gibill"
                    ]
                  },
                  "rating": {
                    "type": "integer",
                    "description": "Disability rating 10-100 (for disability type)"
                  },
                  "serviceYears": {
                    "type": "number",
                    "description": "Years of service (for gibill type)"
                  },
                  "hasDependent": {
                    "type": "boolean",
                    "description": "Has dependents (for disability type)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Benefits calculation result"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Resource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "resource_type": {
            "type": "string",
            "enum": [
              "va_hospital",
              "va_clinic",
              "vet_center",
              "benefits_office",
              "mental_health",
              "housing",
              "employment",
              "vso",
              "other"
            ]
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          },
          "phone": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "services": {
            "type": "string",
            "description": "JSON array of services offered"
          },
          "distance": {
            "type": "string",
            "description": "Distance in miles from search location"
          },
          "data_source": {
            "type": "string"
          },
          "verified_date": {
            "type": "string"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          },
          "zip": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "state_name": {
            "type": "string"
          },
          "county": {
            "type": "string"
          },
          "population": {
            "type": "integer"
          },
          "veteran_percentage": {
            "type": "number"
          },
          "radius": {
            "type": "integer"
          },
          "resources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Resource"
            }
          }
        }
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "total_resources": {
            "type": "integer"
          },
          "total_zip_codes": {
            "type": "integer"
          },
          "states_covered": {
            "type": "integer"
          },
          "by_type": {
            "type": "object"
          },
          "by_state": {
            "type": "object"
          },
          "last_updated": {
            "type": "string"
          },
          "crisis_line": {
            "type": "string",
            "example": "988 Press 1"
          }
        }
      }
    }
  }
}