Azure SQL Database FailoverGroups API

openapi: 3.0.0
info:
  title: Azure SQL Database failoverGroups API (Microsoft.Sql 2025-01-01)
  version: 2025-01-01
  description: The Azure SQL Database management API provides a RESTful set of web APIs that interact with Azure SQL Database services to manage your databases. The API enables users to create, retrieve,
    update, and delete databases, servers, and other entities.
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
  x-source: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/sql/resource-manager/Microsoft.Sql/SQL/stable/2025-01-01/failoverGroups.json
  x-provenance:
    method: searched
    generated: '2026-11-05'
    note: Converted Swagger 2.0 to OpenAPI 3 (swagger2openapi, refs resolved, x-ms-examples dropped) from Microsoft own Azure/azure-rest-api-specs repo; host management.azure.com is Azure Resource Manager,
      operated by Microsoft. Verbatim originals in openapi/_original/.
security:
- azure_auth:
  - user_impersonation
tags:
- name: FailoverGroups
paths:
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/failoverGroups
  : get:
      operationId: FailoverGroups_ListByServer
      tags:
      - FailoverGroups
      description: Lists the failover groups in a server.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroupListResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/failoverGroups/{failoverGroupName}
  : get:
      operationId: FailoverGroups_Get
      tags:
      - FailoverGroups
      description: Gets a failover group.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: FailoverGroups_CreateOrUpdate
      tags:
      - FailoverGroups
      description: Creates or updates a failover group.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailoverGroup'
        description: The failover group parameters.
        required: true
      responses:
        '200':
          description: Resource 'FailoverGroup' update operation succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        '201':
          description: Resource 'FailoverGroup' create operation succeeded
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        '202':
          description: Resource operation accepted.
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation-options:
        final-state-via: location
        final-state-schema: '#/definitions/FailoverGroup'
      x-ms-long-running-operation: true
    patch:
      operationId: FailoverGroups_Update
      tags:
      - FailoverGroups
      description: Updates a failover group.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailoverGroupUpdate'
        description: The failover group parameters.
        required: true
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        '202':
          description: Resource update request accepted.
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation-options:
        final-state-via: location
        final-state-schema: '#/definitions/FailoverGroup'
      x-ms-long-running-operation: true
    delete:
      operationId: FailoverGroups_Delete
      tags:
      - FailoverGroups
      description: Deletes a failover group.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resource deleted successfully.
        '202':
          description: Resource deletion accepted.
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        '204':
          description: Resource does not exist.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation-options:
        final-state-via: location
      x-ms-long-running-operation: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/failoverGroups/{failoverGroupName}/failover
  : post:
      operationId: FailoverGroups_Failover
      tags:
      - FailoverGroups
      description: Fails over from the current primary server to this server.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        '202':
          description: Resource operation accepted.
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation-options:
        final-state-via: location
        final-state-schema: '#/definitions/FailoverGroup'
      x-ms-long-running-operation: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/failoverGroups/{failoverGroupName}/forceFailoverAllowDataLoss
  : post:
      operationId: FailoverGroups_ForceFailoverAllowDataLoss
      tags:
      - FailoverGroups
      description: Fails over from the current primary server to this server. This operation might result in data loss.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        '202':
          description: Resource operation accepted.
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation-options:
        final-state-via: location
        final-state-schema: '#/definitions/FailoverGroup'
      x-ms-long-running-operation: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/failoverGroups/{failoverGroupName}/tryPlannedBeforeForcedFailover
  : post:
      operationId: FailoverGroups_TryPlannedBeforeForcedFailover
      tags:
      - FailoverGroups
      description: Fails over from the current primary server to this server. This operation tries planned before forced failover but might still result in data loss.
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - name: serverName
        in: path
        description: The name of the server.
        required: true
        schema:
          type: string
      - name: failoverGroupName
        in: path
        description: The name of the failover group.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailoverGroup'
        '202':
          description: Resource operation accepted.
          headers:
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
            Retry-After:
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
              schema:
                type: integer
                format: int32
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation-options:
        final-state-via: location
        final-state-schema: '#/definitions/FailoverGroup'
      x-ms-long-running-operation: true
