### Install Medblocks SDK

Source: https://medblocks.com/docs/patient-access/quickstart

Install the package using your preferred package manager.

```bash
npm install medblocks
```

```bash
pnpm add medblocks
```

```bash
yarn add medblocks
```

```bash
bun add medblocks
```

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

### Start the Development Server

Source: https://medblocks.com/docs/patient-access/quickstart

Commands to launch the server using Bun or Node.js.

```bash
bun run src/server.ts
```

```bash
node --env-file=.env --import tsx src/server.ts
```

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

### Install Medblocks skills for AI agents

Source: https://medblocks.com/docs/build-with-ai

Commands to install Medblocks skills for various AI coding agents. These skills guide agents on integration flows and security rules.

```bash
# Adds the Medblocks marketplace, then installs the skills as a plugin with automatic updates
claude plugin marketplace add medblocks/skills
claude plugin install medblocks-skills@medblocks
```

```bash
# Installs the skills to .agents/skills in your repo, which Codex reads natively
npx skills add medblocks/skills -a codex
```

```bash
# Installs the skills to .agents/skills in your repo, which Cursor reads natively
npx skills add medblocks/skills -a cursor
```

```bash
# One command installs the skills for every agent the skills CLI supports
npx skills add medblocks/skills
```

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

### GET /launch-contexts/{id}

Source: https://medblocks.com/docs/reference/api/retrieve-launch-context

Resolves the mb_launch handle into the patient, encounter, practitioner, or EHR context.

```APIDOC
## GET /launch-contexts/{id}

### Description
Resolve the mb_launch handle (appended to your app's launch URL after an EHR launch) into the patient / encounter / practitioner / EHR the app was launched in.

### Method
GET

### Endpoint
/launch-contexts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The mb_launch handle identifier.
```

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

### Handle Success and Failure Return URLs

Source: https://medblocks.com/docs/patient-access/create-patient-session/your-own-ui

These examples show the structure of return URLs for successful and failed connection attempts.

```text
https://app.example.com/connected?patient_id=user_42&patient_session_id=ps_...&success=true&connection_id=fhirsrc_...
```

```text
https://app.example.com/connected?patient_id=user_42&patient_session_id=ps_...&success=false&error=user_denied&error_description=Patient+canceled+the+connection
```

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

### Example connection response item

Source: https://medblocks.com/docs/patient-access/find-connections

A JSON object representing a single connection result from the API.

```json
{
  "id": "fhirsrc_01J9YR9N3X4VZ6P2K5RH7M3LMP",
  "name": "Epic MyChart",
  "type": "epic",
  "fhir_base_url": "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
  "logo_url": "https://cdn.medblocks.com/logos/epic.png",
  "portal_url": "https://www.mychart.com"
}
```

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

### POST /patient-sessions

Source: https://medblocks.com/docs/reference/api/init-patient-session

Starts a new patient session and returns a URL for the patient to connect their records.

```APIDOC
## POST /patient-sessions

### Description
Start a patient session and get back a url to send the patient to so they can connect their records. Track progress with the session's status.

### Method
POST

### Endpoint
/patient-sessions
```

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

### Serve JWKS with Node.js and Express

Source: https://medblocks.com/docs/patient-access/athena

This example demonstrates how to derive a public JWK from a private key and serve it via an Express route. Ensure the JWK includes the required 'alg' and 'use' fields.

```javascript
import { createPrivateKey } from "crypto";
import { exportJWK, calculateJwkThumbprint } from "jose";
import { readFileSync } from "fs";
import express from "express";

const app = express();
const privateKeyPem = readFileSync("privatekey.pem", "utf-8");
const privateKey = createPrivateKey(privateKeyPem);

// Derive the public JWK from the private key
const publicJwk = await exportJWK(privateKey.export({ type: "spki", format: "pem" }));
publicJwk.alg = "RS384";
publicJwk.use = "sig";
publicJwk.kid = await calculateJwkThumbprint(publicJwk, "sha256");

app.get("/.well-known/jwks.json", (req, res) => {
  res.json({ keys: [publicJwk] });
});

app.listen(3000, () => console.log("Listening on port 3000"));
```

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

### Start Patient Session

Source: https://medblocks.com/docs/patient-access/quickstart

Initiate a session and redirect the user to the Medblocks authorization page.

