> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Introduction

The CAIL Health API is the programmatic surface of CAIL Health, the healthcare access infrastructure that routes care-seeking demand to available care capacity. Use it to discover providers, resolve jurisdiction-aware pathways, check availability, navigate members to care, and read demand and access analytics.

This reference describes every endpoint. The pages in this section cover what every endpoint shares: how to authenticate, how errors are returned, and how the API is versioned.

## Base URL and version

Every endpoint is versioned by a path prefix. The current version is `v1`, so every path in this reference begins with `/v1`. See [Versioning](/api-reference/versioning) for what that version guarantees.

## How the reference is organized

Operations are grouped by the capability they serve, such as discovering providers, navigating to care, and monitoring performance. Each operation page lists its path, parameters, request body, responses, and worked examples.

Each operation also declares which audience may call it. An operation accepts exactly one authentication path and rejects the other. The required scheme is shown on every operation; see [Authentication](/api-reference/authentication) for how to read it.

## Two audiences

CAIL Health serves two audiences, and each authenticates on its own path.

* **Member clients** authenticate anonymously through Firebase Auth. They carry no personally identifying information.
* **Operator clients** authenticate through Auth0, scoped to the organization the user belongs to.

The two paths never mix. [Authentication](/api-reference/authentication) explains both.

## Healthcare data on the wire

Clinical resources are modeled in [FHIR R4](https://hl7.org/fhir/R4/) where appropriate. Regional differences such as provider taxonomy, network rules, and routing semantics are resolved per jurisdiction, so the same endpoint behaves correctly across the regions CAIL supports. For background, see [FHIR R4 in CAIL Health](/concepts/fhir-r4-in-cail) and [Jurisdictions](/concepts/jurisdictions).

## The shared contract

Before calling any endpoint, read the three pages that describe behavior common to all of them:

* [Authentication](/api-reference/authentication): the two token paths and how to send a token.
* [Errors](/api-reference/errors): the single error envelope every failure uses.
* [Versioning](/api-reference/versioning): how the API is versioned and what changes are compatible.

Two further references describe contracts shared across endpoints: the [Error envelope](/reference/error-envelope) and [Pagination](/reference/pagination).