Organizations

In this article

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.

List organizations

Lists all organizations, in the order that they were created on GitHub.

Note: Pagination is powered exclusively by the since parameter. Use the Link header to get the URL for the next page of organizations.

get /organizations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

since string query

Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

per_page integer query

Results per page (max 100)

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/organizations
JavaScript (@octokit/core.js)
await octokit.request('GET /organizations')

Default response

Status: 200 OK
[
  {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
]

Not modified

Status: 304 Not Modified

Notes


Get an organization

To see many of the organization response values, you need to be an authenticated organization owner with the admin:org scope. 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.

GitHub Apps with the Organization plan permission can use this endpoint to retrieve information about an organization's GitHub plan. See "Authenticating with GitHub Apps" for details. For an example response, see "Response with GitHub plan information."

get /orgs/{org}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

org string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}', {
  org: 'org'
})

Default response

Status: 200 OK
{
  "login": "github",
  "id": 1,
  "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "hooks_url": "https://api.github.com/orgs/github/hooks",
  "issues_url": "https://api.github.com/orgs/github/issues",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization",
  "name": "github",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "twitter_username": "github",
  "is_verified": true,
  "has_organization_projects": true,
  "has_repository_projects": true,
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "html_url": "https://github.com/octocat",
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2014-03-03T18:58:10Z",
  "type": "Organization",
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "private_gists": 81,
  "disk_usage": 10000,
  "collaborators": 8,
  "billing_email": "mona@github.com",
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20
  },
  "default_repository_permission": "read",
  "members_can_create_repositories": true,
  "two_factor_requirement_enabled": true,
  "members_allowed_repository_creation_type": "all",
  "members_can_create_public_repositories": false,
  "members_can_create_private_repositories": false,
  "members_can_create_internal_repositories": false,
  "members_can_create_pages": true
}

Response with GitHub plan information

Status: 200 OK
{
  "login": "github",
  "id": 1,
  "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "hooks_url": "https://api.github.com/orgs/github/hooks",
  "issues_url": "https://api.github.com/orgs/github/issues",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization",
  "name": "github",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "twitter_username": "github",
  "is_verified": true,
  "has_organization_projects": true,
  "has_repository_projects": true,
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "html_url": "https://github.com/octocat",
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2014-03-03T18:58:10Z",
  "type": "Organization",
  "plan": {
    "name": "team",
    "space": 976562499,
    "private_repos": 999999,
    "filled_seats": 4,
    "seats": 5
  }
}

Resource not found

Status: 404 Not Found

Notes

Preview notice

New repository creation permissions are available to preview. You can now use members_can_create_public_repositories, members_can_create_private_repositories, and members_can_create_internal_repositories. 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+. These parameters provide more granular permissions to configure the type of repositories organization members can create.

To access these new parameters during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.surtur-preview+json

Update an organization

Parameter Deprecation Notice: GitHub 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.

Enables an authenticated organization owner with the admin:org scope to update the organization's profile and member privileges.

patch /orgs/{org}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

org string path
billing_email string body

Billing email address. This address is not publicized.

company string body

The company name.

email string body

The publicly visible email address.

twitter_username string body

The Twitter username of the company.

location string body

The location.

name string body

The shorthand name of the company.

description string body

The description of the company.

has_organization_projects boolean body

Toggles whether an organization can use organization projects.

has_repository_projects boolean body

Toggles whether repositories that belong to the organization can use repository projects.

default_repository_permission string body

Default permission level members have for organization repositories:
* read - can pull, but not push to or administer this repository.
* write - can pull and push, but not administer this repository.
* admin - can pull, push, and administer this repository.
* none - no permissions granted by default.

Default: read
members_can_create_repositories boolean body

Toggles the ability of non-admin organization members to create repositories. Can be one of:
* true - all organization members can create repositories.
* false - only organization owners can create repositories.
Default: true
Note: A parameter can override this parameter. See members_allowed_repository_creation_type in this table for details. 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 boolean body

Toggles 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+. Can be one of:
* true - all organization members can create internal repositories.
* false - only organization owners can create internal repositories.
Default: true. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation.

