canonical: https://jentic.com/apis/medplum.com/medplum

# Medplum - OpenAPI 3.0

The Medplum API exposes a standards-based HL7 FHIR R4 server for storing and querying healthcare data, where any FHIR resource type, such as Patient, Observation, or Encounter, is addressed by name in the URL path. It supports search, create, read, full and conditional update, JSON Patch, delete, and validation without saving, plus version history and reads of a specific past version. Batch and transaction Bundles post many operations in one request, conditional create with If-None-Exist avoids duplicates, and If-Match headers guard concurrent edits.

## For AI agents

Search, create, read, update, patch, validate, and delete any FHIR R4 resource on Medplum, run batch or transaction Bundles, and read a resource's version history.

## Scope

Does not handle claims billing, e-prescribing to pharmacies, or video visits. Use for storing and querying FHIR R4 healthcare resources only.

## Capabilities

- Search any FHIR resource type, such as Patient or Observation, with FHIR search criteria in the query
- Create a resource, or create it conditionally with If-None-Exist so a matching record is not duplicated
- Upsert a resource by search criteria with a conditional update, or update and patch a known id with If-Match concurrency checks
- Validate a resource against FHIR rules with $validate before saving it
- Run a batch or transaction Bundle that applies many creates, updates, and reads in one request
- Read a resource's full _history and fetch any past version by versionId

## Use cases

### Agent-maintained clinical records through Jentic

A healthcare agent can keep records current in a Medplum project through Jentic. It searches for the patient by identifier, validates a new Observation with $validate, and saves it, using If-Match on updates so it never overwrites a newer edit. Because the resource type is part of the path, the agent's access can be held to the resource types it actually needs.

Example prompt: Search Patient with criteria identifier=MRN-1001, validate an Observation for a blood pressure of 120/80 for that patient, then create it and return the new resource id

### Idempotent data import into FHIR

Importing data from another system risks duplicates on retry. Medplum supports conditional create with If-None-Exist, conditional update by search criteria, and transaction Bundles that either apply every entry or none, so an import can be rerun without creating duplicate Patients or orphaned Encounters.

Example prompt: Post a transaction Bundle to `/fhir/R4` that conditionally creates a Patient with identifier MRN-2002 and creates an Encounter referencing it

### Audit and recovery from version history

Every FHIR resource on Medplum keeps its version history. Reading _history shows who changed what and when, and reading a specific versionId recovers an earlier state of a record, which supports clinical audit and rollback of a mistaken edit.

Example prompt: Read the _history of Patient 123, fetch the version before the latest, and report which fields differ between the two versions

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/fhir/R4/{resourceType}` | Search resources |
| POST | `/fhir/R4/{resourceType}` | Create a resource |
| GET | `/fhir/R4/{resourceType}/{id}` | Read a resource |
| PATCH | `/fhir/R4/{resourceType}/{id}` | Patch a resource |
| POST | `/fhir/R4/{resourceType}/$validate` | Validate a resource |
| POST | `/fhir/R4` | Batch or transaction Bundle |
| GET | `/fhir/R4/{resourceType}/{id}/_history` | Read resource history |

## Key resources

- **FHIR resources** — Search, create, read, update, conditionally update, patch, validate, and delete any FHIR R4 resource type.
- **Batch and transaction** — Post a Bundle that applies many operations in one request.
- **History** — Read a resource's version history and specific past versions.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 53 / 100
  - Developer Experience & Jentic Compatibility: 60 / 100
  - AI-Readiness & Agent Experience: 60 / 100
  - Agent Usability: 94 / 100
  - Security: 68 / 100
  - AI Discoverability: 44 / 100
- **View full report:** https://jentic.com/apis/medplum.com/medplum/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Medplum by hand means picking among Basic, bearer JWT, OpenID Connect, and SMART OAuth flows, refreshing tokens, and handling If-Match and If-None-Exist headers yourself. Through Jentic you install once, import Medplum from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Medplum puts the FHIR resource type and id in the URL path (`/fhir/R4/{resourceType}/{id}`), so a rule can limit your agent to specific resource types, such as Appointment, and the operations you pick. You choose the operations it may call, so destructive ones like deleting resources or posting transaction Bundles are not included unless you add them.
- **Credential handling:** Your Medplum credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a FHIR patient' or 'search observations', and Jentic returns the matching Medplum operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Oystehr** — FHIR-based healthcare platform with added services for building clinical apps.
- **Epic FHIR API** — FHIR access to records held in Epic hospital EHRs.
- **1upHealth** — Aggregates patient data from payers and providers over FHIR.
- **openEHR API** — Archetype-based clinical data standard as an alternative to FHIR storage.

## FAQ

### What authentication does the Medplum API use?

Per its OpenAPI spec, Medplum accepts HTTP Basic, a JWT bearer token, OpenID Connect, or OAuth 2.0 with authorization code and client credentials flows following SMART App Launch, with scopes such as patient/*.rs and user/*.cruds. Any one of these schemes authenticates a request. Through Jentic the credential is stored encrypted on your own instance and injected at call time.

### Is there a Medplum MCP server?

You don't need an MCP server to give your agent Medplum. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are discovered on demand, so another server's tool definitions never crowd your agent's context.

### Can I limit what my agent is allowed to do with the Medplum API?

Yes. For a scheduling assistant, write a rule that allows only GET and POST on `/fhir/R4/Appointment` and GET on `/fhir/R4/Slot`, so it can find slots and book visits but cannot read Observations or delete any resource. Every call it makes is logged.

### What are the rate limits for the Medplum API?

The OpenAPI spec does not specify rate limits; check https://www.medplum.com/docs for current limits on the hosted service.

### How do I avoid creating duplicate patients in Medplum?

Use a conditional create: POST `/fhir/R4/Patient` with an If-None-Exist header holding search criteria such as an identifier, and Medplum only creates the resource if nothing matches. Alternatively, PUT `/fhir/R4/{resourceType}` with criteria performs an upsert that updates the match or creates a new record.

### How do I create a FHIR resource in Medplum through Jentic?

Search Jentic for an intent like 'create a FHIR patient', import the Medplum API, and store your client credentials once. Your agent then calls POST `/fhir/R4/{resourceType}` with the resource body, optionally validating it first with the $validate operation. To run it on your own infrastructure, install Jentic One from its GitHub repo.