```typescript
import { mb } from "./medblocks";

/**
 * GET /start — open a patient session and redirect the patient's browser to the
 * Medblocks-hosted page. No frontend: the redirect is the whole integration.
 */
export async function initPatientSession(_req: Request): Promise<Response> {
  const session = await mb.patientSession.init({
    patient_id: "demo-patient",
    return_url: "http://localhost:3000/connected",
    return_button_label: "Back to Acme Health",
  });

  return Response.redirect(session.url, 302);
}
```

```typescript
import type { Request, Response } from "express";
import { mb } from "./medblocks";

/**
 * GET /start — open a patient session and redirect the patient to the
 * Medblocks-hosted page. No frontend: the redirect is the whole integration.
 */
export async function initPatientSession(_req: Request, res: Response) {
  const session = await mb.patientSession.init({
    patient_id: "demo-patient",
    return_url: "http://localhost:3000/connected",
    return_button_label: "Back to Acme Health",
  });

  res.redirect(session.url);
}
```

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

### Initialize Patient Session (TypeScript)

Source: https://medblocks.com/docs/patient-access/create-patients

Starts a patient session, creating the patient if they do not exist or updating their details if they do.

```ts
const session = await mb.patientSession.init({
  patient_id: "user_42",
  return_url: "https://your-app.example.com/connected",
});
```

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

### Client ID Format

Source: https://medblocks.com/docs/patient-access/cerner

Example of the UUID format for the Cerner Client ID.

```text
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

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

### Handling Medblocks Errors

Source: https://medblocks.com/docs/patient-access/errors

Example of how to catch and handle typed errors thrown by the SDK.

```APIDOC
## Handling Medblocks Errors

### Description
Every failed request throws a typed error that extends `MedblocksError`. Developers should use `instanceof` to branch on specific error types and handle them accordingly.

### Usage Example
```ts
import { MedblocksError } from "medblocks";

try {
  const session = await mb.patientSession.init(input);
} catch (err) {
  if (err instanceof MedblocksError) {
    // every API error lands here, typed
    console.error(err.code, err.requestId);
  }
  throw err;
}
```
```

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

### Handle feature_not_enabled error response

Source: https://medblocks.com/docs/billing

Example JSON response when a requested feature is not included in the current workspace plan.

```json
{
  "error": {
    "type": "billing_error",
    "code": "feature_not_enabled",
    "message": "This feature isn't part of your plan. Contact support to enable it.",
    "param": null,
    "doc_url": "https://docs.medblocks.com/errors/feature_not_enabled",
    "request_id": "9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d"
  }
}
```

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

### View Retrieved FHIR Resources

Source: https://medblocks.com/docs/patient-access/quickstart

Example output showing the list of FHIR resources retrieved after a successful patient connection.

```text
Found 58 resources
Patient/eq081-VQEgP8drUUqCWzHfw3
Observation/ejPFhUXYm7Bnv7yiCQnKsA3
Condition/e-Y7RyVDLDdLdRhU5N35rBQ3
...
```

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

### Handle patient_session.completed Event

Source: https://medblocks.com/docs/webhooks/events

Example of processing the patient_session.completed event using the WebhookEvent type for discrimination.

```ts
import type { WebhookEvent } from "medblocks";

function handle(event: WebhookEvent) {
  if (event.type !== "patient_session.completed") return;
  const flow = event.data.object;

  const active = flow.connections.filter((c) => c.status === "active");
  const failed = flow.connections.filter((c) => c.status === "failed");

  console.log(`patient ${flow.patient_id}: ${active.length} active, ${failed.length} failed`);
}
```

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

### Start a patient session

Source: https://medblocks.com/docs/patient-access/create-patient-session/medblocks-hosted-page

The server-side implementation initializes the session using the Medblocks SDK, while the client-side implementation fetches the session URL and redirects the user.

```typescript
import { mb } from "../medblocks";

export async function initPatientSession(input: { patientId: string }) {
  const session = await mb.patientSession.init({
    patient_id: input.patientId,
    return_url: "https://app.example.com/connected",
    return_button_label: "Back to Acme Health",
  });

  return { url: session.url };
}
```

```typescript
async function startSession(patientId: string) {
  const response = await fetch("/api/patient-sessions", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ patientId }),
  });

  const { url } = await response.json();
  window.location.href = url;
}
```

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

### Create patient via server and client

Source: https://medblocks.com/docs/patient-access/create-patients

Use these examples to create a patient record. The server-side code uses the Medblocks SDK, while the client-side code performs a fetch request to your own API endpoint.

```typescript
import { mb } from "./medblocks";

