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 describes the APIs available to 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 (one-time operation).
  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, HEAD, 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
Authorization oracle-dts-signed {apiKey} {base64Signature} 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 (empty string for GET or HEAD). Sign this string with RSA PKCS#1 v1.5 using SHA-512, then Base64-encode the signature. Any change to whitespace, encoding, or header order after signing will invalidate the request.

  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 GET and HEAD 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 headers: Authorization: oracle-dts-signed {api_key} {signature}, 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 urn:scn:clregid:osso:v2:3f11615f-0b06-4c9a-a571-f5113d4474d2:20240617173308564 0EKVuhLi9Uq7ZJ17S0ld9+1T6G2ybin1UUtFw6Nv7lQENYT/hVBNQH+V7qXh3GZ3f6FYFfIy5x6+8BBkIQ3v1Q==
date: 1732838405123
{"requestType":"SoftwareGetStatus", "...":"..."}

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.

Reject any response with HTTP 401 or service message UPD-02002 by re-registering to obtain a new API key. Treat private keys as secrets: store them outside source control, encrypt them at rest, and rotate them in concert with API key regeneration.

Credential Lifestyle

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.
Get Software Health Status POST, GET (poll) /v2/patchplanner/requests and /v2/patchplanner/requests/{requestId} Evaluates installed software against policy and returns health status.
Get Software Health and Recommendations POST, GET (poll) /v2/patchplanner/requests and /v2/patchplanner/requests/{requestId} Returns health status plus Oracle patch recommendations.

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.

Required Headers

Header Required Description
Content-Type Yes application/json or application/xml.
Accept Yes application/json orapplication/xml.

Request Body Fields

Field Type Required Allowed Values Notes
requestType string Yes SoftwareGetStatus. Request type – get software health status
locale.langCode string Optional Default en. ISO 639-1 code
locale.countryCode string Optional Default US. ISO 3166-1 alpha-2 code.
globalElement.systemInfo.platform string Yes Default: 226 Oracle platform code (for example 226 for Linux x86-64).
globalElement.systemInfo.cluster string Optional true (default) or false Boolean value. Use true if the system is part of a database cluster; otherwise use false.
globalElement.policy.updateLag string Optional N (default), N-1, or N-2. Patch Policy: User’s preferred release lag.
globalElement.policy.applyFrequency string Optional M (Monthly), Q (Quarterly), S (Semi-Annual), A (Annual), or L (Long Term Release Update). Default is Q. Patch Policy: Specifies users’ patching cadence.  This will have an impact on determining health status
globalElement.policy.notificationLevel string Optional Critical (default) or Important. Patch Policy:  Critical is always included by default. If Important is selected, the content will include Critical + Important patches.
globalElement.policy.recommendationArea string Optional ALL (default) or DataGuard. Clients have the option to include other software patches – by selecting one or more or ALL available recommendation area.
requestElement[].id string Optional User defined identifier This is user defined values to track individual requests. This is useful when user submits bulk requests.
requestElement[].installedSoftwareInfo.version string Optional 19.x  or 26ai. Oracle software version: API only supports long term releases such as 19c or 26ai.  You can specify specific RU example - 19.27 or simply 19.
requestElement[].installedSoftwareInfo.type string Optional DB (default) or GI. Software Type
requestElement[].patchList.installedPatches[].number string Optional Installed patch number (OPatch inventory). Each installed patch may include:

number: installed patch number
 upi: Universal Patch Identifier
requestElement[].patchList.installedPatches[].upi string Optional Universal Patch Identifier. This is uniq patch identifier installed on the system, provided as name:value pair.  {number: <number>, upi:<number>}

Each request can contain up to 25 requestElement entries. You may override systemInfo or policy inside a requestElement to target asset-specific settings.

Example Request

{
 "requestType": "SoftwareGetStatus",
 "locale": {
   "langCode": "en",
   "countryCode": "US"
 },
 "globalElement": {
   "systemInfo": {
     "platform": "226",
     "cluster": "true"
   },
   "policy": {
     "updateLag": "N",
     "applyFrequency": "Q",
     "notificationLevel": "Critical",
     "recommendationArea": "ALL"
   }
 },
 "requestElement": [
   {
     "id": "1",
     "installedSoftwareInfo": {
       "version": "19.21",
       "type": "DB"
     },
     "patchList": {
       "installedPatches": [
         {
           "number":"36587533",
           "upi": "25728021"
         }
       ]
     }
   }
 ]
}

Example Responses

