Oracle Update Advisor API Reference and Integration Guide

What is Oracle Update Advisor?

Oracle Update Advisor (OUA) is a REST service that evaluates Oracle software configurations, reports software health, and provides software recommendations aligned with Oracle update policies. This reference is for developers who want to integrate directly with OUA outside native Oracle tools such as Database Configuration Assistant (DBCA), Fleet Patching and Provisioning (FPP), and AutoUpgrade.

OUA is a secured service. Only registered Oracle customers can call the health and recommendation endpoints. A client must first complete a one-time registration to obtain an API key. After registration succeeds, the client reuses the same API key, together with the corresponding RSA private key, to authenticate and sign subsequent Oracle Update Advisor API requests. Oracle SSO credentials are used only during registration and are not required for runtime health or recommendation API calls.

Typical OUA workflow:

  1. Register to obtain an API key.
  2. Call the Health API to evaluate software health.
  3. If the returned status is not GREEN, call the Recommendation API.
  4. If requested and available, use the returned image metadata for gold image workflows.

Base URLs and Authentication

The service endpoint is:

https://updateadvisor.oracle.com/

This endpoint is the canonical endpoint for production workloads.

All operation paths in this document are relative to this base URL. For example:

Customer Authentication Model

Oracle Update Advisor uses the following authentication model for customers:

  1. The client generates an RSA key pair locally.

  2. The client calls the registration API using:

    • Oracle SSO username and password
    • Base64-encoded public key
    • Tool name
  3. The service returns an API key.
  4. All subsequent protected API requests:
    • Use the issued API key
    • Are signed with the client’s corresponding private key
    • Do not require Oracle SSO credentials again

Oracle SSO credentials are used only during registration. After registration succeeds, the API key and request signature are the only runtime authentication mechanism for Oracle Update Advisor API requests. Do not send Oracle SSO credentials with health, recommendation, polling, or DELETE requests.

Authentication and Signing Workflow

Registration is a one-time setup step. A client generates an RSA key pair, registers the public key with Oracle Update Advisor, receives an API key, and then reuses that API key for subsequent Oracle Update Advisor API requests.

Each protected request must be signed with the RSA private key that corresponds to the public key submitted during registration.

  1. Generate an RSA key pair for the client application.
  2. Store the private key securely in the client environment. The private key must never be sent to Oracle Update Advisor.
  3. Call the registration API to obtain an API key.
  4. Persist the API key, private key, and configuration metadata in a secure local location, such as ~/.<toolName>/.
  5. For each runtime API request, compute a millisecond Unix timestamp.
  6. Build the canonical string as METHOD|API_KEY|TIMESTAMP|PAYLOAD.
  7. Sign the canonical string with RSA PKCS#1 v1.5 using SHA-512.
  8. Base64-encode the signature without line breaks.
  9. Send the API key and signature in the Authorization header using the oracle-dts-signed scheme.
  10. Reuse the same timestamp value in the date header.

Authorization Header and Message Signing

Update Advisor uses a custom signed-request authorization scheme rather than OAuth, IDCS token exchange, or a conventional bearer token. Every protected request must include a digitally signed Authorization header that proves possession of the API key and corresponding RSA private key. The server validates the signature, timestamp, and payload hash to block tampering or replayed traffic.

Header format notes:

Header Value Notes
Authorization oracle-dts-signed {apiKey} {base64Signature} The signature is computed over the canonical string shown below. Do not use Bearer.
date Epoch timestamp in milliseconds Reuse the exact timestamp value embedded in the canonical string.
Content-Type application/json, application/xml, or */* Must match the transmitted body; used when signing payloads.
Accept application/json, application/xml, or */* Selects the response media type. Unrelated to signature but required.

