Oracle Enterprise Manager Blackouts API

openapi: 3.1.0
info:
  title: Oracle Enterprise Manager Cloud Control REST Blackouts API
  description: REST API for Oracle Enterprise Manager Cloud Control providing programmatic access to monitoring, configuration, and administration capabilities. This specification covers core resources including targets, metrics, incidents, and blackouts for managing Oracle IT infrastructure and applications.
  version: 13.5.0.23
  contact:
    name: Oracle Support
    url: https://www.oracle.com/support/
    email: support@oracle.com
  license:
    name: Oracle Technology Network License
    url: https://www.oracle.com/legal/terms.html
  x-logo:
    url: https://www.oracle.com/a/ocom/img/oracle-enterprise-manager.jpg
servers:
- url: https://{emHost}:{emPort}/em/api
  description: Enterprise Manager Cloud Control server
  variables:
    emHost:
      default: localhost
      description: Enterprise Manager OMS hostname
    emPort:
      default: '7803'
      description: Enterprise Manager HTTPS console port
security:
- basicAuth: []
tags:
- name: Blackouts
  description: Manage blackout windows for maintenance activities. Blackouts suppress monitoring and alerting during scheduled maintenance periods, preventing false alerts.
  externalDocs:
    url: https://docs.oracle.com/en/enterprise-manager/cloud-control/enterprise-manager-cloud-control/13.5/emrest/rest-endpoints.html
