API reference
The /api/* paths below are available directly on MDMbox or through App/mdmbox on Aidbox. When MDMBOX_API_AIDBOX_APP_ONLY=true, use the Aidbox host and grant access with Aidbox AccessPolicies. Use API authentication for protected endpoints. For FHIR resource management, use the Aidbox REST API on the Aidbox host at /fhir.
Open /api/docs for Swagger UI or /api/openapi.json for the full specification and request schemas. The specification reports the running image version.
The mdm helpers supplied to server-side scripts are documented separately in the JavaScript algorithm API.
Infrastructure
| Method | Path | Description |
|---|---|---|
GET | /healthz | Liveness check |
GET | /readyz | Readiness check |
GET | /api/docs | Swagger UI |
GET | /api/openapi.json | OpenAPI specification |
Call /healthz and /readyz directly on the MDMbox host; App/mdmbox does not expose these probes through Aidbox. /readyz returns HTTP 200 when ready, otherwise 503. Its JSON body contains status and the individual checks.db and checks.fhir results.
Both probes remain available before license activation and while a running instance is restricted by its license. A successful probe does not indicate that the license is active. See License configuration.
Matching models
| Method | Path | Description |
|---|---|---|
GET | /api/models | List all models (optional ?resource=Patient) |
POST | /api/models | Create a model |
GET | /api/models/:id | Get model by ID |
PUT | /api/models/:id | Update model |
DELETE | /api/models/:id | Delete model |
These endpoints manage MatchingModel resources. Manage BulkMatchingModel through the Admin UI or the Aidbox FHIR API.
FHIR operations
$match
| Method | Path | Description |
|---|---|---|
POST | /api/fhir/:resource/$match | Match a resource (FHIR Parameters body) |
POST | /api/fhir/:resource/:id/$match | Match existing resource by ID |
POST | /api/fhir/r4/:resource/$match | Match a resource using FHIR R4 |
POST | /api/fhir/r4/:resource/:id/$match | Match an existing resource using FHIR R4 |
POST | /api/fhir/r6/:resource/$match | Match a resource using FHIR R6 |
POST | /api/fhir/r6/:resource/:id/$match | Match an existing resource using FHIR R6 |
The unversioned routes use the release selected by MDMBOX_DEFAULT_FHIR_RELEASE.
Merge lifecycle
| Method | Path | Description |
|---|---|---|
POST | /api/fhir/$merge/v2 | Server-managed merge |
POST | /api/fhir/$unmerge/v2 | Server-managed unmerge |
POST | /api/fhir/$merge | Client-plan merge |
POST | /api/fhir/$unmerge | Client-plan unmerge |
See Merge operation and Unmerge operation.
Link lifecycle
| Method | Path | Description |
|---|---|---|
POST | /api/fhir/$link | Execute or preview a link plan |
POST | /api/fhir/$unlink | Reverse a previous link from its link Task |
See Link operation and Unlink operation.
$mark-not-a-match
| Method | Path | Description |
|---|---|---|
POST | /api/fhir/$mark-not-a-match | Record that two resources are not the same real-world entity |
See Mark not a match for the request, response, and effect on matching and merging.
$referencing
| Method | Path | Description |
|---|---|---|
POST | /api/fhir/:resource/:id/$referencing | Find resources referencing a given resource |
Matching
Bulk matching
All bulk match endpoints are scoped to a BulkMatchingModel by ID.
| Method | Path | Description |
|---|---|---|
GET | /api/bulk-match/:model-id/status | Get preparation state and active or latest non-archived job progress |
GET | /api/bulk-match/:model-id/status/:job-id | Get a specific job's progress, including archived jobs |
POST | /api/bulk-match/:model-id/start | Prepare data if needed and start a job (body: {batchSize, workersCount, refreshSourceData}) |
POST | /api/bulk-match/:model-id/stop | Stop job (?force=true for immediate cancellation) |
POST | /api/bulk-match/:model-id/continue | Resume a stopped job |
POST | /api/bulk-match/:model-id/archive | Archive a completed or stopped job |
GET | /api/bulk-match/:model-id/result | Export the latest completed or stopped job |
GET | /api/bulk-match/:model-id/result/:job-id | Export a specific job of this model |
Commands and status return FHIR Parameters; errors use OperationOutcome. Both result routes accept Accept: text/csv or Accept: application/x-ndjson (default), and an optional decisionStatus filter. See Bulk matching.
Continuous matching
Continuous status includes pendingChanges and appliedChanges as whole-number valueDecimal parameters. They count captured events awaiting application and events applied since the latest build or reset. Several events can refer to one record. See Continuous matching for the separate application and matching progress shown in the admin UI.
| Method | Path | Description |
|---|---|---|
POST | /api/continuous-match/:model-id/start | Start, resume, or rebuild after a model change |
POST | /api/continuous-match/:model-id/pause | Pause while keeping progress and results |
POST | /api/continuous-match/:model-id/retry | Requeue failed batches |
GET | /api/continuous-match/:model-id/status | Get process status and counts |
GET | /api/continuous-match/:model-id/result | Export current pairs |
DELETE | /api/continuous-match/:model-id | Reset a paused process, keeping the model and source records |
Commands and status return FHIR Parameters; errors use OperationOutcome. Results support CSV, NDJSON, and paginated JSON with a decisionStatus filter. See Continuous matching for parameters and limits.
Admin UI
The admin interface is available through Aidbox at /mdmbox/admin. It provides:
/mdmbox/admin— model management (create, edit, delete MatchingModel and BulkMatchingModel)/mdmbox/admin/bulk-match— Bulk matching (start, monitor, download, stop)/mdmbox/admin/continuous-match— Continuous matching (start, pause, retry, download, reset)
The Algorithms section manages merge and unmerge scripts and their Git sources. See Algorithm management.