Organizations

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`	integer	query	An organization ID. Only return organizations with an ID greater than this ID.
`per_page`	integer	query	Results per page (max 100) Default: `30`

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')

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

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`304`	Not modified

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

get /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/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,
    "filled_seats": 4,
    "seats": 5
  },
  "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,
  "members_can_fork_private_repositories": false
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	Default response
`404`	Resource not found

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.
`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:
`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 the parameter deprecation notice in the operation description 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:
`members_can_create_public_pages`	boolean	body	Toggles whether organization members can create public GitHub Pages sites. Can be one of: * `true` - all organization members can create public GitHub Pages sites. * `false` - no organization members can create public GitHub Pages sites. Existing published sites will not be impacted. Default:
`members_can_create_private_pages`	boolean	body	Toggles whether organization members can create private GitHub Pages sites. Can be one of: * `true` - all organization members can create private GitHub Pages sites. * `false` - no organization members can create private GitHub Pages sites. Existing published sites will not be impacted. Default:
`members_can_fork_private_repositories`	boolean	body	Toggles whether organization members can fork private organization repositories. Can be one of: * `true` - all organization members can fork private repositories within the organization. * `false` - no organization members can fork private repositories within the organization.
`blog`	string	body

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'
})

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,
  "members_can_create_public_pages": true,
  "members_can_create_private_pages": true,
  "members_can_fork_private_repositories": false,
  "updated_at": "2014-03-03T18:58:10Z"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`409`	Conflict
`422`	Validation failed

Get the audit log for an organization

Gets the audit log for an organization. For more information, see "Reviewing the audit log for your organization."

This endpoint is available for organizations on GitHub Enterprise Cloud. To use this endpoint, you must be an organization owner, and you must use an access token with the admin:org scope. GitHub Apps must have the organization_administration read permission to use this endpoint.

By default, the response includes up to 30 events from the past three months. Use the phrase parameter to filter results and retrieve older events. For example, use the phrase parameter with the created qualifier to filter events based on when the events occurred. For more information, see "Reviewing the audit log for your organization."

Use pagination to retrieve fewer or more than 30 events. For more information, see "Resources in the REST API."

get /orgs/{org}/audit-log

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`phrase`	string	query	A search phrase. For more information, see Searching the audit log.
`include`	string	query	The event types to include: `web` - returns web (non-Git) events. `git` - returns Git events. `all` - returns both web and Git events. The default is `web`.
`after`	string	query	A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.
`before`	string	query	A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.
`order`	string	query	The order of audit log events. To list newest events first, specify `desc`. To list oldest events first, specify `asc`. The default is `desc`.
`per_page`	integer	query	Results per page (max 100) Default: `30`

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/audit-log

JavaScript (@octokit/core.js)

 await octokit.request('GET /orgs/{org}/audit-log', {
  org: 'org'
})

Response

 Status: 200 OK

 [
  {
    "@timestamp": 1606929874512,
    "action": "team.add_member",
    "actor": "octocat",
    "created_at": 1606929874512,
    "_document_id": "xJJFlFOhQ6b-5vaAFy9Rjw",
    "org": "octo-corp",
    "team": "octo-corp/example-team",
    "user": "monalisa"
  },
  {
    "@timestamp": 1606507117008,
    "action": "org.create",
    "actor": "octocat",
    "created_at": 1606507117008,
    "_document_id": "Vqvg6kZ4MYqwWRKFDzlMoQ",
    "org": "octocat-test-org"
  },
  {
    "@timestamp": 1605719148837,
    "action": "repo.destroy",
    "actor": "monalisa",
    "created_at": 1605719148837,
    "_document_id": "LwW2vpJZCDS-WUmo9Z-ifw",
    "org": "mona-org",
    "repo": "mona-org/mona-test-repo",
    "visibility": "private"
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

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
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page token
`login`	string	query	Limits the list of credentials authorizations for an organization to a specific login

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'
})

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",
    "authorized_credential_expires_at": "2011-02-25T19:06:43Z",
    "scopes": [
      "user",
      "repo"
    ]
  },
  {
    "login": "hubot",
    "credential_id": 161196,
    "credential_type": "personal access token",
    "token_last_eight": "Ae178B4a",
    "credential_authorized_at": "2019-03-29T19:06:43Z",
    "authorized_credential_expires_at": "2019-04-28T19:06:43Z",
    "scopes": [
      "repo"
    ]
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

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
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`404`	Resource not found

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

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": "config.yml",
      "has_multiple_single_files": true,
      "single_file_paths": [
        "config.yml",
        ".github/issue_TEMPLATE.md"
      ],
      "app_slug": "github-actions",
      "suspended_at": null,
      "suspended_by": null
    }
  ]
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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')

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

Status codes

HTTP Status Code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

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

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

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'
})

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

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

Check if a user is blocked by an organization

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

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	If the user is blocked:
`404`	If the user is not blocked:

Block a user from an organization

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'
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`422`	Validation failed

Unblock a user from an organization

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'
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content

Custom repository roles

List custom repository roles in an organization

List the custom repository roles available in this organization. In order to see custom repository roles in an organization, the authenticated user must be an organization owner.

For more information on custom repository roles, see "Managing custom repository roles for an organization".

get /organizations/{organization_id}/custom_roles

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`organization_id`	string	path

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/organizations/ORGANIZATION_ID/custom_roles

JavaScript (@octokit/core.js)

 await octokit.request('GET /organizations/{organization_id}/custom_roles', {
  organization_id: 'organization_id'
})

Response - list of custom role names

 Status: 200 OK

 {
  "total_count": 2,
  "custom_roles": [
    {
      "id": 8030,
      "name": "Developer"
    },
    {
      "id": 8031,
      "name": "Designer"
    }
  ]
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	Response - list of custom role names

Members

List failed organization invitations

The return hash contains failed_at and failed_reason fields which represent the time at which the invitation failed and the reason for the failure.

get /orgs/{org}/failed_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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/failed_invitations

JavaScript (@octokit/core.js)

 await octokit.request('GET /orgs/{org}/failed_invitations', {
  org: 'org'
})

Response

 Status: 200 OK

 [
  {
    "id": 1,
    "login": "monalisa",
    "node_id": "MDQ6VXNlcjE=",
    "email": "octocat@github.com",
    "role": "direct_member",
    "created_at": "2016-11-30T06:46:10-08:00",
    "failed_at": "",
    "failed_reason": "",
    "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_teams_url": "https://api.github.com/organizations/2/invitations/1/teams"
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

Response

 Status: 200 OK

 [
  {
    "id": 1,
    "login": "monalisa",
    "node_id": "MDQ6VXNlcjE=",
    "email": "octocat@github.com",
    "role": "direct_member",
    "created_at": "2016-11-30T06:46:10-08:00",
    "failed_at": "",
    "failed_reason": "",
    "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_teams_url": "https://api.github.com/organizations/2/invitations/1/teams"
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

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 secondary rate limiting. See "Secondary rate limits" and "Dealing with secondary 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
})

Response

 Status: 201 Created

 {
  "id": 1,
  "login": "monalisa",
  "node_id": "MDQ6VXNlcjE=",
  "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_teams_url": "https://api.github.com/organizations/2/invitations/1/teams"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`201`	Created
`404`	Resource not found
`422`	Validation failed

Cancel an organization invitation

Cancel an organization invitation. In order to cancel an organization invitation, the authenticated user must be an organization owner.

This endpoint triggers notifications.

delete /orgs/{org}/invitations/{invitation_id}

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

Code samples

Shell

 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/invitations/42

JavaScript (@octokit/core.js)

 await octokit.request('DELETE /orgs/{org}/invitations/{invitation_id}', {
  org: 'org',
  invitation_id: 42
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`404`	Resource not found
`422`	Validation failed

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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
})

Response

 Status: 200 OK

 [
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://github.com/orgs/github/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
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

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. Default: `all`
`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. Default: `all`
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

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

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`302`	Response if requester is not an organization member
`422`	Validation failed

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

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	Response if requester is an organization member and user is a member
`302`	Response if requester is not an organization member
`404`	Not Found if requester is an organization member and user is not a member

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'
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`403`	Forbidden

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. The state parameter in the response can be used to identify the user's membership status.

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
  }
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	Response if user has an active admin membership with organization
`403`	Forbidden
`404`	Resource not found

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 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
  }
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	Response if user has an active admin membership with organization
`403`	Forbidden
`422`	Validation failed

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'
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`403`	Forbidden
`404`	Resource not found

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

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

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

