### POST /conformance/runs

Source: https://finchnode.com/docs/api

Starts a conformance run.

```APIDOC
## POST /conformance/runs

### Description
Starts a conformance run.

### Method
POST

### Endpoint
/conformance/runs

### Authentication
Authorization: Bearer $FINCHNODE_API_KEY

### Response
#### Success Response (200)
- **run** (object) - The created conformance run.

#### Error Response
- **error** (object) - Contains type, code, message, and requestId.

```

--------------------------------

### GET /app

Source: https://finchnode.com/docs/api/platform

Resolves the application and environment for the current API key.

```APIDOC
## GET /app

### Description
Resolves the application and environment for the current key.

### Method
GET

### Endpoint
https://api.finchnode.com/api/v1/app

### Response
#### Success Response (200)
Current application.

#### Error Responses
- **401**: API key is missing, invalid, or revoked.
- **429**: Request budget exceeded.
```

--------------------------------

### start_conformance_run

Source: https://finchnode.com/docs/api/mcp-tools

Starts a conformance run. Mirrors the REST endpoint POST /conformance/runs.

```APIDOC
## POST /conformance/runs

### Description
Starts a conformance run.

### Method
POST

### Endpoint
/conformance/runs

```

--------------------------------

### Example simulation session response (JSON)

Source: https://finchnode.com/docs/get-started/quickstart.md

Example JSON response from a completed simulation session. Contains the session ID, status, subject (patient ID), and simulation details. The subject is used to fetch patient records.

```json
{
  "id": "cs_4b2e9d0c7a1f5e3d8c6b",
  "status": "completed",
  "subject": "u_4f3a9c1e2b7d6a05",
  "simulation": { "scenario": "baseline-adult", "state": "completed" }
}
```

--------------------------------

### GET /conformance/runs

Source: https://finchnode.com/docs/api

Lists this application's conformance runs.

```APIDOC
## GET /conformance/runs

### Description
Lists this application's conformance runs.

### Method
GET

### Endpoint
/conformance/runs

### Query Parameters
- **limit** (integer) - Optional - Number of results per page.
- **cursor** (string) - Optional - Pagination cursor.

### Authentication
Authorization: Bearer $FINCHNODE_API_KEY

### Response
#### Success Response (200)
- **runs** (array) - List of conformance runs.
- **hasMore** (boolean) - Indicates if more results exist.
- **nextCursor** (string) - Cursor for next page.

#### Error Response
- **error** (object) - Contains type, code, message, and requestId.

```

--------------------------------

### get_app

Source: https://finchnode.com/docs/api/mcp-tools

Retrieves your application and its environment. Mirrors the REST endpoint GET /app.

```APIDOC
## GET /app

### Description
Returns your application and its environment.

### Method
GET

### Endpoint
/app

```

--------------------------------

### Example medication records response (JSON)

Source: https://finchnode.com/docs/get-started/quickstart.md

Example JSON response for a page of medication records in FinchNode's normalized format. Shows a list object with a single medication record and pagination fields.

```json
{
  "object": "list",
  "category": "medications",
  "data": [
    {
      "id": "rec_a81e05c4c049bf549c1e4fc5",
      "resourceType": "MedicationRequest",
      "name": "Metformin 500 mg tablet",
      "status": "active",
      "startDate": "2026-07-18",
      "source": "northstar-health",
      "sourceName": "Northstar Health System (Synthetic)",
      "codes": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "861007", "display": "Metformin 500 MG Oral Tablet" }]
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

--------------------------------

### create_connect_session

Source: https://finchnode.com/docs/api/mcp-tools

Starts a Connect session. Mirrors the REST endpoint POST /connect/sessions.

```APIDOC
## POST /connect/sessions

### Description
Starts a Connect session.

### Method
POST

### Endpoint
/connect/sessions

