Production access is free and self-serve with an account. · Synthetic demo · no account needed
Sandbox
Named synthetic patients and deterministic failure cases, on the public demo and inside your sandbox.
Named synthetic scenarios, from ordinary records to consent, rate-limit, and source failures. On the public demo, their records, FHIR resources, and MCP tools answer with no account or key. In your sandbox, a sandbox key completes a Connect session with a record or behavior scenario’s synthetic patient, which goes through the same consent, import, completion, receipts, webhooks, record reads, and change feed as a real one, and the sandbox controls then advance its records, end its consent, or fail its source.
Built for: Developers and agents testing an integration against deterministic synthetic patients and failure cases before a real patient connects.
Base URL: https://api.finchnode.com/demo/v1 (public demo, no key) and https://api.finchnode.com/api/v1 (simulation and controls, sandbox key)
Authentication: The public demo (https://api.finchnode.com/demo/v1 and https://api.finchnode.com/demo/mcp) takes no account or key and serves synthetic data only. Simulation and the sandbox controls, on https://api.finchnode.com/api/v1 and https://api.finchnode.com/api/mcp, take a sandbox key as a Bearer token from your backend: Authorization: Bearer ck_test_... A live key (ck_live_...) receives 403 sandbox_only. Keys are hashed at rest, revocable, and must never be embedded in browser or mobile code.
Create a free account to get sandbox keys: https://finchnode.com/signup
https://api.finchnode.com/demo/mcphttps://api.finchnode.com/api/mcpcurl https://api.finchnode.com/demo/v1/scenariosNo account or key. Each entry names the scenario’s id, kind, subject, what it exercises, and the sandbox controls it supports, with links to its demo routes.
Expected response: 200 with a list of demo_scenario objects: id, kind, title, summary, subject, sources, categories, exercises, controls, the behavior or session outcome, and links. No clinical data.
Synthetic data only. Not for clinical use.
Three ways in for a coding agent: connect the MCP endpoints below, load the OpenAPI document (https://finchnode.com/openapi.yaml), or fetch this page as markdown (https://finchnode.com/products/scenario-sandbox.md). https://finchnode.com/llms.txt lists every product’s markdown twin.
https://api.finchnode.com/demo/mcpclaude mcp add --transport http finchnode-demo https://api.finchnode.com/demo/mcpcodex mcp add finchnode-demo --url https://api.finchnode.com/demo/mcp{
"mcpServers": {
"finchnode-demo": {
"url": "https://api.finchnode.com/demo/mcp"
}
}
}https://api.finchnode.com/api/mcpexport FINCHNODE_API_KEY=ck_test_...claude mcp add --scope project --transport http finchnode https://api.finchnode.com/api/mcp --header 'Authorization: Bearer ${FINCHNODE_API_KEY}'Claude Code writes this server to the project's .mcp.json, which is meant to be checked into version control and shared with the project, and expands ${FINCHNODE_API_KEY} when it connects, so the file never holds the key: set FINCHNODE_API_KEY in the shell that runs Claude Code.
codex mcp add finchnode --url https://api.finchnode.com/api/mcp --bearer-token-env-var FINCHNODE_API_KEY{
"mcpServers": {
"finchnode": {
"url": "https://api.finchnode.com/api/mcp",
"headers": {
"Authorization": "Bearer ${env:FINCHNODE_API_KEY}"
}
}
}
}Every scenario has an id and a kind, and record and behavior scenarios have a subject. GET /scenarios/{scenarioId} returns one entry. Its exercises and controls fields describe the authenticated sandbox; the public demo lists them for reference.
curl https://api.finchnode.com/demo/v1/scenarios/polypharmacy-seniorRead a subject’s records with no key. A behavior subject answers with the production codes: patient-demo-rate-limited answers 429 rate_limited with Retry-After in alternating time slots, so a client that waits the stated seconds succeeds on its next attempt. The demo OpenAPI document gives the slot length.
curl 'https://api.finchnode.com/demo/v1/users/patient-demo-rate-limited/records'With a sandbox key, create a sandbox Connect session (POST https://api.finchnode.com/api/v1/connect/sessions; the body is optional, so the bare first request below works); its id is SESSION_ID. A session from the public demo cannot be simulated. Then complete the session with a scenario’s synthetic patient instead of sending a person to the hosted page. The response is 202 with the session and its simulation. Repeating the request with the same scenario resumes the simulation and never creates a second patient. A session scenario returns 400 invalid_scenario, and a scenario whose consent covers none of the session’s categories returns 400 invalid_categories. A session that is no longer pending or has expired, already has a patient, or was simulated with another scenario returns 409 session_not_simulatable: use a new session for each simulation.
curl -X POST "https://api.finchnode.com/api/v1/connect/sessions" -H "Authorization: Bearer $FINCHNODE_API_KEY"
curl -X POST https://api.finchnode.com/api/v1/connect/sessions/$SESSION_ID/simulate -H "Authorization: Bearer $FINCHNODE_API_KEY" -H "Content-Type: application/json" -d '{"scenario":"polypharmacy-senior"}'Poll GET /connect/sessions/{sessionId} until simulation.state is completed or failed. Poll simulation.state rather than status: for the two-source scenarios and consent-revoked, status reads completed first. Once simulation.state is completed, the session exposes the synthetic patient’s app-scoped subject (its id is SUBJECT). Read its records and receipts as for any other user; its webhooks reach your application’s webhook URL as a real patient’s do.
curl "https://api.finchnode.com/api/v1/users/$SUBJECT/records" -H "Authorization: Bearer $FINCHNODE_API_KEY"POST /sandbox/subjects/{subject}/events with a control the scenario lists. records.advance imports the scenario’s new and changed records into the change feed (records.updated for continuous consent), consent.revoke and consent.expire end the consent (consent.revoked, consent.expired), and source.fail makes the next import fail (sync.failed for continuous consent). The response is 202; a control the scenario does not list returns 409 control_unsupported, and records.advance or source.fail for a user whose source is not connected yet returns 409 subject_not_connected.
curl -X POST https://api.finchnode.com/api/v1/sandbox/subjects/$SUBJECT/events -H "Authorization: Bearer $FINCHNODE_API_KEY" -H "Content-Type: application/json" -d '{"type":"records.advance"}'| Scenario | Kind | What it exercises | Controls |
|---|---|---|---|
| Baseline adult, age 38 | record | the default record every quickstart uses; one source, one encounter, no pagination | records.advance, consent.revoke, consent.expire, source.fail |
| Polypharmacy, age 78 | record | cursor pagination past 25 records in medications and labs; MedicationDispense alongside MedicationRequest; reference ranges on every lab; a record change that removes a medication | records.advance, consent.revoke, consent.expire, source.fail |
| Pediatric asthma, age 9 | record | immunization schedules with repeated vaccine codes; growth vitals as time series; pediatric dosing text | records.advance, consent.revoke, consent.expire, source.fail |
| Two sources with overlapping records, age 40 | record | source attribution on every record; deduplication of the same code across sources; a unit difference on the same lab (mIU/L vs uIU/mL); conflicting allergy statements between sources | records.advance, consent.revoke, consent.expire, source.fail |
| Sparse record, age 30 | record | missingCategories in the envelope; empty category pages with hasMore false; a record change that adds the first vital sign | records.advance, consent.revoke, consent.expire, source.fail |
| Messy coding, age 63 | record | medications with text but no coding; observations with no value or a coded value; zero reference-range bounds; ICD-10-CM without SNOMED; non-default units | records.advance, consent.revoke, consent.expire, source.fail |
| Rate limited reads | behavior | honoring Retry-After; bounded retries; RateLimit headers | consent.revoke, consent.expire, source.fail |
| Consent revoked | behavior | failing closed on 410; not retrying a revoked subject | consent.revoke, consent.expire, source.fail |
| Partial consent | behavior | reading consent.receipts before requesting categories; handling 403 consent_scope_exceeded | consent.revoke, consent.expire, source.fail |
| One source unavailable | behavior | meta.syncStatus partial; per-source lastSyncedAt; a source_unavailable warning in meta.warnings | consent.revoke, consent.expire, source.fail |
| Connect session cancelled | session | cancelled session state; no subject on incomplete sessions | none |
| Connect session failed | session | failed session state; failure_code handling; offering the user a retry | none |
Scenario ids: record scenarios baseline-adult, polypharmacy-senior, pediatric-asthma, multi-source-overlap, sparse-record, messy-coding; behavior scenarios rate-limited, consent-revoked, consent-partial, source-unavailable; session scenarios connect-cancelled, connect-failed. Record and behavior scenarios run on the public demo and simulate in your sandbox. Session scenarios run only in the public demo, where they end its simulated Connect session cancelled or failed.
Simulated in your sandbox, consent-partial grants only medications and allergies, consent-revoked revokes consent right after the session completes, and source-unavailable leaves its second source failing every later import. The timed 429 responses of rate-limited exist only in the public demo; simulated, it is an ordinary small record.
The demo routes on https://api.finchnode.com/demo/v1 take no key; the https://api.finchnode.com/api/v1 routes take sandbox keys. Create the session you simulate on https://api.finchnode.com/api/v1: a demo session cannot be simulated. Each row names its full URL.
| Method | Path | OpenAPI operationId |
|---|---|---|
| GET | https://api.finchnode.com/demo/v1/scenarios | listDemoScenarios |
| GET | https://api.finchnode.com/demo/v1/scenarios/{scenarioId} | getDemoScenario |
| GET | https://api.finchnode.com/demo/v1/users/{subject}/records | getDemoHealthRecord |
| POST | https://api.finchnode.com/demo/v1/connect/sessions | createDemoConnectSession |
| POST | https://api.finchnode.com/api/v1/connect/sessions | createConnectSession |
| POST | https://api.finchnode.com/api/v1/connect/sessions/{sessionId}/simulate | simulateConnectSession |
| POST | https://api.finchnode.com/api/v1/sandbox/subjects/{subject}/events | triggerSandboxEvent |
| Tool | Endpoint |
|---|---|
| list_demo_scenarios | https://api.finchnode.com/demo/mcp (no key) |
| get_demo_health_record | https://api.finchnode.com/demo/mcp (no key) |
| search_demo_fhir | https://api.finchnode.com/demo/mcp (no key) |
| simulate_demo_connect | https://api.finchnode.com/demo/mcp (no key) |
| simulate_connect_session | https://api.finchnode.com/api/mcp (sandbox keys) |
| trigger_sandbox_event | https://api.finchnode.com/api/mcp (sandbox keys) |
Yes. Each scenario’s records come from one fixed synthetic Bundle, so a scenario always starts from the same fictional data, and records.advance applies one fixed set of changes. On the public demo, rate-limited alternates fixed time slots: reads answer 429 rate_limited with Retry-After in one slot and succeed in the next, so a client that waits the stated seconds succeeds on its next attempt. The demo OpenAPI document gives the slot length.
Two connected sources that each synced once, of which Quillhaven Medical Group (Synthetic) now fails every sync. Reads report meta.syncStatus partial, a source_unavailable warning in meta.warnings, and an older lastSyncedAt for that source. Simulated in your sandbox, it connects both sources and leaves the second failing every later import, so its reads report the partial status from the moment simulation.state is completed.
The public demo takes no account or key; its Connect sessions are simulated and non-persistent, and it cannot perform the sandbox controls. The sandbox takes a sandbox key: simulate completes one of your application’s sandbox Connect sessions with the scenario’s synthetic patient, through the same consent, import, completion, receipts, webhooks, record reads, and change feed as a real patient, and the sandbox controls then advance its records, revoke or expire its consent, or fail its source.
Yes. The hosted Connect page of a sandbox session lists the FinchNode Scenario Sandbox organizations above its search, and choosing one connects without a hospital sign-in; the account and consent steps are unchanged. Production sessions never list them. The sandbox controls act only on patients created by simulate, not on the account a person used.