Check public organization membership for a user

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

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	Response if user is a public member
`404`	Not Found if user is not a public member

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'
})

Response

 Status: 204 No Content

Status codes

HTTP Status Code	Description
`204`	No Content
`403`	Forbidden

Remove public organization membership for the authenticated user

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'
})

Response

 Status: 204 No Content

Status codes

HTTP Status Code	Description
`204`	No Content

List organization memberships for the authenticated user

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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')

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

Status codes

HTTP Status Code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`422`	Validation failed

Get an organization membership for the authenticated user

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'
})

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
  }
}

Status codes

HTTP Status Code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Update an organization membership for the authenticated user

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'
})

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
  }
}

Status codes

HTTP Status Code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed

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. Default: `all`
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

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

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

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

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

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`202`	User is getting converted asynchronously
`204`	User was converted
`403`	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."
`404`	Resource not found

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'
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`422`	Unprocessable Entity if user is a member of the organization

Webhooks

Organization webhooks allow you to receive HTTP POST payloads whenever certain events happen in an organization. The webhook REST APIs enable you to manage repository, organization, and app webhooks. You can use this API to list webhook deliveries for a webhook, or get and redeliver an individual delivery for a webhook, which can be integrated into an external app or service. You can also use the REST API to change the configuration of the webhook. For example, you can modify the payload URL, content type, SSL verification, and secret. For more information, see:

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.

