{"openapi":"3.0.3","info":{"title":"Sharp Health Plan Formulary API","description":"FHIR R4-compliant Formulary API, built to the Da Vinci US Drug Formulary Implementation Guide. Provides read-only access to the drugs covered by Sharp Health Plan's coverage plans, with each plan's tier, prior authorization, step therapy, and quantity limits.\n\nSupport: call 858-499-8300. Identify yourself as a developer and reference the name, email, company, and application name you submitted when registering.","version":"0.1.0","contact":{"name":"Sharp Health Plan API Support","url":"tel:858-499-8300"},"license":{"name":"Proprietary - Sharp Health Plan internal/partner use only"}},"externalDocs":{"description":"Da Vinci US Drug Formulary Implementation Guide (STU 1.1)","url":"https://hl7.org/fhir/us/davinci-drug-formulary/STU1.1/"},"servers":[{"url":"/","description":"Current environment"}],"tags":[{"name":"Conformance","description":"FHIR conformance / capability endpoints"},{"name":"Registration","description":"Self-service API key registration"},{"name":"MedicationKnowledge","description":"Formulary drugs, with each plan's tier and coverage limits"},{"name":"List","description":"Coverage plans and the drugs on each plan's formulary"},{"name":"Health","description":"API and database health check"},{"name":"Documentation","description":"This documentation page and its OpenAPI document"}],"paths":{"/metadata":{"get":{"tags":["Conformance"],"summary":"FHIR CapabilityStatement","description":"Returns the server CapabilityStatement. This endpoint is public and does not require an API key.","operationId":"getMetadata","parameters":[{"$ref":"#/components/parameters/Accept"}],"responses":{"200":{"description":"CapabilityStatement","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/CapabilityStatement"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML CapabilityStatement."}}}}}}},"/v1/ping":{"get":{"tags":["Health"],"summary":"Health check","description":"Checks API and database connectivity.","operationId":"ping","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Database ping succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"$ref":"#/components/responses/ApiGatewayForbidden"},"503":{"description":"Database ping failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/MedicationKnowledge":{"get":{"tags":["MedicationKnowledge"],"summary":"Search formulary drugs","description":"Searches formulary drugs. Unknown query parameters are silently stripped. Pages larger than 2 MB drop the per-plan extension[] detail and tag returned MedicationKnowledge resources with meta.tag SUBSETTED; DrugPlan-scoped searches keep full detail.","operationId":"searchMedicationKnowledge","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Accept"},{"name":"code","in":"query","description":"RxNorm code of the drug.","required":false,"schema":{"type":"string"}},{"name":"DrugPlan","in":"query","description":"Coverage plan id. Non-standard name retained from the legacy API.","required":false,"schema":{"type":"string"}},{"name":"DrugTier","in":"query","description":"Drug tier code. Non-standard name retained from the legacy API.","required":false,"schema":{"type":"string"}},{"name":"DrugName","in":"query","description":"Partial match on the drug ingredient name. Non-standard name retained from the legacy API.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Count"},{"$ref":"#/components/parameters/GetPagesOffset"}],"responses":{"200":{"description":"A FHIR searchset Bundle of MedicationKnowledge resources.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/Bundle"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML Bundle."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ApiGatewayForbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/MedicationKnowledge/{id}":{"get":{"tags":["MedicationKnowledge"],"summary":"Read one formulary drug","description":"Returns one MedicationKnowledge resource by drug code.","operationId":"readMedicationKnowledge","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"A MedicationKnowledge resource.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/MedicationKnowledge"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML MedicationKnowledge."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ApiGatewayForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/List":{"get":{"tags":["List"],"summary":"Search coverage plan formularies","description":"Searches coverage plans. Unknown query parameters are silently stripped. Search results omit each List entry[] drug reference collection and tag returned List resources with meta.tag SUBSETTED. Read a single List by id to get full entries.","operationId":"searchList","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Accept"},{"name":"identifier","in":"query","description":"Coverage plan id.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Count"},{"$ref":"#/components/parameters/GetPagesOffset"}],"responses":{"200":{"description":"A FHIR searchset Bundle of List resources.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/Bundle"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML Bundle."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ApiGatewayForbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/List/{id}":{"get":{"tags":["List"],"summary":"Read one coverage plan formulary","description":"Returns one full List resource by coverage plan id, including entry[] drug references.","operationId":"readList","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"A List resource.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/List"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML List."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ApiGatewayForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/register":{"get":{"tags":["Registration"],"summary":"Registration form","description":"Returns the self-service API key registration form as an HTML page. This endpoint is public and does not require an API key. The `error` and `fields` parameters are set by the server when redirecting back after a failed submission; they are not intended to be supplied by clients directly.","operationId":"getRegisterForm","parameters":[{"name":"error","in":"query","required":false,"description":"Error message to display above the form.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"JSON object of previously submitted values used to prefill the form. Malformed JSON is ignored and an empty form is rendered.","schema":{"type":"string"}}],"responses":{"200":{"description":"The registration form.","content":{"text/html":{"schema":{"type":"string","description":"An HTML document."}}}},"500":{"description":"The reCAPTCHA configuration could not be read, so the form cannot be rendered.","content":{"text/html":{"schema":{"type":"string","description":"An HTML document."}}}}}},"post":{"tags":["Registration"],"summary":"Request an API key","description":"Validates the submitted form, verifies the reCAPTCHA v3 token, creates an API Gateway key, associates it with the default usage plan, and emails the key to the registrant. This endpoint is public and does not require an API key. On a validation or verification failure it responds 302 back to `GET /register` with `error` and `fields` set rather than returning an error status.","operationId":"submitRegistration","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name","email","g-recaptcha-response"],"properties":{"name":{"type":"string","description":"Contact name. Also used as the API key name, sanitised to alphanumerics and spaces and truncated to 50 characters."},"email":{"type":"string","format":"email","description":"Address the API key is sent to."},"company":{"type":"string","description":"Optional organisation name."},"app_name":{"type":"string","description":"Optional application name."},"g-recaptcha-response":{"type":"string","description":"reCAPTCHA v3 token obtained by the form for the `register` action."}}}}}},"responses":{"200":{"description":"The key was created. The key itself is delivered by email and is shown on this page only when that email could not be sent.","content":{"text/html":{"schema":{"type":"string","description":"An HTML document."}}}},"302":{"description":"Validation or reCAPTCHA verification failed; redirects back to the form with an error message.","headers":{"Location":{"description":"The form URL with `error` and `fields` set.","schema":{"type":"string"}}}},"405":{"description":"Unsupported HTTP method.","content":{"text/html":{"schema":{"type":"string","description":"An HTML document."}}}}}}},"/docs":{"get":{"tags":["Documentation"],"summary":"API documentation page","description":"Returns this API's documentation as an HTML page with an embedded Swagger UI reference generated from `GET /docs/openapi.json`. This endpoint is public and does not require an API key.","operationId":"getDocs","responses":{"200":{"description":"The documentation page.","content":{"text/html":{"schema":{"type":"string","description":"An HTML document."}}}}}}},"/docs/openapi.json":{"get":{"tags":["Documentation"],"summary":"OpenAPI document","description":"Returns this OpenAPI 3.0 document. This endpoint is public and does not require an API key.","operationId":"getOpenApi","responses":{"200":{"description":"The OpenAPI document.","content":{"application/json":{"schema":{"type":"object","description":"An OpenAPI 3.0 document."}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key issued via the self-service /register form. Required for all endpoints except /metadata, /register, and /docs."}},"parameters":{"Accept":{"name":"Accept","in":"header","required":false,"description":"Send application/fhir+xml, application/xml, or text/xml for XML; JSON is returned by default.","schema":{"type":"string","enum":["application/fhir+json","application/fhir+xml","application/xml","text/xml"]}},"ResourceId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"Count":{"name":"_count","in":"query","required":false,"description":"FHIR page size. Defaults to 20 and is capped at 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"GetPagesOffset":{"name":"_getpagesoffset","in":"query","required":false,"description":"Zero-based result offset. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}}},"responses":{"BadRequest":{"description":"Invalid search parameters or missing resource id.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML OperationOutcome."}}}},"NotFound":{"description":"Resource not found.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML OperationOutcome."}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}},"application/fhir+xml":{"schema":{"type":"string","description":"FHIR XML OperationOutcome."}}}},"ApiGatewayForbidden":{"description":"Missing or invalid API key. Returned by API Gateway, not as a FHIR OperationOutcome.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"schemas":{"Bundle":{"type":"object","description":"FHIR R4 Bundle returned by search endpoints.","additionalProperties":true,"properties":{"resourceType":{"type":"string","enum":["Bundle"]}}},"OperationOutcome":{"type":"object","description":"FHIR R4 OperationOutcome returned for Lambda-generated errors.","additionalProperties":true,"properties":{"resourceType":{"type":"string","enum":["OperationOutcome"]}}},"MedicationKnowledge":{"type":"object","description":"FHIR R4 MedicationKnowledge resource using the US Drug Formulary profile subset implemented by this API.","additionalProperties":true,"properties":{"resourceType":{"type":"string","enum":["MedicationKnowledge"]}}},"List":{"type":"object","description":"FHIR R4 List resource using the US Drug Formulary CoveragePlan profile subset implemented by this API.","additionalProperties":true,"properties":{"resourceType":{"type":"string","enum":["List"]}}},"CapabilityStatement":{"type":"object","description":"FHIR R4 CapabilityStatement served by GET /metadata.","additionalProperties":true,"properties":{"resourceType":{"type":"string","enum":["CapabilityStatement"]}}}}}}