GitHub Orgs API

openapi: 3.0.3
info:
  version: 1.1.4
  title: GitHub Application About Orgs 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: Orgs
paths:
  /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:
      - Orgs
      operationId: orgs/list
      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
      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:
      - Orgs
      operationId: orgs/list-custom-roles
      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
      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:
      - Orgs
      operationId: orgs/get
      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
      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:
      - Orgs
      operationId: orgs/update
      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
      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: orgs/delete
      tags:
      - Orgs
      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
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/announcement:
    get:
      summary: GitHub Get Announcement Banner for Organization
      description: 'Gets the announcement banner currently set for the organization. Only returns the announcement banner set at the

        organization level. Organization members may also see an enterprise-level announcement banner. To get an

        announcement banner displayed at the enterprise level, use the enterprise-level endpoint.'
      tags:
      - Orgs
      operationId: announcement-banners/get-announcement-banner-for-org
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/announcement-banners/organizations#get-announcement-banner-for-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/announcement-banner'
              examples:
                default:
                  $ref: '#/components/examples/announcement'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: announcement-banners
        subcategory: organizations
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Set Announcement Banner for Organization
      description: Sets the announcement banner to display for the organization.
      tags:
      - Orgs
      operationId: announcement-banners/set-announcement-banner-for-org
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/announcement-banners/organizations#set-announcement-banner-for-organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/announcement'
            examples:
              default:
                $ref: '#/components/examples/announcement'
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/announcement-banner'
              examples:
                default:
                  $ref: '#/components/examples/announcement'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: announcement-banners
        subcategory: organizations
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Remove Announcement Banner from Organization
      description: Removes the announcement banner currently set for the organization.
      tags:
      - Orgs
      operationId: announcement-banners/remove-announcement-banner-for-org
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/announcement-banners/organizations#remove-announcement-banner-from-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: announcement-banners
        subcategory: organizations
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/audit-log:
    get:
      summary: GitHub Get the Audit Log for an Organization
      description: 'Gets the audit log for an organization. For more information, see "[Reviewing the audit log for your organization](https://docs.github.com/enterprise-server@3.9/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization)."


        By default, the response includes up to 30 events from the past three months. Use the `phrase` parameter to filter results and retrieve older events. For example, use the `phrase` parameter with the `created` qualifier to filter events based on when the events occurred. For more information, see "[Reviewing the audit log for your organization](https://docs.github.com/enterprise-server@3.9/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#searching-the-audit-log)."


        Use pagination to retrieve fewer or more than 30 events. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/guides/using-pagination-in-the-rest-api)."


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


        OAuth app tokens and personal access tokens (classic) need the `read:audit_log` scope to use this endpoint.'
      operationId: orgs/get-audit-log
      tags:
      - Orgs
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/orgs#get-the-audit-log-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/audit-log-phrase'
      - $ref: '#/components/parameters/audit-log-include'
      - $ref: '#/components/parameters/audit-log-after'
      - $ref: '#/components/parameters/audit-log-before'
      - $ref: '#/components/parameters/audit-log-order'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/audit-log-event'
              examples:
                default:
                  $ref: '#/components/examples/audit-log'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/custom-repository-roles:
    get:
      summary: GitHub List Custom Repository Roles in an Organization
      description: '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 an 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:
      - Orgs
      operationId: orgs/list-custom-repo-roles
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/custom-roles#list-custom-repository-roles-in-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      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-list-example'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: orgs
        subcategory: custom-roles
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: GitHub Create a Custom Repository Role
      description: 'Creates a custom repository role that can be used by all repositories owned by the 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 an administrator for the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
      tags:
      - Orgs
      operationId: orgs/create-custom-repo-role
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/custom-roles#create-a-custom-repository-role
      parameters:
      - $ref: '#/components/parameters/org'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/organization-custom-repository-role-create-schema'
            examples:
              default:
                value:
                  name: Labeler
                  description: A role for issue and pull request labelers
                  base_role: read
                  permissions:
                  - add_label
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization-custom-repository-role'
              examples:
                default:
                  $ref: '#/components/examples/organization-custom-repository-role-example'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: orgs
        subcategory: custom-roles
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/custom-repository-roles/{role_id}:
    get:
      summary: GitHub Get a Custom Repository Role
      description: 'Gets a custom repository role that is available to all repositories owned by the 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 an 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:
      - Orgs
      operationId: orgs/get-custom-repo-role
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/orgs/custom-roles#get-a-custom-repository-role
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/role-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization-custom-repository-role'
              examples:
                default:
                  $ref: '#/components/examples/organization-custom-repository-role-example'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: orgs
        subcategory: custom-roles
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Update a Custom Repository Role
      description: 'Updates a custom repository role that can be used by all repositories owned by the organization. For more information about custom repository roles, see "[About custom repository roles](https://docs.github.com/enterprise-server@3.9

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