openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Collaborators 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: Collaborators
paths:
/orgs/{org}/outside_collaborators:
get:
summary: GitHub List Outside Collaborators for an Organization
description: List all users who are outside collaborators of an organization.
tags:
- Collaborators
operationId: listOutsideCollaboratorsForAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/outside-collaborators#list-outside-collaborators-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
- name: filter
description: Filter the list of outside collaborators. `2fa_disabled` means that only outside collaborators without [two-factor authentication](https://github.com/blog/1614-two-factor-authentication) enabled will be returned.
in: query
required: false
schema:
type: string
enum:
- 2fa_disabled
- all
default: all
example: 2fa_disabled
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: outside-collaborators
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/outside_collaborators/{username}:
put:
summary: GitHub Convert an Organization Member to Outside Collaborator
description: When an organization member is converted to an outside collaborator, they'll only have access to the repositories that their current team membership allows. The user will no longer be a member of the organization. For more information, see "[Converting an organization member to an outside collaborator](https://docs.github.com/enterprise-server@3.9/articles/converting-an-organization-member-to-an-outside-collaborator/)". Converting an organization member to an outside collaborator may be restricted by enterprise administrators. For more information, see "[Enforcing repository management policies in your enterprise](https://docs.github.com/enterprise-server@3.9/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories)."
tags:
- Collaborators
operationId: convertAnOrganizationMemberToOutsideCollaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/outside-collaborators#convert-an-organization-member-to-outside-collaborator
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/username'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
async:
type: boolean
description: When set to `true`, the request will be performed asynchronously. Returns a 202 status code when the job is successfully queued.
default: false
examples:
'202':
summary: Status code 202, asynchronous request
value:
async: true
'204':
summary: Status code 204, synchronous request
value: null
responses:
'202':
description: User is getting converted asynchronously
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
examples:
'202':
value: null
'204':
description: User was converted
'403':
description: Forbidden if user is the last owner of the organization, not a member of the organization, or if the enterprise enforces a policy for inviting outside collaborators. For more information, see "[Enforcing repository management policies in your enterprise](https://docs.github.com/enterprise-server@3.9/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories)."
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: outside-collaborators
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove Outside Collaborator from an Organization
description: Removing a user from this list will remove them from all the organization's repositories.
tags:
- Collaborators
operationId: removeOutsideCollaboratorFromAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/outside-collaborators#remove-outside-collaborator-from-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/username'
responses:
'204':
description: Response
'422':
description: Unprocessable Entity if user is a member of the organization
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
examples:
response-if-user-is-a-member-of-the-organization:
value:
message: You cannot specify an organization member to remove as an outside collaborator.
documentation_url: https://docs.github.com/enterprise-server@3.9/rest/orgs/outside-collaborators#remove-outside-collaborator-from-an-organization
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: outside-collaborators
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/{project_id}/collaborators:
get:
summary: GitHub List Project Collaborators
description: Lists the collaborators for an organization project. For a project, 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. You must be an organization owner or a project `admin` to list collaborators.
tags:
- Collaborators
operationId: listProjectCollaborators
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/collaborators#list-project-collaborators
parameters:
- $ref: '#/components/parameters/project-id'
- name: affiliation
description: Filters the collaborators by their affiliation. `outside` means outside collaborators of a project that are not a member of the project's organization. `direct` means collaborators with permissions to a project, 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
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: collaborators
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/{project_id}/collaborators/{username}:
put:
summary: GitHub Add Project Collaborator
description: Adds a collaborator to an organization project and sets their permission level. You must be an organization owner or a project `admin` to add a collaborator.
tags:
- Collaborators
operationId: addProjectCollaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/collaborators#add-project-collaborator
parameters:
- $ref: '#/components/parameters/project-id'
- $ref: '#/components/parameters/username'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
permission:
description: The permission to grant the collaborator.
enum:
- read
- write
- admin
default: write
example: write
type: string
nullable: true
examples:
default:
summary: Applying write permissions for the new collaborator
value:
permission: write
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: collaborators
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove User as Collaborator
description: Removes a collaborator from an organization project. You must be an organization owner or a project `admin` to remove a collaborator.
tags:
- Collaborators
operationId: removeUserAsCollaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/collaborators#remove-user-as-a-collaborator
parameters:
- $ref: '#/components/parameters/project-id'
- $ref: '#/components/parameters/username'
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: collaborators
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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
operationId: listRepositoryCollaborators
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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:
- Collaborators
operationId: checkIfUserIsRepositoryCollaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/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:
- Collaborators
operationId: addRepositoryCollaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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.\n\nTo use this endpoint, the authenticated user must either be an administrator of the repository or target themselves for removal.\n\nThis endpoint also:\n- Cancels any outstanding invitations\n- Unasigns the user from any issues\n- Removes access to organization projects if the user is not an organization member and is not a collaborator on any other organization repositories.\n- Unstars the repository\n- Updates access permissions to packages\n\nRemoving a user as a collaborator has the following effects on forks:\n\n\n\n\n\n\n\n\n\n\n - If the user had access to a fork through their membership to this repository, the user will also be removed from the fork.\n - If the user had their own fork of the repository, the fork will be deleted.\n - If the user still has read access to the repository, open pull requests by this user from a fork will be denied.\n\n**Note**: user can still have access to the repository through organization permissions like base repository permissions.\n\nAlthough the API responds immediately, the additional permission updates might take some extra time to complete in the background.\n\nFor more information on fork permissions, see \"[About permissions and visibility of forks](https://docs.github.com/enterprise-server@3.9/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks)\"."
tags:
- Collaborators
operationId: removeRepositoryCollaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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
components:
responses:
forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
not_found:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
requires_authentication:
description: Requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
not_modified:
description: Not modified
validation_failed:
description: Validation failed, or the endpoint has been spammed.
content:
application/json:
schema:
$ref: '#/components/schemas/validation-error'
parameters:
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
org:
name: org
description: The organization name. The name is not case sensitive.
in: path
required: true
schema:
type: string
project-id:
name: project_id
description: The unique identifier of the project.
in: path
required: true
schema:
type: integer
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-server@3.9/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/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
in: query
schema:
type: integer
default: 1
headers:
link:
example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
schema:
type: string
examples:
simple-user-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
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
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:
# --- truncated at 32 KB (639 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-collaborators-api-openapi.yml