Quickstart
Quickstart
Pick your transport — REST cURL, MCP package, or OpenAPI spec — and make your first authenticated call to CribScore in under two minutes.
Get an API key#
Every CribScore surface (REST, MCP, webhooks, decision memo) authenticates with a bearer token. Generate one from the dashboard, then export it once in the shell where you will test calls so the examples below run unmodified.
- Treat the key like a password: rotate it if you leak it in a repo or notebook.
- Local development can put the key in a `.env` file consumed by `dotenv` or `direnv`.
- Production deploys should pull from a secret manager (1Password, Vault, AWS Secrets Manager).
Path 1 — cURL one-liner#
Fastest sanity check. Search facilities by ZIP and confirm you can read trust-tagged provider records. No SDK, no install — just confirm authentication and JSON shape.
curl -sS "https://api.cribscore.co/v1/facilities?zip_code=90003&limit=5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"import httpx
response = httpx.get(
"https://api.cribscore.co/v1/facilities",
params={"zip_code": "90003", "limit": 5},
headers={"Authorization": "Bearer YOUR_API_KEY"},
timeout=30.0,
)
response.raise_for_status()
payload = response.json()
for facility in payload["data"]:
print(facility["id"], facility["name"], facility.get("safety_score"))const params = new URLSearchParams({ zip_code: "90003", limit: "5" });
const response = await fetch(`https://api.cribscore.co/v1/facilities?${params.toString()}`, {
headers: {
Authorization: "Bearer YOUR_API_KEY",
Accept: "application/json",
},
});
if (!response.ok) {
throw new Error(`CribScore search failed: ${response.status}`);
}
const { data } = await response.json();
console.log(data.map((facility: { id: string; name: string }) => facility.name));{
"data": [
{
"id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
"name": "Sunrise Learning Center",
"state_code": "CA",
"facility_type": "center",
"license_status": "active",
"safety_score": 87,
"source_url": "https://www.ccld.dss.ca.gov/carefacilitysearch/details/198000123"
}
],
"meta": { "limit": 5, "offset": 0, "total": 41 }
}Path 2 — npm / MCP#
If you are building an agent, install the MCP package and skip request plumbing. The npm package exposes the same tools the hosted MCP surface offers — search, detail, compare, trust, evidence, decision memo — over local stdio transport.
- Package: @cribscore/mcp — published on npm.
- Source: https://github.com/musa8026/CribScore/tree/main/apps/mcp
- Hosted endpoint: https://api.cribscore.co/mcp (bearer auth).
npx -y @cribscore/mcp{
"mcpServers": {
"cribscore": {
"command": "npx",
"args": ["-y", "@cribscore/mcp"],
"env": {
"MCP_API_KEY": "YOUR_API_KEY"
}
}
}
}{
"cribscore": {
"type": "streamable-http",
"url": "https://api.cribscore.co/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}Path 3 — OpenAPI spec#
If you are generating typed clients, downloading a Postman collection, or wiring CribScore into an API gateway, start from the OpenAPI document. It is the canonical contract and powers our docs, MCP tool surface, and Postman collection source.
- Spec: https://api.cribscore.co/openapi.json
- Postman: https://www.cribscore.co/postman/CribScore.postman_collection.json
- Spec stays in lock-step with production — regenerated on every release.
curl -sS https://api.cribscore.co/openapi.json -o cribscore.openapi.jsonnpx @openapitools/openapi-generator-cli generate \
-i https://api.cribscore.co/openapi.json \
-g typescript-fetch \
-o ./src/cribscore-clientWhat to read next#
Once your first call works, pick the deep section that matches your build path. The API reference is the source of truth for endpoints; the MCP guide covers agent integration; recipes show end-to-end tutorials.
- Endpoint reference → /docs/api
- Agent build → /docs/mcp
- End-to-end recipes → /docs/recipes