members_can_create_private_repositories boolean body

Toggles whether organization members can create private repositories, which are visible to organization members with permission. Can be one of:
* true - all organization members can create private repositories.
* false - only organization owners can create private repositories.
Default: true. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation.

members_can_create_public_repositories boolean body

Toggles whether organization members can create public repositories, which are visible to anyone. Can be one of:
* true - all organization members can create public repositories.
* false - only organization owners can create public repositories.
Default: true. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation.

members_allowed_repository_creation_type string body

Specifies which types of repositories non-admin organization members can create. Can be one of:
* all - all organization members can create public and private repositories.
* private - members can create private repositories. This option is only available to repositories that are part of an organization on GitHub Enterprise Cloud.
* none - only admin members can create repositories.
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 this note for details.

members_can_create_pages boolean body

Toggles whether organization members can create GitHub Pages sites. Can be one of:
* true - all organization members can create GitHub Pages sites.
* false - no organization members can create GitHub Pages sites. Existing published sites will not be impacted.
Default: true.

blog string body

undefined

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG \
  -d '{"billing_email":"billing_email"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /orgs/{org}', {
  org: 'org',
  billing_email: 'billing_email'
})

Default response

Status: 200 OK
{
  "login": "github",
  "id": 1,
  "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "hooks_url": "https://api.github.com/orgs/github/hooks",
  "issues_url": "https://api.github.com/orgs/github/issues",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization",
  "name": "github",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "twitter_username": "github",
  "is_verified": true,
  "has_organization_projects": true,
  "has_repository_projects": true,
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "html_url": "https://github.com/octocat",
  "created_at": "2008-01-14T04:33:35Z",
  "type": "Organization",
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "private_gists": 81,
  "disk_usage": 10000,
  "collaborators": 8,
  "billing_email": "mona@github.com",
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20
  },
  "default_repository_permission": "read",
  "members_can_create_repositories": true,
  "two_factor_requirement_enabled": true,
  "members_allowed_repository_creation_type": "all",
  "members_can_create_public_repositories": false,
  "members_can_create_private_repositories": false,
  "members_can_create_internal_repositories": false,
  "members_can_create_pages": true,
  "updated_at": "2014-03-03T18:58:10Z"
}

Conflict

Status: 409 Conflict

Preview header missing

Status: 415 Unsupported Media Type

Validation failed

Status: 422 Unprocessable Entity

Notes

Preview notice

New repository creation permissions are available to preview. You can now use members_can_create_public_repositories, members_can_create_private_repositories, and members_can_create_internal_repositories. 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+. These parameters provide more granular permissions to configure the type of repositories organization members can create.

To access these new parameters during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.surtur-preview+json

List SAML SSO authorizations for an organization

Listing and deleting credential authorizations is available to organizations with GitHub Enterprise Cloud. For more information, see GitHub's products.

An authenticated organization owner with the read:org scope can list all credential authorizations for an organization that uses SAML single sign-on (SSO). The credentials are either personal access tokens or SSH keys that organization members have authorized for the organization. For more information, see About authentication with SAML single sign-on.

get /orgs/{org}/credential-authorizations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/credential-authorizations
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/credential-authorizations', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "login": "octocat",
    "credential_id": 161195,
    "credential_type": "personal access token",
    "token_last_eight": "71c3fc11",
    "credential_authorized_at": "2011-01-26T19:06:43Z",
    "scopes": [
      "user",
      "repo"
    ]
  },
  {
    "login": "hubot",
    "credential_id": 161196,
    "credential_type": "personal access token",
    "token_last_eight": "12345678",
    "credential_authorized_at": "2019-03-29T19:06:43Z",
    "scopes": [
      "repo"
    ]
  }
]

Notes


Remove a SAML SSO authorization for an organization

Listing and deleting credential authorizations is available to organizations with GitHub Enterprise Cloud. For more information, see GitHub's products.

An authenticated organization owner with the admin:org scope can remove a credential authorization for an organization that uses SAML SSO. Once you remove someone's credential authorization, they will need to create a new personal access token or SSH key and authorize it for the organization they want to access.

