ALF Citations Spine API

Status: Documentation complete for sales and integration planning. Public API surface is provisioned per customer — not a free public endpoint.

Placeholder: All examples use {BASE_URL}. Replace with the host we send you after onboarding.

Authentication

API keys are bound to an organization and tier. Send the key on every request:

Bearer header

Authorization: Bearer {API_KEY}

Alternate header (same key)

X-Api-Key: {API_KEY}

Keys can be rotated or revoked without changing your commercial tier.
Tier controls rate limits, state allow-lists (Explorer), and export features.
Never commit keys to public repos; use secrets stores in CI.

Base URL

Path prefix

{BASE_URL}/v1

Illustrative host (not live)

https://{your-workspace}.cloud.davvv.net/alf/v1

Tier limits (planned defaults)

Tier	Req / min	Notes
Explorer	~60	State allow-list; low daily row cap
Builder	~300	Full A/B spine
Platform	~1,000+	Multi-key; higher concurrency
Enterprise	Custom	Contracted

Exceeded limits return 429 with Retry-After when applicable.

Common response envelope

Success

{
  "data": [ /* resource objects */ ],
  "meta": {
    "request_id": "req_…",
    "tier": "builder",
    "page": { "next_cursor": "…", "limit": 100 }
  }
}

Error

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable detail",
    "request_id": "req_…"
  }
}

Endpoints

Method	Path	Description
`GET`	`/v1/health`	Liveness for your provisioned host
`GET`	`/v1/me`	Org, tier, remaining limits
`GET`	`/v1/coverage`	Per-state coverage levels (A/B/F…)

Facilities

Method	Path	Description
`GET`	`/v1/facilities`	List / search facilities
`GET`	`/v1/facilities/{facility_key}`	Single facility

Query params: state, q (name), limit, cursor.

Findings & citations

Method	Path	Description
`GET`	`/v1/findings`	Finding / citation rows
`GET`	`/v1/findings/{id}`	Single finding

Query params: state, facility_key, survey_date_from, survey_date_to, is_citation, is_complaint, open_like, tag, limit, cursor.

Method	Path	Description
`GET`	`/v1/tags`	Tag dictionary

Bulk export (Platform+)

Method	Path	Description
`POST`	`/v1/exports`	Request a scoped export job
`GET`	`/v1/exports/{id}`	Job status / download handle

Examples

List coverage

curl -sS "{BASE_URL}/v1/coverage" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"

Findings for a state (R12-style window)

curl -sS "{BASE_URL}/v1/findings?state=OR&survey_date_from=2025-07-29&is_citation=true&limit=100" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"

Coverage honesty

Always join or check /v1/coverage before ranking states.
F-level states may appear with empty findings arrays — that is intentional, not an outage.
Do not treat missing severity maps as zero risk.

Changelog

Date	Notes
2026-07-29	Initial public contract for ALF Citations Spine (docs-only; provisioned access later).

Docs