GitHub Organizations API

openapi: 3.0.3
info:
  version: 1.1.4
  title: GitHub Application About Organizations 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: Organizations
paths:
  /users/{username}/events/orgs/{org}:
    get:
      summary: GitHub List Organization Events for the Authenticated User
      description: The GitHub Events API endpoint `/users/{username}/events/orgs/{org}` using the GET method retrieves a list of events for the authenticated user within a specific organization. This endpoint allows developers to access activity data related to a particular organization that the authenticated user is associated with, providing visibility into organization-level events and actions. The API returns event data in a paginated format, showing activities such as repository changes, issue updates, pull requests, and other collaborative actions performed within the specified organization context. Authentication is required to access this endpoint, and the results are filtered to show only events relevant to both the specified username and organization that the authenticated user has permission to view.
      tags:
      - Organizations
      operationId: listOrganizationEventsForTheAuthenticatedUser
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/activity/events#list-organization-events-for-the-authenticated-user
      parameters:
      - $ref: '#/components/parameters/username'
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
              examples:
                default:
                  $ref: '#/components/examples/user-org-events-items'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: activity
        subcategory: events
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/installation:
    get:
      summary: GitHub Get an Organization Installation for the Authenticated App
      description: 'Enables an authenticated GitHub App to find the organization''s installation information.


        You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
      tags:
      - Organizations
      operationId: getAnOrganizationInstallationForTheAuthenticatedApp
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/apps#get-an-organization-installation-for-the-authenticated-app
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/installation'
              examples:
                default:
                  $ref: '#/components/examples/installation'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: apps
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/installations:
    get:
      summary: GitHub List App Installations for an Organization
      description: 'Lists all GitHub Apps in an organization. The installation count includes

        all GitHub Apps installed on repositories in the organization.


        The authenticated user must be an organization owner to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `admin:read` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: listAppInstallationsForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/orgs#list-app-installations-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                required:
                - total_count
                - installations
                properties:
                  total_count:
                    type: integer
                  installations:
                    type: array
                    items:
                      $ref: '#/components/schemas/installation'
              examples:
                default:
                  $ref: '#/components/examples/installation-paginated'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /organizations:
    get:
      summary: GitHub List Organizations
      description: 'Lists all organizations, in the order that they were created on GitHub Enterprise Server.


        **Note:** Pagination is powered exclusively by the `since` parameter. Use the [Link header](https://docs.github.com/enterprise-server@3.9/rest/guides/using-pagination-in-the-rest-api#using-link-headers) to get the URL for the next page of organizations.'
      tags:
      - Organizations
      operationId: listOrganizations
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/orgs#list-organizations
      parameters:
      - $ref: '#/components/parameters/since-org'
      - $ref: '#/components/parameters/per-page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/organization-simple'
              examples:
                default:
                  $ref: '#/components/examples/organization-simple-items'
          headers:
            Link:
              example: <https://api.github.com/organizations?since=135>; rel="next"
              schema:
                type: string
        '304':
          $ref: '#/components/responses/not_modified'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /organizations/{organization_id}/custom_roles:
    get:
      summary: GitHub Deprecated - List Custom Repository Roles in an Organization
      description: '**Note**: This operation is deprecated and will be removed in the future.

        Use the "[List custom repository roles](https://docs.github.com/enterprise-server@3.9/rest/orgs/custom-roles#list-custom-repository-roles-in-an-organization)" endpoint instead.


        List the custom repository roles available in this organization. For more information on custom repository roles, see "[About custom repository roles](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles)."


        The authenticated user must be administrator of the organization or of a repository of the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `admin:org` or `repo` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: deprecatedListCustomRepositoryRolesInAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/custom-roles#deprecatedlist-custom-repository-roles-in-an-organization
      parameters:
      - name: organization_id
        description: The unique identifier of the organization.
        in: path
        required: true
        schema:
          type: string
        example: '12345678'
      responses:
        '200':
          description: Response - list of custom role names
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    description: The number of custom roles in this organization
                    example: 3
                    type: integer
                  custom_roles:
                    type: array
                    items:
                      $ref: '#/components/schemas/organization-custom-repository-role'
              examples:
                default:
                  $ref: '#/components/examples/organization-custom-repository-role-example'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        removalDate: '2025-02-15'
        deprecationDate: '2023-02-15'
        category: orgs
        subcategory: custom-roles
      deprecated: true
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}:
    get:
      summary: GitHub Get an Organization
      description: 'Gets information about an organization.


        When the value of `two_factor_requirement_enabled` is `true`, the organization requires all members, billing managers, and outside collaborators to enable [two-factor authentication](https://docs.github.com/enterprise-server@3.9/articles/securing-your-account-with-two-factor-authentication-2fa/).


        To see the full details about an organization, the authenticated user must be an organization owner.


        OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to see the full details about an organization.


        To see information about an organization''s GitHub Enterprise Server plan, GitHub Apps need the `Organization plan` permission.'
      tags:
      - Organizations
      operationId: getAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/orgs#get-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization-full'
              examples:
                default-response:
                  $ref: '#/components/examples/organization-full'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Update an Organization
      description: '**Parameter Deprecation Notice:** GitHub Enterprise Server will replace and discontinue `members_allowed_repository_creation_type` in favor of more granular permissions. The new input parameters are `members_can_create_public_repositories`, `members_can_create_private_repositories` for all organizations and `members_can_create_internal_repositories` for organizations associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+. For more information, see the [blog post](https://developer.github.com/changes/2019-12-03-internal-visibility-changes).


        Updates the organization''s profile and member privileges.


        The authenticated user must be an organization owner to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `admin:org` or `repo` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: updateAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/orgs#update-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                billing_email:
                  type: string
                  description: Billing email address. This address is not publicized.
                company:
                  type: string
                  description: The company name.
                email:
                  type: string
                  description: The publicly visible email address.
                twitter_username:
                  type: string
                  description: The Twitter username of the company.
                location:
                  type: string
                  description: The location.
                name:
                  type: string
                  description: The shorthand name of the company.
                description:
                  type: string
                  description: The description of the company.
                has_organization_projects:
                  type: boolean
                  description: Whether an organization can use organization projects.
                has_repository_projects:
                  type: boolean
                  description: Whether repositories that belong to the organization can use repository projects.
                default_repository_permission:
                  type: string
                  description: Default permission level members have for organization repositories.
                  enum:
                  - read
                  - write
                  - admin
                  - none
                  default: read
                members_can_create_repositories:
                  type: boolean
                  description: Whether of non-admin organization members can create repositories. **Note:** A parameter can override this parameter. See `members_allowed_repository_creation_type` in this table for details.
                  default: true
                members_can_create_internal_repositories:
                  type: boolean
                  description: Whether organization members can create internal repositories, which are visible to all enterprise members. You can only allow members to create internal repositories if your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+. For more information, see "[Restricting repository creation in your organization](https://docs.github.com/enterprise-server@3.9/github/setting-up-and-managing-organizations-and-teams/restricting-repository-creation-in-your-organization)" in the GitHub Help documentation.
                members_can_create_private_repositories:
                  type: boolean
                  description: Whether organization members can create private repositories, which are visible to organization members with permission. For more information, see "[Restricting repository creation in your organization](https://docs.github.com/enterprise-server@3.9/github/setting-up-and-managing-organizations-and-teams/restricting-repository-creation-in-your-organization)" in the GitHub Help documentation.
                members_can_create_public_repositories:
                  type: boolean
                  description: Whether organization members can create public repositories, which are visible to anyone. For more information, see "[Restricting repository creation in your organization](https://docs.github.com/enterprise-server@3.9/github/setting-up-and-managing-organizations-and-teams/restricting-repository-creation-in-your-organization)" in the GitHub Help documentation.
                members_allowed_repository_creation_type:
                  type: string
                  description: "Specifies which types of repositories non-admin organization members can create. \n**Note:** This parameter is deprecated and will be removed in the future. Its return value ignores internal repositories. Using this parameter overrides values set in `members_can_create_repositories`. See the parameter deprecation notice in the operation description for details."
                  enum:
                  - all
                  - private
                  - none
                members_can_create_pages:
                  type: boolean
                  description: Whether organization members can create GitHub Pages sites. Existing published sites will not be impacted.
                  default: true
                members_can_fork_private_repositories:
                  type: boolean
                  description: Whether organization members can fork private organization repositories.
                  default: false
                web_commit_signoff_required:
                  type: boolean
                  description: Whether contributors to organization repositories are required to sign off on commits they make through GitHub's web interface.
                  default: false
                blog:
                  type: string
                  example: '"http://github.blog"'
                advanced_security_enabled_for_new_repositories:
                  type: boolean
                  description: 'Whether GitHub Advanced Security is automatically enabled for new repositories.


                    To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."


                    You can check which security and analysis features are currently enabled by using a `GET /orgs/{org}` request.'
                dependabot_alerts_enabled_for_new_repositories:
                  type: boolean
                  description: 'Whether Dependabot alerts is automatically enabled for new repositories.


                    To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."


                    You can check which security and analysis features are currently enabled by using a `GET /orgs/{org}` request.'
                dependabot_security_updates_enabled_for_new_repositories:
                  type: boolean
                  description: 'Whether Dependabot security updates is automatically enabled for new repositories.


                    To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."


                    You can check which security and analysis features are currently enabled by using a `GET /orgs/{org}` request.'
                dependency_graph_enabled_for_new_repositories:
                  type: boolean
                  description: 'Whether dependency graph is automatically enabled for new repositories.


                    To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."


                    You can check which security and analysis features are currently enabled by using a `GET /orgs/{org}` request.'
                secret_scanning_enabled_for_new_repositories:
                  type: boolean
                  description: 'Whether secret scanning is automatically enabled for new repositories.


                    To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."


                    You can check which security and analysis features are currently enabled by using a `GET /orgs/{org}` request.'
                secret_scanning_push_protection_enabled_for_new_repositories:
                  type: boolean
                  description: 'Whether secret scanning push protection is automatically enabled for new repositories.


                    To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.9/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."


                    You can check which security and analysis features are currently enabled by using a `GET /orgs/{org}` request.'
                secret_scanning_push_protection_custom_link_enabled:
                  type: boolean
                  description: Whether a custom link is shown to contributors who are blocked from pushing a secret by push protection.
                secret_scanning_push_protection_custom_link:
                  type: string
                  description: If `secret_scanning_push_protection_custom_link_enabled` is true, the URL that will be displayed to contributors who are blocked from pushing a secret.
            examples:
              default:
                value:
                  billing_email: mona@github.com
                  company: GitHub
                  email: mona@github.com
                  twitter_username: github
                  location: San Francisco
                  name: github
                  description: GitHub, the company.
                  default_repository_permission: read
                  members_can_create_repositories: true
                  members_allowed_repository_creation_type: all
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization-full'
              examples:
                default:
                  $ref: '#/components/examples/organization-full'
        '409':
          $ref: '#/components/responses/conflict'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/validation-error'
                - $ref: '#/components/schemas/validation-error-simple'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Delete an Organization
      description: 'Deletes an organization and all its repositories.


        The organization login will be unavailable for 90 days after deletion.


        Please review the Terms of Service regarding account deletion before using this endpoint:


        https://docs.github.com/enterprise-server@3.9/site-policy/github-terms/github-terms-of-service'
      operationId: deleteAnOrganization
      tags:
      - Organizations
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/orgs#delete-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '202':
          $ref: '#/components/responses/accepted'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/actions/cache/usage:
    get:
      summary: GitHub Get Github Actions Cache Usage for an Organization
      description: 'Gets the total GitHub Actions cache usage for an organization.

        The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.


        OAuth tokens and personal access tokens (classic) need the `read:org` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: getGithubActionsCacheUsageForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/cache#get-github-actions-cache-usage-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/actions-cache-usage-org-enterprise'
              examples:
                default:
                  $ref: '#/components/examples/actions-cache-usage-org-enterprise'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: actions
        subcategory: cache
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/actions/cache/usage-by-repository:
    get:
      summary: GitHub List Repositories with Github Actions Cache Usage for an Organization
      description: 'Lists repositories and their GitHub Actions cache usage for an organization.

        The data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.


        OAuth tokens and personal access tokens (classic) need the `read:org` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: listRepositoriesWithGithubActionsCacheUsageForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/cache#list-repositories-with-github-actions-cache-usage-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                required:
                - total_count
                - repository_cache_usages
                properties:
                  total_count:
                    type: integer
                  repository_cache_usages:
                    type: array
                    items:
                      $ref: '#/components/schemas/actions-cache-usage-by-repository'
              examples:
                default:
                  $ref: '#/components/examples/org-actions-cache-usage-by-repo'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: actions
        subcategory: cache
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/actions/oidc/customization/sub:
    get:
      summary: GitHub Get the Customization Template for an Oidc Subject Claim for an Organization
      description: 'Gets the customization template for an OpenID Connect (OIDC) subject claim.


        OAuth app tokens and personal access tokens (classic) need the `read:org` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: getTheCustomizationTemplateForAnOidcSubjectClaimForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/oidc#get-the-customization-template-for-an-oidc-subject-claim-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: A JSON serialized template for OIDC subject claim customization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oidc-custom-sub'
              examples:
                default:
                  $ref: '#/components/examples/oidc-custom-sub'
      x-github:
        enabledForGitHubApps: true
        category: actions
        subcategory: oidc
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: GitHub Set the Customization Template for an Oidc Subject Claim for an Organization
      description: 'Creates or updates the customization template for an OpenID Connect (OIDC) subject claim.


        OAuth app tokens and personal access tokens (classic) need the `write:org` scope to use this endpoint.'
      tags:
      - Organizations
      operationId: setTheCustomizationTemplateForAnOidcSubjectClaimForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/oidc-custom-sub'
            examples:
              default:
                $ref: '#/components/examples/oidc-custom-sub'
      responses:
        '201':
          description: Empty response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-object'
              examples:
                default:
                  value: null
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        enabledForGitHubApps: true
        previews: []
        category: actions
        subcategory: oidc
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALL

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