Reference

API reference

Four application operations are active. The contract is OpenAPI 3.1, source-controlled, linted in CI, and authoritative — when this page and the checked contract disagree, the contract wins.

#Conventions

Base originhttp://127.0.0.1:8081 (loopback only)

AuthenticationBearer credential on draft creation. Review routes authenticate by one-time grant, then session cookie.

CorrelationSend X-Correlation-Id, or one is generated and echoed on every response.

CachingAll application responses are no-store.

Content typeapplication/json, except the review shell which returns HTML.

#Create a prescription draft

POST/api/v1/prescription-drafts

Creates exactly one standard, non-controlled synthetic prescription draft. The tenant and caller are derived from the bearer credential, and every referenced resource is resolved within that tenant and authorized practice. The operation has no network or pharmacy side effect.

#Headers

Header	Required	Notes
`Authorization`	Yes	`Bearer <token>`. Locally, `local-sandbox-token`.
`Idempotency-Key`	Yes	Scoped by tenant, caller, and operation.
`X-Correlation-Id`	No	Echoed on the response; generated when absent.

#Request

{
  "practiceId": "prc_demo",
  "patientId": "pat_demo",
  "prescriberId": "pre_demo",
  "medication": { "ndc": "00000000000" },
  "quantity": { "value": 30, "unitCode": "TABLET" },
  "directions": { "text": "Take one tablet by mouth once daily" },
  "refills": 1,
  "substitutionAllowed": true,
  "pharmacyId": "phm_demo",
  "diagnoses": [
    {
      "codeSystem": "ICD10CM",
      "code": "Z00.00",
      "display": "General adult medical examination"
    }
  ]
}

#Responses

Status	Meaning
`201`	Draft, validation snapshot, grant verifier, audit evidence, outbox fact, and encrypted replay committed atomically. No `Location` header — there is no standalone draft-read route.
`400`	Request failed structural validation or a blocking mechanical check. Nothing was persisted.
`401`	Missing or invalid bearer credential.
`403`	Caller lacks draft-creation authority, or the authority graph does not permit the referenced resources.
`409`	The idempotency key was reused with a materially different request.
`410`	The idempotency key has expired into a permanent tombstone and can never be replayed.
`429`	Rate limit exceeded. A `Retry-After` header is supplied.

A successful response carries Idempotency-Replayed: false on first commit and true when the stored encrypted response is returned again. The response contains a review URL whose secret is in the URI fragment; treat the whole response as sensitive.

#Idempotency semantics

After a successful commit, the same key and the same canonical request fingerprint returns the stored success status and body with no second business effect. The fingerprint is semantic rather than textual: equivalent decimal representations, insignificant whitespace, and key ordering do not change it, while clinically material differences do. Failed reservations are abandoned rather than cached, so a transient failure never poisons a key.

#Load the review shell

GET/prescribe/review/{publicGrantId}

Returns the HTML application shell for the read-only review client. This route never receives the fragment secret — the browser retains it client-side and removes it from the URL before the application mounts.

#Exchange a review grant

POST/api/v1/review-grants/{publicGrantId}/exchange

Consumes a five-minute, single-use review grant and establishes a bound review session.

{ "secret": "<opaque secret from the URI fragment>" }

Status	Meaning
`204`	Grant consumed. A short-lived, device-bound, HttpOnly session cookie is set.
`410`	Unknown, expired, already-consumed, or tampered grant. These cases are deliberately indistinguishable.
`429`	Exchange attempts are rate limited per grant and per caller address.

#Read the current review session

GET/api/v1/review-sessions/current

Returns the exact immutable projection bound to the established session. The session is revalidated on every read against environment, verifier hash, device binding, expiry, prescription state, and aggregate version — so a draft that expires mid-session immediately stops being readable.

Status	Meaning
`200`	The bound review projection, including validation results and explicit capability statements.
`401`	No valid session cookie.
`410`	The session or underlying draft expired, or the bound aggregate changed.

The projection carries explicit statements that the environment is a sandbox, that validation was mechanical only, and that nothing was sent to a pharmacy. Those statements are part of the contract, not presentation copy.

#Health probes

GET/health/live

GET/health/ready

Unauthenticated and deliberately detail-free. Liveness reflects the process; readiness additionally reflects database availability. Neither exposes component diagnostics, and evidence-chain verification is intentionally excluded from readiness.