Demo API

The demo API 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

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.

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. 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 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.

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