Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.1.1",
"info": {
"title": "Medblocks API",
"version": "2026-04-25",
"description": "Developer API for the Medblocks Platform.\n\nConnect any patient to one or more EHRs (Epic, Cerner, Athena, …) via a single hosted PatientSession, then pull their unified FHIR records through this API. Server-to-server only — no browser-side calls. Authenticate every request with a Bearer secret key.\n\n**Resources:** `PatientSession`, `Patient`, `Connection`, `FhirSource`. **Conventions:** date-pinned versioning (optional `Version` header), a typed error envelope on every non-2xx response.",
"license": {
"name": "Proprietary",
"url": "https://medblocks.com/terms"
}
},
"servers": [
{
"url": "https://app.medblocks.com"
}
],
"security": [
{
"BearerAuth": []
}
],
"paths": {
"/health": {
"get": {
"operationId": "api.health",
"summary": "Liveness check",
"description": "Unauthenticated probe that returns `ok` and the current `server_time` to confirm the API is reachable.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"const": true,
"description": "Always true. Presence of this field plus 200 status confirms the server is reachable."
},
"server_time": {
"type": "string",
"description": "Current server time in ISO 8601. Use to spot clock skew."
}
},
"required": [
"ok",
"server_time"
]
}
}
}
}
}
}
},
"/patients": {
"post": {
"operationId": "api.createPatient",
"summary": "Create a patient",
"description": "Create a patient with your own `patient_id` plus optional email, name, and metadata. The id is unique within your organization.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatientCreateInput"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Patient"
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/Version"
}
]
},
"get": {
"operationId": "api.listPatients",
"summary": "List patients",
"description": "List your organization's patients with cursor pagination and optional exact-match filters on `patient_id` or `email`.",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Maximum number of items to return."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "starting_after",
"in": "query",
"schema": {
"type": "string",
"description": "Pagination cursor from `next_cursor`."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "patient_id",
"in": "query",
"schema": {
"type": "string",
"description": "Exact-match filter on `patient_id`."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "email",
"in": "query",
"schema": {
"type": "string",
"description": "Exact-match filter on `email`."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"$ref": "#/components/parameters/Version"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource_type": {
"const": "list",
"description": "Resource type discriminator. Always `\"list\"` for paginated responses."
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Patient"
},
"description": "Items on this page."
},
"has_more": {
"type": "boolean",
"description": "`true` when there's at least one more page after this one."
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as `starting_after` to fetch the next page. `null` when there's no more data."
}
},
"required": [
"resource_type",
"data",
"has_more",
"next_cursor"
],
"examples": [
{
"resource_type": "list",
"data": [
{
"id": "user_42",
"resource_type": "patient",
"email": "jane@example.com",
"name": "Jane Doe",
"metadata": {
"plan": "premium"
},
"created_at": "2026-04-25T14:30:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
]
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
},
"/patients/{id}": {
"get": {
"operationId": "api.getPatient",
"summary": "Retrieve a patient",
"description": "Retrieve a patient by their `patient_id` - the developer-provided identifier set on creation.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Your `patient_id` from Patient creation or Session upsert."
}
},
{
"$ref": "#/components/parameters/Version"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatientDetail"
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
},
"put": {
"operationId": "api.updatePatient",
"summary": "Update a patient",
"description": "Update a patient by id. Omitted optional fields are cleared. `patient_id` in the body must match the URL.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Your `patient_id` from Patient creation or Session upsert."
}
},
{
"$ref": "#/components/parameters/Version"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"patient_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Must match the `{id}` URL param. 400 if mismatched. Immutable."
},
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "New email. Omit or pass `null` to clear."
},
"name": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "New name. Omit or pass `null` to clear (UI falls back to the patient_id)."
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "New metadata. Omit to clear (replaced with `{}`)."
}
},
"required": [
"patient_id"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Patient"
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
},
"delete": {
"operationId": "api.deletePatient",
"summary": "Delete a patient",
"description": "Permanently delete a patient and their connections by `patient_id`. Returns a tombstone confirming the deletion.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Your `patient_id` from Patient creation or Session upsert."
}
},
{
"$ref": "#/components/parameters/Version"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatientDeleted"
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
},
"/patients/{id}/connections/{connection_id}": {
"delete": {
"operationId": "api.disconnectPatientConnection",
"summary": "Disconnect a connection",
"description": "Revoke your organization's access to one of the patient's connections by its `conn_` id. The patient's link to the source EHR is removed for your organization; stored tokens are revoked when no other workspace still uses them. Returns a tombstone confirming the disconnect.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Your `patient_id` from Patient creation or Session upsert."
}
},
{
"name": "connection_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "The `conn_` connection id from the patient's `connections[]`."
}
},
{
"$ref": "#/components/parameters/Version"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionDisconnected"
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
},
"/patients/{id}/patient-sessions": {
"get": {
"operationId": "api.listPatientSessionsForPatient",
"summary": "List patient sessions for a patient",
"description": "List a patient's sessions with cursor pagination and an optional `status` filter, identified by their `patient_id`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Your `patient_id` from Patient creation or Session upsert."
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Maximum number of items to return."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "starting_after",
"in": "query",
"schema": {
"type": "string",
"description": "Pagination cursor from `next_cursor`."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "status",
"in": "query",
"schema": {
"enum": [
"open",
"complete",
"expired"
],
"type": "string",
"description": "Filter by patient_session status."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"$ref": "#/components/parameters/Version"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource_type": {
"const": "list",
"description": "Resource type discriminator. Always `\"list\"` for paginated responses."
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PatientSession"
},
"description": "Items on this page."
},
"has_more": {
"type": "boolean",
"description": "`true` when there's at least one more page after this one."
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as `starting_after` to fetch the next page. `null` when there's no more data."
}
},
"required": [
"resource_type",
"data",
"has_more",
"next_cursor"
],
"examples": [
{
"resource_type": "list",
"data": [
{
"id": "ps_01J9YQ8M2X4VZ6P2K5RH7M3KQT",
"resource_type": "patient_session",
"status": "open",
"url": "https://app.medblocks.com/c/9c9b6f7a8e4f4a3b9c1e6f3a2d8b7c4d",
"patient_id": "user_42",
"connection_id": null,
"recommended_connection_ids": [
"fhirsrc_02Zh2bnvRoWQJYgOAkI0Twcc",
"fhirsrc_0a9Ea55aR4u7HaWMyFBN8wcc",
"fhirsrc_lcvXRHLSSI2WK9Prrt5Qggcc"
],
"return_url": "https://app.example.com/connected",
"return_button_label": "Acme Health",
"connections": [],
"expires_at": "2026-04-25T15:00:00.000Z",
"metadata": {
"signup_source": "checkout"
},
"created_at": "2026-04-25T14:30:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
]
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
},
"headers": {
"Retry-After": {
"$ref": "#/components/headers/RetryAfter"
}
}
},
"500": {
"description": "500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
},
"/patients/{id}/records": {
"get": {
"operationId": "api.getPatientRecords",
"summary": "Get patient records",
"description": "Return the patient's latest stored FHIR resources with their source EHR, paginated.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Your `patient_id` from Patient creation or Session upsert."
}
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"description": "Comma-separated FHIR resource types to include, e.g. `Observation,Condition`."
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "since",
"in": "query",
"schema": {
"anyOf": [
{
# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/medblocks/refs/heads/main/openapi/medblocks-platform-openapi.json