export async function createPatient(input: { patientId: string; email?: string; name?: string }) {
  return mb.patients.create({
    patient_id: input.patientId,
    email: input.email,
    name: input.name,
    metadata: { signup_source: "intake" },
  });
}
```

```typescript
async function createPatient(values: { patientId: string; email?: string; name?: string }) {
  const response = await fetch("/api/patients", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(values),
  });

  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(error?.message ?? "Could not create patient");
  }

  return response.json() as Promise<{ id: string; email: string | null; name: string | null }>;
}
```

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

### GET /connections

Source: https://medblocks.com/docs/reference/api/list-fhir-sources

Search the catalog of registered EHRs with cursor pagination and optional q text and vendor type filters.

```APIDOC
## GET /connections

### Description
Search the catalog of registered EHRs with cursor pagination and optional q text and vendor type filters.

### Method
GET

### Endpoint
/connections
```

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

### NDJSON File Format Example

Source: https://medblocks.com/docs/export-to-s3

Example of the NDJSON format where each line contains a single FHIR resource JSON object.

```json
{"resourceType":"Patient","id":"example-patient","identifier":[{"system":"urn:medblocks:patient-id","value":"patient_123"}]}
{"resourceType":"Observation","id":"example-observation","status":"final"}
```

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

### Read patient records with Medblocks SDK

Source: https://medblocks.com/docs/patient-access/get-the-data

Use the Medblocks SDK to fetch a paginated list of patient records. The server-side example requires an API key, while the client-side example fetches data from a proxy route.

```ts
import { Medblocks } from "medblocks";

const mb = new Medblocks(process.env.MEDBLOCKS_API_KEY!);

const page = await mb.patients.records("user_42", { count: 100 });

for (const item of page.data) {
  console.log(item.source, item.resource.resourceType);
}
```

```ts
// Your API key stays on the server. The browser calls your own route,
// which runs the read above and returns the page as JSON.
const response = await fetch("/api/records?patient_id=user_42");
const page = await response.json();

for (const item of page.data) {
  console.log(item.source, item.resource.resourceType);
}
```

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

### Initialize Express Server Routes

Source: https://medblocks.com/docs/patient-access/quickstart

Sets up the basic Express routes for initiating a patient session, handling the connection callback, and fetching patient records.

```javascript
const app = express();
app.get("/start", initPatientSession);
app.get("/connected", connected);
app.get("/records", patientRecords);

app.listen(3000, () => console.log("open http://localhost:3000/start"));
```

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

### GET /webhooks

Source: https://medblocks.com/docs/reference/api/list-webhooks

Retrieve a list of webhook endpoints for the organization.

```APIDOC
## GET /webhooks

### Description
List your organization's webhook endpoints with cursor pagination and an optional status filter. Secrets are never returned.

### Method
GET

### Endpoint
/webhooks

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter the webhook endpoints by their status.
```

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

### Initialize Server Routes

Source: https://medblocks.com/docs/patient-access/quickstart

Configures the server to host the patient access routes.

```typescript
import { initPatientSession } from "./init-patient-session";
import { connected } from "./connections";
import { patientRecords } from "./patient-records";

Bun.serve({
  port: 3000,
  routes: {
    "/start": { GET: initPatientSession },
    "/connected": { GET: connected },
    "/records": { GET: patientRecords },
  },
});

console.log("open http://localhost:3000/start");
```

```typescript
import express from "express";
import { initPatientSession } from "./init-patient-session";
import { connected } from "./connections";
import { patientRecords } from "./patient-records";
```

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

### GET /health

Source: https://medblocks.com/docs/reference/api/health

Performs an unauthenticated liveness check to verify that the API is operational.

```APIDOC
## GET /health

### Description
Unauthenticated probe that returns 'ok' and the current server_time to confirm the API is reachable.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Returns 'ok'
- **server_time** (string) - The current server time
```

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

### list(options)

Source: https://medblocks.com/docs/patient-access/pagination

Fetches a single page of resources. The returned object contains the data, a 'has_more' flag, and a 'next_cursor' for subsequent requests.

```APIDOC
## list(options)

### Description
Fetches a single page of resources from a list method. Await the call to receive a Page object containing the current items and cursor information.