```

--------------------------------

### Discovery response example (JSON)

Source: https://finchnode.com/docs/tefca/developer-api.md

Example of the discovery response from the TEFCA Developer API, showing the structure with id, object, status, scenario, categories, matches, documents, results, and failures. This is an abbreviated synthetic example.

```json
{
  "id": "tefca_sim_a808a58f-15f9-4272-b35e-1685721cc757",
  "object": "tefca_session",
  "status": "discovered",
  "scenario": "partial",
  "categories": ["medications", "labs"],
  "matches": [{ "id": "synthetic-match", "source": "Northstar Health System (Synthetic)", "synthetic": true }],
  "documents": [
    { "id": "synthetic-Observation", "title": "Observation records (synthetic)", "resourceType": "Observation", "resourceCount": 18 },
    { "id": "synthetic-DiagnosticReport", "title": "DiagnosticReport records (synthetic)", "resourceType": "DiagnosticReport", "resourceCount": 1 },
    { "id": "synthetic-MedicationRequest", "title": "MedicationRequest records (synthetic)", "resourceType": "MedicationRequest", "resourceCount": 3 },
    { "id": "synthetic-MedicationAdministration", "title": "MedicationAdministration records (synthetic)", "resourceType": "MedicationAdministration", "resourceCount": 1 },
    { "id": "synthetic-MedicationDispense", "title": "MedicationDispense records (synthetic)", "resourceType": "MedicationDispense", "resourceCount": 2 }
  ],
  "results": [],
  "failures": []
}
```

--------------------------------

### GET /connect/sessions/{sessionId}

Source: https://finchnode.com/docs/api/connect

Retrieves a Connect session and its source-sync state. The subject is non-null only after completion.

```APIDOC
## GET /connect/sessions/{sessionId}

### Description
Retrieves a Connect session and its source-sync state. The subject is non-null only after completion.

### Method
GET

### Endpoint
https://api.finchnode.com/api/v1/connect/sessions/{sessionId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The session ID.

### Response
#### Success Response (200)
Current session. Subject is non-null only after completion.

#### Error Responses
- **401**: API key is missing, invalid, or revoked.
- **404**: App-scoped resource does not exist.
- **429**: Request budget exceeded.

```

--------------------------------

### GET /providers

Source: https://finchnode.com/docs/api/demo

Lists fictional sample providers. This endpoint requires no authentication key and returns synthetic providers.

```APIDOC
## GET /providers

### Description
Lists fictional sample providers.

### Method
GET

### Endpoint
https://api.finchnode.com/demo/v1/providers

### Response
#### Success Response (200)
- **200**: Synthetic providers.

#### Error Response (429)
- **429**: rate_limited: the per-IP request limit was reached, or the rate-limited scenario is in a limited slot (then X-FinchNode-Scenario is set). Wait Retry-After seconds. Never publicly cacheable.

```

--------------------------------

### GET /tefca/config

Source: https://finchnode.com/docs/api/sandbox

Reads the synthetic TEFCA configuration. This endpoint is used to retrieve the current configuration, including the consent version required for starting sessions.

```APIDOC
## GET /tefca/config

### Description
Reads the synthetic TEFCA configuration. This endpoint is used to retrieve the current configuration, including the consent version required for starting sessions.

### Method
GET

### Endpoint
https://api.finchnode.com/api/v1/tefca/config

### Parameters
None

### Response
#### Success Response (200)
Synthetic TEFCA workflow response.

#### Error Responses
- **400**: Invalid synthetic input or document selection.
- **401**: API key is missing, invalid, or revoked.
- **403**: Requires an active application sandbox key and categories within its allowlist. Agent and conformance-run credentials are refused.
- **404**: Session not found for this application.
- **409**: Invalid workflow state or concurrent session change. Read the current session before retrying.
- **410**: Session expired or consent revoked.
- **429**: Request budget exceeded.
- **503**: TEFCA API sandbox storage is not available on this deployment.
```

--------------------------------

### Start a conformance run with curl

Source: https://finchnode.com/docs/testing/conformance.md

Starts a conformance run against your sandbox application. Requires a sandbox key and a separate application in sandbox status. The response holds `run_key`, a sandbox key for your application; save it to a private temporary file outside your repository and keep it out of logs and transcripts. `mktemp` creates the file readable only by you, and `jq -e` fails if there's no key, so a failed request never writes `null` in its place.

```bash
RUN_KEY_FILE=$(mktemp)
RESPONSE=$(curl -s --fail-with-body -X POST "https://api.finchnode.com/api/v1/conformance/runs" \
  -H "Authorization: Bearer $FINCHNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario": "polypharmacy-senior"}') &&
  printf '%s' "$RESPONSE" | jq -er .run_key > "$RUN_KEY_FILE" &&
  printf '%s' "$RESPONSE" | jq '{id, status, phase, links}' ||
  printf '%s' "$RESPONSE" | jq .error
