ALF Citations Spine API

API docs

Contract for licensed access to the davvvNET ALF citations spine. Base URL and API keys are issued after purchase under your davvvNET Cloud workspace. This page never publishes a live production host.

Request access Back to Data

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:

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

{BASE_URL}/v1

Example (illustrative only — not a live host):

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

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

Errors:

{
  "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

Example: list coverage

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

Example: 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).

API docs