### Parameters
- **limit** (number) - Optional - The number of items to return per page (1-100). Default is 10.
- **starting_after** (string) - Optional - The cursor token from a previous page's 'next_cursor' to fetch the next set of results.

### Response
- **data** (Array) - The items on the current page.
- **has_more** (boolean) - Indicates if more pages exist.
- **next_cursor** (string|null) - The token to use for the next page request.
```

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

### mb.patientSession.init

Source: https://medblocks.com/docs/patient-access/create-patients

Initializes a patient session. If the patient does not exist, it is created; otherwise, it is updated and reused.

```APIDOC
## mb.patientSession.init

### Description
Initializes a patient session. If the patient does not exist, Medblocks creates it. If the patient already exists, Medblocks reuses it and updates the provided details.

### Signature
`mb.patientSession.init(params: { patient_id: string, return_url: string, patient_email?: string, patient_name?: string, metadata?: object })`

### Parameters
- **patient_id** (string) - Required - Unique identifier for the patient.
- **return_url** (string) - Required - URL to redirect to after the session.
- **patient_email** (string) - Optional - Email address of the patient.
- **patient_name** (string) - Optional - Name of the patient.
- **metadata** (object) - Optional - Additional metadata.
```

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

### GET /patients/{id}

Source: https://medblocks.com/docs/reference/api/get-patient

Retrieve a patient by their patient_id - the developer-provided identifier set on creation.

```APIDOC
## GET /patients/{id}

### Description
Retrieve a patient by their patient_id - the developer-provided identifier set on creation.

### Method
GET

### Endpoint
/patients/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The developer-provided identifier of the patient.
```

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

### mb.patientSession.init

Source: https://medblocks.com/docs/patient-access/create-patient-session/your-own-ui

Initializes a new patient session for a specific connection. This method should be called from your server to securely obtain a redirect URL.

```APIDOC
## mb.patientSession.init

### Description
Initializes a patient session for a selected connection. This returns a URL that the patient should be redirected to for authentication at their facility's portal.

### Parameters
#### Request Body
- **patient_id** (string) - Required - The unique identifier for the patient in your system.
- **connection_id** (string) - Required - The ID of the connection chosen by the patient.
- **return_url** (string) - Required - The URL the patient is redirected to after authorization.
- **patient_email** (string) - Optional - The email address of the patient.
- **patient_name** (string) - Optional - The name of the patient.
- **metadata** (object) - Optional - Additional metadata associated with the session.

### Response
- **url** (string) - The URL to redirect the patient to for the facility's patient portal.
```

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

### GET /patients

Source: https://medblocks.com/docs/reference/api/list-patients

Retrieves a list of patients for the organization with support for cursor pagination and filtering.

```APIDOC
## GET /patients

### Description
List your organization's patients with cursor pagination and optional exact-match filters on patient_id or email.

### Method
GET

### Endpoint
/patients

### Parameters
#### Query Parameters
- **patient_id** (string) - Optional - Filter by exact patient ID.
- **email** (string) - Optional - Filter by exact email address.
```

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

### Add Medblocks server with API key

Source: https://medblocks.com/docs/mcp

Configures a scripted workspace connection using an authorization header instead of browser-based OAuth.

```bash
codex mcp add medblocks --url https://app.medblocks.com/mcp \
  --header "Authorization: Bearer mb_sk_..."
```

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

### Initialize Medblocks Client

Source: https://medblocks.com/docs/patient-access/quickstart

Create and export a singleton client instance for use throughout your application.

```typescript
import { Medblocks } from "medblocks";

const apiKey = process.env.MEDBLOCKS_API_KEY;
if (!apiKey) throw new Error("MEDBLOCKS_API_KEY is not configured");

export const mb = new Medblocks(apiKey);
```

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

### list_people

Source: https://medblocks.com/docs/mcp

Lists everyone set up in the workspace.

```APIDOC
## list_people

### Description
Lists everyone set up in your workspace.
```

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

### Configure Redirect URIs

Source: https://medblocks.com/docs/patient-access/cerner

List of valid redirect URIs for development and production environments.

```text
http://localhost:3000/api/auth/smart/callback             # local development
https://app.medblocks.com/api/auth/smart/callback         # Medblocks Platform
```

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

### Patient Resource Identifier Structure

Source: https://medblocks.com/docs/export-to-fhir-server

Example of a Patient resource containing the custom Medblocks identifier system.

```json
{
  "resourceType": "Patient",
  "id": "eCB8Nuu2lGe...",
  "identifier": [
    { "system": "urn:oid:1.2.840.114350...", "value": "MRN12345" },
    { "system": "urn:medblocks:patient-id", "value": "patient_123" } // [!code highlight]
  ]
}
```

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

### get_workspace_overview

Source: https://medblocks.com/docs/mcp

Reports the current user identity and a summary of the workspace.

```APIDOC
## get_workspace_overview