servers:
- url: https://management.azure.com
components:
  parameters:
    ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      schema:
        type: string
        minLength: 1
    SubscriptionIdParameter:
      name: subscriptionId
      in: path
      description: The ID of the target subscription. The value must be an UUID.
      required: true
      schema:
        type: string
        format: uuid
    ResourceGroupNameParameter:
      name: resourceGroupName
      in: path
      description: The name of the resource group. The name is case insensitive.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
        minLength: 1
        maxLength: 90
  securitySchemes:
    azure_auth:
      type: oauth2
      description: Azure Active Directory OAuth2 Flow.
      flows:
        implicit:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
          scopes:
            user_impersonation: impersonate your user account
  schemas:
    FailoverGroup:
      type: object
      description: A failover group.
      properties:
        properties:
          $ref: '#/components/schemas/FailoverGroupProperties'
        tags:
          type: object
          description: Resource tags.
          additionalProperties:
            type: string
        location:
          type: string
          description: Resource location.
          readOnly: true
      allOf:
      - type: object
        title: Proxy Resource
        description: The resource model definition for a Azure Resource Manager proxy resource. It will not have tags and a location
        allOf:
        - type: object
          title: Resource
          description: Common fields that are returned in the response for all Azure Resource Manager resources
          properties:
            id:
              type: string
              format: arm-id
              description: Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
              readOnly: true
            name:
              type: string
              description: The name of the resource
              readOnly: true
            type:
              type: string
              description: The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"
              readOnly: true
            systemData:
              type: object
              description: Metadata pertaining to creation and last modification of the resource.
              properties:
                createdBy:
                  type: string
                  description: The identity that created the resource.
                createdByType:
                  type: string
                  description: The type of identity that created the resource.
                  enum:
                  - User
                  - Application
                  - ManagedIdentity
                  - Key
                  x-ms-enum:
                    name: createdByType
                    modelAsString: true
                createdAt:
                  type: string
                  format: date-time
                  description: The timestamp of resource creation (UTC).
                lastModifiedBy:
                  type: string
                  description: The identity that last modified the resource.
                lastModifiedByType:
                  type: string
                  description: The type of identity that last modified the resource.
                  enum:
                  - User
                  - Application
                  - ManagedIdentity
                  - Key
                  x-ms-enum:
                    name: createdByType
                    modelAsString: true
                lastModifiedAt:
                  type: string
                  format: date-time
                  description: The timestamp of resource last modification (UTC)
              readOnly: true
          x-ms-azure-resource: true
    FailoverGroupListResult:
      type: object
      description: The response of a FailoverGroup list operation.
      properties:
        value:
          type: array
          description: The FailoverGroup items on this page
          items:
            $ref: '#/components/schemas/FailoverGroup'
        nextLink:
          type: string
          format: uri
          description: The link to the next page of items
      required:
      - value
    FailoverGroupProperties:
      type: object
      description: Properties of a failover group.
      properties:
        readWriteEndpoint:
          $ref: '#/components/schemas/FailoverGroupReadWriteEndpoint'
        readOnlyEndpoint:
          $ref: '#/components/schemas/FailoverGroupReadOnlyEndpoint'
        replicationRole:
          type: string
          description: Local replication role of the failover group instance.
          enum:
          - Primary
          - Secondary
          x-ms-enum:
            name: FailoverGroupReplicationRole
            modelAsString: true
            values:
            - name: Primary
              value: Primary
              description: Primary
            - name: Secondary
              value: Secondary
              description: Secondary
        replicationState:
          type: string
          description: Replication state of the failover group instance.
          readOnly: true
        partnerServers:
          type: array
          description: List of partner server information for the failover group.
          items:
            $ref: '#/components/schemas/PartnerInfo'
        databases:
          type: array
          description: List of databases in the failover group.
          items:
            type: string
            format: arm-id
            description: A type definition that refers the id to an Azure Resource Manager resource.
            x-ms-arm-id-details:
              allowedResources:
              - type: Microsoft.Sql/servers/databases
        secondaryType:
          type: string
          description: Databases secondary type on partner server.
          enum:
          - Geo
          - Standby
          x-ms-enum:
            name: FailoverGroupDatabasesSecondaryType
            modelAsString: true
            values:
            - name: Geo
              value: Geo
              description: Geo
            - name: Standby
              value: Standby
              description: Standby
      required:
      - readWriteEndpoint
      - partnerServers
    FailoverGroupReadOnlyEndpoint:
      type: object
      description: Read-only endpoint of the failover group instance.
      properties:
        failoverPolicy:
          type: string
          description: Failover policy of the read-only endpoint for the failover group.
          enum:
          - Disabled
          - Enabled
          x-ms-enum:
            name: ReadOnlyEndpointFailoverPolicy
            modelAsString: true
            values:
            - name: Disabled
              value: Disabled
              description: Disabled
            - name: Enabled
              value: Enabled
              description: Enabled
        targetServer:
          type: string
          format: arm-id
          description: The target partner server where the read-only endpoint points to.
          x-ms-arm-id-details:
            allowedResources:
            - type: Microsoft.Sql/servers
    FailoverGroupReadWriteEndpoint:
      type: object
      description: Read-write endpoint of the failover group instance.
      properties:
        failoverPolicy:
          type: string
          description: Failover policy of the read-write endpoint for the failover group. If failoverPolicy is Automatic then failoverWithDataLossGracePeriodMinutes is required.
          enum:
          - Manual
          - Automatic
          x-ms-enum:
            name: ReadWriteEndpointFailoverPolicy
            modelAsString: true
            values:
            - name: Manual
              value: Manual
              description: Manual
            - name: Automatic
              value: Automatic
              description: Automatic
        failoverWithDataLossGracePeriodMinutes:
          type: integer
          format: int32
          description: Grace period before failover with data loss is attempted for the read-write endpoint. If failoverPolicy is Automatic then failoverWithDataLossGracePeriodMinutes is required.
      required:
      - failoverPolicy
    FailoverGroupUpdate:
      type: object
      description: A failover group update request.
      properties:
        properties:
          $ref: '#/components/schemas/FailoverGroupUpdateProperties'
        tags:
          type: object
          description: Resource tags.
          additionalProperties:
            type: string
    FailoverGroupUpdateProperties:
      type: object
      description: Properties of a failover group update.
      properties:
        readWriteEndpoint:
          $ref: '#/components/schemas/FailoverGroupReadWriteEndpoint'
        readOnlyEndpoint:
          $ref: '#/components/schemas/FailoverGroupReadOnlyEndpoint'
        databases:
          type: array
          description: List of databases in the failover group.
          items:
            type: string
            format: arm-id
            description: A type definition that refers the id to an Azure Resource Manager resource.
            x-ms-arm-id-details:
              allowedResources:
              - type: Microsoft.Sql/servers/databases
        partnerServers:
          type: array
          description: List of partner server information for the failover group.
          items:
            $ref: '#/components/schemas/PartnerInfo'
        secondaryType:
          $ref: '#/components/schemas/FailoverGroupProperties/properties/secondaryType'
    PartnerInfo:
      type: object
      description: Partner server information for the failover group.
      properties:
        id:
          type: string
          format: arm-id
          description: Resource identifier of the partner server.
          x-ms-arm-id-details:
            allowedResources:
            - type: Microsoft.Sql/servers
        location:
          type: string
          description: Geo location of the partner server.
          readOnly: true
        replicationRole:
          $ref: '#/components/schemas/FailoverGroupProperties/properties/replicationRole'
      required:
      - id
    ErrorDetail:
      type: object
      description: The error detail.
      properties:
        code:
          type: string
          description: The error code.
          readOnly: true
        message:
          type: string
          description: The error message.
          readOnly: true
        target:
          type: string
          description: The error target.
          readOnly: true
        details:
          type: array
          description: The error details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
          readOnly: true
          x-ms-identifiers:
          - message
          - target
        additionalInfo:
          type: array
          description: The error additional info.
          items:
            type: object
            description: The resource management error additional info.
            properties:
              type:
                type: string
                description: The additional info type.
                readOnly: true
              info:
                type: object
                description: The additional info.
                readOnly: true
          readOnly: true
          x-ms-identifiers: []
    ErrorResponse:
      type: object
      title: Error response
      description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
      properties:
        error:
          type: object
          description: The error detail.
          properties:
            code:
              type: string
              description: The error code.
              readOnly: true
            message:
              type: string
              description: The error message.
              readOnly: true
            target:
              type: string
              description: The error target.
              readOnly: true
            details:
              type: array
              description: The error details.
              items:
                $ref: '#/components/schemas/ErrorDetail'
              readOnly: true
              x-ms-identifiers:
              - message
              - target
            additionalInfo:
              type: array
              description: The error additional info.
              items:
                type: object
                description: The resource management error additional info.
                properties:
                  type:
                    type: string
                    description: The additional info type.
                    readOnly: true
                  info:
                    type: object
                    description: The additional info.
                    readOnly: true
              readOnly: true
              x-ms-identifiers: []