GitHub Collaborators API

openapi: 3.1.0
info:
  version: 1.1.4
  title: github-repos-api
  description: |-
    Use the REST API to create, manage and control the workflow of public and
    private GitHub repositories.
  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
servers:
- url: '{protocol}://{hostname}'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: api.github.com
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: https
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/[email protected]/rest/
tags:
- name: Add
- name: Checks
- name: Collaborators
- name: Get
- name: Lists
- name: Permissions
- name: Remove
- name: Repositories
  description: Source control repositories.
- name: Users
paths:
  /repos/{owner}/{repo}/collaborators:
    get:
      summary: GitHub List Repository Collaborators
      description: |-
        For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.
        Organization members with write, maintain, or admin privileges on the organization-owned repository can use this endpoint.

        Team members will include the members of child teams.

        The authenticated user must have push access to the repository to use this endpoint.

        OAuth app tokens and personal access tokens (classic) need the `read:org` and `repo` scopes to use this endpoint.
      tags:
      - Collaborators
      - Lists
      - Repositories
      operationId: listRepositoryCollaborators
      externalDocs:
        description: API method documentation
        url: |-
          https://docs.github.com/[email protected]/rest/collaborators/collaborators#list-repository-collaborators
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: affiliation
        description: |-
          Filter collaborators returned by their affiliation. `outside` means all outside collaborators of an organization-owned repository. `direct` means all collaborators with permissions to an organization-owned repository, regardless of organization membership status. `all` means all collaborators the authenticated user can see.
        in: query
        required: false
        schema:
          type: string
          enum:
          - outside
          - direct
          - all
          default: all
        example: outside
      - name: permission
        description: |-
          Filter collaborators by the permissions they have on the repository. If not specified, all collaborators will be returned.
        in: query
        required: false
        schema:
          type: string
          enum:
          - pull
          - triage
          - push
          - maintain
          - admin
        example: pull
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/collaborator'
              examples:
                default:
                  $ref: '#/components/examples/collaborator-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: collaborators
        subcategory: collaborators
      x-api-evangelist-certified: '2025-07-16'
      x-api-naftiko-published: '2025-07-25'
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/collaborators/{username}:
    get:
      summary: GitHub Check if User is Repository Collaborator
      description: |-
        For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.

        Team members will include the members of child teams.

        The authenticated user must have push access to the repository to use this endpoint.

        OAuth app tokens and personal access tokens (classic) need the `read:org` and `repo` scopes to use this endpoint.
      tags:
      - Checks
      - Collaborators
      - Repositories
      - Users
      operationId: checkIfUserIsRepositoryCollaborator
      externalDocs:
        description: API method documentation
        url: |-
          https://docs.github.com/[email protected]/rest/collaborators/collaborators#check-if-a-user-is-a-repository-collaborator
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/username'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '204':
          description: Response if user is a collaborator
        '404':
          description: Not Found if user is not a collaborator
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: collaborators
        subcategory: collaborators
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: GitHub Add Repository Collaborator
      description: |-
        This endpoint triggers [notifications](https://docs.github.com/[email protected]/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/[email protected]/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/[email protected]/rest/guides/best-practices-for-using-the-rest-api)."

        Adding an outside collaborator may be restricted by enterprise administrators. For more information, see "[Enforcing repository management policies in your enterprise](https://docs.github.com/[email protected]/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories)."

        For more information on permission levels, see "[Repository permission levels for an organization](https://docs.github.com/[email protected]/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization)". There are restrictions on which permissions can be granted to organization members when an organization base role is in place. In this case, the permission being given must be equal to or higher than the org base permission. Otherwise, the request will fail with:

        ```
        Cannot assign {member} permission of {role name}
        ```

        Note that, if you choose not to pass any parameters, you'll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see "[HTTP method](https://docs.github.com/[email protected]/rest/guides/getting-started-with-the-rest-api#http-method)."

        **Updating an existing collaborator's permission level**

        The endpoint can also be used to change the permissions of an existing collaborator without first removing and re-adding the collaborator. To change the permissions, use the same endpoint and pass a different `permission` parameter. The response will be a `204`, with no other indication that the permission level changed.
      tags:
      - Add
      - Collaborators
      - Repositories
      operationId: addRepositoryCollaborator
      externalDocs:
        description: API method documentation
        url: |-
          https://docs.github.com/[email protected]/rest/collaborators/collaborators#add-a-repository-collaborator
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/username'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                permission:
                  type: string
                  description: |-
                    The permission to grant the collaborator. **Only valid on organization-owned repositories.**
                  default: push
            examples:
              new-invitation-is-created:
                summary: Add a collaborator with triage permissions
                value:
                  permission: triage
      responses:
        '204':
          description: |-
            Response when:
            - an existing collaborator is added as a collaborator
            - an organization member is added as an individual collaborator
            - an existing team member (whose team is also a repository collaborator) is added as an individual collaborator
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        triggersNotification: true
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: collaborators
        subcategory: collaborators
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Remove Repository Collaborator
      description: |-
        Removes a collaborator from a repository.

        To use this endpoint, the authenticated user must either be an administrator of the repository or target themselves for removal.

        This endpoint also:
        - Cancels any outstanding invitations
        - Unasigns the user from any issues
        - Removes access to organization projects if the user is not an organization member and is not a collaborator on any other organization repositories.
        - Unstars the repository
        - Updates access permissions to packages

        Removing a user as a collaborator has the following effects on forks:










         - If the user had access to a fork through their membership to this repository, the user will also be removed from the fork.
         - If the user had their own fork of the repository, the fork will be deleted.
         - If the user still has read access to the repository, open pull requests by this user from a fork will be denied.

        **Note**: user can still have access to the repository through organization permissions like base repository permissions.

        Although the API responds immediately, the additional permission updates might take some extra time to complete in the background.

        For more information on fork permissions, see "[About permissions and visibility of forks](https://docs.github.com/[email protected]/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks)".
      tags:
      - Collaborators
      - Remove
      - Repositories
      operationId: removeRepositoryCollaborator
      externalDocs:
        description: API method documentation
        url: |-
          https://docs.github.com/[email protected]/rest/collaborators/collaborators#remove-a-repository-collaborator
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/username'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '204':
          description: No Content when collaborator was removed from the repository.
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: collaborators
        subcategory: collaborators
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/collaborators/{username}/permission:
    get:
      summary: GitHub Get Repository Permissions for User
      description: |-
        Checks the repository permission of a collaborator. The possible repository
        permissions are `admin`, `write`, `read`, and `none`.

        *Note*: The `permission` attribute provides the legacy base roles of `admin`, `write`, `read`, and `none`, where the
        `maintain` role is mapped to `write` and the `triage` role is mapped to `read`. To determine the role assigned to the
        collaborator, see the `role_name` attribute, which will provide the full role name, including custom roles. The
        `permissions` hash can also be used to determine which base level of access the collaborator has to the repository.
      tags:
      - Get
      - Permissions
      - Repositories
      - Users
      operationId: getRepositoryPermissionsForUser
      externalDocs:
        description: API method documentation
        url: |-
          https://docs.github.com/[email protected]/rest/collaborators/collaborators#get-repository-permissions-for-a-user
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/username'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: if user has admin permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/repository-collaborator-permission'
              examples:
                response-if-user-has-admin-permissions:
                  $ref: |-
                    #/components/examples/repository-collaborator-permission-response-if-user-has-admin-permissions
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: collaborators
        subcategory: collaborators
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
    validation-error:
      title: Validation Error
      description: Validation Error
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        errors:
          type: array
          items:
            type: object
            required:
            - code
            properties:
              resource:
                type: string
              field:
                type: string
              message:
                type: string
              code:
                type: string
              index:
                type: integer
              value:
                oneOf:
                - type: string
                - type: integer
                - type: array
                  items:
                    type: string
    collaborator:
      title: Collaborator
      description: Collaborator
      type: object
      properties:
        login:
          type: string
          example: octocat
        id:
          type: integer
          format: int64
          example: 1
        email:
          type: string
          example: [email protected]
        name:
          type: string
          example: octocat
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type: string
          example: 41d064eb2195891e12d0413f63227ea7
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
          example: true
        permissions:
          type: object
          properties:
            pull:
              type: boolean
            triage:
              type: boolean
            push:
              type: boolean
            maintain:
              type: boolean
            admin:
              type: boolean
          required:
          - pull
          - push
          - admin
        role_name:
          type: string
          example: admin
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    nullable-collaborator:
      title: Collaborator
      description: Collaborator
      type: object
      properties:
        login:
          type: string
          example: octocat
        id:
          type: integer
          format: int64
          example: 1
        email:
          type: string
          example: [email protected]
        name:
          type: string
          example: octocat
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type: string
          example: 41d064eb2195891e12d0413f63227ea7
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
          example: true
        permissions:
          type: object
          properties:
            pull:
              type: boolean
            triage:
              type: boolean
            push:
              type: boolean
            maintain:
              type: boolean
            admin:
              type: boolean
          required:
          - pull
          - push
          - admin
        role_name:
          type: string
          example: admin
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    repository-collaborator-permission:
      title: Repository Collaborator Permission
      description: Repository Collaborator Permission
      type: object
      properties:
        permission:
          type: string
          example: example_value
        role_name:
          type: string
          example: admin
        user:
          $ref: '#/components/schemas/nullable-collaborator'
      required:
      - permission
      - role_name
      - user
  examples:
    collaborator-items:
      value:
      - login: octocat
        id: 1
        node_id: MDQ6VXNlcjE=
        avatar_url: https://github.com/images/error/octocat_happy.gif
        gravatar_id: ''
        url: https://api.github.com/users/octocat
        html_url: https://github.com/octocat
        followers_url: https://api.github.com/users/octocat/followers
        following_url: https://api.github.com/users/octocat/following{/other_user}
        gists_url: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url: https://api.github.com/users/octocat/subscriptions
        organizations_url: https://api.github.com/users/octocat/orgs
        repos_url: https://api.github.com/users/octocat/repos
        events_url: https://api.github.com/users/octocat/events{/privacy}
        received_events_url: https://api.github.com/users/octocat/received_events
        type: User
        site_admin: false
        permissions:
          pull: true
          triage: true
          push: true
          maintain: false
          admin: false
        role_name: write
    repository-collaborator-permission-response-if-user-has-admin-permissions:
      value:
        permission: admin
        role_name: admin
        user:
          login: octocat
          id: 1
          node_id: MDQ6VXNlcjE=
          avatar_url: https://github.com/images/error/octocat_happy.gif
          gravatar_id: ''
          url: https://api.github.com/users/octocat
          html_url: https://github.com/octocat
          followers_url: https://api.github.com/users/octocat/followers
          following_url: https://api.github.com/users/octocat/following{/other_user}
          gists_url: https://api.github.com/users/octocat/gists{/gist_id}
          starred_url: https://api.github.com/users/octocat/starred{/owner}{/repo}
          subscriptions_url: https://api.github.com/users/octocat/subscriptions
          organizations_url: https://api.github.com/users/octocat/orgs
          repos_url: https://api.github.com/users/octocat/repos
          events_url: https://api.github.com/users/octocat/events{/privacy}
          received_events_url: https://api.github.com/users/octocat/received_events
          type: User
          site_admin: false
  parameters:
    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/[email protected]/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
    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/[email protected]/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 1
    username:
      name: username
      description: The handle for the GitHub user account.
      in: path
      required: true
      schema:
        type: string
    owner:
      name: owner
      description: The account owner of the repository. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    repo:
      name: repo
      description: |-
        The name of the repository without the `.git` extension. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
  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:
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    validation_failed:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer