GitHub Servers API

openapi: 3.0.3
info:
  version: 1.1.4
  title: GitHub Application About Servers API
  description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App

    installations.'
  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: Servers
paths:
  /meta:
    get:
      summary: GitHub Get Github Enterprise Server Meta Information
      description: The GitHub Meta API's GET /meta endpoint retrieves essential metadata and configuration information about a GitHub Enterprise Server instance. This operation provides details such as IP address ranges used by GitHub services, supported SSH key fingerprints, webhook IP addresses, and other infrastructure-related information that is useful for network configuration, firewall rules, and security policies. The endpoint requires no authentication and returns data in JSON format, making it a straightforward way for administrators and developers to programmatically access current GitHub Enterprise Server environment settings and verify connectivity requirements.
      tags:
      - Servers
      operationId: getGithubEnterpriseServerMetaInformation
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/meta/meta#get-apiname-meta-information
      parameters: []
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api-overview'
              examples:
                default:
                  $ref: '#/components/examples/api-overview'
        '304':
          $ref: '#/components/responses/not_modified'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: meta
        subcategory: meta
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/pages:
    get:
      summary: GitHub Get Github Enterprise Server Pages Site
      description: 'Gets information about a GitHub Enterprise Server Pages site.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Servers
      operationId: getGithubEnterpriseServerPagesSite
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#get-a-apiname-pages-site
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/page'
              examples:
                default:
                  $ref: '#/components/examples/page'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: GitHub Create Github Enterprise Server Pages Site
      description: 'Configures a GitHub Enterprise Server Pages site. For more information, see "[About GitHub Pages](/github/working-with-github-pages/about-github-pages)."


        The authenticated user must be a repository administrator, maintainer, or have the ''manage GitHub Pages settings'' permission.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Servers
      operationId: createGithubEnterpriseServerPagesSite
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#create-a-apiname-pages-site
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The source branch and directory used to publish your Pages site.
              properties:
                build_type:
                  type: string
                  description: The process in which the Page will be built. Possible values are `"legacy"` and `"workflow"`.
                  enum:
                  - legacy
                  - workflow
                source:
                  type: object
                  description: The source branch and directory used to publish your Pages site.
                  properties:
                    branch:
                      type: string
                      description: The repository branch used to publish your site's source files.
                    path:
                      type: string
                      description: 'The repository directory that includes the source files for the Pages site. Allowed paths are `/` or `/docs`. Default: `/`'
                      enum:
                      - /
                      - /docs
                      default: /
                  required:
                  - branch
              anyOf:
              - required:
                - source
              - required:
                - build_type
            examples:
              default:
                value:
                  source:
                    branch: main
                    path: /docs
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/page'
              examples:
                default:
                  $ref: '#/components/examples/page'
        '409':
          $ref: '#/components/responses/conflict'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: GitHub Update Information About Github Enterprise Server Pages Site
      description: 'Updates information for a GitHub Enterprise Server Pages site. For more information, see "[About GitHub Pages](/github/working-with-github-pages/about-github-pages).


        The authenticated user must be a repository administrator, maintainer, or have the ''manage GitHub Pages settings'' permission.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Servers
      operationId: updateInformationAboutGithubEnterpriseServerPagesSite
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#update-information-about-a-apiname-pages-site
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cname:
                  type: string
                  description: Specify a custom domain for the repository. Sending a `null` value will remove the custom domain. For more about custom domains, see "[Using a custom domain with GitHub Pages](https://docs.github.com/enterprise-server@3.9/articles/using-a-custom-domain-with-github-pages/)."
                https_enforced:
                  type: boolean
                  description: Specify whether HTTPS should be enforced for the repository.
                build_type:
                  type: string
                  description: The process by which the GitHub Pages site will be built. `workflow` means that the site is built by a custom GitHub Actions workflow. `legacy` means that the site is built by GitHub when changes are pushed to a specific branch.
                  enum:
                  - legacy
                  - workflow
                source:
                  anyOf:
                  - type: string
                    description: Update the source for the repository. Must include the branch name, and may optionally specify the subdirectory `/docs`. Possible values are `"gh-pages"`, `"master"`, and `"master /docs"`.
                    enum:
                    - gh-pages
                    - master
                    - master /docs
                  - type: object
                    description: Update the source for the repository. Must include the branch name and path.
                    properties:
                      branch:
                        type: string
                        description: The repository branch used to publish your site's source files.
                      path:
                        type: string
                        description: The repository directory that includes the source files for the Pages site. Allowed paths are `/` or `/docs`.
                        enum:
                        - /
                        - /docs
                    required:
                    - branch
                    - path
              anyOf:
              - required:
                - build_type
              - required:
                - source
              - required:
                - cname
              - required:
                - public
              - required:
                - https_enforced
            examples:
              default:
                value:
                  cname: octocatblog.com
                  source:
                    branch: main
                    path: /
      responses:
        '204':
          description: Response
        '400':
          $ref: '#/components/responses/bad_request'
        '409':
          $ref: '#/components/responses/conflict'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Delete Github Enterprise Server Pages Site
      description: 'Deletes a GitHub Enterprise Server Pages site. For more information, see "[About GitHub Pages](/github/working-with-github-pages/about-github-pages).


        The authenticated user must be a repository administrator, maintainer, or have the ''manage GitHub Pages settings'' permission.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Servers
      operationId: deleteGithubEnterpriseServerPagesSite
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#delete-a-apiname-pages-site
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '204':
          description: Response
        '404':
          $ref: '#/components/responses/not_found'
        '409':
          $ref: '#/components/responses/conflict'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/pages/builds:
    get:
      summary: GitHub List Github Enterprise Server Pages Builds
      description: 'Lists builts of a GitHub Enterprise Server Pages site.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Servers
      operationId: listGithubEnterpriseServerPagesBuilds
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#list-apiname-pages-builds
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/page-build'
              examples:
                default:
                  $ref: '#/components/examples/page-build-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: GitHub Request Github Enterprise Server Pages Build
      description: 'You can request that your site be built from the latest revision on the default branch. This has the same effect as pushing a commit to your default branch, but does not require an additional commit. Manually triggering page builds can be helpful when diagnosing build warnings and failures.


        Build requests are limited to one concurrent build per repository and one concurrent build per requester. If you request a build while another is still in progress, the second request will be queued until the first completes.'
      tags:
      - Servers
      operationId: requestGithubEnterpriseServerPagesBuild
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#request-a-apiname-pages-build
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/page-build-status'
              examples:
                default:
                  $ref: '#/components/examples/page-build-status'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/pages/builds/{build_id}:
    get:
      summary: GitHub Get Github Enterprise Server Pages Build
      description: 'Gets information about a GitHub Enterprise Server Pages build.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Servers
      operationId: getGithubEnterpriseServerPagesBuild
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/pages/pages#get-apiname-pages-build
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: build_id
        in: path
        required: true
        schema:
          type: integer
        example: 42
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/page-build'
              examples:
                default:
                  $ref: '#/components/examples/page-build'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pages
        subcategory: pages
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    nullable-simple-user:
      title: Simple User
      description: GitHub user.
      type: object
      properties:
        name:
          type: string
          example: octocat
        email:
          type: string
          example: octocat@github.com
        login:
          type: string
          example: octocat
        id:
          type: integer
          format: int64
          example: 1
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type: string
          example: 41d064eb2195891e12d0413f63227ea7
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
          example: true
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    api-overview:
      title: Api Overview
      description: Api Overview
      type: object
      properties:
        verifiable_password_authentication:
          type: boolean
          example: true
        packages:
          type: array
          items:
            type: string
          example:
          - 192.0.2.1
        dependabot:
          type: array
          items:
            type: string
          example:
          - 192.0.2.1
        domains:
          type: object
          properties:
            website:
              type: array
              items:
                type: string
                example:
                - example.com
            codespaces:
              type: array
              items:
                type: string
                example:
                - example.com
            copilot:
              type: array
              items:
                type: string
                example:
                - example.com
            packages:
              type: array
              items:
                type: string
                example:
                - example.com
            actions:
              type: array
              items:
                type: string
                example:
                - example.com
        installed_version:
          type: string
          example: 3.9.0
      required:
      - verifiable_password_authentication
    pages-https-certificate:
      title: Pages Https Certificate
      type: object
      properties:
        state:
          type: string
          enum:
          - new
          - authorization_created
          - authorization_pending
          - authorized
          - authorization_revoked
          - issued
          - uploaded
          - approved
          - errored
          - bad_authz
          - destroy_pending
          - dns_changed
          example: approved
        description:
          type: string
          example: Certificate is approved
        domains:
          type: array
          items:
            type: string
          description: Array of the domain set and its alternate name (if it is configured)
          example:
          - example.com
          - www.example.com
        expires_at:
          type: string
          format: date
          example: '2026-04-17T12:00:00Z'
      required:
      - state
      - description
      - domains
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
    page:
      title: GitHub Pages
      description: The configuration for GitHub Pages for a repository.
      type: object
      properties:
        url:
          type: string
          description: The API address for accessing this Page resource.
          format: uri
          example: https://api.github.com/repos/github/hello-world/pages
        status:
          type: string
          description: The status of the most recent build of the Page.
          example: built
          enum:
          - built
          - building
          - errored
        cname:
          description: The Pages site's custom domain
          example: example.com
          type: string
        protected_domain_state:
          type: string
          description: The state if the domain is verified
          example: pending
          enum:
          - pending
          - verified
          - unverified
        pending_domain_unverified_at:
          type: string
          description: The timestamp when a pending domain becomes unverified.
          format: date-time
          example: '2026-04-17T12:00:00Z'
        custom_404:
          type: boolean
          description: Whether the Page has a custom 404 page.
          example: false
          default: false
        html_url:
          type: string
          description: The web address the Page can be accessed from.
          format: uri
          example: https://example.com
        build_type:
          type: string
          description: The process in which the Page will be built.
          example: legacy
          enum:
          - legacy
          - workflow
        source:
          $ref: '#/components/schemas/pages-source-hash'
        public:
          type: boolean
          description: Whether the GitHub Pages site is publicly visible. If set to `true`, the site is accessible to anyone on the internet. If set to `false`, the site will only be accessible to users who have at least `read` access to the repository that published the site.
          example: true
        https_certificate:
          $ref: '#/components/schemas/pages-https-certificate'
        https_enforced:
          type: boolean
          description: Whether https is enabled on the domain
          example: true
      required:
      - url
      - status
      - cname
      - custom_404
      - public
    validation-error:
      title: Validation Error
      description: Validation Error
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        errors:
          type: array
          items:
            type: object
            required:
            - code
            properties:
              resource:
                type: string
              field:
                type: string
              message:
                type: string
              code:
                type: string
              index:
                type: integer
              value:
                oneOf:
                - type: string
                - type: integer
                - type: array
                  items:
                    type: string
    page-build:
      title: Page Build
      description: Page Build
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
        error:
          type: object
          properties:
            message:
              type: string
          required:
          - message
        pusher:
          $ref: '#/components/schemas/nullable-simple-user'
        commit:
          type: string
          example: example_value
        duration:
          type: integer
          example: 42
        created_at:
          type: string
          format: date-time
          example: '2026-04-17T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-04-17T12:00:00Z'
      required:
      - url
      - status
      - error
      - pusher
      - commit
      - duration
      - created_at
      - updated_at
    scim-error:
      title: Scim Error
      description: Scim Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        detail:
          type: string
          example: example_value
        status:
          type: integer
          example: 42
        scimType:
          type: string
          example: User
        schemas:
          type: array
          items:
            type: string
    pages-source-hash:
      title: Pages Source Hash
      type: object
      properties:
        branch:
          type: string
          example: main
        path:
          type: string
          example: src/index.js
      required:
      - branch
      - path
    page-build-status:
      title: Page Build Status
      description: Page Build Status
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://api.github.com/repos/github/hello-world/pages/builds/latest
        status:
          type: string
          example: queued
      required:
      - url
      - status
  responses:
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    bad_request:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
        application/scim+json:
          schema:
            $ref: '#/components/schemas/scim-error'
    conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    not_modified:
      description: Not modified
    validation_failed:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error'
  headers:
    link:
      example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
      schema:
        type: string
  examples:
    page-build-status:
      value:
        url: https://api.github.com/repos/github/developer.github.com/pages/builds/latest
        status: queued
    page:
      value:
        url: https://api.github.com/repos/github/developer.github.com/pages
        status: built
        cname: developer.github.com
        custom_404: false
        html_url: https://developer.github.com
        source:
          branch: master
          path: /
        public: true
        pending_domain_unverified_at: '2024-04-30T19:33:31Z'
        protected_domain_state: verified
        https_certificate:
          state: approved
          description: Certificate is approved
          domains:
          - developer.github.com
          expires_at: '2021-05-22'
        https_enforced: true
    page-build-items:
      value:
      - url: https://api.github.com/repos/gi

# --- truncated at 32 KB (638 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-servers-api-openapi.yml