{
  "openapi": "3.0.3",
  "info": {
    "title": "Ramona Community Resources API",
    "version": "1.0.0",
    "description": "Approved senior community resources (food banks, VA facilities, health services, transportation) with geo search. No member data, no PHI. Authentication: `X-Agent-API-Key` header. Rate limit: 10 requests/minute per key."
  },
  "servers": [
    {
      "url": "https://api.hiramona.com",
      "description": "Production API host"
    },
    {
      "url": "https://api-staging.hiramona.com",
      "description": "Staging API host"
    }
  ],
  "components": {
    "securitySchemes": {
      "AgentKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Agent-API-Key"
      }
    }
  },
  "paths": {
    "/api/v1/community-resources/": {
      "get": {
        "summary": "Search approved community resources",
        "description": "Returns approved resources near a location. Provide either `city` (+ optional `state`) or `lat`+`lng`. Results are ordered by quality score; distance is computed via haversine from the query center.",
        "security": [
          {
            "AgentKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "City name (case-insensitive). Required unless lat+lng given."
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter state abbreviation; disambiguates city."
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Latitude of search center. Requires lng."
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Longitude of search center. Requires lat."
          },
          {
            "name": "radius_miles",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 10,
              "minimum": 0.1,
              "maximum": 500
            },
            "description": "Radius filter for geo searches."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by resource category slug (see enum in response schema)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resource list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "resource_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string",
                            "enum": [
                              "senior_center",
                              "health_service",
                              "social_activity",
                              "fitness",
                              "nutrition",
                              "transportation",
                              "support_group",
                              "education",
                              "government",
                              "recreation",
                              "pharmacy",
                              "hospital",
                              "clinic",
                              "food_bank",
                              "housing_support",
                              "utility_assistance",
                              "snap_enrollment",
                              "paratransit",
                              "volunteer_driver_program"
                            ]
                          },
                          "description": {
                            "type": "string"
                          },
                          "address": {
                            "type": "string"
                          },
                          "phone": {
                            "type": "string"
                          },
                          "website": {
                            "type": "string"
                          },
                          "coordinates": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "lat": {
                                "type": "number"
                              },
                              "lng": {
                                "type": "number"
                              }
                            }
                          },
                          "accessibility": {
                            "type": "object",
                            "properties": {
                              "notes": {
                                "type": "string"
                              }
                            }
                          },
                          "senior_friendly": {
                            "type": "boolean"
                          },
                          "city_name": {
                            "type": "string"
                          },
                          "distance_miles": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Set only when the query had a geo center."
                          },
                          "source": {
                            "type": "integer"
                          },
                          "external_id": {
                            "type": "string"
                          },
                          "last_verified_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "integer"
                    },
                    "correlation_id": {
                      "type": "string",
                      "description": "Include when reporting issues."
                    }
                  }
                },
                "example": {
                  "resources": [
                    {
                      "resource_id": "f4e23622-37e6-4166-bdd2-3cfefe05dbd2",
                      "name": "Community Food Bank of Eastern Oklahoma",
                      "category": "food_bank",
                      "description": "",
                      "address": "1304 N. Kenosha Ave., Tulsa, OK 74106",
                      "phone": "",
                      "website": "",
                      "coordinates": {
                        "lat": 36.1734,
                        "lng": -95.98302
                      },
                      "accessibility": {
                        "notes": ""
                      },
                      "senior_friendly": true,
                      "city_name": "Tulsa",
                      "distance_miles": 1.4,
                      "source": 6,
                      "external_id": "feeding_america:92",
                      "last_verified_at": "2026-08-22T06:30:00Z"
                    }
                  ],
                  "count": 1,
                  "correlation_id": "b2c9f0aa-1234-5678-9abc-def012345678"
                }
              }
            }
          },
          "400": {
            "description": "Bad request \u2014 invalid or missing params"
          },
          "401": {
            "description": "Missing or invalid X-Agent-API-Key"
          },
          "403": {
            "description": "Client IP not in AGENT_ALLOWED_IPS (if set)"
          },
          "429": {
            "description": "Rate limited \u2014 10 requests/minute per key"
          },
          "500": {
            "description": "Server misconfiguration"
          }
        }
      }
    },
    "/api/v1/community-resources/{resource_uuid}/events/": {
      "get": {
        "summary": "List upcoming events for a resource",
        "description": "Returns upcoming approved events (today onward, max 50) for one resource, including recurrence details.",
        "security": [
          {
            "AgentKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "resource_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource's `resource_id`."
          }
        ],
        "responses": {
          "description": "Successful response",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "404": {
            "description": "No approved resource with that UUID"
          },
          "400": {
            "description": "Bad request \u2014 invalid or missing params"
          },
          "401": {
            "description": "Missing or invalid X-Agent-API-Key"
          },
          "403": {
            "description": "Client IP not in AGENT_ALLOWED_IPS (if set)"
          },
          "429": {
            "description": "Rate limited \u2014 10 requests/minute per key"
          },
          "500": {
            "description": "Server misconfiguration"
          }
        }
      }
    }
  }
}