### Description
Reports who you are and a summary of your workspace. A good place to start.
```

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

### Configure API Key

Source: https://medblocks.com/docs/patient-access/quickstart

Store your secret API key in an environment variable.

```bash
MEDBLOCKS_API_KEY="mb_sk_live_..."
```

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

### Handle quota_exceeded error response

Source: https://medblocks.com/docs/billing

Example JSON response when a Free-tier workspace exceeds its active-patient limit.

```json
{
  "error": {
    "type": "billing_error",
    "code": "quota_exceeded",
    "message": "You've hit your patient limit. Contact support to increase it.",
    "param": null,
    "doc_url": "https://docs.medblocks.com/errors/quota_exceeded",
    "request_id": "9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d"
  }
}
```

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

### GET /v2/uscore/STU6/{Resource}

Source: https://medblocks.com/docs/patient-access/meditech

Fetches a specific FHIR resource for a given patient using an access token.

```APIDOC
## GET https://greenfield-prod-apis.meditech.com/v2/uscore/STU6/{Resource}

### Description
Fetches patient resources from the Meditech FHIR R4 API after successful token exchange.

### Method
GET

### Endpoint
https://greenfield-prod-apis.meditech.com/v2/uscore/STU6/{Resource}?patient={patient_id}

### Parameters
#### Path Parameters
- **Resource** (string) - Required - The FHIR resource type to retrieve (e.g., Patient, AllergyIntolerance, Observation).

#### Query Parameters
- **patient** (string) - Required - The unique identifier of the patient.

### Request Headers
- **Authorization** (string) - Required - Bearer {access_token}
- **Accept** (string) - Required - application/fhir+json
```

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

### Generate RSA Private Key with OpenSSL

Source: https://medblocks.com/docs/patient-access/athena

Use this command to generate a 2048-bit RSA private key locally. Store the resulting file securely and never commit it to version control.

```shell
openssl genrsa -out privatekey.pem 2048
```

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

### GET /webhooks/{id}/events

Source: https://medblocks.com/docs/reference/api/list-webhook-events

Retrieves a list of recent delivery records for a specific webhook endpoint.

```APIDOC
## GET /webhooks/{id}/events

### Description
List recent delivery records for one endpoint with cursor pagination and an optional delivered filter for the delivery audit.

### Method
GET

### Endpoint
/webhooks/{id}/events

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook endpoint.

#### Query Parameters
- **delivered** (boolean) - Optional - Filter results by delivery status.
```

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

### GET /patients/{id}/records

Source: https://medblocks.com/docs/reference/api/get-patient-records

Retrieves the latest stored FHIR resources for a given patient ID.

```APIDOC
## GET /patients/{id}/records

### Description
Return the patient's latest stored FHIR resources with their source EHR, paginated.

### Method
GET

### Endpoint
/patients/{id}/records

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the patient.
```

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

### Retrieve supported SMART scopes

Source: https://medblocks.com/docs/patient-access/meditech

Use this command to query the Meditech SMART configuration endpoint and view the list of supported scopes.

```shell
curl -s https://greenfield-prod-apis.meditech.com/v2/uscore/STU6/.well-known/smart-configuration | jq .scopes_supported
```

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

### GET /connections/{id}

Source: https://medblocks.com/docs/reference/api/get-fhir-source

Retrieve a single EHR from the catalog by its fhirsrc_ id or raw fhir_base_url, scoped to your environment.

```APIDOC
## GET /connections/{id}

### Description
Retrieve a single EHR from the catalog by its fhirsrc_ id or raw fhir_base_url, scoped to your environment.

### Method
GET

### Endpoint
/connections/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The fhirsrc_ id or raw fhir_base_url of the EHR to retrieve.
```

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

### GET /patient-sessions/{id}

Source: https://medblocks.com/docs/reference/api/retrieve-patient-session

Retrieve a patient session by its ps_ id, including its current status and the connections created during it.

```APIDOC
## GET /patient-sessions/{id}

