SAP HANA Alerts API

openapi: 3.1.0
info:
  title: SAP HANA Cloud REST Alerts API
  description: REST API for managing SAP HANA Cloud instances, monitoring alerts, accessing metrics, and retrieving metering data. The API uses the SAP Service Manager framework to provision, configure, start, stop, and delete SAP HANA Cloud database instances within SAP Business Technology Platform subaccounts. Additionally, the alerts and metrics endpoints provide access to triggered alerts, database performance metrics, and consumption metering data for SAP HANA Cloud, SAP HANA database and SAP HANA Cloud, data lake instances.
  version: 1.0.0
  contact:
    name: SAP SE
    url: https://www.sap.com
    email: help@sap.com
  license:
    name: SAP Developer License
    url: https://www.sap.com/about/trust-center/agreements.html
  termsOfService: https://www.sap.com/about/trust-center/agreements.html
  x-logo:
    url: https://www.sap.com/content/dam/application/shared/logos/sap-logo-svg.svg
servers:
- url: https://api.cf.{region}.hana.ondemand.com
  description: SAP HANA Cloud API (Cloud Foundry environment)
  variables:
    region:
      default: eu10
      description: SAP BTP region identifier. Common values include eu10 (Europe - Frankfurt), us10 (US East - VA), ap10 (Australia - Sydney), jp10 (Japan - Tokyo), and others based on your SAP BTP subaccount provisioning.
      enum:
      - eu10
      - eu11
      - eu20
      - eu30
      - us10
      - us20
      - us21
      - us30
      - ap10
      - ap11
      - ap12
      - ap20
      - ap21
      - jp10
      - jp20
      - br10
      - ca10
      - in30
security:
- oauth2: []
tags:
- name: Alerts
  description: Operations for accessing and managing triggered alerts for SAP HANA Cloud instances, including alert state queries, severity filtering, and alert rule configuration.
