Document FHIR operation routes and match modes

skylightis666 · skylightis666 · commit f7046492f05d · 2026-06-30T18:54:48.000+03:00
Update API docs for /api/fhir operation paths, R4/R6 match route behavior, TEFCA mode, and default FHIR release.

Point Aidbox subscription links to the Health Samurai docs site and keep absolute-link lint focused on the legacy docs domain.
diff --git a/docs-lint.yaml b/docs-lint.yaml
@@ -6,3 +6,6 @@ checks:
   warn_only:
     - title-mismatch
     - absolute-links
+  absolute-links:
+    domains:
+      - docs.aidbox.app
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -57,17 +57,36 @@ so any valid authenticated `User` or `Client` can call them. Responses omit
 | --- | --- | --- |
 | `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 the R4 operation implementation |
+| `POST` | `/api/fhir/r4/:resource/:id/$match` | Match an existing resource by ID using the R4 operation implementation |
+| `POST` | `/api/fhir/r6/:resource/$match` | Match a resource using the R6 operation implementation |
+| `POST` | `/api/fhir/r6/:resource/:id/$match` | Match an existing resource by ID using the R6 operation implementation |
+
+The unversioned routes use the release selected by
+`MDMBOX_DEFAULT_FHIR_RELEASE`.
 
 See [Find duplicates: $match](match-operation.md).
 
 ### $merge
 
 | Method | Path | Description |
 | --- | --- | --- |
-| `POST` | `/api/$merge` | Execute or preview a merge |
+| `POST` | `/api/fhir/$merge` | Execute or preview a merge |
 
 See [Merge operation](merge-operation.md).
 
+### $unmerge
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `POST` | `/api/fhir/$unmerge` | Reverse a previous merge from its merge Task |
+
+### $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 |
+
 ### $referencing
 
 | Method | Path | Description |
diff --git a/docs/config-reference.md b/docs/config-reference.md
@@ -40,6 +40,8 @@ endpoints and the Admin UI:
 | Variable | Description | Default |
 | --- | --- | --- |
 | `MDMBOX_MATCH_DEFAULT_COUNT` | Default maximum number of `$match` results when the request omits `count`. | `10` |
+| `MDMBOX_TEFCA_MODE` | Enable R4 TEFCA `$match` behavior. When enabled, potential-match responses (`onlyCertainMatches=false`) return no more than 100 entries. | unset (`false`) |
+| `MDMBOX_DEFAULT_FHIR_RELEASE` | FHIR release used by unversioned `/api/fhir/:resource/...` routes. Accepted values: `4.0.1` and `6.0.0`. | `6.0.0` |
 
 ## Database
 
diff --git a/docs/match-operation.md b/docs/match-operation.md
@@ -15,6 +15,12 @@ type `searchset`. MDMbox generalizes the operation to any configured FHIR
 resource type and adds `modelId` and `threshold` parameters so callers can choose
 the matching model and score cutoff.
 
+Unversioned routes such as `/api/fhir/Patient/$match` use the FHIR release
+selected by `MDMBOX_DEFAULT_FHIR_RELEASE`. Versioned routes are also available
+as `/api/fhir/r4/:resource/$match` and `/api/fhir/r6/:resource/$match`.
+Instance-level matching is available at
+`/api/fhir/r4/:resource/:id/$match` and `/api/fhir/r6/:resource/:id/$match`.
+
 ## Match a resource
 
 Send a FHIR Parameters resource containing the record to match:
@@ -66,36 +72,50 @@ will not be returned as its own match.
 
 ## Parameters
 
-### Request body parameters (FHIR Parameters)
+### Common request body parameters
 
 | Name | Type | Required | Description |
 | --- | --- | --- | --- |
 | `modelId` | valueString | Yes | ID of the MatchingModel to use |
 | `resource` | resource | Only for `/api/fhir/:resource/$match` | The FHIR resource to find matches for. Omit this parameter when matching an existing resource by ID. |
-| `threshold` | valueDecimal | No | Override the model's `probable` threshold |
-| `onlyCertainMatches` | valueBoolean | No | Only return matches above the `certain` threshold |
-| `onlySingleMatch` | valueBoolean | No | Return the single most appropriate match |
-| `count` | valueInteger | No | Maximum number of results (default: 10) |
+| `threshold` | valueDecimal | No | Override the model's `probable` threshold in normal potential-match mode. Cannot be combined with `onlyCertainMatches`. |
+| `count` | valueInteger | No | Maximum number of returned entries (default: 10). `Bundle.total` still reports the full number of matches above the effective threshold. |
 
 The default `count` is controlled by `MDMBOX_MATCH_DEFAULT_COUNT` and is `10`
-unless configured otherwise. When `onlyCertainMatches=false`, MDMbox returns no
-more than 100 potential matches.
+unless configured otherwise.
+
+### R6 flag behavior
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `onlyCertainMatches` | valueBoolean | Sets the effective threshold to the model's `certain` threshold. Cannot be combined with `threshold` or `onlySingleMatch`. `count` still applies. |
+| `onlySingleMatch` | valueBoolean | Returns one best candidate. Cannot be combined with `threshold`, `count`, or `onlyCertainMatches`. |
+
+In normal R6 mode, MDMbox uses `threshold` when supplied, otherwise the model's
+`probable` threshold. There is no 100-entry TEFCA cap for R6.
+
+In R6 `onlySingleMatch=true` mode, MDMbox asks the server-side matching
+algorithm to designate one best candidate. If several candidates are eligible,
+MDMbox returns the highest-scored one; if scores are tied, MDMbox uses resource
+ID as a stable tie-breaker. If no candidate is eligible, the response is an
+empty searchset.
+
+### R4 flag behavior
 
-### Flag behavior
+| Name | Type | Description |
+| --- | --- | --- |
+| `onlyCertainMatches` | valueBoolean | Sets the effective threshold to the model's `certain` threshold. Cannot be combined with `threshold`. `count` still applies. |
 
-`onlyCertainMatches=true` returns only candidates above the model's `certain`
-threshold. If `threshold` is also provided, MDMbox uses the stricter of the two
-values.
+R4 routes do not implement `onlySingleMatch`; use an R6 route when that behavior
+is required.
 
-`onlySingleMatch=true` returns the single most appropriate candidate above the
-effective `certain` threshold. If more than one candidate passes, MDMbox returns
-the highest-scored candidate. If scores are tied, MDMbox uses resource ID as a
-stable tie-breaker. If no candidate passes, the response is an empty searchset.
-`onlySingleMatch` ignores `count`.
+In normal R4 potential-match mode (`onlyCertainMatches` omitted or `false`),
+MDMbox uses `threshold` when supplied, otherwise the model's `probable`
+threshold.
 
-`count` limits the number of returned entries for normal matching and
-`onlyCertainMatches=true`. In normal potential-match mode, MDMbox also applies a
-100-result safety cap even when `count` is larger.
+When `MDMBOX_TEFCA_MODE=true`, R4 potential-match responses return no more than
+100 entries, even when `count` is larger. The TEFCA cap is not applied when
+`onlyCertainMatches=true`.
 
 ## Response
 
diff --git a/docs/merge-operation.md b/docs/merge-operation.md
@@ -16,7 +16,7 @@ The `$merge` operation merges two FHIR resources by executing a client-provided
 ## Request
 
 ```http