delete /orgs/{org}/credential-authorizations/{credential_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
credential_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/credential-authorizations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/credential-authorizations/{credential_id}', {
  org: 'org',
  credential_id: 42
})

Default Response

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes


List app installations for an organization

Lists all GitHub Apps in an organization. The installation count includes all GitHub Apps installed on repositories in the organization. You must be an organization owner with admin:read scope to use this endpoint.

get /orgs/{org}/installations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/installations
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/installations', {
  org: 'org'
})

Default response

Status: 200 OK
{
  "total_count": 1,
  "installations": [
    {
      "id": 25381,
      "account": {
        "login": "octo-org",
        "id": 6811672,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjY4MTE2NzI=",
        "avatar_url": "https://avatars3.githubusercontent.com/u/6811672?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octo-org",
        "html_url": "https://github.com/octo-org",
        "followers_url": "https://api.github.com/users/octo-org/followers",
        "following_url": "https://api.github.com/users/octo-org/following{/other_user}",
        "gists_url": "https://api.github.com/users/octo-org/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octo-org/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octo-org/subscriptions",
        "organizations_url": "https://api.github.com/users/octo-org/orgs",
        "repos_url": "https://api.github.com/users/octo-org/repos",
        "events_url": "https://api.github.com/users/octo-org/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octo-org/received_events",
        "type": "Organization",
        "site_admin": false
      },
      "repository_selection": "selected",
      "access_tokens_url": "https://api.github.com/app/installations/25381/access_tokens",
      "repositories_url": "https://api.github.com/installation/repositories",
      "html_url": "https://github.com/organizations/octo-org/settings/installations/25381",
      "app_id": 2218,
      "target_id": 6811672,
      "target_type": "Organization",
      "permissions": {
        "deployments": "write",
        "metadata": "read",
        "pull_requests": "read",
        "statuses": "read"
      },
      "events": [
        "deployment",
        "deployment_status"
      ],
      "created_at": "2017-05-16T08:47:09.000-07:00",
      "updated_at": "2017-06-06T11:23:23.000-07:00",
      "single_file_name": null,
      "app_slug": "github-actions"
    }
  ]
}

Notes


List organizations for the authenticated user

List organizations for the authenticated user.

OAuth scope requirements

This only lists organizations that your authorization allows you to operate on in some way (e.g., you can list teams with read:org scope, you can publicize your organization membership with user scope, etc.). Therefore, this API requires at least user or read:org scope. OAuth requests with insufficient scope receive a 403 Forbidden response.

get /user/orgs

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/orgs
JavaScript (@octokit/core.js)
await octokit.request('GET /user/orgs')

Default response

Status: 200 OK
[
  {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
]

Not modified

Status: 304 Not Modified

Requires authentication

Status: 401 Unauthorized

Forbidden

Status: 403 Forbidden

List organizations for a user

List public organization memberships for the specified user.

This method only lists public memberships, regardless of authentication. If you need to fetch all of the organization memberships (public and private) for the authenticated user, use the List organizations for the authenticated user API instead.

get /users/{username}/orgs

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/orgs
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/orgs', {
  username: 'username'
})

Default response

Status: 200 OK
[
  {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
]

Notes


Blocking users

The token used to authenticate the call must have the admin:org scope in order to make any blocking calls for an organization. Otherwise, the response returns HTTP 404.

List users blocked by an organization

List the users blocked by an organization.

get /orgs/{org}/blocks

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/blocks
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/blocks', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Preview header missing

Status: 415 Unsupported Media Type

Notes


get /orgs/{org}/blocks/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/blocks/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/blocks/{username}', {
  org: 'org',
  username: 'username'
})

If the user is blocked

Status: 204 No Content

If the user is not blocked

Status: 404 Not Found

Notes


