Community Resources API

Find approved senior services near you. Food banks, VA facilities, health services, and more.

Overview

The Community Resources API exposes Ramona's curated catalog of senior services to developers and AI agents. Every record is an approved, publicly-shareable location entry: no member data, no PHI. Base URL: https://api.hiramona.com/api/v1/.

Authentication

Every request must carry your API key in the X-Agent-API-Key header. Keys are issued by Ramona. Email support@hiramona.com to request one.

# Authenticated request
curl -H "X-Agent-API-Key: YOUR_API_KEY" \
  "https://api.hiramona.com/api/v1/community-resources/?city=Tulsa"

Requests without a valid key return 401 Unauthorized. If your key is IP-restricted, requests from unlisted IPs return 403 Forbidden.

Rate limits

The API allows 10 requests per minute per key. Exceeding it returns 429 Too Many Requests; wait and retry. Every response includes a correlation_id. Include it when reporting issues.

Errors

Status	Meaning
`400`	Invalid or missing parameters (non-numeric lat/lng, limit out of range, no location given).
`401`	Missing or invalid `X-Agent-API-Key`.
`403`	Your client IP is not whitelisted (only when IP allowlisting is enabled for your key).
`404`	No approved resource exists with the given UUID.
`429`	Rate limit exceeded.
`500`	Server misconfiguration. Contact support with the correlation_id.

Machine-readable schemas

For AI agents and SDK generation:

OpenAPI 3.0 schema: /api/v1/community-resources/openapi.json
Agent discovery summary: /llms.txt

GET /api/v1/community-resources/

Returns approved community resources near a location. Provide either city (+ optional state) or lat+lng. Results are ordered by quality score; when a geo center is present each item carries its haversine distance in miles.

Parameter	Type	Description
city optional	string	City name, case-insensitive. Required unless `lat`+`lng` are provided.
state optional	string	Two-letter state abbreviation; disambiguates the city.
lat, lng optional	number	Search center coordinates. Both required together.
radius_miles optional	number default 10 0.1 to 500	Radius filter applied around the geo center.
category optional	string	Category slug, e.g. `food_bank`, `health_service`, `transportation`, `senior_center`, `housing_support`.
limit optional	integer default 50 1 to 100	Maximum results returned.

Example:

curl -H "X-Agent-API-Key: YOUR_API_KEY" \
  "https://api.hiramona.com/api/v1/community-resources/?lat=36.154&lng=-95.9928&radius_miles=25&category=food_bank"

Response:

{
  "resources": [
    {
      "resource_id: "f4e23622-37e6-4166-bdd2-3cfefe05dbd2",
      "name": "Community Food Bank of Eastern Oklahoma",
      "category": "food_bank",
      "address": "1304 N. Kenosha Ave., Tulsa, OK 74106",
      "coordinates": { "lat": 36.1734, "lng": -95.98302 },
      "accessibility": { "notes": "" },
      "senior_friendly": true,
      "city_name": "Tulsa",
      "distance_miles": 1.4,
      "last_verified_at": "2026-08-22T06:30:00Z"
    }
  ],
  "count": 1,
  "correlation_id": "b2c9f0aa-…"
}

distance_miles is set only when the query included a geo center; treat null as "no reference point". Records without known coordinates are returned by city queries but excluded from radius-filtered results. For geo queries the engine considers the top 200 records by quality score before applying the radius; in very dense catalogs a closer low-quality record may be outranked.

GET /api/v1/community-resources/{uuid}/events/

Returns upcoming approved events (today onward, at most 50) for a single resource, including recurrence details.

curl -H "X-Agent-API-Key: YOUR_API_KEY" \
  "https://api.hiramona.com/api/v1/community-resources/f4e23622-37e6-4166-bdd2-3cfefe05dbd2/events/"

Response:

[
  {
    "event_id": "7c2e…",
    "title": "Senior Fitness Class",
    "category": "fitness",
    "start_date": "2026-09-01",
    "start_time": "10:00:00",
    "recurrence": "weekly",
    "cost": "",
    "is_virtual": false,
    "resource_name": "Tulsa Senior Center",
    "resource_address": "…"
  }
]

Questions or key requests: support@hiramona.com