Oracle Announcements Preferences API

openapi: 3.2.0
info:
  description: Manage Oracle Cloud Infrastructure console announcements.
  title: Announcements Service Announcements Preferences API
  version: 0.0.1
  x-provenance:
    method: harvested
    first_party: true
    publisher: Oracle
    source: https://docs.oracle.com/en-us/iaas/api/specs/ad81e510c25e589a2fdfbfe0fb957253a658175b2922b7951ddb17b4910c849b.yaml
    harvested: '2026-08-04'
    note: Published by Oracle as the contract for the Announcements Service API OCI service and stored verbatim; API Evangelist added only this provenance block.
  x-evidence:
  - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json
    what: Oracle's own index of every OCI service specification
  - url: https://docs.oracle.com/en-us/iaas/api/specs/ad81e510c25e589a2fdfbfe0fb957253a658175b2922b7951ddb17b4910c849b.yaml
    what: the harvested document for Announcements Service API
servers:
- url: http://127.0.0.1/20180904
- url: https://127.0.0.1/20180904
tags:
- name: announcementsPreferences
paths:
  /announcementsPreferences:
    get:
      description: 'Gets the current preferences of the tenancy regarding receiving announcements by email.


        This call is subject to an Announcements limit that applies to the total number of requests across all read or write operations. Announcements might throttle this call to reject an otherwise valid request when the total rate of operations exceeds 20 requests per second for a given user. The service might also throttle this call to reject an otherwise valid request when the total rate of operations exceeds 100 requests per second for a given tenancy.

        '
      operationId: ListAnnouncementsPreferences
      parameters:
      - $ref: '#/components/parameters/PaginationLimitQueryParam'
      - $ref: '#/components/parameters/PaginationTokenQueryParam'
      - $ref: '#/components/parameters/CompartmentIdQueryParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      responses:
        200:
          description: 'The current tenancy preferences for receiving announcements by email.

            '
          headers:
            opc-next-page:
              description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

                then a partial list might have been returned. Include this value as the `page` parameter for the

                subsequent GET request to get the next batch of items.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AnnouncementsPreferencesSummary'
                type: array
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      summary: ListAnnouncementsPreferences
      tags:
      - announcementsPreferences
      x-example: 'GET /20180904/announcementsPreferences?compartmentId=<var>&lt;compartmentId&gt;</var>

        Host: announcements.us-ashburn-1.oraclecloud.com

        <var>&lt;authorization and other headers&gt;</var>

        '
    post:
      description: 'Creates a request that specifies preferences for the tenancy regarding receiving announcements by email.


        This call is subject to an Announcements limit that applies to the total number of requests across all read or write operations. Announcements might throttle this call to reject an otherwise valid request when the total rate of operations exceeds 20 requests per second for a given user. The service might also throttle this call to reject an otherwise valid request when the total rate of operations exceeds 100 requests per second for a given tenancy.

        '
      operationId: CreateAnnouncementsPreference
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - description: Idempotency token
        in: header
        name: opc-retry-token
        schema:
          type: string
      responses:
        200:
          description: OK
          headers:
            etag:
              description: 'For optimistic concurrency control. See `if-match`.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnouncementsPreferencesSummary'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      summary: Creates email preferences.
      tags:
      - announcementsPreferences
      x-example: "POST /20180904/announcementsPreferences/<var>&lt;rootCompartmentId&gt;</var>\nhost: announcements.us-ashburn-1.oraclecloud.com\n<var>&lt;authorization and other headers&gt;</var>\n{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleauingds4uwkcvbxv4ijs7zxuqnoewldef4fauxs7vaax2fab4gcsq\",\n  \"preferenceType\": \"OPT_IN_TENANT_AND_INFORMATIONAL_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"type\": \"CreateAnnouncementsPreferencesDetails\"\n}\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnouncementsPreferencesDetails'
        description: The object that contains details about tenancy preferences for receiving announcements by email.
        required: true
  /announcementsPreferences/{preferenceId}:
    get:
      description: 'Gets the current preferences of the tenancy regarding receiving announcements by email.


        This call is subject to an Announcements limit that applies to the total number of requests across all read or write operations. Announcements might throttle this call to reject an otherwise valid request when the total rate of operations exceeds 20 requests per second for a given user. The service might also throttle this call to reject an otherwise valid request when the total rate of operations exceeds 100 requests per second for a given tenancy.

        '
      operationId: GetAnnouncementsPreference
      parameters:
      - $ref: '#/components/parameters/PreferenceIdPathParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      responses:
        200:
          description: 'The current tenancy preferences for receiving announcements by email.

            '
          headers:
            etag:
              description: 'For optimistic concurrency control. See `if-match`.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnouncementsPreferences'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      summary: Gets the current email preferences for announcements.
      tags:
      - announcementsPreferences
      x-example: 'GET /20180904/announcementsPreferences/<var>&lt;preferenceId&gt;</var>

        host: announcements.us-ashburn-1.oraclecloud.com

        <var>&lt;authorization and other headers&gt;</var>

        '
    put:
      description: 'Updates the preferences of the tenancy regarding receiving announcements by email.


        This call is subject to an Announcements limit that applies to the total number of requests across all read or write operations. Announcements might throttle this call to reject an otherwise valid request when the total rate of operations exceeds 20 requests per second for a given user. The service might also throttle this call to reject an otherwise valid request when the total rate of operations exceeds 100 requests per second for a given tenancy.

        '
      operationId: UpdateAnnouncementsPreference
      parameters:
      - $ref: '#/components/parameters/PreferenceIdPathParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/IfMatchHeader'
      responses:
        200:
          description: 'Updated email preferences for announcements for the specified compartment.

            '
          headers:
            etag:
              description: 'For optimistic concurrency control. See `if-match`.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnouncementsPreferencesSummary'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      summary: Updates email preferences for announcements.
      tags:
      - announcementsPreferences
      x-example: "PUT /20180904/announcementsPreferences/<var>&lt;preferenceId&gt;</var>\nhost: announcements.us-ashburn-1.oraclecloud.com\n<var>&lt;authorization and other headers&gt;</var>\n{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleauingds4uwkcvbxv4ijs7zxuqnoewldef4fauxs7vaax2fab4gcsq\",\n  \"preferenceType\": \"OPT_IN_TENANT_AND_INFORMATIONAL_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"type\": \"UpdateAnnouncementsPreferencesDetails\"\n}\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnnouncementsPreferencesDetails'
        description: The object that contains details about tenancy preferences for receiving announcements by email.
        required: true