put /orgs/{org}/blocks/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/blocks/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('PUT /orgs/{org}/blocks/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

Validation failed

Status: 422 Unprocessable Entity

Notes


delete /orgs/{org}/blocks/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/blocks/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/blocks/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

Notes


Members

List pending organization invitations

The return hash contains a role field which refers to the Organization Invitation role and will be one of the following values: direct_member, admin, billing_manager, hiring_manager, or reinstate. If the invitee is not a GitHub member, the login field in the return hash will be null.

get /orgs/{org}/invitations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/invitations
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/invitations', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "login": "monalisa",
    "email": "octocat@github.com",
    "role": "direct_member",
    "created_at": "2016-11-30T06:46:10-08:00",
    "inviter": {
      "login": "other_user",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/other_user_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/other_user",
      "html_url": "https://github.com/other_user",
      "followers_url": "https://api.github.com/users/other_user/followers",
      "following_url": "https://api.github.com/users/other_user/following{/other_user}",
      "gists_url": "https://api.github.com/users/other_user/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/other_user/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/other_user/subscriptions",
      "organizations_url": "https://api.github.com/users/other_user/orgs",
      "repos_url": "https://api.github.com/users/other_user/repos",
      "events_url": "https://api.github.com/users/other_user/events{/privacy}",
      "received_events_url": "https://api.github.com/users/other_user/received_events",
      "type": "User",
      "site_admin": false
    },
    "team_count": 2,
    "invitation_team_url": "https://api.github.com/organizations/2/invitations/1/teams"
  }
]

Resource not found

Status: 404 Not Found

Notes


Create an organization invitation

Invite people to an organization by using their GitHub user ID or their email address. In order to create invitations in an organization, the authenticated user must be an organization owner.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" and "Dealing with abuse rate limits" for details.

post /orgs/{org}/invitations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
invitee_id integer body

Required unless you provide email. GitHub user ID for the person you are inviting.

email string body

Required unless you provide invitee_id. Email address of the person you are inviting, which can be an existing GitHub user.

role string body

Specify role for new member. Can be one of:
* admin - Organization owners with full administrative rights to the organization and complete access to all repositories and teams.
* direct_member - Non-owner organization members with ability to see other members and join teams by invitation.
* billing_manager - Non-owner organization members with ability to manage the billing settings of your organization.

Default: direct_member
team_ids array of integers body

Specify IDs for the teams you want to invite new members to.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/invitations \
  -d '{"invitee_id":42}'
JavaScript (@octokit/core.js)
await octokit.request('POST /orgs/{org}/invitations', {
  org: 'org',
  invitee_id: 42
})

Default response

Status: 201 Created
{
  "id": 1,
  "login": "monalisa",
  "email": "octocat@github.com",
  "role": "direct_member",
  "created_at": "2016-11-30T06:46:10-08:00",
  "inviter": {
    "login": "other_user",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/other_user_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/other_user",
    "html_url": "https://github.com/other_user",
    "followers_url": "https://api.github.com/users/other_user/followers",
    "following_url": "https://api.github.com/users/other_user/following{/other_user}",
    "gists_url": "https://api.github.com/users/other_user/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/other_user/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/other_user/subscriptions",
    "organizations_url": "https://api.github.com/users/other_user/orgs",
    "repos_url": "https://api.github.com/users/other_user/repos",
    "events_url": "https://api.github.com/users/other_user/events{/privacy}",
    "received_events_url": "https://api.github.com/users/other_user/received_events",
    "type": "User",
    "site_admin": false
  },
  "team_count": 2,
  "invitation_team_url": "https://api.github.com/organizations/2/invitations/1/teams"
}

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes


List organization invitation teams

List all teams associated with an invitation. In order to see invitations in an organization, the authenticated user must be an organization owner.

get /orgs/{org}/invitations/{invitation_id}/teams

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
invitation_id integer path

invitation_id parameter

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/invitations/42/teams
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/invitations/{invitation_id}/teams', {
  org: 'org',
  invitation_id: 42
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Resource not found

Status: 404 Not Found

Notes


List organization members

List all users who are members of an organization. If the authenticated user is also a member of this organization then both concealed and public members will be returned.

get /orgs/{org}/members

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
filter string query

Filter members returned in the list. Can be one of:
* 2fa_disabled - Members without two-factor authentication enabled. Available for organization owners.
* all - All members the authenticated user can see.

