> ## Documentation Index
> Fetch the complete documentation index at: https://hfsaa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started
> Use the HFSAA Public API.
Start with a rate-limited test key for development—no developer account required.
## Base URLs
The v1 API is read-only and requires an API key. Use the URL that matches the environment shown when the key is claimed.
| Key | Base URL |
| - | - |
| Test (`hfsaa_test_…`) | `https://hfsaa-public-api-staging.idris-ocasio.workers.dev` |
| Production (`hfsaa_live_…`) | `https://api.hfsaa.org` |
## Get an API key
Open the [API access application](https://api.hfsaa.org/developer/apply), choose test or production access, and verify your email address. HFSAA manually approves or denies each request.
Test access does not require an account. A test key does not expire automatically, but it only works at the test base URL and is subject to its assigned rate and monthly request limits. Production access is reviewed separately and may require a paid capacity agreement.
Approved applicants receive a short-lived, one-time claim link. The raw API key is shown once, so store it in a server-side secret manager. Never include it in browser or mobile application code.
## Core resource
`Location` is the canonical resource. Every currently certified restaurant, meat market, and dining hall has an opaque HFSAA location ID and a `type`.
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "restaurant",
"name": "Example Restaurant",
"verification_url": "https://hfsaa-public-locator.pages.dev/?certificate_id=HFSAA-R-EXAMPLE",
"certification_status": "certified",
"chapter_name": "Example Chapter",
"address": "123 Main Street",
"city": "Example City",
"state": "NY",
"zip_code": "10001",
"cuisine_type": "Mediterranean",
"google_place_id": "ChIJ..."
}
```
`chapter_name`, `address`, `city`, `state`, `zip_code`, `cuisine_type`, and `google_place_id` may each be `null`. Applications should omit or adapt any corresponding UI when a value is unavailable.
## Make a request
Every directory-data endpoint requires an API key. Send it in the `Authorization` header on every request; query-string keys and anonymous requests are not supported.
```bash theme={null}
curl "$HFSAA_API_BASE_URL/v1/locations?type=restaurant&limit=25" \
-H "Authorization: Bearer $HFSAA_API_KEY"
```
The production API accepts only production keys, and the test API accepts only test keys. A missing, malformed, unknown, or wrong-environment key returns HTTP `401`. A revoked key returns HTTP `403`. The public `/health` check and developer application, email-verification, key-claim, and accountless management pages do not require an API key; they do not expose directory data and use their own one-time-token or session protections where applicable.
## Filtering and pagination
`GET /v1/locations` supports filters for type, state, city, ZIP code, chapter, and free-text search. Lists use a `limit` and cursor-based `cursor` parameter.
Every list response includes a `dataset_version`. A cursor is bound to that immutable version, and subsequent pages repeat the same version even if HFSAA publishes a newer dataset while you paginate. Keep the same filters with every page request and treat cursors as opaque.
Superseded versions remain available for at least seven days. If a cursor's version has expired, the API returns HTTP `410`; restart pagination without the expired cursor.
## Dataset snapshots
`GET /v1/dataset` returns the current `dataset_version`, UTC `generated_at` time, exact `location_count`, a SHA-256 checksum, and a version-specific `download_url`.
The checksum covers the exact bytes returned by that URL. Use the version-specific URL rather than an unversioned download when reproducibility matters.
## Caching
API data may be cached for no more than one hour. Responses use `Cache-Control: private, max-age=3600, must-revalidate`, which permits a private application or browser cache while preventing shared caches from serving authenticated responses without running API-key checks and usage tracking.
After one hour, revalidate or fetch fresh data before displaying it as current HFSAA certification information. A versioned snapshot remaining available for cursor stability does not extend this one-hour caching allowance.
## Rate limits and retries
Test keys default to 10 requests per minute and 1,000 requests per month. HFSAA can assign different limits during production review. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` for the monthly allowance.
When a per-minute or monthly limit is exceeded, the API returns HTTP `429` with a `Retry-After` header and a structured JSON error body.
Retry `429`, `500`, `502`, `503`, and `504` responses with bounded exponential backoff and jitter. Honor `Retry-After` whenever it is present. Correct `400` requests rather than retrying them unchanged.
## Verification and attribution
When your product states or implies that a location is certified or halal verified by HFSAA, identify HFSAA and give users reasonable access to the exact `verification_url` returned for that location.
For example, this is one acceptable presentation:
```html theme={null}
Certified by HFSAA
```
The link can instead be associated with a badge, **Learn more** link, or another clearly related details element. No exact wording is required. In digital products the URL must be clickable; offline material may use a printed URL or QR code. See the [data policy](/data-policy) for caching, redistribution, freshness, and verification requirements.
Do not present HFSAA data in a way that implies HFSAA endorses your application.
## Google Place IDs
When supplied, a `google_place_id` is an identifier only. If your application uses Google Places to look up photos, hours, maps, or other Google content, you are responsible for your own Google Maps Platform credentials, billing, attribution, and policy compliance.