Build the canonical string as METHOD|API_KEY|TIMESTAMP|PAYLOAD, where PAYLOAD is the exact byte sequence sent in the body. For bodyless GET and DELETE requests, use an empty payload string. Sign this string with RSA PKCS#1 v1.5 using SHA-512, and then Base64-encode the signature. Any change to the method, API key, timestamp, or serialized payload invalidates the signature.

  1. Generate a millisecond timestamp: timestamp_ms = time.time_ns() // 1_000_000.

  2. Serialize the request payload exactly once and preserve that exact byte sequence for both signing and transmission. For bodyless GET requests, use an empty payload string.

  3. Construct the canonical string as METHOD|API_KEY|TIMESTAMP|PAYLOAD.

  4. Sign canonical with RSA SHA-512 using the registered private key. Remove any line breaks from the Base64 output.

  5. Set the headers to Authorization: oracle-dts-signed {api_key} {signature} and date: {timestamp_ms}.

  6. Send the payload byte-for-byte as signed.

Example canonical string for POST:

POST|{apiKey}|{timestamp_ms}|{"requestType":"SoftwareGetStatus","locale":{"langCode":"en","countryCode":"US"}}

HTTP/1.1 request example:

POST /v2/patchplanner/requests HTTP/1.1
Host: updateadvisor.oracle.com
Content-Type: application/json
Accept: application/json
Authorization: oracle-dts-signed {apiKey} {signature}
date: {timestamp_ms}

Example canonical string for asynchronous GET polling:

GET|{apiKey}|{timestamp_ms}|

For asynchronous polling requests, the payload is empty. The trailing separator (|) must still be included in the canonical string.

Re-register only for UPD-02002 or a confirmed invalid/expired API key. Otherwise, first validate the timestamp, header, payload, and signature. Treat private keys as secrets: store them outside source control, encrypt them at rest, and rotate them in concert with API key regeneration.

Credential Lifecycle

The API key returned by the registration API is the persistent credential used for subsequent Oracle Update Advisor API requests.

Clients should monitor service message codes in every response and re-register before credentials expire.

Security Considerations

All registration and API requests must be sent over HTTPS using TLS 1.2 or later.

During registration, the client sends Oracle SSO credentials only to authenticate the user and issue an API key. SSO credentials are not used for runtime API calls and must not be persisted by the client after registration.

The API key is the persistent credential returned by the service. Store it securely with the client configuration.

The RSA private key must remain in the client environment and must never be sent to Oracle Update Advisor. Only the Base64-encoded public key is sent during registration. All protected requests are signed locally using the private key.

Oracle Update Advisor does not store the Oracle SSO password beyond the registration authentication transaction.

API Summary

Operation Method(s) External URI Description
Register client POST /v2/patchplanner/registration Registers a client application and returns an API key.
Verify registration GET /v2/patchplanner/registration Verifies the current registration.
Revoke registration DELETE /v2/patchplanner/registration Revokes the current registration.
Get software health status POST /v2/patchplanner/requests Evaluates installed software against policy and returns health status.
Get software health and recommendations POST /v2/patchplanner/requests Returns health status plus Oracle patch recommendations.
Retrieve request result GET /v2/patchplanner/requests/{requestId} Returns the status or result of an asynchronous OUA request.
Perform lookup GET /v2/patchplanner/lookup Returns lookup data for RAC two-stage rolling updates.

Use the POST variant to submit a request. If the service returns 202 Accepted, poll the returned request ID using the GET form of the same endpoint.

API Operations

Use the following information to carry out API operations.

Registration API

The Registration API establishes the credentials required to access Oracle Update Advisor. Clients register their public key and receive an API key used to authenticate and sign subsequent OUA requests. The API also supports verifying and revoking an existing registration.

Register client

POST /v2/patchplanner/registration
Content-Type: application/json
Accept: application/json
Request fields
Field Type Required Description
username string Yes My Oracle Support or Oracle SSO username.
password string Yes Password used only for registration. Do not Base64-encode it.
publicKey string Yes Base64-encoded RSA public key in DER SubjectPublicKeyInfo format. Do not include PEM headers or footers.
toolName string Yes Name of the integrating client or tool.
Example request
{
 "username": "user@example.com",
 "password": "<password>",
 "publicKey": "<public-key-base64>",
 "toolName": "Automation"
}
Example response
{
 "apiKey": "<issued-api-key>"
}

