API documentation

MediSynth API reference

Build repeatable synthetic patient cohorts, simulate upstream provider variance, and export records into product tests, demos, migrations, and integration QA.

Start with cURL Browse endpoints

Workflow

Validate, preview, generate, export.

The API reference now mirrors the actual automation flow from cohort spec to retained artifacts.

API sequence4 calls

Quickstart

Generate a cohort

Most teams start by validating a cohort spec, previewing population shape, then generating export-ready records with a fixed seed.

cURL

curl -X POST https://app.cloud.medisynth.io/workspace/tenants/$MEDISYNTH_TENANT_ID/cohort-jobs \
  -H "Authorization: Bearer $MEDISYNTH_TOKEN" \
  -H "X-API-Key: $MEDISYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "enterprise-mpi-evaluation",
    "population": 1000,
    "seed": 4107,
    "geography": { "state": "Washington", "city": "Vancouver" },
    "demographics": {
      "ageBands": [
        { "label": "0-17", "min": 0, "max": 17, "weight": 0.18 },
        { "label": "18-64", "min": 18, "max": 64, "weight": 0.58 },
        { "label": "65+", "min": 65, "max": 94, "weight": 0.24 }
      ],
      "sexAtBirth": { "female": 0.52, "male": 0.48 },
      "payerMix": { "commercial": 0.48, "medicare": 0.24, "medicaid": 0.23, "self-pay": 0.05 },
      "language": { "en": 0.78, "es": 0.15, "other": 0.07 }
    },
    "conditions": [
      { "name": "diabetes-type-2", "prevalence": 0.42 },
      { "name": "hypertension", "prevalence": 0.64 }
    ],
    "hie": {
      "sourceSystems": ["regional-hie", "county-provider", "claims-feed", "lab-network"],
      "duplicateRate": 0.11,
      "addressDriftRate": 0.22,
      "missingPhoneRate": 0.14
    },
    "exports": { "formats": ["json", "ndjson", "manifest"] }
  }'

Endpoints

Core API surface

Endpoint responses are deterministic for a given seed and spec, so they work cleanly in CI and repeatable product demos.

GET/heartbeat

Health check

Confirm the API is reachable before a workflow starts.

GET/cohorts/scenarios

List scenarios

Read built-in recipes for demos, QA cases, and upstream matching edge cases.

POST/cohorts/validate

Validate a spec

Return warnings and errors without generating records or consuming a generation run.

POST/cohorts/preview

Preview shape

Estimate population, provider spread, source-record count, and identity variance.

POST/workspace/tenants/{tenantID}/cohort-jobs

Create cohort job

Create a retained cohort run that returns job metadata, usage counts, and downloadable artifacts without inlining large clinical payloads.

POST/cohorts/export/fhir

Export FHIR

Return Bundle and NDJSON artifacts for product pipelines and downstream integration tests.

GET/billing/plans

Read plans

Inspect quotas, API-key limits, included usage, and metered overage pricing.

POST/billing/tenants/{tenantID}/usage

Record usage

Write metered generation usage for credits, quotas, and customer-facing usage views.

Schemas

Request and response fields

Use these fields to build typed clients, fixtures, and account usage views.

Authentication

Header	Required	Description
`Authorization`	Yes	Bearer token for the signed-in account.
`X-API-Key`	Yes	Workspace key scoped to cohort generation and export calls.
`Content-Type`	POST	Use `application/json` for JSON request bodies.

Cohort request

Field	Type	Description
`name`	string	Human-readable scenario or cohort identifier.
`population`	number	Total synthetic patient count to generate.
`seed`	number	Deterministic seed for repeatable cohorts.
`conditions`	array	Clinical conditions with prevalence targets.
`hie`	object	Provider spread, missingness, and identity drift settings.

Generate response

Field	Type	Description
`manifest`	object	Resource counts, source-record counts, and duplicate identity totals.
`quality`	object	Deterministic seed, document count, demographics, conditions, mutations, source-system counts, and warnings.
`patients[].documents`	array	Linked clinical documents generated from encounters, conditions, and observations.
`patientSummaries`	array	Short inspection strings for generated patients.

Abbreviated generate response

{
  "spec": { "name": "mpi-hard-matches", "population": 250 },
  "preview": { "documents": { "estimatedDocumentCount": 2076 } },
  "manifest": {
    "sourcePatientRecordCount": 1038,
    "resourceCounts": {
      "Patient": 1038,
      "DocumentReference": 2076
    }
  },
  "quality": {
    "documentCount": 2076,
    "conditionCounts": { "asthma": 40, "hypertension": 78 }
  },
  "patients": [
    {
      "sourceSystem": "north-hie",
      "documents": [
        { "type": "encounter-summary", "text": "..." }
      ]
    }
  ],
  "patientSummaries": ["1 -- Ava Garcia (1974-01-01, female) Vancouver, Washington"]
}

Usage event

Field	Type	Description
`patientsGenerated`	number	Generated patient count for the metered event.
`sourceRecords`	number	Total provider-specific records created.
`fhirResources`	number	Total exported clinical resources.
`generationJobCount`	number	Number of generation jobs to record.

Error model

Field	Type	Description
`code`	string	Stable machine-readable reason.
`message`	string	Human-readable corrective detail.
`requestID`	string	Identifier to correlate client and server logs.

Examples

Client-ready snippets

Copy the language example closest to your integration and replace the token, key, and cohort spec.

TypeScript

const response = await fetch("https://app.cloud.medisynth.io/cohorts/preview", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MEDISYNTH_TOKEN}`,
    "X-API-Key": process.env.MEDISYNTH_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(cohortSpec)
});

if (!response.ok) throw new Error(await response.text());
const preview = await response.json();

Python

import os
import requests

response = requests.post(
    "https://app.cloud.medisynth.io/cohorts/export/fhir",
    headers={
        "Authorization": f"Bearer {os.environ['MEDISYNTH_TOKEN']}",
        "X-API-Key": os.environ["MEDISYNTH_API_KEY"],
    },
    json=cohort_spec,
    timeout=30,
)
response.raise_for_status()
fhir_export = response.json()

Usage event

{
  "patientsGenerated": 250,
  "sourceRecords": 1038,
  "fhirResources": 5770,
  "generationJobCount": 1
}

Operational behavior

Failure responses stay predictable.

Every failed request returns a stable status code, a short machine-readable reason, and enough context for callers to retry, correct the payload, or pause generation.

400

Invalid spec

Malformed JSON, impossible prevalence, or unsupported cohort settings.

401

Unauthenticated

The account session is missing or expired.

429

Rate limited

The account or calling client is above the allowed request envelope.