role string query

Filter members returned by their role. Can be one of:
* all - All members of the organization, regardless of role.
* admin - Organization owners.
* member - Non-owner organization members.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/members
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/members', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Response if requester is not an organization member

Status: 302 Found

Validation failed

Status: 422 Unprocessable Entity

Notes


Check organization membership for a user

Check if a user is, publicly or privately, a member of the organization.

get /orgs/{org}/members/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/members/{username}', {
  org: 'org',
  username: 'username'
})

Response if requester is an organization member and user is a member

Status: 204 No Content

Response if requester is not an organization member

Status: 302 Found

Response if requester is an organization member and user is not a member

Status: 404 Not Found

Notes


Remove an organization member

Removing a user from this list will remove them from all teams and they will no longer have any access to the organization's repositories.

delete /orgs/{org}/members/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/members/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

Forbidden

Status: 403 Forbidden

Notes


Get organization membership for a user

In order to get a user's membership with an organization, the authenticated user must be an organization member.

get /orgs/{org}/memberships/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/memberships/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/memberships/{username}', {
  org: 'org',
  username: 'username'
})

Response if user has an active admin membership with organization

Status: 200 OK
{
  "url": "https://api.github.com/orgs/octocat/memberships/defunkt",
  "state": "active",
  "role": "admin",
  "organization_url": "https://api.github.com/orgs/octocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Response if user has an active membership with organization

Status: 200 OK
{
  "url": "https://api.github.com/orgs/octocat/memberships/defunkt",
  "state": "active",
  "role": "member",
  "organization_url": "https://api.github.com/orgs/octocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Response if user has a pending membership with organization

Status: 200 OK
{
  "url": "https://api.github.com/orgs/invitocat/memberships/defunkt",
  "state": "pending",
  "role": "member",
  "organization_url": "https://api.github.com/orgs/invitocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Notes


Set organization membership for a user

Only authenticated organization owners can add a member to the organization or update the member's role.

  • If the authenticated user is adding a member to the organization, the invited user will receive an email inviting them to the organization. The user's membership status will be pending until they accept the invitation.
  • Authenticated users can update a user's membership by passing the role parameter. If the authenticated user changes a member's role to admin, the affected user will receive an email notifying them that they've been made an organization owner. If the authenticated user changes an owner's role to member, no email will be sent.

Rate limits

To prevent abuse, the authenticated user is limited to 50 organization invitations per 24 hour period. If the organization is more than one month old or on a paid plan, the limit is 500 invitations per 24 hour period.

put /orgs/{org}/memberships/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path
role string body

The role to give the user in the organization. Can be one of:
* admin - The user will become an owner of the organization.
* member - The user will become a non-owner member of the organization.

Default: member

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/memberships/USERNAME \
  -d '{"role":"role"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /orgs/{org}/memberships/{username}', {
  org: 'org',
  username: 'username',
  role: 'role'
})

Response if user was previously unaffiliated with organization

Status: 200 OK
{
  "url": "https://api.github.com/orgs/invitocat/memberships/defunkt",
  "state": "pending",
  "role": "admin",
  "organization_url": "https://api.github.com/orgs/invitocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Response if user already had membership with organization

Status: 200 OK
{
  "url": "https://api.github.com/orgs/octocat/memberships/defunkt",
  "state": "active",
  "role": "admin",
  "organization_url": "https://api.github.com/orgs/octocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Forbidden

Status: 403 Forbidden

Validation failed

Status: 422 Unprocessable Entity

Notes


Remove organization membership for a user

In order to remove a user's membership with an organization, the authenticated user must be an organization owner.

If the specified user is an active member of the organization, this will remove them from the organization. If the specified user has been invited to the organization, this will cancel their invitation. The specified user will receive an email notification in both cases.

delete /orgs/{org}/memberships/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/memberships/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/memberships/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Notes


List public organization members

Members of an organization can choose to have their membership publicized or not.

get /orgs/{org}/public_members

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/public_members
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/public_members', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Notes


get /orgs/{org}/public_members/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/public_members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/public_members/{username}', {
  org: 'org',
  username: 'username'
})

Response if user is a public member

Status: 204 No Content

Response if user is not a public member

Status: 404 Not Found

Notes


Set public organization membership for the authenticated user

The user can publicize their own membership. (A user cannot publicize the membership for another user.)

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /orgs/{org}/public_members/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/public_members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('PUT /orgs/{org}/public_members/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

Forbidden

Status: 403 Forbidden

delete /orgs/{org}/public_members/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/public_members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/public_members/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

get /user/memberships/orgs

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

state string query

Indicates the state of the memberships to return. Can be either active or pending. If not specified, the API returns both active and pending memberships.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/memberships/orgs
JavaScript (@octokit/core.js)
await octokit.request('GET /user/memberships/orgs')

Default response

Status: 200 OK
[
  {
    "url": "https://api.github.com/orgs/octocat/memberships/defunkt",
    "state": "active",
    "role": "admin",
    "organization_url": "https://api.github.com/orgs/octocat",
    "organization": {
      "login": "github",
      "id": 1,
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
      "url": "https://api.github.com/orgs/github",
      "repos_url": "https://api.github.com/orgs/github/repos",
      "events_url": "https://api.github.com/orgs/github/events",
      "hooks_url": "https://api.github.com/orgs/github/hooks",
      "issues_url": "https://api.github.com/orgs/github/issues",
      "members_url": "https://api.github.com/orgs/github/members{/member}",
      "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    },
    "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
    }
  },
  {
    "url": "https://api.github.com/orgs/invitocat/memberships/defunkt",
    "state": "pending",
    "role": "admin",
    "organization_url": "https://api.github.com/orgs/invitocat",
    "organization": {
      "login": "github",
      "id": 1,
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
      "url": "https://api.github.com/orgs/github",
      "repos_url": "https://api.github.com/orgs/github/repos",
      "events_url": "https://api.github.com/orgs/github/events",
      "hooks_url": "https://api.github.com/orgs/github/hooks",
      "issues_url": "https://api.github.com/orgs/github/issues",
      "members_url": "https://api.github.com/orgs/github/members{/member}",
      "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    },
    "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
    }
  }
]

Not modified

Status: 304 Not Modified

Requires authentication

Status: 401 Unauthorized

Forbidden

Status: 403 Forbidden

Validation failed

Status: 422 Unprocessable Entity

get /user/memberships/orgs/{org}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/memberships/orgs/ORG
JavaScript (@octokit/core.js)
await octokit.request('GET /user/memberships/orgs/{org}', {
  org: 'org'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/orgs/invitocat/memberships/defunkt",
  "state": "pending",
  "role": "admin",
  "organization_url": "https://api.github.com/orgs/invitocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

patch /user/memberships/orgs/{org}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
state string body

Required. The state that the membership should be in. Only "active" will be accepted.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/memberships/orgs/ORG \
  -d '{"state":"state"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /user/memberships/orgs/{org}', {
  org: 'org',
  state: 'state'
})

Default response

Status: 200 OK
{
  "url": "https://api.github.com/orgs/octocat/memberships/defunkt",
  "state": "active",
  "role": "admin",
  "organization_url": "https://api.github.com/orgs/octocat",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "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
  }
}

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Outside collaborators

List outside collaborators for an organization

List all users who are outside collaborators of an organization.

get /orgs/{org}/outside_collaborators

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
filter string query

Filter the list of outside collaborators. Can be one of:
* 2fa_disabled: Outside collaborators without two-factor authentication enabled.
* all: All outside collaborators.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/outside_collaborators
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/outside_collaborators', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "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
  }
]

Notes


Convert an organization member to outside collaborator

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".

put /orgs/{org}/outside_collaborators/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/outside_collaborators/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('PUT /orgs/{org}/outside_collaborators/{username}', {
  org: 'org',
  username: 'username'
})

User is getting converted asynchronously

Status: 202 Accepted

User was converted

Status: 204 No Content

Response if user is the last owner of the organization

Status: 403 Forbidden
{
  "message": "Cannot convert the last owner to an outside collaborator",
  "documentation_url": "https://developer.github.com/v3/orgs/outside_collaborators/#convert-member-to-outside-collaborator"
}

Response if user is not a member of the organization

Status: 403 Forbidden
{
  "message": "<user> is not a member of the <organization> organization.",
  "documentation_url": "https://developer.github.com/v3/orgs/outside_collaborators/#convert-member-to-outside-collaborator"
}

Resource not found

Status: 404 Not Found

Notes


Remove outside collaborator from an organization

Removing a user from this list will remove them from all the organization's repositories.

delete /orgs/{org}/outside_collaborators/{username}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
username string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/outside_collaborators/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/outside_collaborators/{username}', {
  org: 'org',
  username: 'username'
})