paths:
  /blackouts:
    get:
      operationId: listBlackouts
      summary: Oracle Enterprise Manager List Blackouts
      description: Returns a list of blackouts (maintenance windows) configured in Enterprise Manager. Supports filtering by status and associated target.
      tags:
      - Blackouts
      parameters:
      - name: status
        in: query
        description: Filter by blackout status.
        schema:
          type: string
          enum:
          - SCHEDULED
          - STARTED
          - STOPPED
          - ENDED
          - MODIFY_PENDING
        example: SCHEDULED
      - name: targetName
        in: query
        description: Filter by associated target name.
        schema:
          type: string
        example: example_value
      - $ref: '#/components/parameters/limitQuery'
      - $ref: '#/components/parameters/offsetQuery'
      responses:
        '200':
          description: A paginated list of blackouts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlackoutCollection'
              examples:
                Listblackouts200Example:
                  summary: Default listBlackouts 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - blackoutId: '500123'
                      blackoutName: example_value
                      description: A sample description.
                      status: SCHEDULED
                      reason: example_value
                      createdBy: example_value
                      targets: {}
                      timeCreated: '2026-01-15T10:30:00Z'
                      timeUpdated: '2026-01-15T10:30:00Z'
                      canonicalLink: https://www.example.com
                    totalCount: 10
                    limit: 10
                    offset: 10
                    hasMore: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createBlackout
      summary: Oracle Enterprise Manager Create a Blackout
      description: Creates a new blackout (maintenance window) for one or more targets. During a blackout, monitoring data is still collected but alerts and notifications are suppressed.
      tags:
      - Blackouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlackoutCreateRequest'
            examples:
              CreateblackoutRequestExample:
                summary: Default createBlackout request
                x-microcks-default: true
                value:
                  blackoutName: example_value
                  description: A sample description.
                  reason: example_value
                  schedule:
                    startTime: '2026-01-15T10:30:00Z'
                    endTime: '2026-01-15T10:30:00Z'
                    duration: 10
                    timezone: example_value
                    frequency: ONCE
                    repeatInterval: 10
                    daysOfWeek:
                    - {}
                  targets:
                  - targetName: example_value
                    targetType: example_value
                    includeMembers: true
      responses:
        '201':
          description: Blackout created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blackout'
              examples:
                Createblackout201Example:
                  summary: Default createBlackout 201 response
                  x-microcks-default: true
                  value:
                    blackoutId: '500123'
                    blackoutName: example_value
                    description: A sample description.
                    status: SCHEDULED
                    reason: example_value
                    createdBy: example_value
                    schedule:
                      startTime: '2026-01-15T10:30:00Z'
                      endTime: '2026-01-15T10:30:00Z'
                      duration: 10
                      timezone: example_value
                      frequency: ONCE
                      repeatInterval: 10
                      daysOfWeek:
                      - {}
                    targets:
                    - targetName: example_value
                      targetType: example_value
                      includeMembers: true
                    timeCreated: '2026-01-15T10:30:00Z'
                    timeUpdated: '2026-01-15T10:30:00Z'
                    canonicalLink: https://www.example.com
          headers:
            Location:
              description: URI of the newly created blackout resource.
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /blackouts/{blackoutId}:
    get:
      operationId: getBlackout
      summary: Oracle Enterprise Manager Get Blackout Details
      description: Returns detailed information about a specific blackout including its schedule, affected targets, status, and reason.
      tags:
      - Blackouts
      parameters:
      - $ref: '#/components/parameters/blackoutIdPath'
      responses:
        '200':
          description: Blackout details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blackout'
              examples:
                Getblackout200Example:
                  summary: Default getBlackout 200 response
                  x-microcks-default: true
                  value:
                    blackoutId: '500123'
                    blackoutName: example_value
                    description: A sample description.
                    status: SCHEDULED
                    reason: example_value
                    createdBy: example_value
                    schedule:
                      startTime: '2026-01-15T10:30:00Z'
                      endTime: '2026-01-15T10:30:00Z'
                      duration: 10
                      timezone: example_value
                      frequency: ONCE
                      repeatInterval: 10
                      daysOfWeek:
                      - {}
                    targets:
                    - targetName: example_value
                      targetType: example_value
                      includeMembers: true
                    timeCreated: '2026-01-15T10:30:00Z'
                    timeUpdated: '2026-01-15T10:30:00Z'
                    canonicalLink: https://www.example.com
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: editBlackout
      summary: Oracle Enterprise Manager Edit a Blackout
      description: Modifies an existing blackout. Can update the schedule, targets, reason, or other properties. Only scheduled or started blackouts can be edited.
      tags:
      - Blackouts
      parameters:
      - $ref: '#/components/parameters/blackoutIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlackoutUpdateRequest'
            examples:
              EditblackoutRequestExample:
                summary: Default editBlackout request
                x-microcks-default: true
                value:
                  description: A sample description.
                  reason: example_value
                  schedule:
                    startTime: '2026-01-15T10:30:00Z'
                    endTime: '2026-01-15T10:30:00Z'
                    duration: 10
                    timezone: example_value
                    frequency: ONCE
                    repeatInterval: 10
                    daysOfWeek:
                    - {}
                  targets:
                  - targetName: example_value
                    targetType: example_value
                    includeMembers: true
      responses:
        '200':
          description: Blackout updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blackout'
              examples:
                Editblackout200Example:
                  summary: Default editBlackout 200 response
                  x-microcks-default: true
                  value:
                    blackoutId: '500123'
                    blackoutName: example_value
                    description: A sample description.
                    status: SCHEDULED
                    reason: example_value
                    createdBy: example_value
                    schedule:
                      startTime: '2026-01-15T10:30:00Z'
                      endTime: '2026-01-15T10:30:00Z'
                      duration: 10
                      timezone: example_value
                      frequency: ONCE
                      repeatInterval: 10
                      daysOfWeek:
                      - {}
                    targets:
                    - targetName: example_value
                      targetType: example_value
                      includeMembers: true
                    timeCreated: '2026-01-15T10:30:00Z'
                    timeUpdated: '2026-01-15T10:30:00Z'
                    canonicalLink: https://www.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteBlackout
      summary: Oracle Enterprise Manager Delete a Blackout
      description: Deletes a blackout. Only scheduled (not yet started) blackouts can be deleted. Use the stop action to end an active blackout.
      tags:
      - Blackouts
      parameters:
      - $ref: '#/components/parameters/blackoutIdPath'
      responses:
        '204':
          description: Blackout deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /blackouts/{blackoutId}/actions/stop:
    post:
      operationId: stopBlackout
      summary: Oracle Enterprise Manager Stop a Blackout
      description: Stops an active blackout before its scheduled end time. Monitoring and alerting resume immediately for all affected targets.
      tags:
      - Blackouts
      parameters:
      - $ref: '#/components/parameters/blackoutIdPath'
      responses:
        '200':
          description: Blackout stopped successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blackout'
              examples:
                Stopblackout200Example:
                  summary: Default stopBlackout 200 response
                  x-microcks-default: true
                  value:
                    blackoutId: '500123'
                    blackoutName: example_value
                    description: A sample description.
                    status: SCHEDULED
                    reason: example_value
                    createdBy: example_value
                    schedule:
                      startTime: '2026-01-15T10:30:00Z'
                      endTime: '2026-01-15T10:30:00Z'
                      duration: 10
                      timezone: example_value
                      frequency: ONCE
                      repeatInterval: 10
                      daysOfWeek:
                      - {}
                    targets:
                    - targetName: example_value
                      targetType: example_value
                      includeMembers: true
                    timeCreated: '2026-01-15T10:30:00Z'
                    timeUpdated: '2026-01-15T10:30:00Z'
                    canonicalLink: https://www.example.com
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Blackout is not in a stoppable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Stopblackout409Example:
                  summary: Default stopBlackout 409 response
                  x-microcks-default: true
                  value:
                    errorCode: example_value
                    message: example_value
                    details: example_value
                    httpStatusCode: 10
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /blackouts/{blackoutId}/targets:
    get:
      operationId: getBlackoutTargets
      summary: Oracle Enterprise Manager Get Blackout Targets
      description: Returns the list of targets affected by a specific blackout, including both directly specified targets and targets included via group membership.
      tags:
      - Blackouts
      parameters:
      - $ref: '#/components/parameters/blackoutIdPath'
      responses:
        '200':
          description: A list of targets in the blackout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlackoutTargetCollection'
              examples:
                Getblackouttargets200Example:
                  summary: Default getBlackoutTargets 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - targetName: example_value
                      targetType: example_value
                      includeMembers: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /blackouts/dashboard:
    get:
      operationId: getBlackoutDashboard
      summary: Oracle Enterprise Manager Get Blackout Statistics
      description: Returns summary statistics about blackouts including counts by status, upcoming blackouts, and recently ended blackouts.
      tags:
      - Blackouts
      responses:
        '200':
          description: Blackout dashboard statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlackoutDashboard'
              examples:
                Getblackoutdashboard200Example:
                  summary: Default getBlackoutDashboard 200 response
                  x-microcks-default: true
                  value:
                    totalBlackouts: 10
                    activeBlackouts: 10
                    scheduledBlackouts: 10
                    endedBlackouts: 10
                    targetsInBlackout: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /blackouts/reasons:
    get:
      operationId: listBlackoutReasons
      summary: Oracle Enterprise Manager List Blackout Reasons
      description: Returns a list of predefined blackout reasons that can be associated with blackouts for categorization and reporting.
      tags:
      - Blackouts
      responses:
        '200':
          description: A list of blackout reasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlackoutReasonCollection'
              examples:
                Listblackoutreasons200Example:
                  summary: Default listBlackoutReasons 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - reasonId: '500123'
                      reason: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createBlackoutReason
      summary: Oracle Enterprise Manager Create a Blackout Reason
      description: Creates a new blackout reason that can be used when creating or editing blackouts.
      tags:
      - Blackouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlackoutReasonCreateRequest'
            examples:
              CreateblackoutreasonRequestExample:
                summary: Default createBlackoutReason request
                x-microcks-default: true
                value:
                  reason: example_value
      responses:
        '201':
          description: Blackout reason created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlackoutReason'
              examples:
                Createblackoutreason201Example:
                  summary: Default createBlackoutReason 201 response
                  x-microcks-default: true
                  value:
                    reasonId: '500123'
                    reason: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /blackouts/reasons/{reasonId}:
    delete:
      operationId: deleteBlackoutReason
      summary: Oracle Enterprise Manager Delete a Blackout Reason
      description: Deletes a blackout reason by its identifier.
      tags:
      - Blackouts
      parameters:
      - name: reasonId
        in: path
        required: true
        description: Unique identifier of the blackout reason.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: Blackout reason deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    BlackoutSchedule:
      type: object
      description: Schedule definition for a blackout.
      properties:
        startTime:
          type: string
          format: date-time
          description: Scheduled start time of the blackout.
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          description: Scheduled end time of the blackout.
          example: '2026-01-15T10:30:00Z'
        duration:
          type: integer
          description: Duration in minutes if no explicit end time is specified.
          example: 10
        timezone:
          type: string
          description: Time zone for the schedule.
          example: example_value
        frequency:
          type: string
          description: Recurrence frequency for repeating blackouts.
          enum:
          - ONCE
          - DAILY
          - WEEKLY
          - MONTHLY
          - YEARLY
          example: ONCE
        repeatInterval:
          type: integer
          description: Interval for repeating blackouts (e.g., every 2 weeks).
          example: 10
        daysOfWeek:
          type: array
          description: Days of the week for weekly recurrence.
          items:
            type: string
            enum:
            - SUNDAY
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
          example: []
    Error:
      type: object
      description: Error response returned by the API.
      properties:
        errorCode:
          type: string
          description: Machine-readable error code.
          example: example_value
        message:
          type: string
          description: Human-readable error message.
          example: example_value
        details:
          type: string
          description: Additional details about the error.
          example: example_value
        httpStatusCode:
          type: integer
          description: HTTP status code.
          example: 10
    BlackoutCreateRequest:
      type: object
      description: Request body for creating a new blackout.
      required:
      - blackoutName
      - schedule
      - targets
      properties:
        blackoutName:
          type: string
          description: Display name for the blackout.
          example: example_value
        description:
          type: string
          description: Description of the blackout purpose.
          example: A sample description.
        reason:
          type: string
          description: Reason for the blackout.
          example: example_value
        schedule:
          $ref: '#/components/schemas/BlackoutSchedule'
        targets:
          type: array
          description: List of targets to include in the blackout.
          items:
            $ref: '#/components/schemas/BlackoutTarget'
          example: []
    BlackoutTarget:
      type: object
      description: A target included in a blackout.
      properties:
        targetName:
          type: string
          description: Name of the target.
          example: example_value
        targetType:
          type: string
          description: Type of the target.
          example: example_value
        includeMembers:
          type: boolean
          description: Whether to include member targets (for composite targets and groups).
          example: true
    BlackoutCollection:
      type: object
      description: Paginated collection of blackouts.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Blackout'
          example: []
        totalCount:
          type: integer
          example: 10
        limit:
          type: integer
          example: 10
        offset:
          type: integer
          example: 10
        hasMore:
          type: boolean
          example: true
    BlackoutUpdateRequest:
      type: object
      description: Request body for updating a blackout.
      properties:
        description:
          type: string
          example: A sample description.
        reason:
          type: string
          example: example_value
        schedule:
          $ref: '#/components/schemas/BlackoutSchedule'
        targets:
          type: array
          items:
            $ref: '#/components/schemas/BlackoutTarget'
          example: []
    BlackoutReasonCreateRequest:
      type: object
      description: Request body for creating a blackout reason.
      required:
      - reason
      properties:
        reason:
          type: string
          description: Text of the blackout reason.
          example: example_value
    BlackoutReason:
      type: object
      description: A predefined reason for blackouts.
      properties:
        reasonId:
          type: string
          description: Unique identifier for the reason.
          example: '500123'
        reason:
          type: string
          description: Text of the blackout reason.
          example: example_value
    BlackoutTargetCollection:
      type: object
      description: Collection of targets in a blackout.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BlackoutTarget'
          example: []
    BlackoutDashboard:
      type: object
      description: Summary statistics for blackouts.
      properties:
        totalBlackouts:
          type: integer
          description: Total number of blackouts.
          example: 10
        activeBlackouts:
          type: integer
          description: Number of currently active blackouts.
          example: 10
        scheduledBlackouts:
          type: integer
          description: Number of scheduled future blackouts.
          example: 10
        endedBlackouts:
          type: integer
          description: Number of ended blackouts.
          example: 10
        targetsInBlackout:
          type: integer
          description: Total number of targets currently in blackout.
          example: 10
    BlackoutReasonCollection:
      type: object
      description: Collection of blackout reasons.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BlackoutReason'
          example: []
    Blackout:
      type: object
      description: Represents a blackout (maintenance window) in Enterprise Manager. Blackouts suppress alerting and notifications for specified targets during scheduled maintenance periods.
      properties:
        blackoutId:
          type: string
          description: Unique identifier of the blackout.
          example: '500123'
        blackoutName:
          type: string
          description: Display name of the blackout.
          example: example_value
        description:
          type: string
          description: Description of the blackout purpose.
          example: A sample description.
        status:
          type: string
          description: Current status of the blackout.
          enum:
          - SCHEDULED
          - STARTED
          - STOPPED
          - ENDED
          - MODIFY_PENDING
          example: SCHEDULED
        reason:
          type: string
          description: Reason for the blackout.
          example: example_value
        createdBy:
          type: string
          description: Username of the blackout creator.
          example: example_value
        schedule:
          $ref: '#/components/schemas/BlackoutSchedule'
        targets:
          type: array
          description: List of targets included in the blackout.
          items:
            $ref: '#/components/schemas/BlackoutTarget'
          example: []
        timeCreated:
          type: string
          format: date-time
          description: Timestamp when the blackout was created.
          example: '2026-01-15T10:30:00Z'
        timeUpdated:
          type: string
          format: date-time
          description: Timestamp of the last blackout update.
          example: '2026-01-15T10:30:00Z'
        canonicalLink:
          type: string
          format: uri
          description: Canonical URI for this blackout resource.
          example: https://www.example.com
  parameters:
    limitQuery:
      name: limit
      in: query
      description: Maximum number of items to return per page.
      schema:
        type: integer
        default: 25
        minimum: 1
        maximum: 1000
    blackoutIdPath:
      name: blackoutId
      in: path
      required: true
      description: Unique identifier of the blackout.
      schema:
        type: string
    offsetQuery:
      name: offset
      in: query
      description: Number of items to skip for pagination.
      schema:
        type: integer
        default: 0
        minimum: 0
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed. Provide valid Enterprise Manager credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid. Check the request body and parameters for errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: The request conflicts with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Enterprise Manager administrator credentials. All API requests must include valid credentials.
externalDocs:
  description: Oracle Enterprise Manager Cloud Control REST API Documentation
  url: https://docs.oracle.com/en/enterprise-manager/cloud-control/enterprise-manager-cloud-control/13.5/emrest/APIOverview.html