Octokit Rest API

Block a user from an organization

octokit.orgs.blockUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.cancelInvitation({
  org,
  invitation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

Check if a user is blocked by an organization

octokit.orgs.checkBlockedUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

Check organization membership for a user

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

octokit.orgs.checkMembershipForUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

Check public organization membership for a user

octokit.orgs.checkPublicMembershipForUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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

octokit.orgs.convertMemberToOutsideCollaborator({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.createInvitation({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Create an organization webhook

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

octokit.orgs.createWebhook({
        org,
name,
config,
config.url
      })

Parameters

See also: GitHub Developer Guide documentation.

Delete an organization webhook

octokit.orgs.deleteWebhook({
  org,
  hook_id,
});

Parameters

See also: GitHub Developer Guide documentation.

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

octokit.orgs.get({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Get an organization membership for the authenticated user

octokit.orgs.getMembershipForAuthenticatedUser({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.getMembershipForUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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

octokit.orgs.getWebhook({
  org,
  hook_id,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.getWebhookConfigForOrg({
  org,
  hook_id,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.list();

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listAppInstallations({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List users blocked by an organization

List the users blocked by an organization.

octokit.orgs.listBlockedUsers({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listFailedInvitations({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listForUser({
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listInvitationTeams({
  org,
  invitation_id,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listMembers({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List organization memberships for the authenticated user

octokit.orgs.listMembershipsForAuthenticatedUser();

Parameters

See also: GitHub Developer Guide documentation.

List outside collaborators for an organization

List all users who are outside collaborators of an organization.

octokit.orgs.listOutsideCollaborators({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.listPendingInvitations({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List public organization members

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

octokit.orgs.listPublicMembers({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

List organization webhooks

octokit.orgs.listWebhooks({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Ping an organization webhook

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

octokit.orgs.pingWebhook({
  org,
  hook_id,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.removeMember({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.removeMembershipForUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

Remove outside collaborator from an organization

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

octokit.orgs.removeOutsideCollaborator({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

Remove public organization membership for the authenticated user

octokit.orgs.removePublicMembershipForAuthenticatedUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.setMembershipForUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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

octokit.orgs.setPublicMembershipForAuthenticatedUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

Unblock a user from an organization

octokit.orgs.unblockUser({
  org,
  username,
});

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.update({
  org,
});

Parameters

See also: GitHub Developer Guide documentation.

Update an organization membership for the authenticated user

octokit.orgs.updateMembershipForAuthenticatedUser({
  org,
  state,
});

Parameters

See also: GitHub Developer Guide documentation.

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

octokit.orgs.updateWebhook({
        org,
hook_id,
config.url
      })

Parameters

See also: GitHub Developer Guide documentation.

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.

octokit.orgs.updateWebhookConfigForOrg({
  org,
  hook_id,
});

Parameters

See also: GitHub Developer Guide documentation.