{
 "requestType": "SoftwareGetStatus",
 "requestStatus": {
   "value": "Pending",
   "response": {
     "estimatedTime": "10m",
     "uri": "/v2/patchplanner/requests/151731",
     "requestID": 151731
   },
   "message": [
     {
       "type": "info",
       "code": "UPD-01001",
       "shortDesc": "In Progress",
       "cause": "Request is in progress!",
       "action": "Check after 'estimated time'"
     }
   ]
 },
 "referenceId": "af006b65-835e-4086-9c31-84f251f2ee40:1732730758154"
}

HTTP/1.1 200 OK
{
  "requestType": "SoftwareGetStatus",
  "referenceId": "711e62b7-8a87-4437-a549-e34287010f8a:1732730101707",
  "globalElement": {
    "systemInfo": {
      "platform": "226",
      "cluster": "true"
    },
    "policy": {
      "updateLag": "N",
      "applyFrequency": "Q",
      "notificationLevel": "Critical",
      "recommendationArea": "ALL"
    }
  },
  "responseElement": [
    {
      "id": "1",
      "installedSoftwareInfo": {
        "version": "19.21",
        "type": "DB"
      },
      "installedSoftwareHealth": {
        "status": "RED",
        "comment": "More than one cycle behind your policy."
      },
      "recommendedSoftwareInfo": {
        "version": "19.25.0.0.0",
        "releaseDate": "1754963442000"
      },
      "stats": {
        "requestedAtInISO": "2025-08-13T08:59:31Z",
        "completedAtInISO": "2025-08-13T08:59:31Z",
        "processingDuration": "0s"
      }
    }
  ]
}

Note: The Health API response may include additional software target information for context. Full recommendation content, including detailed patch recommendation output, is described in Section 4.4.

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.
400 Bad Request Malformed payload or missing requestType.
422 Unprocessable Entity Validation errors such as unsupported policy values or patch identifiers.
401 Unauthorized API key invalid, signature mismatch or invalid key.
415 Unsupported Media Type Payload must be JSON or XML.
406 Not Acceptable Requested response media type not supported.
429 Too Many Requests Rate limit exceeded; Retry-After header specifies wait time.
500 Internal Server Error Unexpected server-side fault.

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

Get Software Health and Recommendations

Combines health evaluation with Oracle-recommended patches, optionally considering customer-provided additional requested patches and gold image requirements. Responses may also include image download metadata when available. This is a runtime API request and must use the issued API key and a signature generated with the corresponding private key. Do not send Oracle SSO credentials with this request. 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.

HTTP Request

POST /v2/patchplanner/requests
GET /v2/patchplanner/requests/{requestId} (poll asynchronous result)

Required Headers

Header Required Description
Content-Type Yes application/json or application/xml.
Accept Yes application/json, application/xml, or /.
Authorization Yes oracle-dts-signed {apiKey} {signature}. Include the payload in the signature for POST requests.
date Yes Millisecond epoch reused from the signature string.

Request Body Fields

Field Type Required Allowed Values Notes
requestType string Yes SoftwareGetStatusAndRecommendation. Request type – get software recommendation
locale.langCode string Optional Default en. ISO 639-1 code
locale.countryCode string Optional Default US. ISO 3166-1 alpha-2 code.
globalElement.systemInfo.platform string Yes Default: 226 Oracle platform code (for example 226 for Linux x86-64).
globalElement.systemInfo.cluster string Optional true (default) or false. Boolean value. Use true if the system is part of a database cluster; otherwise use false.
globalElement.policy.updateLag string Optional N (default), N-1, or N-2. Patch Policy: User’s preferred release lag.
globalElement.policy.applyFrequency string Optional M (Monthly), Q (Quarterly), S (Semi-Annual), A (Annual), or L (Long Term Release Update). Default is Q. Specifies the client’s patching cadence and affects health evaluation and recommendation results.
globalElement.policy.notificationLevel string Optional Critical (default) or Important. Patch Policy:  Critical is always included by default. If Important is selected, the content will include Critical + Important patches.
globalElement.policy.recommendationArea string Optional ALL (default) or DataGuard. Clients have the option to include other software patches – by selecting one or more or ALL available recommendation area.
requestElement[].id string Optional User defined identifier This is user defined values to track individual requests. This is useful when user submits bulk requests.
requestElement[].installedSoftwareInfo.version string Optional 19.x  or 26ai. Oracle software version: API only supports long term releases such as 19c or 26ai.  You can specify specific RU example - 19.27 or simply 19.
requestElement[].installedSoftwareInfo.type string Optional DB (default), GI, or DBCACTL Software Type
requestElement[].patchList.installedPatches[].number string Optional Installed patch number (OPatch inventory). Each installed patch may include:

