Guides

Getting started

The mdhub platform exposes two complementary interfaces: the proprietary mdhub API (v1) for sessions, notes, and questionnaires, and a standards-based FHIR R4 API for reading and writing clinical data. Both are served over HTTPS and return JSON.

1. Get credentials

Request access from support@mdhub.ai. You will receive an API key for the v1 API and OAuth 2.0 client credentials for the FHIR API.

2. Make your first request

Search Patient resources over the FHIR R4 API:

curl https://api.mdhub.ai/fhir/R4/Patient \
  -H "Authorization: Bearer $MDHUB_TOKEN" \
  -H "Accept: application/fhir+json" \
  -G -d "name=Ramirez"

Explore every endpoint in the API reference.

Authentication

The two APIs use different authentication schemes. Use the one that matches the endpoint you are calling.

mdhub API (v1) — API key

Send your API key in the x-api-key header with every request: 

curl https://api.mdhub.ai/v1/patients \
  -H "x-api-key: $MDHUB_API_KEY"

FHIR R4 — OAuth 2.0 (SMART Backend Services)

The FHIR API follows the SMART Backend Services profile. Request an access token with the client_credentials grant, then send it as a bearer token: 

curl -X POST https://api.mdhub.ai/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "scope=system/Patient.read system/Appointment.write"

Access is controlled with SMART v2 system scopes such as system/Patient.read and system/Appointment.write.

Using the FHIR R4 API

The FHIR API is available at https://api.mdhub.ai/fhir/R4 and speaks the application/fhir+json media type for both requests and responses.

Interactions

  • GET /{Resource}/{id} — read a single resource
  • GET /{Resource}?<params> — search
  • POST /{Resource} — create
  • PUT /{Resource}/{id} — update

Searching and Bundles

Search interactions return a Bundle of type searchset. Common parameters include _id, _lastUpdated, _count (page size), and _sort; the link array carries the next page URL.

Errors

Failed requests return an OperationOutcome resource with an issue array describing the problem, using standard HTTP status codes.

Events and webhooks

Register a Subscription with a rest-hook channel and mdhub will POST notifications to your endpoint when resources matching your criteria change.

See the full resource catalog in the API reference.