SAP HANA Cloud REST API

openapi: 3.1.0
info:
  title: SAP HANA Cloud REST 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: [email protected]
  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: Instances
  description: >-
    Operations for managing SAP HANA Cloud database instances including
    provisioning, configuration, lifecycle management, and status retrieval.
- 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.
- name: Metrics
  description: >-
    Operations for retrieving database performance metrics and resource
    utilization data for SAP HANA Cloud instances.
- name: Metering
  description: >-
    Operations for accessing consumption metering data used for billing and
    capacity planning for SAP HANA Cloud instances.
- name: Instance Mappings
  description: >-
    Operations for creating and managing instance mappings that associate
    SAP HANA Cloud instances across subaccounts and environments.
paths:
  /v1/service_instances:
    get:
      operationId: listServiceInstances
      summary: List All Sap Hana Cloud Service Instances
      description: >-
        Retrieves a list of all SAP HANA Cloud service instances provisioned
        in the current subaccount. Results can be filtered using query parameters
        to narrow down by service plan, label, or other criteria. The response
        includes instance metadata, configuration parameters, and current status.
      tags:
      - Instances
      parameters:
      - $ref: '#/components/parameters/FieldQuery'
      - $ref: '#/components/parameters/LabelQuery'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved the list of service instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInstanceList'
              examples:
                Listserviceinstances200Example:
                  summary: Default listServiceInstances 200 response
                  x-microcks-default: true
                  value:
                    num_items: 10
                    items:
                    - id: abc123
                      name: Example Title
                      service_plan_id: '500123'
                      platform_id: '500123'
                      context: {}
                      labels: example_value
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
                      ready: true
                      usable: true
                    token: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createServiceInstance
      summary: Create a New Sap Hana Cloud Service Instance
      description: >-
        Provisions a new SAP HANA Cloud database instance in the current
        subaccount. The request body must include the service plan identifier,
        instance name, and configuration parameters such as memory size, vCPU
        count, storage size, system password, and optional features like
        script server, document store, or data lake. The instance is created
        asynchronously and the response includes the instance identifier for
        tracking provisioning status.
      tags:
      - Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceInstanceRequest'
            examples:
              CreateserviceinstanceRequestExample:
                summary: Default createServiceInstance request
                x-microcks-default: true
                value:
                  name: Example Title
                  service_plan_id: '500123'
                  parameters:
                    data:
                      edition: cloud
                      memory: 10
                      vcpu: 10
                      storage: 10
                      systempassword: example_value
                      whitelistIPs: {}
                      enabledservices: {}
                      serviceStopped: true
                      availabilityZone: example_value
                      slaLevel: standard
                  labels: example_value
      responses:
        '201':
          description: Service instance creation initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInstance'
              examples:
                Createserviceinstance201Example:
                  summary: Default createServiceInstance 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    service_plan_id: '500123'
                    platform_id: '500123'
                    context:
                      subaccount_id: '500123'
                      organization_guid: '500123'
                      space_guid: '500123'
                      instance_name: example_value
                    parameters:
                      data:
                        edition: cloud
                        memory: 10
                        vcpu: 10
                        storage: 10
                        systempassword: example_value
                        whitelistIPs: {}
                        enabledservices: {}
                        serviceStopped: true
                        availabilityZone: example_value
                        slaLevel: standard
                    labels: example_value
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    ready: true
                    usable: true
                    last_operation:
                      type: create
                      state: succeeded
                      description: A sample description.
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '202':
          description: Service instance creation accepted and processing asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInstance'
              examples:
                Createserviceinstance202Example:
                  summary: Default createServiceInstance 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    service_plan_id: '500123'
                    platform_id: '500123'
                    context:
                      subaccount_id: '500123'
                      organization_guid: '500123'
                      space_guid: '500123'
                      instance_name: example_value
                    parameters:
                      data:
                        edition: cloud
                        memory: 10
                        vcpu: 10
                        storage: 10
                        systempassword: example_value
                        whitelistIPs: {}
                        enabledservices: {}
                        serviceStopped: true
                        availabilityZone: example_value
                        slaLevel: standard
                    labels: example_value
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    ready: true
                    usable: true
                    last_operation:
                      type: create
                      state: succeeded
                      description: A sample description.
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/service_instances/{instanceId}:
    get:
      operationId: getServiceInstance
      summary: Retrieve a Specific Sap Hana Cloud Service Instance
      description: >-
        Retrieves the details of a specific SAP HANA Cloud service instance
        identified by its unique instance ID. The response includes the full
        configuration, current status, connection endpoints, and metadata.
      tags:
      - Instances
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: Successfully retrieved the service instance details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInstance'
              examples:
                Getserviceinstance200Example:
                  summary: Default getServiceInstance 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    service_plan_id: '500123'
                    platform_id: '500123'
                    context:
                      subaccount_id: '500123'
                      organization_guid: '500123'
                      space_guid: '500123'
                      instance_name: example_value
                    parameters:
                      data:
                        edition: cloud
                        memory: 10
                        vcpu: 10
                        storage: 10
                        systempassword: example_value
                        whitelistIPs: {}
                        enabledservices: {}
                        serviceStopped: true
                        availabilityZone: example_value
                        slaLevel: standard
                    labels: example_value
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    ready: true
                    usable: true
                    last_operation:
                      type: create
                      state: succeeded
                      description: A sample description.
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '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: updateServiceInstance
      summary: Update an Sap Hana Cloud Service Instance
      description: >-
        Updates the configuration of an existing SAP HANA Cloud service instance.
        This operation supports starting and stopping instances by setting the
        serviceStopped parameter, scaling memory and vCPU resources, updating
        allowed IP addresses, modifying storage size, and changing other
        configuration parameters. The update is processed asynchronously.
      tags:
      - Instances
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceInstanceRequest'
            examples:
              UpdateserviceinstanceRequestExample:
                summary: Default updateServiceInstance request
                x-microcks-default: true
                value:
                  name: Example Title
                  parameters:
                    data:
                      edition: cloud
                      memory: 10
                      vcpu: 10
                      storage: 10
                      systempassword: example_value
                      whitelistIPs: {}
                      enabledservices: {}
                      serviceStopped: true
                      availabilityZone: example_value
                      slaLevel: standard
                  labels: example_value
                  service_plan_id: '500123'
      responses:
        '200':
          description: Service instance update completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInstance'
              examples:
                Updateserviceinstance200Example:
                  summary: Default updateServiceInstance 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    service_plan_id: '500123'
                    platform_id: '500123'
                    context:
                      subaccount_id: '500123'
                      organization_guid: '500123'
                      space_guid: '500123'
                      instance_name: example_value
                    parameters:
                      data:
                        edition: cloud
                        memory: 10
                        vcpu: 10
                        storage: 10
                        systempassword: example_value
                        whitelistIPs: {}
                        enabledservices: {}
                        serviceStopped: true
                        availabilityZone: example_value
                        slaLevel: standard
                    labels: example_value
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    ready: true
                    usable: true
                    last_operation:
                      type: create
                      state: succeeded
                      description: A sample description.
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '202':
          description: Service instance update accepted and processing asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInstance'
              examples:
                Updateserviceinstance202Example:
                  summary: Default updateServiceInstance 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    service_plan_id: '500123'
                    platform_id: '500123'
                    context:
                      subaccount_id: '500123'
                      organization_guid: '500123'
                      space_guid: '500123'
                      instance_name: example_value
                    parameters:
                      data:
                        edition: cloud
                        memory: 10
                        vcpu: 10
                        storage: 10
                        systempassword: example_value
                        whitelistIPs: {}
                        enabledservices: {}
                        serviceStopped: true
                        availabilityZone: example_value
                        slaLevel: standard
                    labels: example_value
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    ready: true
                    usable: true
                    last_operation:
                      type: create
                      state: succeeded
                      description: A sample description.
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteServiceInstance
      summary: Delete an Sap Hana Cloud Service Instance
      description: >-
        Deletes an SAP HANA Cloud service instance and all associated data.
        This operation is irreversible and permanently removes the database
        instance, all stored data, backups, and configuration. The deletion
        is processed asynchronously.
      tags:
      - Instances
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: Service instance deletion completed successfully.
        '202':
          description: Service instance deletion accepted and processing asynchronously.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /inventory/v2/serviceInstances:
    get:
      operationId: listInventoryInstances
      summary: List Sap Hana Cloud Instances in Inventory
      description: >-
        Retrieves an inventory listing of all SAP HANA Cloud instances across
        the subaccount, including both SAP HANA database and data lake instances.
        The inventory provides a consolidated view of all instances with their
        current operational status, resource allocation, and basic configuration.
      tags:
      - Instances
      parameters:
      - name: provisioningState
        in: query
        description: Filter instances by their current provisioning state.
        schema:
          type: string
          enum:
          - Provisioned
          - Provisioning
          - Deprovisioning
          - Error
        example: Provisioned
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully retrieved the inventory of service instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryInstanceList'
              examples:
                Listinventoryinstances200Example:
                  summary: Default listInventoryInstances 200 response
                  x-microcks-default: true
                  value:
                    totalCount: 10
                    items:
                    - serviceInstanceId: '500123'
                      servicePlanName: example_value
                      instanceName: example_value
                      provisioningState: Provisioned
                      operationalState: Started
                      memory: 10
                      vcpu: 10
                      storage: 10
                      createdAt: '2026-01-15T10:30:00Z'
                      modifiedAt: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /metrics/v1/serviceInstances/{serviceInstanceId}/values:
    get:
      operationId: getMetricValues
      summary: Retrieve Metric Values for a Service Instance
      description: >-
        Retrieves database performance and resource utilization metrics for a
        specific SAP HANA Cloud service instance. Metrics include CPU usage,
        memory consumption, disk utilization, connection counts, statement
        execution statistics, and other operational indicators. Data can be
        queried for specific time ranges and metric types.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/ServiceInstanceId'
      - name: metricType
        in: query
        description: >-
          Filter metrics by type. Specify one or more metric types to retrieve
          specific categories of performance data.
        schema:
          type: string
          enum:
          - cpu
          - memory
          - disk
          - connections
          - statements
          - network
          - rowstore
          - columnstore
        example: cpu
      - name: fromTimestamp
        in: query
        description: >-
          Start timestamp for the metrics query window in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: toTimestamp
        in: query
        description: >-
          End timestamp for the metrics query window in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: granularity
        in: query
        description: >-
          The aggregation granularity for metric data points. Determines the
          time interval between data points in the response.
        schema:
          type: string
          enum:
          - MINUTE
          - FIVE_MINUTES
          - HOUR
          - DAY
        example: MINUTE
      responses:
        '200':
          description: Successfully retrieved metric values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricValueList'
              examples:
                Getmetricvalues200Example:
                  summary: Default getMetricValues 200 response
                  x-microcks-default: true
                  value:
                    metrics:
                    - metricType: example_value
              

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sap-hana/refs/heads/main/openapi/sap-hana-cloud-rest-api.yml