```

--------------------------------

### Export response example (JSON)

Source: https://finchnode.com/docs/tefca/developer-api.md

Example of the export response from the TEFCA Developer API, showing the structure with object, sessionId, mode, synthetic, status, consent, categories, failures, and bundle. This is an abbreviated synthetic example.

```json
{
  "object": "tefca_export",
  "sessionId": "tefca_sim_a808a58f-15f9-4272-b35e-1685721cc757",
  "mode": "simulation",
  "synthetic": true,
  "status": "partial",
  "consent": { "version": "tefca-simulation-2026-09-09", "grantedAt": "2026-10-01T19:26:46.104Z", "revokedAt": null },
  "categories": ["medications", "labs"],
  "failures": [
    { "documentId": "synthetic-DiagnosticReport", "code": "simulated_retrieval_failure", "message": "This document is unavailable in the partial-results scenario." }
  ],
  "bundle": { "resourceType": "Bundle", "type": "collection", "entry": ["..."] }
}
```

--------------------------------

### Run complete backend example (Node.js)

Source: https://finchnode.com/docs/tefca/developer-api.md

Save as tefca-demo.mjs and run with Node 24 and FINCHNODE_API_KEY set. Requires a sandbox key (ck_test_) and sends requests to https://api.finchnode.com/api/v1/tefca. The synthetic consent acceptance applies only to this fictional demonstration.

```javascript
const base = 'https://api.finchnode.com/api/v1/tefca';
const key = process.env.FINCHNODE_API_KEY;
if (!key?.startsWith('ck_test_')) throw new Error('Set a sandbox FINCHNODE_API_KEY.');
async function request(path, body) {
  const response = await fetch(base + path, {
    method: body === undefined ? 'GET' : 'POST',
    redirect: 'error', signal: AbortSignal.timeout(15000),
    headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${result.error?.message}`);
  return result;
}
const config = await request('/config');
const session = await request('/sessions', {
  mode: 'simulation', patientId: config.patientId,
  consent: true, consentVersion: config.consentVersion,
  scenario: 'matched', categories: ['medications', 'labs'],
});
try {
  const found = await request(`/sessions/${session.id}/discover`, {});
  if (!found.documents.length) {
    console.log('No records:', found.status, found.failures);
  } else {
    const retrieved = await request(`/sessions/${session.id}/retrieve`, {
      documentIds: found.documents.map(document => document.id),
    });
    if (retrieved.results.length) {
      const exported = await request(`/sessions/${session.id}/export`);
      console.log(JSON.stringify(exported.bundle, null, 2));
    }
    console.log('Document failures:', retrieved.failures);
  }
} finally {
  await request(`/sessions/${session.id}/revoke`, {});
}
```

--------------------------------

### GET /

Source: https://finchnode.com/docs/api/demo

Returns the Demo API index. This endpoint is used to discover the public demo API and requires no authentication key.

```APIDOC
## GET /

### Description
Returns the Demo API index.

### Method
GET

### Endpoint
https://api.finchnode.com/demo/v1/

### Response
#### Success Response (200)
- **200**: Demo API index.

#### Error Response (429)
- **429**: rate_limited: the per-IP request limit was reached, or the rate-limited scenario is in a limited slot (then X-FinchNode-Scenario is set). Wait Retry-After seconds. Never publicly cacheable.

```

--------------------------------

### GET /conformance/runs/{runId}

Source: https://finchnode.com/docs/api/conformance

Retrieves a conformance run, including the live phase, each check with its evidence (counts, timings, and status codes), and, once the run ends, its verdict. Requires a sandbox key.

```APIDOC
## GET /conformance/runs/{runId}

### Description
Retrieves a conformance run, including the live phase, each check with its evidence (counts, timings, and status codes), and, once the run ends, its verdict. Requires a sandbox key.

### Method
GET

### Endpoint
https://api.finchnode.com/api/v1/conformance/runs/{runId}

### Parameters
#### Path Parameters
- **runId** (string) - Required - The ID of the conformance run.

### Response
#### Success Response (200)
The run, without its run key.

#### Error Responses
- **401** - API key is missing, invalid, or revoked.
- **403** - App scope, environment, or consent does not authorize the request.
- **404** - App-scoped resource does not exist.
- **429** - Request budget exceeded.
- **503** - conformance_unavailable: conformance runs are not available on this deployment yet. Retry later; nothing was changed.
```

--------------------------------

### GET /conformance/reports/{token}

Source: https://finchnode.com/docs/api

Reads a conformance report.

```APIDOC
## GET /conformance/reports/{token}

### Description
Reads a conformance report.

### Method
GET

### Endpoint
/conformance/reports/{token}

### Path Parameters
- **token** (string) - Required - The report token.

### Authentication
Authorization: Bearer $FINCHNODE_API_KEY

### Response
#### Success Response (200)
- **report** (object) - The conformance report.

#### Error Response
- **error** (object) - Contains type, code, message, and requestId.

```

--------------------------------

### GET /consents/{receiptId}

Source: https://finchnode.com/docs/api

Retrieves a consent receipt and current status.

```APIDOC
## GET /consents/{receiptId}

### Description
Retrieves a consent receipt and current status.

### Method
GET

### Endpoint
/consents/{receiptId}

### Path Parameters
- **receiptId** (string) - Required - The consent receipt ID.

### Authentication
Authorization: Bearer $FINCHNODE_API_KEY

### Response
#### Success Response (200)
- **receipt** (object) - The consent receipt.
- **status** (string) - Current status.

#### Error Response
- **error** (object) - Contains type, code, message, and requestId.

```

--------------------------------

### POST /connect/sessions

Source: https://finchnode.com/docs/api/connect

Creates a hosted Connect session. Categories must be a subset of the app allowlist. Reusing an Idempotency-Key with the same body returns the original session and an Idempotent-Replayed header; reusing with a different body returns idempotency_conflict.

```APIDOC
## POST /connect/sessions

### Description
Creates a hosted Connect session. Categories must be a subset of the app allowlist. Reusing an Idempotency-Key with the same body returns the original session and an Idempotent-Replayed header; reusing with a different body returns idempotency_conflict.

### Method
POST

### Endpoint
https://api.finchnode.com/api/v1/connect/sessions

### Parameters
#### Header Parameters
- **Idempotency-Key** (string) - Required - App- and environment-scoped retry key.

#### Request Body
- **externalId** (string) - Required - Opaque caller reference. Do not place email, name, or health information here.
- **categories** (string[]) - Required - List of categories.
- **syncMode** (string) - Required - Sync mode.
- **durationDays** (integer) - Required - Duration in days.
- **returnUrl** (string) - Required - Return URL.

### Request Example
{
  "externalId": "string",
  "categories": ["string"],
  "syncMode": "string",
  "durationDays": 0,
  "returnUrl": "string"
}

### Response
#### Success Response (201)
Session created or idempotently recovered.

#### Error Responses
- **400**: Request validation failed.
- **401**: API key is missing, invalid, or revoked.
- **403**: App scope, environment, or consent does not authorize the request.
- **409**: Request conflicts with resource state or idempotency history.
- **413**: Request body exceeds 64 KiB.
- **429**: Request budget exceeded.

```

--------------------------------

### simulate_connect_session

Source: https://finchnode.com/docs/api/mcp-tools

Completes a sandbox session with a scenario. Mirrors the REST endpoint POST /connect/sessions/{sessionId}/simulate.

```APIDOC
## POST /connect/sessions/{sessionId}/simulate

### Description
Completes a sandbox Connect session with a scenario.

### Method
POST

### Endpoint
/connect/sessions/{sessionId}/simulate

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The Connect session identifier.

```

--------------------------------

### GET /health

Source: https://finchnode.com/docs/api/platform

Checks API availability. Does not require an API key.

```APIDOC
## GET /health

### Description
Checks API availability. No key required.

### Method
GET

### Endpoint
https://api.finchnode.com/api/v1/health

### Response
#### Success Response (200)
API is available.
```

--------------------------------

### Retry GET requests with backoff and Retry-After handling

Source: https://finchnode.com/docs/resources/rate-limits.md

Retry helper for GET requests that handles 429, 5xx, and network errors, honoring the Retry-After header. Use for reads only; do not retry POST /connect/sessions without the same Idempotency-Key and body, and avoid blind retries of sandbox controls or other 4xx responses.

```javascript
// For GET requests. Retries 429, 5xx, and network errors, and honors Retry-After.
async function getWithRetry(url, headers, attempts = 5) {
  for (let attempt = 1; ; attempt += 1) {
    const res = await fetch(url, { headers, signal: AbortSignal.timeout(30_000) }).catch((error) => error);
    const failed = res instanceof Error || res.status === 429 || res.status >= 500;
    if (!failed) return res;
    if (attempt === attempts) {
      if (res instanceof Error) throw res;
      return res;
    }
    const retryAfter = res instanceof Error ? 0 : Number(res.headers.get('Retry-After')) || 0;
    const backoff = Math.min(30, 2 ** attempt) + Math.random();
    await new Promise((resolve) => setTimeout(resolve, Math.max(retryAfter, backoff) * 1000));
  }
}
```

```python
import random
import time

import requests

def get_with_retry(url, headers, attempts=5):
    """For GET requests. Retries 429, 5xx, and network errors, and honors Retry-After."""
    for attempt in range(1, attempts + 1):
        try:
            res = requests.get(url, headers=headers, timeout=30)
        except requests.RequestException:
            if attempt == attempts:
                raise
            res = None
        if res is not None:
            retryable = res.status_code == 429 or res.status_code >= 500
            if not retryable or attempt == attempts:
                return res
        retry_after = float(res.headers.get("Retry-After", 0) or 0) if res is not None else 0
        time.sleep(max(retry_after, min(30, 2 ** attempt) + random.random()))
```

--------------------------------

### POST /connect/sessions

Source: https://finchnode.com/docs/api

Creates a Hosted Connect session.

```APIDOC
## POST /connect/sessions

### Description
Creates a Hosted Connect session.

### Method
POST

### Endpoint
/connect/sessions

### Headers
- **Idempotency-Key** (string) - Optional - Up to 200 characters, scoped to your application and environment.

### Authentication
Authorization: Bearer $FINCHNODE_API_KEY

### Response
#### Success Response (200)
- **session** (object) - The created Connect session.

#### Error Response
- **error** (object) - Contains type, code, message, and requestId.

```

--------------------------------

### Create a Connect session with cURL

Source: https://finchnode.com/docs/get-started/quickstart.md

POSTs to `/api/v1/connect/sessions` to create a Connect session. Both fields are optional; `categories` must be on your application's list. Returns a `201` with the session object.

```bash
curl -X POST "https://api.finchnode.com/api/v1/connect/sessions" \
  -H "Authorization: Bearer $FINCHNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "user_123", "categories": ["medications", "labs"]}'

```

--------------------------------

### Create a Connect session with curl

Source: https://finchnode.com/docs/connect/create-a-session.md

Sends a POST request to create a Connect session. Requires an API key and an Idempotency-Key. The response is 201 with the session and its url. Store the session id and send the patient to the url.

```bash
curl -X POST "https://api.finchnode.com/api/v1/connect/sessions" \
  -H "Authorization: Bearer $FINCHNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-user_123-1" \
  -d '{
    "externalId": "user_123",
    "categories": ["medications", "labs", "allergies"],
    "returnUrl": "https://example.com/connected"
  }'
```

--------------------------------

### get_conformance_run

Source: https://finchnode.com/docs/api/mcp-tools

Retrieves run state and checks. Mirrors the REST endpoint GET /conformance/runs/{runId}.

```APIDOC
## GET /conformance/runs/{runId}

### Description
Returns run state and checks.

### Method
GET

### Endpoint
/conformance/runs/{runId}

### Parameters
#### Path Parameters
- **runId** (string) - Required - The conformance run identifier.

```

--------------------------------

### Create a Connect session with Node.js

Source: https://finchnode.com/docs/get-started/quickstart.md

Uses `fetch` to POST to `/api/v1/connect/sessions`. Throws an error if the response is not OK. The session object is stored in `session`.

```javascript
const response = await fetch('https://api.finchnode.com/api/v1/connect/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FINCHNODE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ externalId: 'user_123', categories: ['medications', 'labs'] }),
});
if (!response.ok) throw new Error(`FinchNode returned ${response.status}`);
const session = await response.json();

```

--------------------------------

### get_connect_session

Source: https://finchnode.com/docs/api/mcp-tools

Retrieves session status and subject. Mirrors the REST endpoint GET /connect/sessions/{sessionId}.

```APIDOC
## GET /connect/sessions/{sessionId}

### Description
Returns session status and subject.

### Method
GET

### Endpoint
/connect/sessions/{sessionId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The Connect session identifier.

```

--------------------------------

### Call demo MCP tool with curl

Source: https://finchnode.com/docs/ai-agents/mcp-server.md

Sends a JSON-RPC tools/call request to the demo MCP server. No session is needed. This example calls get_demo_health_record with scenario 'polypharmacy-senior' and categories ['medications'].

```bash
curl https://api.finchnode.com/demo/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_demo_health_record", "arguments": {"scenario": "polypharmacy-senior", "categories": ["medications"]}}}'
```

--------------------------------

### get_consent_receipt

Source: https://finchnode.com/docs/api/mcp-tools

Retrieves one consent receipt. Mirrors the REST endpoint GET /consents/{receiptId}.

```APIDOC
## GET /consents/{receiptId}

### Description
Returns one consent receipt.

### Method
GET

### Endpoint
/consents/{receiptId}

### Parameters
#### Path Parameters
- **receiptId** (string) - Required - The consent receipt identifier.

```