> ## Documentation Index > Fetch the complete documentation index at: https://docs.haau3.com/llms.txt > Use this file to discover all available pages before exploring further. # Structure a prescription's directions as a FHIR Dosage > FHIR system-level operation `$structure-dosage`. POST a Parameters resource with one `text` part, a prescription's directions as written, at most 1,000 characters, and optionally one `medication` part, the medication's codings as a CodeableConcept (RxNorm or NDC). The answer is a Parameters resource with one `dosage` part: a FHIR Dosage conforming to haau3 Structured Dosage, whose `text` is the directions exactly as sent and whose dose and unit, route, method, timing and as-needed elements are coded where the words support them, in SNOMED CT (Global Patient Set concepts only), NCIt and UCUM. Nothing is invented: an element the directions do not support is absent. Anything a person should check is a review flag on the Dosage, an extension with a code from `https://haau3.com/fhir/CodeSystem/structured-sig-review-flag` and, when the flag is about words, those words. Every Dosage names the engine and vocabulary versions it was written under, and the RxNorm release when the medication's code was looked up. With an RxNorm code, the product's dose form checks the dose's unit and the route, and supplies either when the directions name none, each flagged. Send the directions and the medication's codings only, never a patient's name or identifiers. Nothing a request carries is stored or logged, apart from the request's ids, and every answer is sent with `Cache-Control: no-store`. The operation takes no query parameters, and may be sent inside a batch, one request per entry. The contract is published at https://fhir.haau3.com/OperationDefinition-structure-dosage.html. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/fhir/r4/$structure-dosage openapi: 3.1.0 info: title: haau3 Platform API version: 1.0.0-preview.23 description: >- The haau3 platform API is in preview: it may change as we build, usually to add features or improve performance. Endpoints require an API key, sent as `Authorization: Bearer `. Requests without a valid key return 401. Create a key in the dashboard at https://platform.haau3.com; a new organization starts on the free Developer plan. From 2026-11-02 a request past one of its plan's limits (requests a minute on every plan, requests a month on Developer) returns 429 with `Retry-After`. Every error under `/v1/fhir` is a FHIR `OperationOutcome` and every other error an RFC 9457 problem; https://docs.haau3.com/errors lists every status, whether to retry it, and what a method a path does not take answers. servers: - url: https://api.haau3.com description: Production security: - bearerAuth: [] tags: - name: Scheduling description: 'Provider availability (SMART Scheduling Links): slots and publishers.' - name: FHIR base description: >- What the FHIR R4 base at `/v1/fhir/r4` answers for every service on it: the `CapabilityStatement` that lists them all, and batch Bundles that carry several requests to any of them in one round trip. - name: Terminology description: >- FHIR terminology operations over the code systems listed in TerminologyCapabilities. Some are resolved from their own source when you ask; others are held here at a named release, which that resource also names. - name: Provider directory description: >- CMS's National Provider Directory as FHIR R4: practitioners and their roles, organizations, payers and insurance networks, network membership, healthcare services, locations and endpoints. Every parameter the service serves is declared here, and any other is refused by name rather than ignored. - name: Questionnaires description: >- FHIR Questionnaire, served as its source publishes it. This service holds copies of a curated set and reaches any other questionnaire its source publishes by canonical URL, as well as forms published at their own address under places this service is set up to reach. Read one by id, and build the QuestionnaireResponse in your own application. - name: Medical Benefits description: >- FHIR InsurancePlan: what a Medicare Advantage or ACA Marketplace plan covers and what a member pays, read from the files CMS publishes. Every plan names the CMS release it was read from. Read a plan by its id, or search by identifier, name, state or county, and check whether the CMS National Provider Directory lists providers in a plan's network. - name: Pharmacy Benefits description: >- The CARIN Consumer Real-Time Pharmacy Benefit Check as FHIR messaging: what a medication would cost a member under their coverage, or its price at pharmacies near a ZIP code, in real time, from the sources this service connects to. A member's request receives patient data, so send it only under an executed agreement. - name: MedList description: >- One reconciled medication list from one patient's FHIR medication records, as US Core MedicationRequests with a Provenance for each. This operation receives patient data, so send it only under an executed agreement. - name: Structured Sig description: >- A prescription's free-text directions as a FHIR Dosage: the dose, unit, route, method and timing coded in SNOMED CT, NCIt and UCUM where the words support them, the directions kept verbatim, and a review flag on anything a person should check. It takes the directions and the medication's codings, never a patient. - name: Sandbox description: >- The FHIR base without production behind it, to build and test against: the same paths at `/v1/sandbox/fhir/r4`, answered with synthetic data that always gives the same answer. Its first service is the CARIN Consumer Real-Time Pharmacy Benefit Check, answered by Example Health Plan, a test insurer. It takes a test key (`haau3_sk_test_…`), made on the API keys page, and each request counts like any other. Send test members only, never a real person. paths: /v1/fhir/r4/$structure-dosage: post: tags: - Structured Sig summary: Structure a prescription's directions as a FHIR Dosage description: >- FHIR system-level operation `$structure-dosage`. POST a Parameters resource with one `text` part, a prescription's directions as written, at most 1,000 characters, and optionally one `medication` part, the medication's codings as a CodeableConcept (RxNorm or NDC). The answer is a Parameters resource with one `dosage` part: a FHIR Dosage conforming to haau3 Structured Dosage, whose `text` is the directions exactly as sent and whose dose and unit, route, method, timing and as-needed elements are coded where the words support them, in SNOMED CT (Global Patient Set concepts only), NCIt and UCUM. Nothing is invented: an element the directions do not support is absent. Anything a person should check is a review flag on the Dosage, an extension with a code from `https://haau3.com/fhir/CodeSystem/structured-sig-review-flag` and, when the flag is about words, those words. Every Dosage names the engine and vocabulary versions it was written under, and the RxNorm release when the medication's code was looked up. With an RxNorm code, the product's dose form checks the dose's unit and the route, and supplies either when the directions name none, each flagged. Send the directions and the medication's codings only, never a patient's name or identifiers. Nothing a request carries is stored or logged, apart from the request's ids, and every answer is sent with `Cache-Control: no-store`. The operation takes no query parameters, and may be sent inside a batch, one request per entry. The contract is published at https://fhir.haau3.com/OperationDefinition-structure-dosage.html. operationId: structureDosage parameters: - $ref: '#/components/parameters/XRequestId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/Parameters' examples: One prescription's directions and its medication: summary: One prescription's directions and its medication value: resourceType: Parameters parameter: - name: text valueString: Take 1 tablet by mouth daily - valueCodeableConcept: coding: - code: '311354' system: http://www.nlm.nih.gov/research/umls/rxnorm display: lisinopril 5 MG Oral Tablet name: medication responses: '200': description: >- The structured directions: a FHIR `Parameters` resource with one `dosage` part, a Dosage conforming to haau3 Structured Dosage. content: application/fhir+json: schema: $ref: '#/components/schemas/Parameters' examples: The directions as a coded Dosage: summary: The directions as a coded Dosage value: resourceType: Parameters parameter: - valueDosage: extension: - url: >- https://haau3.com/fhir/StructureDefinition/structured-sig-engine-version valueString: 2026-10-30.v2 - url: >- https://haau3.com/fhir/StructureDefinition/structured-sig-vocabulary-version valueString: 2026-10-29.v1 - url: >- https://haau3.com/fhir/StructureDefinition/structured-sig-rxnorm-release valueString: '10052026' timing: repeat: frequency: 1 period: 1 periodUnit: d code: coding: - code: '69620002' system: http://snomed.info/sct display: Daily - code: QD system: >- http://terminology.hl7.org/CodeSystem/v3-GTSAbbreviation display: QD route: coding: - code: '26643006' system: http://snomed.info/sct display: Oral route - code: C38288 system: >- http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl display: Oral Route of Administration method: coding: - code: '419652001' system: http://snomed.info/sct display: Take doseAndRate: - doseQuantity: value: 1 unit: Tablet system: http://unitsofmeasure.org code: '{tbl}' text: Take 1 tablet by mouth daily name: dosage headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '400': description: >- The request was refused: a query parameter (the operation takes its input in the body only), a body that is not a Parameters resource, a parameter other than `text` and `medication`, a missing, repeated or empty `text`, a repeated `medication` or one that is not a CodeableConcept, or directions over 1,000 characters or a medication with over 20 codings (coded `too-long`). The OperationOutcome names the part by its FHIRPath, never a value sent. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '401': $ref: '#/components/responses/FhirUnauthorized' '403': $ref: '#/components/responses/FhirForbiddenTestKey' '406': $ref: '#/components/responses/FhirNotAcceptable' '413': description: The request body is over 64 KiB. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '415': $ref: '#/components/responses/FhirUnsupportedMediaType' '429': $ref: '#/components/responses/FhirTooManyRequests' '500': $ref: '#/components/responses/FhirServerError' '502': description: >- The medication carries an RxNorm code, and the terminology store behind RxNorm could not be reached. The directions are not structured without it. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '503': description: >- The medication carries an RxNorm code, and RxNorm is not configured on this deployment or no release has been published to it. The directions are not structured without it. It is also the answer when the API key could not be checked just now, with `Retry-After`. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: Retry-After: description: >- Sent when waiting will help: the API key could not be checked just now, or the source behind this service is rate limiting requests. How many seconds to wait before sending the request again. schema: type: integer minimum: 0 X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '504': description: >- The directions could not be structured in time: the terminology store behind RxNorm did not respond, or the operation passed its 8 seconds. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' x-codeSamples: - lang: bash label: cURL source: | curl -X POST "https://api.haau3.com/v1/fhir/r4/\$structure-dosage" \ -H "Authorization: Bearer $HAAU3_API_KEY" \ -H "Content-Type: application/fhir+json" \ -d '{ "resourceType": "Parameters", "parameter": [ { "name": "text", "valueString": "Take 1 tablet by mouth daily" }, { "valueCodeableConcept": { "coding": [ { "code": "311354", "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "display": "lisinopril 5 MG Oral Tablet" } ] }, "name": "medication" } ] }' - lang: typescript label: TypeScript source: > import { Haau3 } from "@haau3/sdk"; const haau3 = new Haau3(); // reads HAAU3_API_KEY const parameters = await haau3.structureDosage({ resourceType: "Parameters", parameter: [ { name: "text", valueString: "Take 1 tablet by mouth daily" }, { valueCodeableConcept: { coding: [ { code: "311354", system: "http://www.nlm.nih.gov/research/umls/rxnorm", display: "lisinopril 5 MG Oral Tablet", }, ], }, name: "medication", }, ], }); for (const parameter of parameters.parameter ?? []) console.log(parameter.name); - lang: python label: Python source: | from haau3 import Haau3 client = Haau3() # reads HAAU3_API_KEY parameters = client.structure_dosage( { "resourceType": "Parameters", "parameter": [ {"name": "text", "valueString": "Take 1 tablet by mouth daily"}, { "valueCodeableConcept": { "coding": [ { "code": "311354", "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "display": "lisinopril 5 MG Oral Tablet", } ] }, "name": "medication", }, ], } ) for parameter in parameters.get("parameter", []): print(parameter.get("name")) - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/haau3/haau3-go\"\n\t\"github.com/haau3/haau3-go/fhir\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := haau3.NewClient() // reads HAAU3_API_KEY\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tparameters, err := client.StructureDosage(ctx, &fhir.Parameters{\n\t\tParameter: []fhir.ParametersParameter{\n\t\t\t{Name: new(\"text\"), ValueString: new(\"Take 1 tablet by mouth daily\")},\n\t\t\t{\n\t\t\t\tName: new(\"medication\"),\n\t\t\t\tValueCodeableConcept: &fhir.CodeableConcept{\n\t\t\t\t\tCoding: []fhir.Coding{\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tCode: new(\"311354\"),\n\t\t\t\t\t\t\tDisplay: new(\"lisinopril 5 MG Oral Tablet\"),\n\t\t\t\t\t\t\tSystem: new(\"http://www.nlm.nih.gov/research/umls/rxnorm\"),\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfor _, parameter := range parameters.Parameter {\n\t\tif parameter.Name != nil {\n\t\t\tfmt.Println(*parameter.Name)\n\t\t}\n\t}\n}\n" components: parameters: XRequestId: name: X-Request-Id in: header required: false schema: type: string format: uuid description: >- An id of your own for this request, as a UUID. It comes back in the `X-Correlation-Id` header and is kept with haau3's record of the request. Any value that is not a UUID is ignored. See https://docs.haau3.com/errors#request-ids. schemas: Parameters: type: object description: A FHIR R4 [Parameters](https://hl7.org/fhir/R4/parameters.html). properties: resourceType: type: string const: Parameters parameter: type: array items: type: object additionalProperties: true required: - resourceType additionalProperties: true OperationOutcome: type: object description: >- A FHIR R4 [OperationOutcome](https://hl7.org/fhir/R4/operationoutcome.html). properties: resourceType: type: string const: OperationOutcome issue: type: array items: type: object properties: severity: type: string enum: - fatal - error - warning - information code: type: string details: type: object properties: text: type: string additionalProperties: true diagnostics: type: string expression: type: array items: type: string required: - severity - code additionalProperties: true required: - resourceType - issue headers: XRequestId: description: >- The id haau3 gave this request, a UUID, on every response. Quote it in a question about the response. A problem carries the same id as its `instance`. schema: type: string format: uuid XCorrelationId: description: The `X-Request-Id` you sent, when it was a UUID. schema: type: string format: uuid responses: FhirUnauthorized: description: Missing or invalid API key. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: WWW-Authenticate: description: >- The scheme to authenticate with: `Bearer realm="api.haau3.com"`, with `error="invalid_token"` when a key was sent and not recognised. schema: type: string X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirForbiddenTestKey: description: >- A test key (`haau3_sk_test_…`) works only in the Sandbox, so one sent here is refused before the request runs: coded `forbidden`, with `test-key-outside-sandbox` from `https://haau3.com/fhir/CodeSystem/api-error` in `issue.details.coding`. Send a live key. headers: WWW-Authenticate: description: >- Sent when the API key works only in the other mode: `Bearer realm="api.haau3.com", error="insufficient_scope"`. schema: type: string X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' examples: A test key outside the Sandbox: summary: A test key outside the Sandbox value: resourceType: OperationOutcome issue: - severity: error code: forbidden details: coding: - system: https://haau3.com/fhir/CodeSystem/api-error code: test-key-outside-sandbox display: Test key outside the Sandbox text: >- This is a test key, which works only in the Sandbox (https://api.haau3.com/v1/sandbox/fhir/r4). Send this request with a live key; create one in the dashboard. See https://docs.haau3.com/authentication#test-and-live-keys FhirNotAcceptable: description: >- The request asked for a format other than JSON (`Accept` or `_format`), or for a FHIR release this endpoint does not serve (the `fhirVersion` media-type parameter). content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirUnsupportedMediaType: description: >- The request body was not sent as JSON: send `Content-Type: application/fhir+json`. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirTooManyRequests: description: >- A limit of the organization's plan was reached: its requests a minute, or the Developer plan's requests a month. Send the request again after `Retry-After`, which for the monthly limit runs to the 1st of the next month (UTC). content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: Retry-After: description: How many seconds to wait before sending the request again. schema: type: integer minimum: 0 X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirServerError: description: The server failed to process this request. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your platform API key, sent as `Authorization: Bearer `: a live key (`haau3_sk_live_…`) for every service, or a test key (`haau3_sk_test_…`) for the Sandbox, the one place a test key works and a live key does not. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.