paths:
  /alerts/v1/serviceInstances/{serviceInstanceId}/events:
    get:
      operationId: listAlertEvents
      summary: List Alert Events for a Service Instance
      description: Retrieves a list of triggered alert events for a specific SAP HANA Cloud service instance. Alerts monitor database health, resource utilization, availability, and operational thresholds. Results can be filtered by alert state and severity to focus on active or critical alerts.
      tags:
      - Alerts
      parameters:
      - $ref: '#/components/parameters/ServiceInstanceId'
      - name: alertState
        in: query
        description: Filter alerts by their current state. Use Active to retrieve currently triggered alerts, or Resolved for previously triggered alerts that have returned to normal.
        schema:
          type: string
          enum:
          - Active
          - Resolved
          - All
        example: Active
      - name: severity
        in: query
        description: Filter alerts by severity level. High severity alerts indicate critical conditions requiring immediate attention.
        schema:
          type: string
          enum:
          - High
          - Medium
          - Low
          - Information
        example: High
      - name: fromTimestamp
        in: query
        description: Start timestamp for the alert event query window in ISO 8601 format. Only alerts triggered on or after this timestamp are returned.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: toTimestamp
        in: query
        description: End timestamp for the alert event query window in ISO 8601 format. Only alerts triggered on or before this timestamp are returned.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: Successfully retrieved the list of alert events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertEventList'
              examples:
                Listalertevents200Example:
                  summary: Default listAlertEvents 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - alertId: '500123'
                      alertRuleId: '500123'
                      alertName: example_value
                      alertState: Active
                      severity: High
                      description: A sample description.
                      triggeredAt: '2026-01-15T10:30:00Z'
                      resolvedAt: '2026-01-15T10:30:00Z'
                      currentValue: 42.5
                      thresholdValue: 42.5
                      unit: example_value
                      serviceInstanceId: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/v1/serviceInstances/{serviceInstanceId}/rules:
    get:
      operationId: listAlertRules
      summary: List Alert Rules for a Service Instance
      description: Retrieves all configured alert rules for a specific SAP HANA Cloud service instance. Alert rules define the conditions and thresholds that trigger alerts, including both cloud-native rules and embedded statistics server (ESS) rules.
      tags:
      - Alerts
      parameters:
      - $ref: '#/components/parameters/ServiceInstanceId'
      responses:
        '200':
          description: Successfully retrieved the list of alert rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRuleList'
              examples:
                Listalertrules200Example:
                  summary: Default listAlertRules 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - ruleId: '500123'
                      ruleName: example_value
                      ruleType: cloud-native
                      enabled: true
                      severity: High
                      metric: example_value
                      thresholdOperator: GREATER_THAN
                      thresholdValue: 42.5
                      unit: example_value
                      description: A sample description.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateAlertRules
      summary: Update Alert Rules for a Service Instance
      description: Updates the configuration of alert rules for a specific SAP HANA Cloud service instance. This allows administrators to modify alert thresholds, enable or disable specific rules, and customize alerting behavior for both cloud-native rules and ESS rules.
      tags:
      - Alerts
      parameters:
      - $ref: '#/components/parameters/ServiceInstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlertRulesRequest'
            examples:
              UpdatealertrulesRequestExample:
                summary: Default updateAlertRules request
                x-microcks-default: true
                value:
                  rules:
                  - ruleId: '500123'
                    enabled: true
                    thresholdValue: 42.5
                    severity: High
      responses:
        '200':
          description: Successfully updated the alert rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRuleList'
              examples:
                Updatealertrules200Example:
                  summary: Default updateAlertRules 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - ruleId: '500123'
                      ruleName: example_value
                      ruleType: cloud-native
                      enabled: true
                      severity: High
                      metric: example_value
                      thresholdOperator: GREATER_THAN
                      thresholdValue: 42.5
                      unit: example_value
                      description: A sample description.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AlertRuleList:
      type: object
      description: A list of alert rules configured for an SAP HANA Cloud service instance.
      properties:
        items:
          type: array
          description: The list of alert rules.
          items:
            $ref: '#/components/schemas/AlertRule'
          example: []
    AlertEvent:
      type: object
      description: An alert event representing a triggered alert condition on an SAP HANA Cloud service instance. Alerts monitor database health, resources, and operational thresholds.
      properties:
        alertId:
          type: string
          description: The unique identifier of the alert event.
          example: '500123'
        alertRuleId:
          type: string
          description: The identifier of the alert rule that triggered this event.
          example: '500123'
        alertName:
          type: string
          description: The human-readable name of the alert (e.g., Memory Usage, Disk Usage, Long-Running Statements).
          example: example_value
        alertState:
          type: string
          description: The current state of the alert event.
          enum:
          - Active
          - Resolved
          example: Active
        severity:
          type: string
          description: The severity level of the alert.
          enum:
          - High
          - Medium
          - Low
          - Information
          example: High
        description:
          type: string
          description: A detailed description of the alert condition.
          example: A sample description.
        triggeredAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the alert was triggered.
          example: '2026-01-15T10:30:00Z'
        resolvedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the alert was resolved. Null if the alert is still active.
          example: '2026-01-15T10:30:00Z'
        currentValue:
          type: number
          format: double
          description: The current metric value that triggered or relates to the alert.
          example: 42.5
        thresholdValue:
          type: number
          format: double
          description: The threshold value configured in the alert rule.
          example: 42.5
        unit:
          type: string
          description: The unit of measurement for the metric values (e.g., %, GB, count).
          example: example_value
        serviceInstanceId:
          type: string
          format: uuid
          description: The service instance identifier associated with this alert.
          example: '500123'
    Error:
      type: object
      description: Standard error response returned by the SAP HANA Cloud REST API when a request fails.
      properties:
        error:
          type: string
          description: The error code identifying the type of error.
          example: example_value
        description:
          type: string
          description: A human-readable description of the error.
          example: A sample description.
        statusCode:
          type: integer
          description: The HTTP status code associated with the error.
          example: 10
    AlertRule:
      type: object
      description: An alert rule defining the condition and threshold that triggers an alert for an SAP HANA Cloud service instance. Rules can be cloud-native or embedded statistics server (ESS) based.
      properties:
        ruleId:
          type: string
          description: The unique identifier of the alert rule.
          example: '500123'
        ruleName:
          type: string
          description: The human-readable name of the alert rule (e.g., Memory Usage Alert, Disk Full Alert).
          example: example_value
        ruleType:
          type: string
          description: The type of alert rule.
          enum:
          - cloud-native
          - ess
          example: cloud-native
        enabled:
          type: boolean
          description: Whether the alert rule is currently active.
          example: true
        severity:
          type: string
          description: The severity level assigned to alerts triggered by this rule.
          enum:
          - High
          - Medium
          - Low
          - Information
          example: High
        metric:
          type: string
          description: The metric being monitored by this rule.
          example: example_value
        thresholdOperator:
          type: string
          description: The comparison operator used to evaluate the threshold.
          enum:
          - GREATER_THAN
          - GREATER_THAN_OR_EQUAL
          - LESS_THAN
          - LESS_THAN_OR_EQUAL
          - EQUAL
          example: GREATER_THAN
        thresholdValue:
          type: number
          format: double
          description: The threshold value that triggers the alert when exceeded.
          example: 42.5
        unit:
          type: string
          description: The unit of measurement for the threshold value.
          example: example_value
        description:
          type: string
          description: A description of what this alert rule monitors.
          example: A sample description.
    AlertEventList:
      type: object
      description: A list of alert events for an SAP HANA Cloud service instance.
      properties:
        items:
          type: array
          description: The list of alert events.
          items:
            $ref: '#/components/schemas/AlertEvent'
          example: []
    UpdateAlertRulesRequest:
      type: object
      description: Request body for updating alert rules.
      properties:
        rules:
          type: array
          description: The list of alert rule updates to apply.
          items:
            type: object
            properties:
              ruleId:
                type: string
                description: The identifier of the rule to update.
              enabled:
                type: boolean
                description: Whether to enable or disable the rule.
              thresholdValue:
                type: number
                format: double
                description: The updated threshold value.
              severity:
                type: string
                description: The updated severity level.
                enum:
                - High
                - Medium
                - Low
                - Information
          example: []
  responses:
    Forbidden:
      description: The authenticated user does not have sufficient permissions to perform this operation on the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request body was valid JSON but contained semantic errors such as invalid parameter combinations or out-of-range values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found. Verify the instance identifier and ensure it exists in the current subaccount.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed. The OAuth 2.0 access token is missing, expired, or invalid. Obtain a new token using the client credentials flow.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or contained invalid parameters. Check the error description for details on what needs to be corrected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: The API rate limit has been exceeded. Retry the request after the duration indicated in the Retry-After response header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An unexpected error occurred on the server. If the issue persists, contact SAP support with the request correlation ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ServiceInstanceId:
      name: serviceInstanceId
      in: path
      required: true
      description: The unique identifier of the SAP HANA Cloud service instance for which to retrieve alerts, metrics, or metering data.
      schema:
        type: string
        format: uuid
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using SAP Business Technology Platform credentials. Obtain an access token using client credentials flow with the UAA service URL, client ID, and client secret from your SAP HANA Cloud service key. Access tokens expire after approximately 1799 seconds (30 minutes) and must be refreshed.
      flows:
        clientCredentials:
          tokenUrl: https://{subdomain}.authentication.{region}.hana.ondemand.com/oauth/token
          scopes: {}