Default Response

Status: 204 No Content

Response if user is a member of the organization

Status: 422 Unprocessable Entity
{
  "message": "You cannot specify an organization member to remove as an outside collaborator.",
  "documentation_url": "https://developer.github.com/v3/orgs/outside_collaborators/#remove-outside-collaborator"
}

Notes


Webhooks

Organization webhooks allow you to receive HTTP POST payloads whenever certain events happen within the organization. Subscribing to these events makes it possible to build integrations that react to actions on GitHub.com. For more information on actions you can subscribe to, see "GitHub event types."

Scopes & Restrictions

All actions against organization webhooks require the authenticated user to be an admin of the organization being managed. Additionally, OAuth tokens require the admin:org_hook scope. For more information, see "Scopes for OAuth Apps."

In order to protect sensitive data which may be present in webhook configurations, we also enforce the following access control rules:

  • OAuth applications cannot list, view, or edit webhooks which they did not create.
  • Users cannot list, view, or edit webhooks which were created by OAuth applications.

Receiving Webhooks

In order for GitHub to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.

For more best practices, see our guide.

Webhook headers

GitHub will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.

get /orgs/{org}/hooks

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/hooks', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "url": "https://api.github.com/orgs/octocat/hooks/1",
    "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
    "name": "web",
    "events": [
      "push",
      "pull_request"
    ],
    "active": true,
    "config": {
      "url": "http://example.com",
      "content_type": "json"
    },
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z",
    "type": "Organization"
  }
]

