API Reference

REST hub: every CribScore endpoint, grouped by resource. Use this page to navigate; deep-dive sub-pages cover params, examples, and response shapes.

Conventions#

Every endpoint is versioned under `/v1/`, accepts JSON, and authenticates with a bearer token. Errors follow RFC 7807 problem details. Pagination uses `limit` + `offset`; ranges are validated server-side.

Base URL: `https://api.cribscore.co`
Auth header: `Authorization: Bearer YOUR_API_KEY`
Content type: `application/json`
Pagination defaults: `limit=20`, max `limit=100`
Rate limits: per-key, burstable. The `Retry-After` header is set on 429.

Resource map#

Endpoints are organized into five resources. Each has its own deep page with full parameter tables, example requests, and example responses.

Facilities — search, detail, compare, risk forecast, evidence. See /docs/api/facilities.
Trust — jurisdiction trust tiers, state coverage. See /docs/api/trust.
Decision — explainable memo with shortlist + trade-offs. See /docs/api/decision.
Webhooks — subscription, delivery, signature verification. See /docs/api/webhooks.
Discovery — `/v1/docs` for AI-readable doc index (mirrors this site).

Authentication#

Use a bearer token. Keys are scoped to your account and can be rotated without code changes. CribScore signs webhook deliveries with a per-key secret; see /docs/api/webhooks for verification.

curl -sS "https://api.cribscore.co/v1/facilities?zip_code=90003&limit=1" \
  -H "Authorization: Bearer $CRIBSCORE_API_KEY"

client = httpx.Client(
    base_url="https://api.cribscore.co",
    headers={"Authorization": f"Bearer {os.environ['CRIBSCORE_API_KEY']}"},
    timeout=30.0,
)

const cribscore = (path: string, init: RequestInit = {}) =>
  fetch(`https://api.cribscore.co${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.CRIBSCORE_API_KEY}`,
      "Content-Type": "application/json",
      ...(init.headers ?? {}),
    },
  });

Errors#

Errors return RFC 7807 problem documents. `type` is a stable URI identifying the error class, `status` mirrors the HTTP status, and `detail` is safe to display to operators (never to end users).

{
  "type": "https://www.cribscore.co/errors/unauthorized",
  "title": "Authentication required",
  "status": 401,
  "detail": "Bearer token missing or invalid."
}

{
  "type": "https://www.cribscore.co/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Slow down — limit resets in 12s.",
  "retry_after_seconds": 12
}

OpenAPI#

All endpoints below are generated from the canonical OpenAPI document. Use it for code generation, gateway config, and contract testing.

Spec: https://api.cribscore.co/openapi.json
Postman: https://www.cribscore.co/postman/CribScore.postman_collection.json

Conventions#

Resource map#

Authentication#

Errors#

OpenAPI#

Related#