components:
  parameters:
    CompartmentIdQueryParam:
      description: 'The OCID of the compartment.

        '
      in: query
      name: compartmentId
      required: true
      schema:
        type: string
        maxLength: 512
        minLength: 1
    IfMatchHeader:
      description: The locking version, used for optimistic concurrency control.
      in: header
      name: if-match
      schema:
        type: string
    PreferenceIdPathParam:
      description: The ID of the preference.
      in: path
      name: preferenceId
      required: true
      schema:
        type: string
    PaginationTokenQueryParam:
      description: The value of the `opc-next-page` response header from the previous "List" call.
      in: query
      name: page
      schema:
        type: string
        maxLength: 3000
        minLength: 1
    RequestIdHeader:
      description: 'The unique Oracle-assigned identifier for the request. If you need to contact Oracle about

        a particular request, please provide the complete request ID.

        '
      in: header
      name: opc-request-id
      schema:
        type: string
    PaginationLimitQueryParam:
      description: The maximum number of items to return in a paginated "List" call.
      in: query
      name: limit
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 1
  schemas:
    BaseAnnouncementsPreferences:
      description: The object that contains the announcement email preferences configured for the tenancy (root compartment).
      discriminator:
        propertyName: type
      properties:
        compartmentId:
          description: 'The OCID of the compartment for which the email preferences apply. Because announcements are

            specific to a tenancy, specify the tenancy by providing the root compartment OCID.

            '
          maxLength: 255
          minLength: 1
          type: string
        id:
          description: The ID of the preferences.
          type: string
        isUnsubscribed:
          description: 'A Boolean value to indicate whether the specified compartment chooses to not to receive informational announcements by email.

            (Manage preferences for receiving announcements by email by specifying the `preferenceType` attribute instead.)

            '
          type: boolean
        preferenceType:
          description: The string representing the user's preference regarding receiving announcements by email.
          type: string
          x-obmcs-enumref: '#/definitions/BaseCreateAnnouncementsPreferencesDetails/preferenceType'
        preferredTimeZone:
          default: UTC
          description: The time zone in which the user prefers to receive announcements. Specify the preference with a value that uses the IANA Time Zone Database format (x-obmcs-time-zone). For example - America/Los_Angeles
          example: America/Los_Angeles
          format: x-obmcs-time-zone
          type: string
        timeCreated:
          description: When the preferences were set initially.
          format: date-time
          type: string
        timeUpdated:
          description: When the preferences were last updated.
          format: date-time
          type: string
        type:
          description: The entity type, which specifies either an object or a summary object for announcement email preferences.
          maxLength: 255
          minLength: 1
          type: string
      required:
      - type
      x-example: "{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleawuu4tcvbsd2ups5fsclgm5ksfjwmx6faux5sbjyw5ob5ojq2vkxa\",\n  \"id\": \"ocid1.tenancy.oc1..exampleawuu4tcvbsd2ups5fsclgm5ksfjwmx6faux5sbjyw5ob5ojq2vkxa\",\n  \"isUnsubscribed\": true,\n  \"preferenceType\": \"OPT_IN_TENANT_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"timeCreated\": \"2022-01-19T21:30:13.803Z\",\n  \"timeUpdated\": \"2023-05-12T23:41:45.968Z\",\n  \"type\": \"AnnouncementsPreferences\"\n}\n"
    AnnouncementsPreferencesSummary:
      allOf:
      - $ref: '#/components/schemas/BaseAnnouncementsPreferences'
      - discriminator: AnnouncementsPreferencesSummary
      description: The summary object for announcement email preferences.
      x-example: "{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleawuu4tcvbsd2ups5fsclgm5ksfjwmx6faux5sbjyw5ob5ojq2vkxa\",\n  \"id\": \"ocid1.tenancy.oc1..exampleawuu4tcvbsd2ups5fsclgm5ksfjwmx6faux5sbjyw5ob5ojq2vkxa\",\n  \"isUnsubscribed\": true,\n  \"preferenceType\": \"OPT_IN_TENANT_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"timeCreated\": \"2022-01-19T21:30:13.803Z\",\n  \"timeUpdated\": \"2023-05-12T23:41:45.968Z\",\n  \"type\": \"AnnouncementsPreferencesSummary\"\n}\n"
    UpdateAnnouncementsPreferencesDetails:
      allOf:
      - $ref: '#/components/schemas/BaseCreateAnnouncementsPreferencesDetails'
      - discriminator: UpdateAnnouncementsPreferencesDetails
      description: The object used to update announcement email preferences.
      x-example: "{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleauingds4uwkcvbxv4ijs7zxuqnoewldef4fauxs7vaax2fab4gcsq\",\n  \"preferenceType\": \"OPT_IN_TENANT_AND_INFORMATIONAL_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"type\": \"UpdateAnnouncementsPreferencesDetails\"\n}\n"
    CreateAnnouncementsPreferencesDetails:
      allOf:
      - $ref: '#/components/schemas/BaseCreateAnnouncementsPreferencesDetails'
      - discriminator: CreateAnnouncementsPreferencesDetails
      description: The object used to create announcement email preferences.
      x-example: "{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleauingds4uwkcvbxv4ijs7zxuqnoewldef4fauxs7vaax2fab4gcsq\",\n  \"isUnsubscribed\": true,\n  \"preferenceType\": \"OPT_IN_TENANT_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"type\": \"CreateAnnouncementsPreferencesDetails\"\n}\n"
    Error:
      description: Error Information.
      properties:
        code:
          description: A short error code that defines the error, meant for programmatic parsing.
          type: string
        message:
          description: A human-readable error string.
          type: string
      required:
      - code
      - message
    AnnouncementsPreferences:
      allOf:
      - $ref: '#/components/schemas/BaseAnnouncementsPreferences'
      - discriminator: AnnouncementsPreferences
      description: The object for announcement email preferences.
      x-example: "{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleawuu4tcvbsd2ups5fsclgm5ksfjwmx6faux5sbjyw5ob5ojq2vkxa\",\n  \"id\": \"ocid1.tenancy.oc1..exampleawuu4tcvbsd2ups5fsclgm5ksfjwmx6faux5sbjyw5ob5ojq2vkxa\",\n  \"isUnsubscribed\": true,\n  \"preferenceType\": \"OPT_IN_TENANT_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"timeCreated\": \"2022-01-19T21:30:13.803Z\",\n  \"timeUpdated\": \"2023-05-12T23:41:45.968Z\",\n  \"type\": \"AnnouncementsPreferences\"\n}\n"
    BaseCreateAnnouncementsPreferencesDetails:
      description: The model for the parameters of announcement email preferences configured for the tenancy (root compartment).
      discriminator:
        propertyName: type
      properties:
        compartmentId:
          description: 'The OCID of the compartment for which you want to manage announcement email preferences. (Specify the tenancy by providing the

            root compartment OCID.)

            '
          maxLength: 255
          minLength: 1
          type: string
        isUnsubscribed:
          description: 'A Boolean value to indicate whether the specified compartment chooses to not to receive informational announcements by email.

            (Manage preferences for receiving announcements by email by specifying the `preferenceType` attribute instead.)

            '
          type: boolean
        preferenceType:
          description: The string representing the user's preference, whether to opt in to only required announcements, to opt in to all announcements, including informational announcements, or to opt out of all announcements.
          enum:
          - OPT_IN_TENANT_ANNOUNCEMENTS
          - OPT_IN_TENANT_AND_INFORMATIONAL_ANNOUNCEMENTS
          - OPT_OUT_ALL_ANNOUNCEMENTS
          type: string
        preferredTimeZone:
          default: UTC
          description: The time zone in which the user prefers to receive announcements. Specify the preference with a value that uses the IANA Time Zone Database format (x-obmcs-time-zone). For example - America/Los_Angeles
          example: America/Los_Angeles
          format: x-obmcs-time-zone
          type: string
        type:
          description: 'The entity type, which specifies a model that either creates new announcement email preferences or updates existing preferences.

            '
          maxLength: 255
          minLength: 1
          type: string
      required:
      - type
      - preferenceType
      x-example: "{\n  \"compartmentId\": \"ocid1.tenancy.oc1..exampleauingds4uwkcvbxv4ijs7zxuqnoewldef4fauxs7vaax2fab4gcsq\",\n  \"isUnsubscribed\": true,\n  \"preferenceType\": \"OPT_IN_TENANT_ANNOUNCEMENTS\",\n  \"preferredTimeZone\": \"UTC\",\n  \"type\": \"BaseCreateAnnouncementsPreferencesDetails\"\n}\n"
  responses:
    default:
      description: Unknown Error
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
x-anchors:
  x-headers:
    etag:
      description: 'For optimistic concurrency control. See `if-match`.

        '
      type: string
    opc-next-page:
      description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

        then a partial list might have been returned. Include this value as the `page` parameter for the

        subsequent GET request to get the next batch of items.

        '
      type: string
    opc-previous-page:
      description: 'For pagination of a list of items. Include this value as the `page` parameter for the

        subsequent GET request to get the previous batch of items.

        '
      type: string
    opc-request-id:
      description: 'Unique Oracle-assigned identifier for the request. If you need to contact

        Oracle about a particular request, please provide the request ID.

        '
      type: string
    opc-work-request-id:
      description: 'Unique Oracle-assigned identifier for the asynchronous request. You can use this to query status of the asynchronous operation.

        '
      type: string
  x-properties:
    definedTags:
      additionalProperties:
        additionalProperties:
          description: 'The value of the tag. Only string, integer and boolean types are supported.

            '
          type: object
        description: 'Key-value pair representing predefined tags'' keys and values scoped to a namespace.

          Example: `{"bar-key": "value"}`

          '
        type: object
      description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace.

        Example: `{"foo-namespace": {"bar-key": "value"}}`

        '
      type: object
    freeformTags:
      additionalProperties:
        type: string
      description: 'Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only.

        Example: `{"bar-key": "value"}`

        '
      type: object
    systemTags:
      additionalProperties:
        additionalProperties:
          description: 'The value of the tag. Only string, integer and boolean types are supported.

            '
          type: object
        description: 'Key-value pair representing system tags'' keys and values scoped to a namespace.

          Example: `{"bar-key": "value"}`

          '
        type: object
      description: 'Usage of system tag keys. These predefined keys are scoped to namespaces.

        Example: `{"orcl-cloud": {"free-tier-retained": "true"}}`

        '
      type: object
x-obmcs-client-retries-enabled: false
x-oracle-package: com.oracle.pic.announcements.announcements-api