APIs.io Engineering Platform Orgs API

openapi: 3.2.0
info:
  version: 1.1.4
  title: APIs.io Engineering Platform GitHub v3 REST Orgs 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: Orgs
  description: Interact with GitHub Orgs.
paths:
  /organizations:
    get:
      summary: APIs.io Engineering Platform List organizations
      description: 'Lists all organizations, in the order that they were created.


        **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
  /organizations/{organization_id}/custom_roles:
    get:
      summary: APIs.io Engineering Platform 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#deprecated---list-custom-repository-roles-in-an-organization
      parameters:
      - name: organization_id
        description: The unique identifier of the organization.
        in: path
        required: true
        schema:
          type: string
      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
  /orgs/{org}:
    get:
      summary: APIs.io Engineering Platform 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.


        The values returned by this endpoint are set by the "Update an organization" endpoint. If your organization set a default security configuration (beta), the following values retrieved from the "Update an organization" endpoint have been overwritten by that configuration:


        - advanced_security_enabled_for_new_repositories

        - dependabot_alerts_enabled_for_new_repositories

        - dependabot_security_updates_enabled_for_new_repositories

        - dependency_graph_enabled_for_new_repositories

        - secret_scanning_enabled_for_new_repositories

        - secret_scanning_push_protection_enabled_for_new_repositories


        For more information on security configurations, see "[Enabling security features at scale](https://docs.github.com/enterprise-server@3.9/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale)."


        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
    patch:
      summary: APIs.io Engineering Platform 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.


        With security configurations (beta), your organization can choose a default security configuration which will automatically apply a set of security enablement settings to new repositories in your organization based on their visibility. For targeted repositories, the following attributes will be overridden by the default security configuration:


        - advanced_security_enabled_for_new_repositories

        - dependabot_alerts_enabled_for_new_repositories

        - dependabot_security_updates_enabled_for_new_repositories

        - dependency_graph_enabled_for_new_repositories

        - secret_scanning_enabled_for_new_repositories

        - secret_scanning_push_protection_enabled_for_new_repositories


        For more information on setting a default security configuration, see "[Enabling security features at scale](https://docs.github.com/enterprise-server@3.9/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale)."


        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. The maximum size is 160 characters.
                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'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/validation-error'
                - $ref: '#/components/schemas/validation-error-simple'
        '409':
          $ref: '#/components/responses/conflict'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
    delete:
      summary: APIs.io Engineering Platform 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'
        '404':
          $ref: '#/components/responses/not_found'
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: orgs
        subcategory: orgs
  /orgs/{org}/announcement:
    get:
      summary: APIs.io Engineering Platform 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
    patch:
      summary: APIs.io Engineering Platform 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
    delete:
      summary: APIs.io Engineering Platform 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
  /orgs/{org}/audit-log:
    get:
      summary: APIs.io Engineering Platform 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
  /orgs/{org}/custom-repository-roles:
    get:
      summary: APIs.io Engineering Platform 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
    post:
      summary: APIs.io Engineering Platform 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'
        '422':
          $ref: '#/components/responses/validation_failed'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: orgs
        subcategory: custom-roles
  /orgs/{org}/custom-repository-roles/{role_id}:
    get:
      summary: APIs.io Engineering Platform 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 acces

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