GitHub Modes API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub Setup Modes 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: Modes
paths:
  /setup/api/maintenance:
    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:
      - Modes
      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/