GitHub Maintenance API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub Setup Maintenance API
  description: The GitHub Setup APIs provide endpoints for configuring and managing the initial setup and administrative settings of GitHub Enterprise Server instances. These APIs allow system administrators to programmatically control enterprise-level configurations such as authentication settings, license management, maintenance mode operations, server statistics and health checks, and other foundational setup tasks required to deploy and maintain a GitHub Enterprise Server installation. This API is primarily used by DevOps teams and system administrators to automate GitHub Enterprise Server deployments, integrate server management into infrastructure-as-code workflows, monitor server health and performance, and ensure consistent configuration across multiple enterprise instances.
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  x-github-plan: ghes
  x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
tags:
- name: Maintenance
paths:
  /setup/api/maintenance:
    get:
      summary: GitHub Get the Maintenance Status
      description: The GitHub Setup API endpoint `/setup/api/maintenance` using the GET method retrieves the current maintenance status of a GitHub Enterprise Server instance. This operation allows administrators and monitoring systems to programmatically check whether the server is currently in maintenance mode, which is useful for coordinating deployments, upgrades, or troubleshooting activities. The endpoint returns information about the maintenance state, helping teams understand if the instance is available for normal operations or if maintenance procedures are currently active, enabling better orchestration of administrative tasks and communication with users about system availability.
      operationId: getTheMaintenanceStatus
      tags:
      - Maintenance
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/management-console#get-the-maintenance-status
      servers:
      - url: '{protocol}://{hostname}'
        variables:
          hostname:
            default: HOSTNAME
            description: Self-hosted Enterprise Server hostname
          protocol:
            default: http
            description: Self-hosted Enterprise Server protocol
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/maintenance-status'
              examples:
                default:
                  $ref: '#/components/examples/maintenance-status'
        '401':
          description: Unauthorized
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: management-console
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: GitHub Enable or Disable Maintenance Mode
      description: '**Note:** The request body for this operation must be submitted as `application/x-www-form-urlencoded` data. You can submit a parameter value as a string, or you can use a tool such as `curl` to submit a parameter value as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode).'
      operationId: enableOrDisableMaintenanceMode
      tags:
      - Maintenance
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/management-console#enable-or-disable-maintenance-mode
      servers:
      - url: '{protocol}://{hostname}'
        variables:
          hostname:
            default: HOSTNAME
            description: Self-hosted Enterprise Server hostname
          protocol:
            default: http
            description: Self-hosted Enterprise Server protocol
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/maintenance-status'
              examples:
                default:
                  $ref: '#/components/examples/maintenance-status'
        '401':
          description: Unauthorized
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                maintenance:
                  type: string
                  description: 'A JSON string with the attributes `enabled` and `when`.


                    The possible values for `enabled` are `true` and `false`. When it''s `false`, the attribute `when` is ignored and the maintenance mode is turned off. `when` defines the time period when the maintenance was enabled.


                    The possible values for `when` are `now` or any date parseable by [mojombo/chronic](https://github.com/mojombo/chronic).'
              required:
              - maintenance
            examples:
              default:
                value:
                  maintenance: '{"enabled":true, "when":"now"}'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: management-console
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    maintenance-status:
      value:
        status: scheduled
        scheduled_time: Tuesday, January 22 at 15:34 -0800
        connection_services:
        - name: git operations
          number: 0
        - name: mysql queries
          number: 233
        - name: aqueduct jobs
          number: 34
        - name: resque jobs
          number: 54
  schemas:
    maintenance-status:
      type: object
      properties:
        status:
          type: string
          example: open
        scheduled_time:
          type: string
          example: '2026-04-17T12:00:00Z'
        connection_services:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              number:
                type: integer
            required:
            - name
            - number
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/