-POST https://<mdmbox-host>/api/$merge
+POST https://<mdmbox-host>/api/fhir/$merge
 Content-Type: application/json
 ```
 
diff --git a/docs/notifications.md b/docs/notifications.md
@@ -4,7 +4,7 @@ description: Subscribe to merge and unmerge events using Aidbox Topic-Based Subs
 
 # Notifications
 
-After a `$merge` or `$unmerge` operation completes, external systems often need to react — update search indexes, sync to a data warehouse, trigger workflows. MDMbox supports this via [Aidbox Topic-Based Subscriptions](https://docs.aidbox.app/modules/topic-based-subscriptions/aidbox-topic-based-subscriptions), a built-in publish/subscribe mechanism that delivers events to webhooks, Kafka, GCP Pub/Sub, and other destinations.
+After a `$merge` or `$unmerge` operation completes, external systems often need to react — update search indexes, sync to a data warehouse, trigger workflows. MDMbox supports this via [Aidbox Topic-Based Subscriptions](https://www.health-samurai.io/docs/aidbox/modules/topic-based-subscriptions/aidbox-topic-based-subscriptions), a built-in publish/subscribe mechanism that delivers events to webhooks, Kafka, GCP Pub/Sub, and other destinations.
 
 ## How it works
 
@@ -93,4 +93,4 @@ Defines the delivery target and parameters. Example using a webhook with at-leas
 | `topic` | Canonical URL of the AidboxSubscriptionTopic to subscribe to |
 | `parameter` | Destination-specific settings (endpoint URL, batch size, timeout, etc.) |
 
-See [Aidbox Topic-Based Subscriptions docs](https://docs.aidbox.app/modules/topic-based-subscriptions/aidbox-topic-based-subscriptions) for the full list of destination kinds and their parameters.
+See [Aidbox Topic-Based Subscriptions docs](https://www.health-samurai.io/docs/aidbox/modules/topic-based-subscriptions/aidbox-topic-based-subscriptions) for the full list of destination kinds and their parameters.