Verify registration

GET /v2/patchplanner/registration
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>

Optional locale headers:

Revoke registration

DELETE /v2/patchplanner/registration
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>

Software Health Status and Recommendation API

The Health Status and Recommendation API evaluates installed Oracle software against the update policy supplied in the request. Both supported operations use the same endpoint and a largely shared request structure. The requestType field determines whether the service returns a health assessment only or a health assessment together with detailed recommendations.

Both runtime request types use:

POST /v2/patchplanner/requests

The requestType discriminator selects the operation:

Request type Description
SoftwareGetStatus Evaluates installed software against the supplied update policy and returns its health status and recommended software version, without detailed patch recommendations.
SoftwareGetStatusAndRecommendation Evaluates installed software health and returns the recommended software version, detailed patch recommendations, and optional gold-image information. This operation supports both synchronous and asynchronous execution. Because recommendation requests may require additional processing time, they are more likely to return 202 Accepted. In that case, poll the GET endpoint with the returned request ID using the same signed request pattern.

Required headers

Header Required Value
Content-Type Yes application/json or application/xml
Accept Yes application/json, application/xml, or */*
Authorization Yes oracle-dts-signed <api-key> <signature>
date Yes Millisecond epoch value used in the signing string

Top-level request fields

Field Type Required Description
requestType string Yes SoftwareGetStatus or SoftwareGetStatusAndRecommendation.
locale object No Response-message locale. Defaults are applied when omitted or invalid.
locale.langCode string Yes when locale is supplied Two-character language code. Default: en.
locale.countryCode string Yes when locale is supplied Two-character country code. Default: US.
globalElement object Yes Global systemInfo and policy.
requestElement array Yes One or more installed-software request elements; maximum 25.

System information

globalElement.systemInfo is required. A request element can supply systemInfo to override the global values.

Field Type Required Allowed values Default
platform string Yes 226 None
cluster string Yes true, false true

Policy parameters

globalElement.policy is required. A request element can supply policy to override individual global values. Missing request-element values inherit from the global policy and then from server rules.

Field Type Required Allowed values Default
updateLag string Yes N, N-1, N-2 N
applyFrequency string Yes M, Q, S, L Q
notificationLevel string Yes Critical, Important Critical
recommendationArea string No Comma-separated recommendation-area and security-level directives Security level defaults to SecurityHigh when no security directive is supplied
applyFrequency values
Value Meaning
M Monthly
Q Quarterly
S Semiannual
L Long Term, monthly on a Long-Term RU
recommendationArea values

recommendationArea is a comma-separated string. It can contain functional recommendation-area directives and zero or one security-level directive.

Functional recommendation-area directives:

Value Description
ALL Includes all supported functional recommendation areas.
IncludeNonRolling For clustered systems, includes confirmed RAC non-rolling Important patches and additional-requested patches. Without this value, confirmed RAC non-rolling Important patches are excluded and confirmed RAC non-rolling additional-requested patches cause validation failure.
JDK Includes JDK bundle-patch recommendations and health evaluation.

Security-level directives:

Value CVSS threshold Description
SecurityLow 0.1 or higher Selects the Low security threshold.
SecurityMedium 4.0 or higher Selects the Medium security threshold.
SecurityHigh 7.0 or higher Selects the High security threshold. This is the default when no security directive is supplied.
SecurityCritical 9.0 or higher Selects the Critical security threshold.

The Common Vulnerability Scoring System (CVSS) is a standardized 0.0–10.0 vulnerability-severity scale.

Security levels are values of recommendationArea; the request schema does not define a separate securityLevel field.

Security health assessment cannot be disabled. If no security-level value is supplied, the service applies SecurityHigh to the effective policy.

Valid examples:

SecurityHigh
IncludeNonRolling,SecurityMedium
IncludeNonRolling,JDK,SecurityHigh
ALL,SecurityCritical

Validation rules implemented by the service:

Request-element fields

Field Type Required Allowed values or description
id string Yes Unique client-defined identifier within the request.
systemInfo object No Overrides global system information.
policy object No Overrides global policy values.
installedSoftwareInfo object Yes Installed software version and type.
installedSoftwareInfo.version string Yes Software version; maximum 20 characters.
installedSoftwareInfo.type string Yes DB, GI, or DBCACTL. Default: DB.
patchList object Yes Installed and optionally requested patches.
patchList.installedPatches array Yes Installed patch inventory.
patchList.installedPatches[].number string Yes Patch number; maximum 20 characters.
patchList.installedPatches[].upi string Yes Unique Patch Identifier; maximum 20 characters.
patchList.additionalRequestedPatches array No Additional patches to evaluate.
patchList.additionalRequestedPatches[].number string Yes Patch number; maximum 20 characters.
patchList.additionalRequestedPatches[].upi string No Unique Patch Identifier; maximum 20 characters.
goldImage string No; recommendation request only true or false. Default: true.

goldImage is a string enum in the current schema, not a JSON boolean.

SoftwareGetStatus example

{
  "requestType": "SoftwareGetStatus",
  "locale": {
    "langCode": "en",
    "countryCode": "US"
  },
  "globalElement": {
    "systemInfo": {
      "platform": "226",
      "cluster": "true"
    },
    "policy": {
      "updateLag": "N",
      "applyFrequency": "Q",
      "notificationLevel": "Critical"
    }
  },
  "requestElement": [
    {
      "id": "1",
      "policy": {
        "updateLag": "N",
        "applyFrequency": "Q",
        "notificationLevel": "Critical",
        "recommendationArea": "SecurityHigh"
      },
      "installedSoftwareInfo": {
        "version": "19.28.0.0.0",
        "type": "DB"
      },
      "patchList": {
        "installedPatches": [
          {
            "number": "11111",
            "upi": "111111"
          }
        ],
        "additionalRequestedPatches": [
          {
            "number": "22222",
            "upi": "222222"
          }
        ]
      }
    }
  ]
}

SoftwareGetStatusAndRecommendation example

{
  "requestType": "SoftwareGetStatusAndRecommendation",
  "locale": {
    "langCode": "en",
    "countryCode": "US"
  },
  "globalElement": {
    "systemInfo": {
      "platform": "226",
      "cluster": "true"
    },
    "policy": {
      "updateLag": "N",
      "applyFrequency": "Q",
      "notificationLevel": "Critical"
    }
  },
  "requestElement": [
    {
      "id": "1",
      "policy": {
        "updateLag": "N",
        "applyFrequency": "Q",
        "notificationLevel": "Critical",
        "recommendationArea": "IncludeNonRolling,SecurityMedium"
      },
      "installedSoftwareInfo": {
        "version": "19.28.0.0.0",
        "type": "DB"
      },
      "patchList": {
        "installedPatches": [
          {
            "number": "11111",
            "upi": "111111"
          }
        ],
        "additionalRequestedPatches": [
          {
            "number": "22222",
            "upi": "222222"
          }
        ]
      },
      "goldImage": "true"
    }
  ]
}

Polling API

Retrieves the status or completed result of a previously submitted asynchronous health or recommendation request. Use the requestId returned with the original 202 Accepted response to poll until processing completes.

GET /v2/patchplanner/requests/{requestId}
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>
Path parameter Type Required Description
requestId string Yes Identifier returned by an asynchronous request submission.

Use an empty payload in the canonical signing string for polling requests.

Lookup API

Retrieves lookup data used to plan RAC two-stage rolling updates. The response is selected using parameters such as category, Oracle Database version, and platform.

GET /v2/patchplanner/lookup
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>
Accept: application/json

The Lookup API requires a signed request. Because the GET request has no body, use an empty payload when constructing the canonical signing string:

GET|{apiKey}|{timestamp_ms}|

Query parameters

Parameter Type Required Allowed values or format
category string Yes ractwostagerollingupdates
version string Yes Supported formats include 23, 23.26, 23.26.0, 19, and 19.X.
platform integer Yes 226
langCode string No en; default en
countryCode string No US; default US

Example:

GET /v2/patchplanner/lookup?category=ractwostagerollingupdates&version=23&platform=226
Authorization: oracle-dts-signed <api-key> <signature>
date: <timestamp-ms>
Accept: application/json

Responses

Runtime request responses can include:

requestStatus.value values:

responseElement.status.value values:

A runtime request can return HTTP 200 with an element-level InvalidRequest. Clients must inspect requestStatus, serviceMessages, and each responseElement.status.

Status Codes

Status Meaning
200 OK Evaluation completed successfully; response contains health data.
202 Accepted Request accepted for asynchronous processing; poll using the provided URI.
204 No Content No result is currently available. Continue polling according to the client’s timeout and backoff policy.
400 Bad Request Malformed payload or missing requestType.
401 Unauthorized Invalid or expired API key, signature failure, or invalid registration credentials.
406 Not Acceptable Requested response media type not supported.
415 Unsupported Media Type Payload must be JSON or XML.
422 Unprocessable Entity Validation errors such as unsupported policy values or patch identifiers.
429 Too Many Requests Rate limit exceeded; retry with backoff and inspect UPD-02001 for throttling guidance.
500 Internal Server Error Unexpected server-side fault.
503 Service Unavailable Transient registration infrastructure error; retry with backoff.

When retrieving asynchronous results, reuse the same Authorization signature pattern and include an empty payload in the canonical string for GET requests.

Request Lifecycle and Throttling

Oracle Update Advisor processes lightweight evaluations synchronously. Larger inventories or recommendation requests may be accepted for asynchronous processing, returning HTTP 202 Accepted with a request ID and polling URI. Retrieve the result by sending a signed GET request to the polling URI. Generate a new timestamp and signature for each polling request, and use an empty payload in the canonical signing string. The service enforces rate limits per API key. If the service returns HTTP 429 Too Many Requests, reduce the request rate and retry using exponential backoff. Monitor UPD-02001 service message for throttling feedback.

Clients should also monitor credential lifecycle messages. UPD-01501 indicates that an API key or public key is nearing expiration. UPD-02002 indicates that the API key has expired and the client must re-register before continuing.

Service Message Codes

Code Severity Description Recommended action
UPD-01001 Info Request in progress. Poll again after the estimated time.
UPD-01501 Warning API key or public key is nearing expiration. Re-register to refresh credentials before expiry.
UPD-02001 Error Request rate limit exceeded. Reduce the request rate and retry using exponential backoff.
UPD-02002 Error API key expired. Repeat registration to obtain a new API key before sending additional protected API requests.
UPD-04004 Error Invalid installedSoftwareInfo.version value. Only 19c and 26ai releases are supported
UPD-04005 Error Invalid installedSoftwareInfo.type value. Use DB, GI, or DBCACTL.

Client handling rules:

Additional Information

Use these guidelines to assist you with update analysis.

Minimal Client Flow

A minimal Oracle Update Advisor client performs the following steps:

  1. Generate an RSA key pair locally.
  2. Register once with Oracle SSO credentials, the generated Base64-encoded public key, and a tool name.
  3. Persist the returned API key securely with the private key and local client configuration.
  4. Build a signed POST request to /v2/patchplanner/requests with request type SoftwareGetStatus.
  5. Send the runtime request using the API key and signature. Do not send Oracle SSO credentials.
  6. If the service returns 200 OK, read the health status from the response.
  7. If the service returns 202 Accepted, poll /v2/patchplanner/requests/{requestId} using signed GET requests until the final response is returned.
  8. If the resulting health status is not GREEN, submit a signed SoftwareGetStatusAndRecommendation request.

Best Practices