Build repeatable synthetic patient cohorts, simulate upstream provider variance, and export
records into product tests, demos, migrations, and integration QA.
The guide follows the real automation flow, from cohort spec to retained artifacts.
API sequence4 calls
validatepreviewgenerateexport
Quickstart
Generate a cohort
Two credentials, never mixed on one request: tenant routes
(/v1/workspace/tenants/{tenantID}/...) accept only
X-API-Key with the full one-time secret, and session routes
(/v1/workspace/me/...) accept only Authorization: Bearer
with a console session token.
Set the placeholders once, then run two calls: a session call to read your workspace
summary, and a tenant call that queues a retained cohort job.
Poll GET /v1/workspace/tenants/{tenantID}/cohort-jobs/{jobID} with the same
API key until status is available, then list and download the
retained artifacts. Prefer a typed client? The SDKs below wrap the same job flow.
Endpoints
Endpoint map by capability
The OpenAPI contract defines 198 operations. The groups below list representative
routes by capability; the interactive reference
renders every operation, schema, and example live from
openapi.yaml. Endpoint responses are deterministic for a
given seed and spec, so they work cleanly in CI and repeatable product demos.
Cohorts & scenarios
Validate and preview a spec, browse built-in scenarios, then create retained generation jobs.
Inspect job artifact inventories, stream files, or mint signed download URLs. Job export formats include FHIR, NDJSON, CSV, X12 837/835, and OMOP CDM (omop or omop-parquet).
Read plans and the current workspace summary, export the usage ledger, and
check remaining quota. Generation and other MediSynth workflows record their
own metered usage automatically.
Typed Python, TypeScript, and Go clients are generated from the same OpenAPI
contract — one method per operation across all 198 operations — and live in this
repository under sdks/. Installs are monorepo-local; registry publishing
is not available yet. Every client raises a structured error carrying the API
code, requestId, and problem detail.
TypeScript
# Build from the monorepo (Node 20.6+)
cd sdks/typescript
npm install
npm run build
# First call: create a retained cohort job on a tenant route (X-API-Key)
import { MediSynthClient } from "@medisynth/sdk";
const client = new MediSynthClient({ apiKey: process.env.MEDISYNTH_API_KEY });
const { job } = await client.createWorkspaceCohortJob(process.env.MEDISYNTH_TENANT_ID ?? "", {
name: "quickstart",
population: 25,
seed: 4107,
exports: { formats: ["fhir", "ndjson"] }
});
console.log(job.id, job.status);
Python
# Install from the monorepo (stdlib only, no runtime dependencies)
cd sdks/python
pip install -e .
# First call: create a retained cohort job on a tenant route (X-API-Key)
from medisynth import MediSynthClient, MediSynthError
client = MediSynthClient(api_key="ms_live_...")
spec = {
"name": "quickstart",
"population": 25,
"seed": 4107,
"exports": {"formats": ["fhir", "ndjson"]},
}
resp = client.create_workspace_cohort_job("tenant-...", spec)
print(resp["job"]["id"], resp["job"]["status"])
Go
# Install the module (this repository is its own Go module)
go get github.com/MediSynth-io/medisynth/sdks/go/medisynth
# First call: create a retained cohort job on a tenant route (X-API-Key)
import medisynth "github.com/MediSynth-io/medisynth/sdks/go/medisynth"
client := medisynth.New(medisynth.WithAPIKey("ms_live_..."))
resp, err := client.CreateWorkspaceCohortJob(ctx, tenantID, medisynth.CohortSpec{
Name: "quickstart",
Population: 25,
Seed: 4107,
Exports: medisynth.ExportProfile{Formats: []string{"fhir", "ndjson"}},
}, medisynth.CreateWorkspaceCohortJobParams{})
Spec fixtures: replay explainability
Replay drift fixtures for HIE ingestion tests, passed as the cohort spec
hie.qualityTargets block.
Problem type URI: https://api.medisynth.io/errors/<code>.
title
string
Short problem summary.
status
number
HTTP status code, repeated in the body.
code
string
Stable machine-readable reason, such as validation_failed, quota_exceeded, or rate_limit_exceeded.
detail
string
Human-readable corrective detail.
requestId
string
Identifier to correlate client and server logs; quote it in support requests.
retryable
boolean
true when an immediate retry can succeed.
retryAfterSeconds
number
Seconds to wait before retrying; present on retryable 429 responses and mirrors the Retry-After header.
fields / errors
array
Per-field validation failures ({ "field", "message" }) on 400 validation_failed; both arrays carry the same rows.
quota
object
Plan quota and current usage metadata on 402 quota_exceeded.
400 validation_failed
{
"error": "population must be greater than zero",
"type": "https://api.medisynth.io/errors/validation_failed",
"title": "Cohort validation failed",
"status": 400,
"code": "validation_failed",
"detail": "population must be greater than zero",
"requestId": "req-7f3c9a21d0b44e86",
"retryable": false,
"valid": false,
"fields": [
{ "field": "population", "message": "must be greater than zero" }
],
"errors": [
{ "field": "population", "message": "must be greater than zero" }
]
}
429 concurrent_generation_limit
{
"error": "concurrent generation job limit reached for the current plan",
"type": "https://api.medisynth.io/errors/concurrent_generation_limit",
"title": "Too many concurrent jobs",
"status": 429,
"code": "concurrent_generation_limit",
"detail": "concurrent generation job limit reached for the current plan",
"requestId": "req-2b8e14f7c3a54c29",
"retryable": true,
"retryAfterSeconds": 30
}
Operational behavior
Failure responses stay predictable.
Every failed request returns the same problem envelope — status,
code, detail, and requestId — so callers can
retry, correct the payload, or pause generation. A 402 quota_exceeded
response also carries plan quota metadata.
400 · validation_failed
Invalid spec
Malformed JSON, impossible prevalence, or unsupported cohort settings; the fields array lists each failing field.
401 · authentication_required
Unauthenticated
The API key or session token is missing, invalid, expired, or sent to the wrong route family.
429 · rate_limit_exceeded
Rate limited
The account or calling client is above the allowed request rate; retryable responses carry retryAfterSeconds.