Resource not found

Status: 404 Not Found

Notes


Create an organization webhook

Here's how you can create a hook that posts payloads in JSON format:

post /orgs/{org}/hooks

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
name string body

Required. Must be passed as "web".

config object body

Required. Key/value pairs to provide settings for this webhook. These are defined below.

Properties of the config object

url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

username (string)

undefined

password (string)

undefined

events array of strings body

Determines what events the hook is triggered for.

Default: push
active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks \
  -d '{"name":"name","config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl","username":"username","password":"password"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /orgs/{org}/hooks', {
  org: 'org',
  name: 'name',
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl',
    username: 'username',
    password: 'password'
  }
})

Default response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes


get /orgs/{org}/hooks/{hook_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
hook_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/hooks/{hook_id}', {
  org: 'org',
  hook_id: 42
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Resource not found

Status: 404 Not Found

Notes


patch /orgs/{org}/hooks/{hook_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
hook_id integer path
config object body

Key/value pairs to provide settings for this webhook. These are defined below.

Properties of the config object

url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

Determines what events the hook is triggered for.

Default: push
active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true
name string body

undefined

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42 \
  -d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /orgs/{org}/hooks/{hook_id}', {
  org: 'org',
  hook_id: 42,
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  }
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Resource not found

Status: 404 Not Found

Validation failed

Status: 422 Unprocessable Entity

Notes


delete /orgs/{org}/hooks/{hook_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
hook_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/hooks/{hook_id}', {
  org: 'org',
  hook_id: 42
})

Default Response

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes


Ping an organization webhook

This will trigger a ping event to be sent to the hook.

post /orgs/{org}/hooks/{hook_id}/pings

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
hook_id integer path

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /orgs/{org}/hooks/{hook_id}/pings', {
  org: 'org',
  hook_id: 42
})

Default Response

Status: 204 No Content

Resource not found

Status: 404 Not Found

Notes


Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.