Execution patterns

Choose the execution endpoint based on where the mapping logic lives, how much control the caller should have over that logic, and whether the mapping needs route-aware HTTP context.

Endpoint selection matrix

Integration goal	Endpoint	Typical request shape	Use it when
Evaluate a caller-supplied expression	`POST /`	JSON envelope with `fume`, optional `input`, optional `contentType`	The client owns the mapping text for this request.
Execute a published mapping by ID	`POST /Mapping/{mappingId}`	Runtime payload in its native format plus an HTTP `Content-Type` header	The deployment owns the mapping and the client should only send business input.
Add route-aware behavior to a saved mapping	`POST /Mapping/{mappingId}/{subroute...}` or `PUT /Mapping/{mappingId}/{subroute...}`	Same input as a saved mapping call, plus path segments and query parameters	One mapping needs to branch on path, method, query, or sanitized headers.
Return diagnostics with the result	`?verbose=true` on supported execution endpoints	Any supported execution request plus the `verbose` query parameter	The caller needs `status`, `diagnostics`, and `executionId`, not just the raw result.

Community + Enterprise

Community and Enterprise share the same execution model. Ad-hoc POST / is always available, while every /Mapping/* execution route depends on at least one configured mapping source through FHIR_SERVER_BASE or MAPPINGS_FOLDER.

Use `POST /` for ad-hoc evaluation

Call POST / when the mapping logic belongs to the caller or the current request, not to the server's saved-mapping catalog.

This is the right endpoint for rapid experiments, preview flows, diagnostics, and any workflow where you want to inspect what FUME sees before you publish a reusable mapping.

{
  "fume": "InstanceOf: Patient\n* active = true",
  "input": {
    "given": "Ada",
    "family": "Lovelace"
  },
  "contentType": "application/json"
}

fume is the mapping expression itself. If you are new to the language, start with the FUME language guide.
input is optional. If you omit it, the expression evaluates against null.
contentType tells the server how to normalize input before evaluation.
fume: "$" is the simplest way to inspect normalized input before you write a real mapping.

Use POST / when the caller needs maximum flexibility. If the mapping should become part of the server's managed behavior, move it into a saved mapping and call the mapping endpoint instead.

Use `POST /Mapping/{mappingId}` for published mappings

Call POST /Mapping/{mappingId} when the deployment owns the mapping and the caller should address it through a stable identifier.

This pattern works well for repeatable integration flows, exported Playground mappings, and operational pipelines where the mapping should be versioned and managed independently from the client code.

The server resolves mappingId from its configured mapping sources before it evaluates the request.
The request body is the mapping input itself, not a JSON envelope around fume.
The HTTP Content-Type header controls how that body is normalized before evaluation.
If no mapping sources are configured, the entire /Mapping/* surface is unavailable and returns 405.
If mapping sources exist but the requested mapping does not, the server returns 404.

Use this endpoint when you want the request contract to stay stable while the mapping evolves under deployment control.

Use subroutes when one mapping needs route-aware behavior

Call a routed mapping endpoint when one saved mapping must behave like a small HTTP adapter instead of a single fixed transform.

POST /Mapping/{mappingId}/{subroute...} and PUT /Mapping/{mappingId}/{subroute...} execute the same saved mapping pattern as the base mapping route, but they also inject $fumeHttpInvocation into the mapping so the expression can react to the HTTP context.

That binding includes the mapping ID, request method, the captured subroute segments, the joined subpath, parsed query parameters, and sanitized headers.

Use subroutes when the mapping needs to branch on route structure or request metadata, for example when you are building interceptors, webhook-style adapters, or endpoint families that share one mapping implementation.

POST /Mapping/{mappingId} still provides $fumeHttpInvocation, but subroute is empty and subpath is an empty string.
PUT /Mapping/{mappingId} without any extra path segment is not a transform route. The base PUT path is reserved for mapping updates.
The OpenAPI contract documents the wildcard route with a single placeholder segment because OpenAPI cannot fully model the multi-segment Express route shape.

Use `verbose=true` when diagnostics matter to the caller

By default, successful execution endpoints return the raw result. Handled failures return a simpler error payload.

Add ?verbose=true or ?verbose=1 when the caller needs the full execution report instead of the default result-only behavior.

Verbose mode is supported on:

POST /
POST /Mapping/{mappingId}
POST /Mapping/{mappingId}/{subroute...}
PUT /Mapping/{mappingId}/{subroute...}

The verbose response keeps the evaluation result together with the execution status, diagnostic arrays, and the server-generated execution ID.

{
  "ok": true,
  "status": 200,
  "result": {},
  "diagnostics": {
    "error": [],
    "warning": [],
    "debug": []
  },
  "executionId": "..."
}

Verbose mode also normalizes early failures that happen before evaluation, such as a missing fume expression, an unsupported media type, or a missing saved mapping. In those cases the server returns a synthetic verbose report instead of the default error body.

Content-type conversion is part of the endpoint choice

Both execution styles run mappings against JSON, but they accept different request shapes before normalization.

Endpoint pattern	Where the content type is declared	What gets normalized
`POST /`	The `contentType` field inside the JSON request body	The value of `input`
`POST /Mapping/{mappingId}` and routed mapping execution	The HTTP `Content-Type` request header	The entire request body

Supported runtime formats include JSON, FHIR JSON, XML, FHIR XML, CSV, and HL7 v2.

If the declared content type is not supported, the request fails with 415.

Use the Input formats overview when you need to understand how those bodies are normalized before evaluation. The format-specific pages are especially useful when you are working with CSV input or HL7 v2 input.

Use the product-specific entries under OpenAPI when you need the exact request and response contract.

Endpoint selection matrix​

Use POST / for ad-hoc evaluation​

Use POST /Mapping/{mappingId} for published mappings​

Use subroutes when one mapping needs route-aware behavior​

Use verbose=true when diagnostics matter to the caller​

Content-type conversion is part of the endpoint choice​