{"openapi":"3.0.3","info":{"title":"FUME Enterprise API","version":"3.0.3","description":"FHIR-Utilized Mapping Engine - Enterprise edition.\n\nEvaluate ad-hoc FUME expressions, manage saved mappings, and generate/list templates."},"tags":[{"name":"Server","description":"General server metadata endpoints."},{"name":"Evaluation","description":"Ad-hoc evaluation endpoints."},{"name":"Health","description":"Liveness/readiness endpoints."},{"name":"Cache","description":"Cache and mapping refresh endpoints."},{"name":"Mapping","description":"Saved mapping retrieval and execution endpoints."},{"name":"Template","description":"Template generation and listing endpoints."}],"servers":[{"url":"/","description":"Current server"}],"components":{"schemas":{"ServerInfo":{"type":"object","properties":{"fume_version":{"type":"string","example":"FUME Enterprise 3.0.3"},"fhir_server":{"type":"string","example":"http://hapi-fhir:8080/fhir"},"uptime":{"type":"string","example":"2 days, 15 hours, 57 minutes and 26 seconds"},"context_packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"hl7.fhir.r4.core"},"version":{"type":"string","example":"4.0.1"}}}},"warming_up":{"type":"boolean","example":false},"warming_up_enabled":{"type":"boolean","example":true},"warming_up_started_at":{"type":"string","format":"date-time","example":"2026-03-30T10:21:47.762Z"},"warming_up_finished_at":{"type":"string","format":"date-time","example":"2026-03-30T10:23:12.101Z"},"warming_up_error":{"type":"string","example":"Warmup failed: example error message"},"licensed_to":{"type":"string","example":"Example Organization Ltd."},"licensed_until":{"type":"string","format":"date"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"UP"},"warming_up":{"type":"boolean","example":false},"warming_up_enabled":{"type":"boolean","example":true},"warming_up_started_at":{"type":"string","format":"date-time","example":"2026-03-30T10:21:47.762Z"},"warming_up_finished_at":{"type":"string","format":"date-time","example":"2026-03-30T10:23:12.101Z"},"warming_up_error":{"type":"string","example":"Warmup failed: example error message"}},"required":["status"]},"DiagnosticsObject":{"type":"object","properties":{"error":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}},"warning":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}},"debug":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}}},"required":["error","warning","debug"]},"Diagnostic":{"type":"object","description":"A single diagnostic entry emitted during evaluation/validation.","additionalProperties":false,"properties":{"code":{"type":"string","example":"F5120"},"position":{"type":"integer","example":57},"start":{"type":"integer","example":52},"line":{"type":"integer","example":2},"instanceOf":{"type":"string","example":"Patient"},"fhirElement":{"type":"string","example":"extension[data-absent-reason].value"},"bindingStrength":{"type":"string","example":"required"},"expansionMode":{"type":"string","example":"full"},"value":{"description":"The value that triggered the diagnostic (may be any JSON type)."},"message":{"type":"string","example":"Value \"abc\" for \"extension[data-absent-reason].value\" in \"Patient\" is not in the required ValueSet."},"severity":{"type":"integer","example":12},"level":{"type":"string","example":"invalid"},"timestamp":{"type":"integer","format":"int64","example":1771327039703}}},"VerboseReport":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"status":{"type":"integer","description":"HTTP-like status code of the evaluation result (e.g. 200, 206)","example":206},"result":{"description":"The raw evaluation result"},"diagnostics":{"$ref":"#/components/schemas/DiagnosticsObject"},"executionId":{"type":"string"}}},"FumeError":{"type":"object","description":"Structured FUME error payload returned on compilation/evaluation failures.","properties":{"__isFumeError":{"type":"boolean"},"__isFlashError":{"type":"boolean"},"message":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"token":{"type":"string"},"cause":{"type":"string"},"line":{"oneOf":[{"type":"string"},{"type":"integer"}]},"start":{"oneOf":[{"type":"string"},{"type":"integer"}]},"position":{"oneOf":[{"type":"string"},{"type":"integer"}]}},"example":{"__isFumeError":true,"__isFlashError":false,"message":"Missing expression after \":\". Objects must contain only key-value pairs","code":"F1101","name":"","value":"","token":":","cause":"","line":1,"start":6,"position":7}},"RecacheResponse":{"type":"object","description":"Recache result describing what was loaded into cache.","properties":{"message":{"type":"string","example":"The following Mappings were loaded to cache"},"mappings":{"type":"array","items":{"type":"string"},"description":"List of mapping keys loaded into cache"}},"example":{"message":"The following Mappings were loaded to cache","mappings":["Patient12","exampleForRepo"]}},"RecacheResponseDeprecated":{"type":"object","description":"Recache result for the deprecated POST /recache endpoint, which includes a deprecation warning.","properties":{"message":{"type":"string","example":"The following Mappings were loaded to cache"},"mappings":{"type":"array","items":{"type":"string"},"description":"List of mapping keys loaded into cache"},"deprecated":{"type":"boolean","description":"Whether the recache endpoint is deprecated (will emit a warning if true)"}},"example":{"message":"The following Mappings were loaded to cache","mappings":["Patient12","exampleForRepo"],"deprecated":true}},"EnterpriseMessage":{"type":"object","description":"Generic message payload used by enterprise-only endpoints.","additionalProperties":false,"properties":{"message":{"type":"string","description":"Human-readable message. May be a string or a structured error object."}},"required":["message"]},"TemplateIdList":{"type":"array","items":{"type":"string"},"description":"List of available template IDs."}},"parameters":{"verbose":{"name":"verbose","in":"query","required":false,"description":"When set to `true` (case-insensitive) or `1`, returns the full evaluation report instead of the raw result.","schema":{"type":"string"}}}},"paths":{"/":{"get":{"tags":["Server"],"summary":"Server info","description":"Returns basic server information including version, configured FHIR server, uptime, and loaded context packages.","operationId":"getServerInfo","responses":{"200":{"description":"Server info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerInfo"}}}}}},"post":{"tags":["Evaluation"],"summary":"Evaluate ad-hoc expression","description":"Evaluate an ad-hoc FUME expression. The request body can be a JSON object with `fume` (required), `input`, and `contentType` fields.","operationId":"evaluateExpression","parameters":[{"$ref":"#/components/parameters/verbose"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fume"],"properties":{"fume":{"type":"string","description":"FUME expression to evaluate","example":"{ resourceType: id }"},"input":{"description":"Input data for the expression","example":{"resourceType":"Patient","id":"123"}},"contentType":{"type":"string","description":"Content type for input conversion","example":"application/json"}}},"examples":{"validRequest":{"summary":"Valid request","value":{"fume":"{ resourceType: id }","input":{"resourceType":"Patient","id":"123"},"contentType":"application/json"}},"invalidRequest":{"summary":"Invalid request (missing fume)","value":{"input":{"resourceType":"Patient","id":"123"},"contentType":"application/json"}},"invalidRequest2":{"summary":"Invalid request (invalid fume)","value":{"fume":"{ resourceType: id ","input":{"resourceType":"Patient","id":"123"},"contentType":"application/json"}},"invalidRequest3":{"summary":"Invalid request (unsupported content type)","value":{"fume":"{ resourceType: id }","input":{"resourceType":"Patient","id":"123"},"contentType":"application/invalid"}},"partialResult":{"summary":"Partial result (with diagnostics)","value":{"fume":"InstanceOf: Patient\\n* extension[data-absent-reason].value = \"abc\""}}}}}},"responses":{"200":{"description":"Evaluation result","content":{"application/json":{"schema":{},"examples":{"result":{"summary":"Response","value":{"Patient":"123"}}}}}},"206":{"description":"Partial evaluation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerboseReport"}}}},"400":{"description":"Missing or empty `fume` expression","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FumeError"}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}},{"$ref":"#/components/schemas/VerboseReport"}]},"examples":{"unsupportedMediaType":{"summary":"Unsupported media type","value":{"message":"Unsupported Content-Type: 'application/invalid'","code":"UNSUPPORTED_MEDIA_TYPE"}},"verboseUnsupportedMediaType":{"summary":"Unsupported media type (verbose mode)","value":{"ok":false,"status":415,"diagnostics":{"error":[{"code":"UNSUPPORTED_MEDIA_TYPE","message":"Unsupported content-type","severity":1,"level":"error","timestamp":1771328556787}],"warning":[],"debug":[]},"executionId":"4362008e-3736-4510-94a2-f9969a0565c9"}}}}}},"422":{"description":"Expression compilation or evaluation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FumeError"}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Health probe","description":"Health check endpoint for load balancers and liveness/readiness probes.","operationId":"healthCheck","responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/$recache":{"post":{"tags":["Cache"],"summary":"Reload mappings","description":"Reloads mappings and aliases from the configured sources into cache. Flushes the ConceptMap cache. Available only when at least one mapping source is configured.","operationId":"recache","responses":{"200":{"description":"Mappings reloaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecacheResponse"}}}},"405":{"description":"Method not allowed. No mapping sources configured."},"500":{"description":"Cache could not be refreshed"}}}},"/recache":{"get":{"tags":["Cache"],"summary":"Recache (method not allowed)","description":"Recache has side-effects, so GET is no longer supported. Use `POST /$recache` instead.","operationId":"recacheGetDisabled","deprecated":true,"responses":{"405":{"description":"Method not allowed. Use POST /$recache."}}},"post":{"tags":["Cache"],"summary":"Reload mappings (deprecated)","description":"Same as `POST /$recache`, but deprecated. Emits a warning in logs and a Warning response header. Will be removed in future releases.","operationId":"recacheDeprecated","deprecated":true,"responses":{"200":{"description":"Mappings reloaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecacheResponseDeprecated"}}}},"405":{"description":"Method not allowed. No mapping sources configured."},"500":{"description":"Cache could not be refreshed"}}}},"/Mapping/{mappingId}":{"put":{"tags":["Mapping"],"summary":"Create or update mapping expression","description":"Creates or updates a saved mapping expression in the configured primary writable store (file or FHIR server).\n\nReturns the stored mapping expression as `application/vnd.outburn.fume`. Responds with 201 when a new mapping is created, and 200 when an existing mapping is updated.","operationId":"upsertMappingExpression","parameters":[{"name":"mappingId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the mapping to create or update."}],"requestBody":{"required":true,"description":"The FUME mapping expression (source).","content":{"application/vnd.outburn.fume":{"schema":{"type":"string"},"examples":{"exampleMapping":{"summary":"Example mapping expression","value":"InstanceOf: Patient\n* name.text = first_name & \" \" & last_name\n"}}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Mapping updated successfully.","content":{"application/vnd.outburn.fume":{"schema":{"type":"string"}}}},"201":{"description":"Mapping created successfully.","content":{"application/vnd.outburn.fume":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request (missing/invalid mapping id or empty mapping expression).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"}}}},"409":{"description":"Writes are disabled or server configuration does not allow updates (no writable store configured).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"}}}}}},"delete":{"tags":["Mapping"],"summary":"Delete saved mapping","description":"Deletes a saved mapping from the configured primary writable store (file or FHIR server).\n\nThis does not clear compiled expression caches; mapping resolution is provider-driven.","operationId":"deleteMapping","parameters":[{"name":"mappingId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the mapping to delete."}],"responses":{"200":{"description":"Mapping deleted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"},"examples":{"deleted":{"summary":"Deleted response","value":{"message":"Mapping: ExampleMapping was deleted."}}}}}},"400":{"description":"Invalid request (missing or invalid mapping id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"}}}},"404":{"description":"Mapping not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"},"examples":{"notFound":{"summary":"Not found response","value":{"message":"Mapping: ExampleMapping was not found."}}}}}},"409":{"description":"Writes are disabled or server configuration does not allow deletes (no writable store configured).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"}}}}}},"get":{"tags":["Mapping"],"summary":"Fetch mapping expression","description":"Fetches the FUME expression for a saved mapping.","operationId":"getMappingExpression","parameters":[{"name":"mappingId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the saved mapping"}],"responses":{"200":{"description":"Mapping expression (FUME source)","content":{"application/vnd.outburn.fume":{"schema":{"type":"string"},"examples":{"exampleMapping":{"summary":"Example mapping expression","value":"// Example FUME mapping expression\nInstanceOf: Patient\n* name.text = first_name & ' ' & last_name\n"}}}}},"404":{"description":"Mapping not found"}}},"post":{"tags":["Mapping"],"summary":"Execute saved mapping","description":"Invokes the saved mapping transform. The request body is treated as the input, converted according to the request Content-Type.","operationId":"executeMappingById","parameters":[{"name":"mappingId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the saved mapping"},{"$ref":"#/components/parameters/verbose"}],"requestBody":{"description":"Input data for the mapping","content":{"application/json":{"schema":{"type":"object"}},"application/fhir+json":{"schema":{"type":"object"}},"application/xml":{"schema":{"type":"string"}},"application/fhir+xml":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"x-application/hl7-v2+er7":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Mapping result (any JSON). When `?verbose` is enabled, returns a VerboseReport."},"206":{"description":"Partial result"},"404":{"description":"Mapping not found"},"415":{"description":"Unsupported media type"},"422":{"description":"Compilation, transform, or evaluation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FumeError"}}}}}}},"/Mapping/{mappingId}/{subroute}":{"post":{"tags":["Mapping"],"summary":"Execute saved mapping with subroutes","description":"Same as `POST /Mapping/{mappingId}`, but path segments after the mapping ID are captured as routing metadata and exposed via `$fumeHttpInvocation`.\nOpenAPI cannot model Express-style multi-segment wildcard routes. The actual server route supports an arbitrary number of path segments after `{mappingId}` (e.g. `POST /Mapping/{mappingId}/a/b/123`).\nThis path is documented with a single `{subroute}` segment for documentation purposes only. Swagger UI \"Try it out\" (and many generated clients) cannot reliably invoke the multi-segment form.","operationId":"executeMappingWithSubroutes","parameters":[{"name":"mappingId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the saved mapping"},{"name":"subroute","in":"path","required":true,"schema":{"type":"string"},"description":"Documentation-only placeholder for the wildcard route remainder. For real multi-segment usage, call the endpoint as `/Mapping/{mappingId}/...` with one or more additional path segments (e.g. `/Mapping/{mappingId}/a/b/123`)."},{"$ref":"#/components/parameters/verbose"}],"requestBody":{"description":"Input data for the mapping","content":{"application/json":{"schema":{"type":"object"}},"application/fhir+json":{"schema":{"type":"object"}},"application/xml":{"schema":{"type":"string"}},"application/fhir+xml":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"x-application/hl7-v2+er7":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Mapping result (any JSON). When `?verbose` is enabled, returns a VerboseReport."},"206":{"description":"Partial result"},"404":{"description":"Mapping not found"},"415":{"description":"Unsupported media type"},"422":{"description":"Compilation, transform, or evaluation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FumeError"}}}}}},"put":{"tags":["Mapping"],"summary":"Execute saved mapping with subroutes (PUT)","description":"Same as the POST subroute form, but with method PUT. Transform is invoked only when there is at least one path segment after the mapping ID. `PUT /Mapping/{mappingId}` without subroutes is reserved for mapping updates.","operationId":"executeMappingWithSubroutesPut","parameters":[{"name":"mappingId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the saved mapping"},{"name":"subroute","in":"path","required":true,"schema":{"type":"string"},"description":"Documentation-only placeholder for the wildcard route remainder (required for PUT transforms). Use one or more additional path segments after `{mappingId}` when invoking manually."},{"$ref":"#/components/parameters/verbose"}],"requestBody":{"description":"Input data for the mapping","content":{"application/json":{"schema":{"type":"object"}},"application/fhir+json":{"schema":{"type":"object"}},"application/xml":{"schema":{"type":"string"}},"application/fhir+xml":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"x-application/hl7-v2+er7":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Mapping result (any JSON). When `?verbose` is enabled, returns a VerboseReport."},"206":{"description":"Partial result"},"404":{"description":"Mapping not found"},"415":{"description":"Unsupported media type"},"422":{"description":"Compilation, transform, or evaluation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FumeError"}}}}}}},"/Template/{templateId}":{"get":{"tags":["Template"],"summary":"Get template or template list","description":"Returns a generated template for a given template id.\n\nWhen `templateId` is `$list`, returns a JSON array of available template IDs filtered by optional `type`.","operationId":"getTemplate","parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"},"description":"Template identifier. Use `$list` to retrieve a list of template IDs."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["profile","resource","datatype","extension"]},"description":"Only used when `templateId` is `$list`. Filters the returned list to a template category. When omitted, the server returns an empty list."}],"responses":{"200":{"description":"Template content or list. Content type depends on `templateId`: `$list` returns JSON, other template IDs return `application/vnd.outburn.fume`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateIdList"},"examples":{"list":{"summary":"Example list response","value":["Patient","Observation","Encounter"]}}},"application/vnd.outburn.fume":{"schema":{"type":"string"},"examples":{"template":{"summary":"Example template","value":"// Template source (FUME)\nInstanceOf: Patient\n* id = \"example\"\n"}}}}},"400":{"description":"Invalid request (missing template id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"},"examples":{"missingTemplateId":{"summary":"Missing template id","value":{"message":"Template id is required"}}}}}},"500":{"description":"Internal server error (including invalid template list type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterpriseMessage"},"examples":{"invalidTemplateType":{"summary":"Invalid template list type","value":{"message":"Invalid template type 'foo'!"}}}}}}}}}}}