APIs.io Engineering Platform Enterprise-Admin API

openapi: 3.2.0
info:
  version: 1.1.4
  title: APIs.io Engineering Platform GitHub v3 REST Enterprise Admin API
  description: GitHub's v3 REST API.
  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: Enterprise-Admin
  description: Enterprise Administration
paths:
  /admin/hooks:
    get:
      summary: APIs.io Engineering Platform List global webhooks
      description: ''
      operationId: enterprise-admin/list-global-webhooks
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/global-webhooks#list-global-webhooks
      parameters:
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/global-hook'
              examples:
                default:
                  $ref: '#/components/examples/global-hook-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: global-webhooks
    post:
      summary: APIs.io Engineering Platform Create a global webhook
      description: ''
      operationId: enterprise-admin/create-global-webhook
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/global-webhooks#create-a-global-webhook
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/global-hook'
              examples:
                default:
                  $ref: '#/components/examples/global-hook'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Must be passed as "web".
                config:
                  type: object
                  description: Key/value pairs to provide settings for this webhook.
                  properties:
                    url:
                      type: string
                      description: The URL to which the payloads will be delivered.
                    content_type:
                      type: string
                      description: The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
                    secret:
                      type: string
                      description: If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [`X-Hub-Signature`](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads/#delivery-headers) header.
                    insecure_ssl:
                      type: string
                      description: Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.**
                  required:
                  - url
                events:
                  type: array
                  description: 'The [events](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads) that trigger this webhook. A global webhook can be triggered by `user` and `organization` events. Default: `user` and `organization`.'
                  items:
                    type: string
                active:
                  type: boolean
                  description: Determines if notifications are sent when the webhook is triggered. Set to `true` to send notifications.
                  default: true
              required:
              - name
              - config
            examples:
              default:
                value:
                  name: web
                  events:
                  - organization
                  - user
                  config:
                    url: https://example.com/webhook
                    content_type: json
                    secret: secret
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: global-webhooks
  /admin/hooks/{hook_id}:
    get:
      summary: APIs.io Engineering Platform Get a global webhook
      description: ''
      operationId: enterprise-admin/get-global-webhook
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/global-webhooks#get-a-global-webhook
      parameters:
      - $ref: '#/components/parameters/hook-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/global-hook'
              examples:
                default:
                  $ref: '#/components/examples/global-hook'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: global-webhooks
    patch:
      summary: APIs.io Engineering Platform Update a global webhook
      description: Parameters that are not provided will be overwritten with the default value or removed if no default exists.
      operationId: enterprise-admin/update-global-webhook
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/global-webhooks#update-a-global-webhook
      parameters:
      - $ref: '#/components/parameters/hook-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/global-hook-2'
              examples:
                default:
                  $ref: '#/components/examples/global-hook-2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  type: object
                  description: Key/value pairs to provide settings for this webhook.
                  properties:
                    url:
                      type: string
                      description: The URL to which the payloads will be delivered.
                    content_type:
                      type: string
                      description: The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
                    secret:
                      type: string
                      description: If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [`X-Hub-Signature`](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads/#delivery-headers) header.
                    insecure_ssl:
                      type: string
                      description: Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.**
                  required:
                  - url
                events:
                  type: array
                  description: 'The [events](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads) that trigger this webhook. A global webhook can be triggered by `user` and `organization` events. Default: `user` and `organization`.'
                  items:
                    type: string
                active:
                  type: boolean
                  description: Determines if notifications are sent when the webhook is triggered. Set to `true` to send notifications.
                  default: true
            examples:
              default:
                value:
                  events:
                  - organization
                  config:
                    url: https://example.com/webhook
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: global-webhooks
    delete:
      summary: APIs.io Engineering Platform Delete a global webhook
      description: ''
      operationId: enterprise-admin/delete-global-webhook
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/global-webhooks#delete-a-global-webhook
      parameters:
      - $ref: '#/components/parameters/hook-id'
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: global-webhooks
  /admin/hooks/{hook_id}/pings:
    post:
      summary: APIs.io Engineering Platform Ping a global webhook
      description: This will trigger a [ping event](https://docs.github.com/enterprise-server@3.9/webhooks/#ping-event) to be sent to the webhook.
      operationId: enterprise-admin/ping-global-webhook
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/global-webhooks#ping-a-global-webhook
      parameters:
      - $ref: '#/components/parameters/hook-id'
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: global-webhooks
  /admin/keys:
    get:
      summary: APIs.io Engineering Platform List public keys
      description: ''
      operationId: enterprise-admin/list-public-keys
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/users#list-public-keys
      parameters:
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/direction'
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - created
          - updated
          - accessed
          default: created
      - name: since
        description: Only show public keys accessed after the given time.
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/public-key-full'
              examples:
                default:
                  $ref: '#/components/examples/enterprise-public-key-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: users
  /admin/keys/{key_ids}:
    delete:
      summary: APIs.io Engineering Platform Delete a public key
      description: ''
      operationId: enterprise-admin/delete-public-key
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/users#delete-a-public-key
      parameters:
      - $ref: '#/components/parameters/key-ids'
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: users
  /admin/ldap/teams/{team_id}/mapping:
    patch:
      summary: APIs.io Engineering Platform Update LDAP mapping for a team
      description: Updates the [distinguished name](https://www.ldap.com/ldap-dns-and-rdns) (DN) of the LDAP entry to map to a team. [LDAP synchronization](https://docs.github.com/enterprise-server@3.9/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync) must be enabled to map LDAP entries to a team. Use the [Create a team](https://docs.github.com/enterprise-server@3.9/rest/teams/teams/#create-a-team) endpoint to create a team with LDAP mapping.
      operationId: enterprise-admin/update-ldap-mapping-for-team
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/ldap#update-ldap-mapping-for-a-team
      parameters:
      - $ref: '#/components/parameters/team-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ldap-mapping-team'
              examples:
                default:
                  $ref: '#/components/examples/ldap-mapping-team'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ldap_dn:
                  type: string
                  description: The [distinguished name](https://www.ldap.com/ldap-dns-and-rdns) (DN) of the LDAP entry to map to a team.
              required:
              - ldap_dn
            examples:
              default:
                value:
                  ldap_dn: cn=Enterprise Ops,ou=teams,dc=github,dc=com
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: ldap
  /admin/ldap/teams/{team_id}/sync:
    post:
      summary: APIs.io Engineering Platform Sync LDAP mapping for a team
      description: Note that this API call does not automatically initiate an LDAP sync. Rather, if a `201` is returned, the sync job is queued successfully, and is performed when the instance is ready.
      operationId: enterprise-admin/sync-ldap-mapping-for-team
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/ldap#sync-ldap-mapping-for-a-team
      parameters:
      - $ref: '#/components/parameters/team-id'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
              examples:
                default:
                  value:
                    status: queued
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: ldap
  /admin/ldap/users/{username}/mapping:
    patch:
      summary: APIs.io Engineering Platform Update LDAP mapping for a user
      description: ''
      operationId: enterprise-admin/update-ldap-mapping-for-user
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/ldap#update-ldap-mapping-for-a-user
      parameters:
      - $ref: '#/components/parameters/username'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ldap-mapping-user'
              examples:
                default:
                  $ref: '#/components/examples/ldap-mapping-user'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ldap_dn:
                  type: string
                  description: The [distinguished name](https://www.ldap.com/ldap-dns-and-rdns) (DN) of the LDAP entry to map to a team.
              required:
              - ldap_dn
            examples:
              default:
                value:
                  ldap_dn: uid=asdf,ou=users,dc=github,dc=com
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: ldap
  /admin/ldap/users/{username}/sync:
    post:
      summary: APIs.io Engineering Platform Sync LDAP mapping for a user
      description: Note that this API call does not automatically initiate an LDAP sync. Rather, if a `201` is returned, the sync job is queued successfully, and is performed when the instance is ready.
      operationId: enterprise-admin/sync-ldap-mapping-for-user
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/ldap#sync-ldap-mapping-for-a-user
      parameters:
      - $ref: '#/components/parameters/username'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
              examples:
                default:
                  value:
                    status: queued
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: ldap
  /admin/organizations:
    post:
      summary: APIs.io Engineering Platform Create an organization
      description: ''
      operationId: enterprise-admin/create-org
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/orgs#create-an-organization
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization-simple'
              examples:
                default:
                  $ref: '#/components/examples/organization-simple'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                login:
                  type: string
                  description: The organization's username.
                admin:
                  type: string
                  description: The login of the user who will manage this organization.
                profile_name:
                  type: string
                  description: The organization's display name.
              required:
              - login
              - admin
            examples:
              default:
                value:
                  login: github
                  profile_name: GitHub, Inc.
                  admin: monalisaoctocat
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: orgs
  /admin/organizations/{org}:
    patch:
      summary: APIs.io Engineering Platform Update an organization name
      description: ''
      operationId: enterprise-admin/update-org-name
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/orgs#update-an-organization-name
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '202':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  url:
                    type: string
              examples:
                default:
                  value:
                    message: Job queued to rename organization. It may take a few minutes to complete.
                    url: https://<hostname>/api/v3/organizations/1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                login:
                  type: string
                  description: The organization's new name.
              required:
              - login
            examples:
              default:
                value:
                  login: the-new-octocats
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: orgs
  /admin/pre-receive-environments:
    get:
      summary: APIs.io Engineering Platform List pre-receive environments
      description: ''
      operationId: enterprise-admin/list-pre-receive-environments
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/pre-receive-environments#list-pre-receive-environments
      parameters:
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/direction'
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - created
          - updated
          - name
          default: created
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pre-receive-environment'
              examples:
                default:
                  $ref: '#/components/examples/pre-receive-environment-items'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: pre-receive-environments
    post:
      summary: APIs.io Engineering Platform Create a pre-receive environment
      description: ''
      operationId: enterprise-admin/create-pre-receive-environment
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/pre-receive-environments#create-a-pre-receive-environment
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pre-receive-environment'
              examples:
                default:
                  $ref: '#/components/examples/pre-receive-environment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new pre-receive environment's name.
                image_url:
                  type: string
                  description: URL from which to download a tarball of this environment.
              required:
              - name
              - image_url
            examples:
              default:
                value:
                  name: DevTools Hook Env
                  image_url: https://my_file_server/path/to/devtools_env.tar.gz
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: pre-receive-environments
  /admin/pre-receive-environments/{pre_receive_environment_id}:
    get:
      summary: APIs.io Engineering Platform Get a pre-receive environment
      description: ''
      operationId: enterprise-admin/get-pre-receive-environment
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/pre-receive-environments#get-a-pre-receive-environment
      parameters:
      - $ref: '#/components/parameters/pre-receive-environment-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pre-receive-environment'
              examples:
                default:
                  $ref: '#/components/examples/pre-receive-environment'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: pre-receive-environments
    patch:
      summary: APIs.io Engineering Platform Update a pre-receive environment
      description: You cannot modify the default environment. If you attempt to modify the default environment, you will receive a `422 Unprocessable Entity` response.
      operationId: enterprise-admin/update-pre-receive-environment
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/pre-receive-environments#update-a-pre-receive-environment
      parameters:
      - $ref: '#/components/parameters/pre-receive-environment-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pre-receive-environment'
              examples:
                default-response:
                  $ref: '#/components/examples/pre-receive-environment-default-response'
        '422':
          description: Client Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        resource:
                          type: string
                        code:
                          type: string
                        message:
                          type: string
              examples:
                client-errors:
                  value:
                    message: Validation Failed
                    errors:
                    - resource: PreReceiveEnvironment
                      code: custom
                      message: Cannot modify or delete the default environment
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: This pre-receive environment's new name.
                image_url:
                  type: string
                  description: URL from which to download a tarball of this environment.
            examples:
              default:
                value:
                  name: DevTools Hook Env
                  image_url: https://my_file_server/path/to/devtools_env.tar.gz
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: pre-receive-environments
    delete:
      summary: APIs.io Engineering Platform Delete a pre-receive environment
      description: 'If you attempt to delete an environment that cannot be deleted, you will receive a `422 Unprocessable Entity` response.


        The possible error messages are:


        *   _Cannot modify or delete the default environment_

        *   _Cannot delete environment that has hooks_

        *   _Cannot delete environment when download is in progress_'
      operationId: enterprise-admin/delete-pre-receive-environment
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/pre-receive-environments#delete-a-pre-receive-environment
      parameters:
      - $ref: '#/components/parameters/pre-receive-environment-id'
      responses:
        '204':
          description: Response
        '422':
          description: Client Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        resource:
                          type: string
                        code:
                          type: string
                        message:
                          type: string
              examples:
                client-errors:
                  value:
                    message: Validation Failed
                    errors:
                    - resource: PreReceiveEnvironment
                      code: custom
                      message: Cannot modify or delete the default environment
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: pre-receive-environments
  /admin/pre-receive-environments/{pre_receive_environment_id}/downloads:
    post:
      summary: APIs.io Engineering Platform Start a pre-receive environment download
      description: 'Triggers a new download of the environment tarball from the environment''s `image_url`. When the download is finished, the newly downloaded tarball will overwrite the existing environment.


        If a download cannot be triggered, you will receive a `422 Unprocessable Entity` response.


        The possible error messages are:


        * _Cannot modify or delete the default environment_

        * _Can not start a new download when a download is in progress_'
      operationId: enterprise-admin/start-pre-receive-environment-download
      tags:
      - Enterprise-Admin
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/pre-receive-environments#start-a-pre-receive-environment-download
      parameters:
      - $ref: '#/components/parameters/pre-receive-environment-id'
      responses:
        '202':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pre-receive-environment-download-status'
              examples:
                default-response:
                  $ref: '#/components/examples/pre-receive-environment-download-status-default-response'
        '422':
          description: Client Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      p

# --- truncated at 32 KB (342 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/engineering-platform/refs/heads/main/openapi/engineering-platform-enterprise-admin-api-openapi.yml