GitHub Enterprise Enterprise Teams API

openapi: 3.2.0
info:
  title: Github Enterprise Enterprise Teams API
  version: 1.1.4
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  x-github-plan: ghec
  description: 'Operations tagged enterprise-teams across 2 of this provider''s published API definitions: github-enterprise-ghec-openapi.json, github-enterprise-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.github.com
tags:
- name: enterprise-teams
  description: Endpoints to manage GitHub Enterprise Teams.
paths:
  /enterprises/{enterprise}/teams:
    get:
      summary: List enterprise teams
      description: List all teams in the enterprise for the authenticated user
      tags:
      - enterprise-teams
      operationId: enterprise-teams/list
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-teams#list-enterprise-teams
      parameters:
      - $ref: '#/components/parameters/enterprise'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/enterprise-team'
              examples:
                default:
                  $ref: '#/components/examples/enterprise-teams-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: enterprise-teams
        subcategory: enterprise-teams
    post:
      summary: Create an enterprise team
      description: To create an enterprise team, the authenticated user must be an owner of the enterprise.
      tags:
      - enterprise-teams
      operationId: enterprise-teams/create
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-teams#create-an-enterprise-team
      parameters:
      - $ref: '#/components/parameters/enterprise'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the team.
                description:
                  type:
                  - string
                  - 'null'
                  description: A description of the team.
                sync_to_organizations:
                  type: string
                  description: 'Retired: this field is no longer supported.

                    Whether the enterprise team should be reflected in each organization.

                    This value cannot be set.

                    '
                  enum:
                  - all
                  - disabled
                  default: disabled
                organization_selection_type:
                  type: string
                  description: 'Specifies which organizations in the enterprise should have access to this team. Can be one of `disabled`, `selected`, or `all`.

                    `disabled`: The team is not assigned to any organizations. This is the default when you create a new team.

                    `selected`: The team is assigned to specific organizations. You can then use the [add organization assignments API](https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-team-organizations#add-organization-assignments) endpoint.

                    `all`: The team is assigned to all current and future organizations in the enterprise.

                    '
                  enum:
                  - disabled
                  - selected
                  - all
                  default: disabled
                group_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the IdP group to assign team membership with. You can get this value from the [REST API endpoints for SCIM](https://docs.github.com/enterprise-cloud@latest/rest/scim#list-provisioned-scim-groups-for-an-enterprise).
                notification_setting:
                  type: string
                  description: 'The notification setting the team is set to. The options are:


                    * `notifications_enabled` - team members receive notifications when the team is @mentioned.

                    * `notifications_disabled` - no one receives notifications.


                    Default: `notifications_enabled`

                    '
                  enum:
                  - notifications_enabled
                  - notifications_disabled
              required:
              - name
            examples:
              default:
                value:
                  name: Justice League
                  description: A great team.
                  group_id: 62ab9291-fae2-468e-974b-7e45096d5021
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/enterprise-team'
              examples:
                default:
                  $ref: '#/components/examples/enterprise-teams-item'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: enterprise-teams
        subcategory: enterprise-teams
    servers:
    - url: https://api.github.com
  /enterprises/{enterprise}/teams/{team_slug}:
    get:
      summary: Get an enterprise team
      description: Gets a team using the team's slug. To create the slug, GitHub replaces special characters in the name string, changes all words to lowercase, and replaces spaces with a `-` separator and adds the "ent:" prefix. For example, "My TEam Näme" would become `ent:my-team-name`.
      tags:
      - enterprise-teams
      operationId: enterprise-teams/get
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-teams#get-an-enterprise-team
      parameters:
      - $ref: '#/components/parameters/enterprise'
      - $ref: '#/components/parameters/team-slug'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/enterprise-team-with-member-count'
              examples:
                default:
                  $ref: '#/components/examples/enterprise-teams-item-with-member-count'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: enterprise-teams
        subcategory: enterprise-teams
    patch:
      summary: Update an enterprise team
      description: To edit a team, the authenticated user must be an enterprise owner.
      tags:
      - enterprise-teams
      operationId: enterprise-teams/update
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-teams#update-an-enterprise-team
      parameters:
      - $ref: '#/components/parameters/enterprise'
      - $ref: '#/components/parameters/team-slug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  description: A new name for the team.
                description:
                  type:
                  - string
                  - 'null'
                  description: A new description for the team.
                sync_to_organizations:
                  type: string
                  description: 'Retired: this field is no longer supported.

                    Whether the enterprise team should be reflected in each organization.

                    This value cannot be changed.

                    '
                  enum:
                  - all
                  - disabled
                  default: disabled
                organization_selection_type:
                  type: string
                  description: 'Specifies which organizations in the enterprise should have access to this team. Can be one of `disabled`, `selected`, or `all`.

                    `disabled`: The team is not assigned to any organizations. This is the default when you create a new team.

                    `selected`: The team is assigned to specific organizations. You can then use the [add organization assignments API](https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-team-organizations#add-organization-assignments).

                    `all`: The team is assigned to all current and future organizations in the enterprise.

                    '
                  enum:
                  - disabled
                  - selected
                  - all
                  default: disabled
                group_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the IdP group to assign team membership with. The new IdP group will replace the existing one, or replace existing direct members if the team isn't currently linked to an IdP group.
                notification_setting:
                  type: string
                  description: 'The notification setting the team is set to. The options are:


                    * `notifications_enabled` - team members receive notifications when the team is @mentioned.

                    * `notifications_disabled` - no one receives notifications.

                    '
                  enum:
                  - notifications_enabled
                  - notifications_disabled
            examples:
              default:
                value:
                  name: Justice League
                  description: A great team.
                  group_id: 62ab9291-fae2-468e-974b-7e45096d5021
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/enterprise-team'
              examples:
                default:
                  $ref: '#/components/examples/enterprise-teams-item'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: enterprise-teams
        subcategory: enterprise-teams
    delete:
      summary: Delete an enterprise team
      description: 'To delete an enterprise team, the authenticated user must be an enterprise owner.


        If you are an enterprise owner, deleting an enterprise team will delete all of its IdP mappings as well.'
      tags:
      - enterprise-teams
      operationId: enterprise-teams/delete
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-teams/enterprise-teams#delete-an-enterprise-team
      parameters:
      - $ref: '#/components/parameters/enterprise'
      - $ref: '#/components/parameters/team-slug'
      responses:
        '204':
          description: Response
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: enterprise-teams
        subcategory: enterprise-teams
    servers:
    - url: https://api.github.com
components:
  headers:
    link:
      example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
      schema:
        type: string
  responses:
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  schemas:
    enterprise-team-with-member-count:
      title: Enterprise Team
      description: Group of enterprise owners and/or members
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        slug:
          type: string
        url:
          type: string
          format: uri
        sync_to_organizations:
          type: string
          description: 'Retired: this field will not be returned with GHEC enterprise teams.'
          example: disabled
        organization_selection_type:
          type: string
          example: selected
        group_id:
          type:
          - string
          - 'null'
          example: 62ab9291-fae2-468e-974b-7e45096d5021
        group_name:
          type:
          - string
          - 'null'
          description: 'Retired: this field will not be returned with GHEC enterprise teams.'
          example: Justice League
        html_url:
          type: string
          format: uri
          example: https://github.com/enterprises/dc/teams/justice-league
        members_url:
          type: string
        members_count:
          type: integer
          description: The number of members in the enterprise team.
          example: 3
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        notification_setting:
          type: string
          description: Whether team members will receive notifications when the team is mentioned.
          example: notifications_enabled
          enum:
          - notifications_enabled
          - notifications_disabled
      required:
      - id
      - url
      - members_url
      - members_count
      - name
      - html_url
      - slug
      - created_at
      - updated_at
      - group_id
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
    enterprise-team:
      title: Enterprise Team
      description: Group of enterprise owners and/or members
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        slug:
          type: string
        url:
          type: string
          format: uri
        sync_to_organizations:
          type: string
          description: 'Retired: this field will not be returned with GHEC enterprise teams.'
          example: disabled | all
        organization_selection_type:
          type: string
          example: disabled | selected | all
        group_id:
          type:
          - string
          - 'null'
          example: 62ab9291-fae2-468e-974b-7e45096d5021
        group_name:
          type:
          - string
          - 'null'
          description: 'Retired: this field will not be returned with GHEC enterprise teams.'
          example: Justice League
        html_url:
          type: string
          format: uri
          example: https://github.com/enterprises/dc/teams/justice-league
        members_url:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        notification_setting:
          type: string
          description: Whether team members will receive notifications when the team is mentioned.
          example: notifications_enabled
          enum:
          - notifications_enabled
          - notifications_disabled
      required:
      - id
      - url
      - members_url
      - name
      - html_url
      - slug
      - created_at
      - updated_at
      - group_id
  parameters:
    page:
      name: page
      description: The page number of the results to fetch. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 1
    team-slug:
      name: team_slug
      description: The slug of the team name.
      in: path
      required: true
      schema:
        type: string
    enterprise:
      name: enterprise
      description: The slug version of the enterprise name.
      in: path
      required: true
      schema:
        type: string
    per-page:
      name: per_page
      description: The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
  examples:
    enterprise-teams-item:
      value:
        id: 1
        name: Justice League
        description: A great team.
        slug: justice-league
        url: https://api.github.com/enterprises/dc/teams/justice-league
        group_id: 62ab9291-fae2-468e-974b-7e45096d5021
        html_url: https://github.com/enterprises/dc/teams/justice-league
        members_url: https://api.github.com/enterprises/dc/teams/justice-league/members{/member}
        created_at: '2019-01-26T19:01:12Z'
        updated_at: '2019-01-26T19:14:43Z'
    enterprise-teams-items:
      value:
      - id: 1
        name: Justice League
        description: A great team.
        slug: justice-league
        url: https://api.github.com/enterprises/dc/teams/justice-league
        group_id: 62ab9291-fae2-468e-974b-7e45096d5021
        html_url: https://github.com/enterprises/dc/teams/justice-league
        members_url: https://api.github.com/enterprises/dc/teams/justice-league/members{/member}
        created_at: '2019-01-26T19:01:12Z'
        updated_at: '2019-01-26T19:14:43Z'
    enterprise-teams-item-with-member-count:
      value:
        id: 1
        name: Justice League
        description: A great team.
        slug: justice-league
        url: https://api.github.com/enterprises/dc/teams/1
        group_id: 62ab9291-fae2-468e-974b-7e45096d5021
        html_url: https://github.com/enterprises/dc/teams/justice-league
        members_url: https://api.github.com/enterprises/dc/teams/1/memberships{/member}
        members_count: 3
        created_at: '2019-01-26T19:01:12Z'
        updated_at: '2019-01-26T19:14:43Z'
externalDocs:
  description: GitHub Enterprise Cloud REST API
  url: https://docs.github.com/enterprise-cloud@latest/rest/
x-refined-from:
- github-enterprise-ghec-openapi.json
- github-enterprise-openapi.yml