# Public Demo API: synthetic EHR records with no account or API key.

Canonical URL: https://finchnode.com/products/demo-api

> Twelve named synthetic scenarios from two synthetic sources, with no account or API key.

Give an agent or developer one URL. The accountless demo serves twelve named synthetic scenarios from two synthetic sources, Northstar Health System and Quillhaven Medical Group, as platform-shaped records, FHIR R4 resources, a simulated Connect flow, and an MCP endpoint.

## What it is

Built for: Agents and developers building prototypes, tutorials, and automated tests before creating an account.

Base URL: https://api.finchnode.com/demo/v1

Authentication: No account, API key, OAuth flow, or billing method is required, and a GET request works immediately. Every response is synthetic.

**At a glance**

- **Status:** Available
- **Auth:** None
- **Contract:** OpenAPI 3.1
- **Public demo MCP endpoint (no key, synthetic):** `https://api.finchnode.com/demo/mcp`

**Documents for this product**

- [Markdown version of this page](https://finchnode.com/products/demo-api.md)
- [OpenAPI 3.1 document](https://finchnode.com/demo-openapi.json)

## Try it in 30 seconds

**Read a synthetic health record**

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

No account or key. patient-demo-001 is the baseline-adult scenario; https://api.finchnode.com/demo/v1/scenarios lists all twelve.

Expected response: 200 with a platform-shaped synthetic health_record (meta.schemaVersion 2) whose consent and sync metadata are explicitly simulated, with X-FinchNode-Data: synthetic and RateLimit-* response headers.

Synthetic data only. Not for clinical use.

## For coding agents

Three ways in for a coding agent: connect the MCP endpoint below, load the OpenAPI document (https://finchnode.com/demo-openapi.json), or fetch this page as markdown (https://finchnode.com/products/demo-api.md). https://finchnode.com/llms.txt lists every product’s markdown twin.

**Public demo MCP endpoint (no key, synthetic)**

- **MCP endpoint:** `https://api.finchnode.com/demo/mcp`
- **Transport:** Streamable HTTP (JSON-RPC over POST)
- **Auth:** None
- **Clients:** ChatGPT, Codex, Claude, and other MCP clients, with no key
- **MCP Registry name:** com.finchnode/health-records-demo

**Tools at https://api.finchnode.com/demo/mcp**

- list_demo_scenarios
- get_demo_health_record
- get_demo_record
- get_demo_fhir_bundle
- search_demo_fhir
- simulate_demo_connect
- get_demo_demographics
- get_demo_medications
- get_demo_conditions
- get_demo_labs
- get_demo_vitals
- get_demo_allergies
- get_demo_immunizations
- get_demo_encounters

**Claude Code**

```bash
claude mcp add --transport http finchnode-demo https://api.finchnode.com/demo/mcp
```

**Codex CLI**

```bash
codex mcp add finchnode-demo --url https://api.finchnode.com/demo/mcp
```

**Cursor (.cursor/mcp.json)**

```json
{
  "mcpServers": {
    "finchnode-demo": {
      "url": "https://api.finchnode.com/demo/mcp"
    }
  }
}
```

**Claude.ai**

- Where your plan offers custom connectors: on a Free, Pro, or Max plan, open Customize > Connectors, click Add custom connector, enter https://api.finchnode.com/demo/mcp as the remote MCP server URL, and click Add. If the dialog asks how people connect, choose No sign-in: the demo takes no key. Turn the connector on for a chat from the + button, under Connectors.
- Where your plan offers custom connectors: on a Team or Enterprise plan, an Owner adds https://api.finchnode.com/demo/mcp under Organization settings > Connectors (Add, then Custom, then Web if asked), and each member clicks Connect on it under Customize > Connectors.

**ChatGPT**

- Where your plan offers custom connectors: turn on Developer mode under Settings > Security and login, then open ChatGPT Plugins (chatgpt.com/plugins), select the plus button, and create a developer-mode app for the remote MCP server https://api.finchnode.com/demo/mcp with no authentication.
- Where your plan offers custom connectors: in a conversation, choose Developer mode from the Plus menu and select the app you created for https://api.finchnode.com/demo/mcp.

**Machine-readable resources**

- [llms.txt: every FinchNode product and guide for agents](https://finchnode.com/llms.txt)
- [This page as markdown](https://finchnode.com/products/demo-api.md)
- [OpenAPI 3.1 document](https://finchnode.com/demo-openapi.json)

## How it works

1. **Pick a scenario**

   Six record scenarios, four behavior scenarios, and two Connect session outcomes, each with its links, such as patient, records, healthRecord, fhirBundle, fhirSearch, and connect. The exercises and controls fields describe the authenticated sandbox; the accountless demo lists them for reference only and cannot perform them.

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

2. **Read a platform-shaped record**

   The /users/{subject}/records route returns the normalized clinical data shape of the authenticated API, with consent and sync explicitly simulated. The legacy /patients/{patientId}/records route returns category-grouped FHIR resources in a different shape.

   ```bash
   curl 'https://api.finchnode.com/demo/v1/users/patient-demo-polypharmacy/records?categories=medications,conditions'
   ```

3. **Exercise an error path**

   Behavior subjects answer with the production error codes: consent-revoked with 410 consent_inactive, consent-partial with 403 consent_scope_exceeded for categories outside its receipt, and rate-limited with 429 rate_limited and Retry-After in alternating time slots (the demo OpenAPI document gives the slot length). Their record-route responses carry Cache-Control: no-store and X-FinchNode-Scenario.

   ```bash
   curl -i 'https://api.finchnode.com/demo/v1/users/patient-demo-consent-revoked/records'
   ```

4. **Query FHIR R4 resources**

   Search one resource type as a FHIR searchset Bundle, optionally for one scenario subject, or read a whole scenario Bundle.

   ```bash
   curl 'https://api.finchnode.com/demo/v1/fhir/Observation?patient=patient-demo-001'
   ```

5. **Simulate a Connect result**

   The POST response is non-persistent. Add an optional scenario to the body: connect-cancelled and connect-failed end the session cancelled or failed.

   ```bash
   curl -X POST https://api.finchnode.com/demo/v1/connect/sessions -H 'Content-Type: application/json' -d '{"external_user_id":"prototype-user-1","categories":["demographics","labs","medications"]}'
   ```

## Reference

Endpoints

| Method | Path | OpenAPI operationId |
| --- | --- | --- |
| GET | https://api.finchnode.com/demo/v1/ | getDemoIndex |
| GET | https://api.finchnode.com/demo/v1/health | getDemoHealth |
| GET | https://api.finchnode.com/demo/v1/providers | listDemoProviders |
| GET | https://api.finchnode.com/demo/v1/scenarios | listDemoScenarios |
| GET | https://api.finchnode.com/demo/v1/scenarios/{scenarioId} | getDemoScenario |
| POST | https://api.finchnode.com/demo/v1/connect/sessions | createDemoConnectSession |
| GET | https://api.finchnode.com/demo/v1/patients | listDemoPatients |
| GET | https://api.finchnode.com/demo/v1/patients/{patientId} | getDemoPatient |
| GET | https://api.finchnode.com/demo/v1/patients/{patientId}/records | getDemoPatientRecords |
| GET | https://api.finchnode.com/demo/v1/users/{subject}/records | getDemoHealthRecord |
| GET | https://api.finchnode.com/demo/v1/fhir/metadata | getDemoCapabilityStatement |
| GET | https://api.finchnode.com/demo/v1/fhir/{resourceType} | searchDemoFhirResources |
| GET | https://api.finchnode.com/demo/v1/fhir/{resourceType}/{resourceId} | readDemoFhirResource |

## What it does not do

- Synthetic data only: it never accesses production records, real patient accounts, credentials, or vendor sandboxes, and it is not for clinical use.
- Writes are unsupported and Connect sessions are simulated; the REST and MCP services may be reset.
- It is rate limited: the default is 120 requests per minute per IP and running API instance, and behavior-scenario requests are charged to their own per-IP bucket. Follow the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After headers.
- Do not assume shape parity on the legacy /patients/{patientId}/records route: it returns category-grouped FHIR resources that differ from the authenticated envelope.
- It cannot access real patient data. With a FinchNode account, developers get free, self-serve production access to real, patient-authorized records.

## Frequently asked questions

### Do I need an account or API key?

No. No account, API key, OAuth flow, or billing method is required. The route is read-only, CORS-enabled, and rate limited, so a browser prototype can call it without a proxy.

### Which synthetic scenarios can I use?

Record scenarios: baseline-adult (patient-demo-001), polypharmacy-senior, pediatric-asthma, multi-source-overlap, sparse-record, and messy-coding. Behavior scenarios: rate-limited, consent-revoked, consent-partial, and source-unavailable. Session scenarios: connect-cancelled and connect-failed. GET /demo/v1/scenarios describes each one, and list_demo_scenarios returns the same list over MCP. Every scenario is fictional.

### Is FinchNode only a synthetic demo or sandbox?

No. With a FinchNode account, developers get free, self-serve production access to real, patient-authorized records. The public demo cannot access real patient data; real requests require a live key, current patient authorization, and available sources.

### How do the error scenarios behave?

consent-revoked answers 410 consent_inactive, consent-partial answers 403 consent_scope_exceeded for categories outside its receipt, and rate-limited answers 429 rate_limited with Retry-After in alternating time slots, whose length the demo OpenAPI document gives. Their record-route responses carry Cache-Control: no-store.

## Related

- [MCP for Agents](https://finchnode.com/products/mcp.md)
- [Hosted Connect](https://finchnode.com/products/hosted-connect.md)
- [Records API](https://finchnode.com/products/records-api.md)
- [Fetch patient data with a FHIR API: Patient, labs, conditions, and medications.](https://finchnode.com/blog/fhir-api-tutorial-patient-data.md)
- [FHIR API error handling: retries, rate limits, and partial results.](https://finchnode.com/blog/fhir-api-errors-retries-rate-limits.md)