overlay: 1.0.0 info: title: Oracle Health Data Intelligence Populations API — API Evangelist enhancements version: 1.0.0 extends: ../openapi/oracle-health-data-intelligence-populations-api-openapi.yml x-provenance: generated: '2026-08-27' method: generated source: https://docs.healtheintent.com/api/v1/allergy/ note: >- Captures corrections and additions read from Oracle's own published Allergy API reference and from a live probe of the demo tenant on 2026-08-27. The underlying OpenAPI is never mutated; apply this overlay to obtain the enhanced document. actions: - target: $.info description: Add contact, licence-relevant terms and documentation links published by Oracle. update: termsOfService: https://www.oracle.com/legal/terms/ contact: name: Oracle Health Data Intelligence url: https://docs.healtheintent.com/api/v1/allergy/ x-support: community: https://community.oracle.com/oraclehealth/group/1423-ignite-apis-community service_records: https://eservice.ucern.com/ - target: $.servers description: >- Record the documented multi-tenant, multi-region base-URL template alongside the concrete demo host. The region is part of the hostname, so it determines data residency. update: - url: https://cernerdemo.api.us-1.healtheintent.com/allergy/v1 description: Oracle-operated cernerdemo sandbox tenant, US region. Synthetic data, no PHI. - url: https://{tenant}.api.{region}.healtheintent.com/allergy/v1 description: Customer tenant. variables: tenant: default: cernerdemo description: Mnemonic assigned to the customer's Health Data Intelligence tenant. region: default: us-1 enum: [us-1, emea-1, emea-2, ca-1, ap-1] description: Oracle Cerner Cloud Region ID. Determines where the data resides. - target: $.components.securitySchemes description: >- Add the two-legged OAuth 1.0a scheme that Oracle documents and that the live WWW-Authenticate header advertises alongside Bearer. update: oauth1: type: apiKey in: header name: Authorization description: >- Two-legged OAuth 1.0a. A consumer key and consumer secret issued with the system account are exchanged for a short-lived oauth_token, sent as an OAuth Authorization header. Documented by Oracle as the alternative to the preferred bearer token. Modelled here as an apiKey header because OpenAPI has no native OAuth 1.0a security scheme type. x-oauth-version: 1.0a x-flow: two-legged x-token-lifetime-seconds: 3600 x-spec: https://oauth.net/core/1.0a/ - target: $.components.schemas.Error description: >- Correct the error envelope. The captured contract types code as a string and omits errorDetails; Oracle's documented schema and the live 401 response both return an integer code plus an errorDetails array. update: type: object required: [code, message] properties: code: type: integer format: int32 description: The HTTP response status code that represents the error. message: type: string description: A human-readable description of the error. errorDetails: type: array description: A list of additional error details. items: $ref: '#/components/schemas/ErrorDetail' example: code: 401 message: Unauthorized errorDetails: - locationType: header location: Authorization message: header missing - target: $.components.schemas description: Add the ErrorDetail schema documented on the Allergy API reference page. update: ErrorDetail: type: object properties: domain: type: string description: A subsystem or context where an error occurred. reason: type: string description: A codified value representing the specific error that caused the status. message: type: string description: A human-readable description of an error. locationType: type: string enum: [query, header, path, formData, body] description: The location or type of the field that caused an error. location: type: string description: The name of the field that caused an error. - target: $.paths['/populations/{populationId}/patients/{patientId}/allergies'].get description: >- Add the platform-wide throttling response and the pagination semantics documented by Oracle. update: responses: '429': description: >- Too Many Requests. Oracle intentionally throttles these APIs. Retry with exponential backoff; no Retry-After header is returned. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- Internal Server Error. Also covers 502, 503 and 504. Quote the cerner-correlation-id response header when reporting. content: application/json: schema: $ref: '#/components/schemas/Error' x-pagination: style: cursor request: {cursor: cursor, limit: limit} response: {first: firstLink, next: nextLink} note: firstLink and nextLink are absolute URLs and should be followed verbatim. - target: $.paths['/populations/{populationId}/patients/{patientId}/allergies/{allergyId}'].get description: Add the platform-wide throttling and server-error responses. update: responses: '429': description: Too Many Requests. Retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error. Also covers 502, 503 and 504. content: application/json: schema: $ref: '#/components/schemas/Error' - target: $ description: >- Record platform-level operating facts that have no natural home in OpenAPI but that any caller of this API needs. update: x-correlation-header: cerner-correlation-id x-user-authorization: >- Not applied by the platform. These are B2B APIs; Oracle expects the calling system to apply authorization controls for its own users. x-identifier-stability: >- Health Data Intelligence patient IDs may change as new source data is aggregated. Do not store them locally for long-term use; resolve them per workflow through the Patient API. x-phi: true