# Demo API

> Call fictional patient records with no key and no account.

The [demo API](/docs/resources/glossary#demo) serves fictional patients from two synthetic health systems. Use it to prototype, write tests, or let a coding agent explore. Demo sessions and request bodies aren't kept; the service records usage metadata such as client type, scenario, and a hashed caller ID.

## Make your first call

```bash
curl "https://api.finchnode.com/demo/v1/users/patient-demo-001/records?categories=medications,labs"
```

You get a synthetic record in FinchNode's normalized format. It has the same structure as the sandbox and production API, with demo IDs and simulated consent and sync values. `patient-demo-001` is the default `baseline-adult` scenario.

## Pick a scenario

`GET /scenarios` lists the named scenarios. Record scenarios cover different patients, such as a senior on many medications or a sparse record. Behavior scenarios return a scripted error or a partial result, so you can test your error handling.

```bash
curl "https://api.finchnode.com/demo/v1/scenarios"
```

Record and behavior scenarios name a `subject`; pass it to `/users/{subject}/records`. That endpoint takes only `categories`: the demo has no pagination or change feed.

## Endpoints

| Endpoint | Returns |
| --- | --- |
| `GET /users/{subject}/records` | A normalized record, shaped like the authenticated API |
| `GET /fhir/{resourceType}` | FHIR R4 resources of one type for `baseline-adult`; add `?patient={subject}` for another scenario |
| `GET /fhir/metadata` | The sample FHIR capability statement |
| `POST /connect/sessions` | A Connect session that finishes in the response: `complete`, or `cancelled` or `failed` for the session scenarios |
| `GET /patients/{patientId}/records` | The older category-grouped format, with 8 categories |

The full list is in the [demo API reference](/docs/api/demo). The OpenAPI document is at `https://api.finchnode.com/demo/v1/openapi.json`.

## Use it from an AI agent

The demo also runs as an MCP server at `https://api.finchnode.com/demo/mcp`, with no key. Start with the `list_demo_scenarios` tool. See [MCP server](/docs/ai-agents/mcp-server) for client setup.

## Limits

By default each network address gets 120 requests a minute, with a separate budget for behavior scenarios. A `429` means wait and retry.

## Moving to the sandbox

The demo takes shortcuts the sandbox and production API don't. When you switch to a `ck_test_` key, change these:

| Demo | Sandbox |
| --- | --- |
| `external_user_id` | `externalId` |
| `connect_url` | `url` |
| `patient_id` | `subject` |
| `created_at`, `expires_at` | `createdAt`, `expiresAt` |
| `status: "complete"` | `status: "completed"` |
| `status: "cancelled"` | `status: "canceled"` |
| `scenario` in the session request | `POST /connect/sessions/{sessionId}/simulate` |
| Completes in the response | Completes later; poll `simulation.state` or use webhooks |

In production there is no `simulate`: the patient completes the session in their browser, and you learn the outcome from webhooks or the session. See [After the patient connects](/docs/connect/after-the-patient-connects).

The two session scenarios, `connect-cancelled` and `connect-failed`, exist only in the demo.