number: installed patch number
 upi: Universal Patch Identifier
requestElement[].patchList.installedPatches[].upi string Optional Universal Patch Identifier. Universal Patch Identifier for the installed patch.
requestElement[].patchList.additionalRequestedPatches[] string Optional Patch numbers or base bugs to validate. Optional list of additional patch numbers that the client wants evaluated alongside the standard recommendation logic.
requestElement[].goldImage boolean Optional true or false. Default is true. Boolean value. Set to true when the client wants the service to evaluate the request for gold image output metadata, if available.

Include all customer-installed patches to receive accurate containment and replacement analysis in the recommendation output.

Example Request

{
 "requestType": "SoftwareGetStatusAndRecommendation",
 "locale": {
   "langCode": "en",
   "countryCode": "US"
 },
 "globalElement": {
   "systemInfo": {
     "platform": "226",
     "cluster": "true"
   },
   "policy": {
     "updateLag": "N",
     "applyFrequency": "Q",
     "notificationLevel": "Critical",
     "recommendationArea": "ALL"
   }
 },
 "requestElement": [
   {
     "id": "1",
     "systemInfo": {
       "platform": "226",
       "cluster": "true"
     },
     "installedSoftwareInfo": {
       "version": "19.21.0.0.0",
       "type": "DB"
     },
     "patchList": {
       "installedPatches": [
         {
           "number":"36916250",
           "upi": "25798172"
         },
         {
           "number":"35077128",
           "upi": "25752980"
         }
       ],
       "additionalRequestedPatches": [
         {
           "number":"36916250"
         },
         {
           "number":"35663882"
         }
       ]
     },
     "goldImage": true
   }
 ]
}

Example Response

HTTP/1.1200 OK
{
 "requestType": "SoftwareGetStatusAndRecommendation",
 "referenceId": "7a8fed6d-904f-42e8-b037-ab0e7eb762b1:1732733946080",
 "responseElement": [
   {
     "id": "1",
     "installedSoftwareHealth": {
       "status": "YELLOW",
       "comment": "One cycle behind yourpolicy."
     },
     "recommendedSoftwareInfo": {
       "version": "19.24.0.0.0"
     },
     "patchList": {
       "recommendedPatches": {
         "desc": "Oracle StandardRecommendation",
         "patches": [
           { "number":"37773720", "upi": "20223261" },
           { "number":"36595830", "upi": "24914840" }
         ]
       },
       "additionalInstalledPatches": {
         "desc": "Not part of OracleStandard Recommendation",
         "patches": [
           { "number":"31805370", "upi": "26501405" }
         ]
       },
       "additionalRequestedPatches": {
         "patches": [
           { "number":"30520436", "upi": "28406272" }
         ]
       },
       "containedPatches": {
         "patches": [
           { "number":"3333", "containedInPatchNumber": "333322","upi": "33331" }
         ]
       },
       "replacementPatches": {
         "patches": [
           { "number":"3333", "replacedPatchNumber": "333322","upi": "33331" }
         ]
       }
     },
     "stats": {
       "requestedAtInISO":"2025-08-13T09:10:59Z",
       "completedAtInISO":"2025-08-13T09:15:00Z",
       "processingDuration": "4m"
     },
     "goldImage": true
   }
 ]
}

Status Codes

Status Meaning
200 OK Recommendation generated successfully; response includes health, patches, and optional image metadata.
202 Accepted Request queued; poll the provided URI for final recommendations.
400 Bad Request Malformed payload or missing requestType.
422 Unprocessable Entity Validation errors such as invalid patch numbers, or unsupported policy values.
401 Unauthorized API key invalid, signature mismatch, or insufficient Gold Image privileges (UPD-02003).
415 Unsupported Media Type Payload must be JSON or XML.
406 Not Acceptable Requested response media type not supported.
429 Too Many Requests Rate limit exceeded; retry after the window resets.
500 Internal Server Error Unexpected server-side fault.

Request Lifecycle and Throttling

Update Advisor executes lightweight evaluations synchronously. Larger inventories or recommendation requests may be queued for asynchronous processing, returning HTTP 202 along with a request ID and callback URI. Poll the same endpoint using GET and the original headers to retrieve the final result. The service enforces rate limits of up to 500 requests per 15-minute window per API key. Exceeding the limit returns HTTP 429 with Retry-After metadata. Retry with exponential backoff and monitor the 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. Throttle requests and respect the Retry-After header.
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.type value. Use DB or GI.

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