### Description
Retrieve a patient session by its ps_ id, including its current status and the connections created during it.

### Method
GET

### Endpoint
/patient-sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ps_ id of the patient session.
```

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

### GET https://fhir-myrecord.cerner.com/r4/{tenant_id}/{Resource}

Source: https://medblocks.com/docs/patient-access/cerner

Fetches a specific FHIR resource for a patient from the Cerner R4 API.

```APIDOC
## GET https://fhir-myrecord.cerner.com/r4/{tenant_id}/{Resource}

### Description
Fetches patient resources using a Bearer token for authorization.

### Method
GET

### Endpoint
https://fhir-myrecord.cerner.com/r4/{tenant_id}/{Resource}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The unique identifier for the tenant.
- **Resource** (string) - Required - The FHIR resource type (e.g., Patient, AllergyIntolerance, Condition, etc.).

### Request Example
GET https://fhir-myrecord.cerner.com/r4/12345/Patient
Authorization: Bearer {access_token}
Accept: application/fhir+json
```

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

### Tunnel Local Port to Public URL

Source: https://medblocks.com/docs/webhooks/local-development

Use cloudflared or ngrok to expose a local development server to the internet for webhook delivery.

```bash
# install once: brew install cloudflared
cloudflared tunnel --url http://localhost:3000
# → https://<random>.trycloudflare.com
```

```bash
# install once: brew install ngrok
ngrok http 3000
# → https://<random>.ngrok.app
```

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

### connect_health_system

Source: https://medblocks.com/docs/mcp

Creates a secure link for patient portal sign-in and adds a new person to the workspace.

```APIDOC
## connect_health_system

### Description
Creates a secure link you open to sign in to your patient portal, and adds a new person to your workspace when one is needed.
```

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

### mb.connections.list

Source: https://medblocks.com/docs/patient-access/find-connections

Retrieves a list of connections from the catalog. Supports pagination via the autoPagingIterator method.

```APIDOC
## mb.connections.list()

### Description
Lists connections in the catalog. Use the autoPagingIterator to handle pagination automatically.

### Parameters
- **limit** (number) - Optional - The number of records to return per page.

### Code Example
```ts
for await (const connection of mb.connections.list({ limit: 100 }).autoPagingIterator()) {
  console.log(connection.id, connection.name);
}
```
```

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

### Patient Identifier Mapping

Source: https://medblocks.com/docs/export-to-s3

Example showing the patient identifier structure used to map files to patients in the destination system.

```json
{
  "resourceType": "Patient",
  "id": "example-patient",
  "identifier": [
    { "system": "urn:medblocks:patient-id", "value": "patient_123" } // [!code highlight]
  ]
}
```

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

### List connections with auto-paging

Source: https://medblocks.com/docs/patient-access/find-connections

Use the autoPagingIterator to traverse the entire connection catalog page by page.

```ts
for await (const connection of mb.connections.list({ limit: 100 }).autoPagingIterator()) {
  console.log(connection.id, connection.name);
}
```

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

### Get Hydrated Connections (TypeScript)

Source: https://medblocks.com/docs/patient-access/create-patients

Retrieves a list of connected facilities with full details by setting the hydrate option to true.

```ts
const facilities = await mb.patients.getConnections("user_42", { hydrate: true });

for (const facility of facilities) {
  console.log(facility.name, facility.logo_url, facility.fhir_base_url);
}
```

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

### Example Clinical Domain Model JSON

Source: https://medblocks.com/docs/clinical-data-models

A sample JSON structure representing a resolved clinical concept with provenance data for auditability.

```json
[
  {
    "subject": "Patient/1",
    "code": "bmi",
    "value": 24.6,
    "unit": "kg/m2",
    "status": "hasValue",
    "resolved_by": "direct",
    "provenance": [
      {
        "reference": "Observation/bmi-1",
        "system": "epic-org-a",
        "performer": "Clinic A",
        "effective": "2024-01-10",
        "value": 24.1,
        "coding": { "system": "LOINC", "code": "39156-5" }
      },
      {
        "reference": "Observation/bmi-2",
        "system": "epic-org-a",
        "performer": "Clinic A",
        "effective": "2024-05-02",
        "value": 25.1,
        "coding": { "system": "LOINC", "code": "39156-5" }
      }
    ]
  }
]
```