List organization webhooks

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) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

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'
})

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",
    "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
    "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"
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

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 toapplication/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 theconfigobject

Name (Type)	Description
`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 for delivery signature headers.
`insecure_ssl` (string or number or )	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)
`password` (string)

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:

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'
  }
})

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",
  "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
  "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"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`201`	Created
`404`	Resource not found
`422`	Validation failed

Get an organization webhook

Returns a webhook configured in an organization. To get only the webhook config properties, see "Get a webhook configuration for an organization."

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
})

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",
  "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
  "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"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

Update an organization webhook

Updates a webhook configured in an organization. When you update a webhook, the secret will be overwritten. If you previously had a secret set, you must provide the same secret or set a new secret or the secret will be removed. If you are only updating individual webhook config properties, use "Update a webhook configuration for an organization."

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

Parameters

Name Type In Description

accept

string

header

Setting toapplication/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 theconfigobject

Name (Type)	Description
`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 for delivery signature headers.
`insecure_ssl` (string or number or )	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:

name

string

body

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'
  }
})

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",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "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"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed

Delete an organization webhook

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
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`404`	Resource not found

Get a webhook configuration for an organization

Returns the webhook configuration for an organization. To get more information about the webhook, including the active state and events, use "Get an organization webhook ."

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:read permission.

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

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/config

JavaScript (@octokit/core.js)

 await octokit.request('GET /orgs/{org}/hooks/{hook_id}/config', {
  org: 'org',
  hook_id: 42
})

Response

 Status: 200 OK

 {
  "content_type": "json",
  "insecure_ssl": "0",
  "secret": "********",
  "url": "https://example.com/webhook"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

Update a webhook configuration for an organization

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use "Update an organization webhook ."

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:write permission.

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

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`hook_id`	integer	path
`url`	string	body	The URL to which the payloads will be delivered.
`content_type`	string	body	The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
`secret`	string	body	If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`	string or number or	body	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.

Code samples

Shell

 curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42/config \
  -d '{"url":"url"}'

JavaScript (@octokit/core.js)

 await octokit.request('PATCH /orgs/{org}/hooks/{hook_id}/config', {
  org: 'org',
  hook_id: 42,
  url: 'url'
})

Response

 Status: 200 OK

 {
  "content_type": "json",
  "insecure_ssl": "0",
  "secret": "********",
  "url": "https://example.com/webhook"
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK

List deliveries for an organization webhook

Returns a list of webhook deliveries for a webhook configured in an organization.

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

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`hook_id`	integer	path
`per_page`	integer	query	Results per page (max 100) Default: `30`
`cursor`	string	query	Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the `link` header for the next and previous page cursors.

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42/deliveries

JavaScript (@octokit/core.js)

 await octokit.request('GET /orgs/{org}/hooks/{hook_id}/deliveries', {
  org: 'org',
  hook_id: 42
})

Response

 Status: 200 OK

 [
  {
    "id": 12345678,
    "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
    "delivered_at": "2019-06-03T00:57:16Z",
    "redelivery": false,
    "duration": 0.27,
    "status": "OK",
    "status_code": 200,
    "event": "issues",
    "action": "opened",
    "installation_id": 123,
    "repository_id": 456
  },
  {
    "id": 123456789,
    "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
    "delivered_at": "2019-06-04T00:57:16Z",
    "redelivery": true,
    "duration": 0.28,
    "status": "OK",
    "status_code": 200,
    "event": "issues",
    "action": "opened",
    "installation_id": 123,
    "repository_id": 456
  }
]

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`400`	Bad Request
`422`	Validation failed

Get a webhook delivery for an organization webhook

Returns a delivery for a webhook configured in an organization.

get /orgs/{org}/hooks/{hook_id}/deliveries/{delivery_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
`delivery_id`	integer	path

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42/deliveries/42

JavaScript (@octokit/core.js)

 await octokit.request('GET /orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}', {
  org: 'org',
  hook_id: 42,
  delivery_id: 42
})

Response

 Status: 200 OK

 {
  "id": 12345678,
  "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
  "delivered_at": "2019-06-03T00:57:16Z",
  "redelivery": false,
  "duration": 0.27,
  "status": "OK",
  "status_code": 200,
  "event": "issues",
  "action": "opened",
  "installation_id": 123,
  "repository_id": 456,
  "url": "https://www.example.com",
  "request": {
    "headers": {
      "X-GitHub-Delivery": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
      "X-Hub-Signature-256": "sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "Accept": "*/*",
      "X-GitHub-Hook-ID": "42",
      "User-Agent": "GitHub-Hookshot/b8c71d8",
      "X-GitHub-Event": "issues",
      "X-GitHub-Hook-Installation-Target-ID": "123",
      "X-GitHub-Hook-Installation-Target-Type": "repository",
      "content-type": "application/json",
      "X-Hub-Signature": "sha1=a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d"
    },
    "payload": {
      "action": "opened",
      "issue": {
        "body": "foo"
      },
      "repository": {
        "id": 123
      }
    }
  },
  "response": {
    "headers": {
      "Content-Type": "text/html;charset=utf-8"
    },
    "payload": "ok"
  }
}

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`200`	OK
`400`	Bad Request
`422`	Validation failed

Redeliver a delivery for an organization webhook

Redeliver a delivery for a webhook configured in an organization.

post /orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`hook_id`	integer	path
`delivery_id`	integer	path

Code samples

Shell

 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/hooks/42/deliveries/42/attempts

JavaScript (@octokit/core.js)

 await octokit.request('POST /orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts', {
  org: 'org',
  hook_id: 42,
  delivery_id: 42
})

Accepted

 Status: 202 Accepted

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`202`	Accepted
`400`	Bad Request
`422`	Validation failed

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
})

Response

 Status: 204 No Content

Notes

Works with GitHub Apps

Status codes

HTTP Status Code	Description
`204`	No Content
`404`	Resource not found

Mar	APR	May
	09
2021	2022	2023

In this article

List organizations

Response

Not modified

Notes

Status codes

Get an organization

Default response

Notes

Status codes

Update an organization

Response

Notes

Status codes

Get the audit log for an organization

Response

Notes

Status codes

List SAML SSO authorizations for an organization

Response

Notes

Status codes

Remove a SAML SSO authorization for an organization

Response

Notes

Status codes

List app installations for an organization

Response

Notes

Status codes

List organizations for the authenticated user

Response

Not modified

Status codes

List organizations for a user

Response

Notes

Status codes

Blocking users

List users blocked by an organization

Response

Notes

Status codes

Check if a user is blocked by an organization

If the user is blocked:

Notes

Status codes

Block a user from an organization

Response

Notes

Status codes

Unblock a user from an organization

Response

Notes

Status codes

Custom repository roles

List custom repository roles in an organization

Response - list of custom role names

Notes

Status codes

Members

List failed organization invitations

Response

Notes

Status codes

List pending organization invitations

Response

Notes

Status codes

Create an organization invitation

Response

Notes

Status codes

Cancel an organization invitation

Response

Notes

Status codes

List organization invitation teams

Response