Organisations

Download Spec

Interact with GitHub Orgs.

List organizations

get /organizations

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

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

since

int

An organization ID. Only return organizations with an ID greater than this ID.

per_page

int

The number of results per page (max 100).

Default
30

Response

Examples Schema

Response

[
  {
    "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

Empty response

array[object (Organization Simple)]

Organization Simple

object (Organization Simple)

A GitHub organization.

login

string

required

Example
"github"

id

int

required

Example
1

node_id

string

required

Example
"MDEyOk9yZ2FuaXphdGlvbjE="

url

string

uri

required

Example
"https://api.github.com/orgs/github"

repos_url

string

uri

required

Example
"https://api.github.com/orgs/github/repos"

events_url

string

uri

required

Example
"https://api.github.com/orgs/github/events"

hooks_url

string

required

Example
"https://api.github.com/orgs/github/hooks"

issues_url

string

required

Example
"https://api.github.com/orgs/github/issues"

members_url

string

required

Example
"https://api.github.com/orgs/github/members{/member}"

public_members_url

string

required

Example
"https://api.github.com/orgs/github/public_members{/member}"

avatar_url

string

required

Example
"https://github.com/images/error/octocat_happy.gif"

description

string or null

required

Example
"A great organization"

Link

string

No schema

Deprecated - List custom repository roles in an organization

get /organizations/{organization_id}/custom_roles

Note: This operation is deprecated and will be removed in the future. Use the "List custom repository roles" endpoint instead.

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.

To use this endpoint the authenticated user must be an administrator of the organization or of a repository of the organization and must use an access token with the admin:org or repo scope. GitHub Apps must have the organization_custom_roles:read or organization_administration:read organization permission to use this endpoint.

For more information on custom repository roles, see "About custom repository roles."

organization_id

string

required

The unique identifier of the organization.

Response

Examples Schema

Response - list of custom role names

{
  "id": 8030,
  "name": "Security Engineer",
  "description": "Able to contribute code and maintain the security pipeline",
  "base_role": "maintain",
  "permissions": [
    "delete_alerts_code_scanning"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:20:11Z"
}

total_count

int

The number of custom roles in this organization

Example
3

custom_roles

array[object (Organization Custom Repository Role)]

Organization Custom Repository Role

object (Organization Custom Repository Role)

Custom repository roles created by organization administrators

id

int

required

The unique identifier of the custom role.

name

string

required

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

required

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

required

A list of additional permissions included in this role.

string

organization

object (organization)

required

A GitHub user.

name

string or null

email

string or null

login

string

required

Example
"octocat"

id

int

required

Example
1

node_id

string

required

Example
"MDQ6VXNlcjE="

avatar_url

string

uri

required

Example
"https://github.com/images/error/octocat_happy.gif"

gravatar_id

string or null

required

Example
"41d064eb2195891e12d0413f63227ea7"

url

string

uri

required

Example
"https://api.github.com/users/octocat"

html_url

string

uri

required

Example
"https://github.com/octocat"

followers_url

string

uri

required

Example
"https://api.github.com/users/octocat/followers"

following_url

string

required

Example
"https://api.github.com/users/octocat/following{/other_user}"

gists_url

string

required

Example
"https://api.github.com/users/octocat/gists{/gist_id}"

starred_url

string

required

Example
"https://api.github.com/users/octocat/starred{/owner}{/repo}"

subscriptions_url

string

uri

required

Example
"https://api.github.com/users/octocat/subscriptions"

organizations_url

string

uri

required

Example
"https://api.github.com/users/octocat/orgs"

repos_url

string

uri

required

Example
"https://api.github.com/users/octocat/repos"

events_url

string

required

Example
"https://api.github.com/users/octocat/events{/privacy}"

received_events_url

string

uri

required

Example
"https://api.github.com/users/octocat/received_events"

type

string

required

Example
"User"

site_admin

boolean

required

starred_at

string

Example
"\"2020-07-09T00:17:55Z\""

created_at

string

date-time

required

updated_at

string

date-time

required

Get an organization

get /orgs/{org}

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 Enterprise Server plan. See "Authenticating with GitHub Apps" for details. For an example response, see 'Response with GitHub Enterprise Server plan information' below."

org

string

required

The organization name. The name is not case sensitive.

Response

Examples Schema

Response

{
  "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,
    "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_create_public_pages": true,
  "members_can_create_private_pages": true,
  "members_can_fork_private_repositories": false,
  "web_commit_signoff_required": false,
  "updated_at": "2014-03-03T18:58:10Z",
  "dependency_graph_enabled_for_new_repositories": false,
  "dependabot_alerts_enabled_for_new_repositories": false,
  "dependabot_security_updates_enabled_for_new_repositories": false,
  "advanced_security_enabled_for_new_repositories": false,
  "secret_scanning_enabled_for_new_repositories": false,
  "secret_scanning_push_protection_enabled_for_new_repositories": false,
  "secret_scanning_push_protection_custom_link": false,
  "secret_scanning_push_protection_custom_link_enabled": "https://github.com/octo-org/octo-repo/blob/main/im-blocked.md"
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

login

string

required

Example
"github"

id

int

required

Example
1

node_id

string

required

Example
"MDEyOk9yZ2FuaXphdGlvbjE="

url

string

uri

required

Example
"https://api.github.com/orgs/github"

repos_url

string

uri

required

Example
"https://api.github.com/orgs/github/repos"

events_url

string

uri

required

Example
"https://api.github.com/orgs/github/events"

hooks_url

string

required

Example
"https://api.github.com/orgs/github/hooks"

issues_url

string

required

Example
"https://api.github.com/orgs/github/issues"

members_url

string

required

Example
"https://api.github.com/orgs/github/members{/member}"

public_members_url

string

required

Example
"https://api.github.com/orgs/github/public_members{/member}"

avatar_url

string

required

Example
"https://github.com/images/error/octocat_happy.gif"

description

string or null

required

Example
"A great organization"

name

string

Example
"github"

company

string

Example
"GitHub"

blog

string

uri

Example
"https://github.com/blog"

location

string

Example
"San Francisco"

email

string

email

Example
"octocat@github.com"

twitter_username

string or null

Example
"github"

is_verified

boolean

Example
true

has_organization_projects

boolean

required

Example
true

has_repository_projects

boolean

required

Example
true

public_repos

int

required

Example
2

public_gists

int

required

Example
1

followers

int

required

Example
20

following

int

required

Example
0

html_url

string

uri

required

Example
"https://github.com/octocat"

created_at

string

date-time

required

Example
"2008-01-14T04:33:35Z"

type

string

required

Example
"Organization"

total_private_repos

int

Example
100

owned_private_repos

int

Example
100

private_gists

int or null

Example
81

disk_usage

int or null

Example
10000

collaborators

int or null

Example
8

billing_email

string or null

email

Example
"org@example.com"

plan

object (plan)

name

string

required

space

int

required

private_repos

int

required

filled_seats

int

seats

int

default_repository_permission

string or null

members_can_create_repositories

boolean or null

Example
true

two_factor_requirement_enabled

boolean or null

Example
true

members_allowed_repository_creation_type

string

Example
"all"

members_can_create_public_repositories

boolean

Example
true

members_can_create_private_repositories

boolean

Example
true

members_can_create_internal_repositories

boolean

Example
true

members_can_create_pages

boolean

Example
true

members_can_create_public_pages

boolean

Example
true

members_can_create_private_pages

boolean

Example
true

members_can_fork_private_repositories

boolean or null

Example
false

web_commit_signoff_required

boolean

Example
false

updated_at

string

date-time

required

advanced_security_enabled_for_new_repositories

boolean

Whether GitHub Advanced Security is enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

dependabot_alerts_enabled_for_new_repositories

boolean

Whether GitHub Advanced Security is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

dependabot_security_updates_enabled_for_new_repositories

boolean

Whether dependabot security updates are automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

dependency_graph_enabled_for_new_repositories

boolean

Whether dependency graph is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

secret_scanning_enabled_for_new_repositories

boolean

Whether secret scanning is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

secret_scanning_push_protection_enabled_for_new_repositories

boolean

Whether secret scanning push protection is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

secret_scanning_push_protection_custom_link_enabled

boolean

Whether a custom link is shown to contributors who are blocked from pushing a secret by push protection.

Example
false

secret_scanning_push_protection_custom_link

string or null

An optional URL string to display to contributors who are blocked from pushing a secret.

Example
"https://github.com/test-org/test-repo/blob/main/README.md"

message

string

documentation_url

string

url

string

status

string

Delete an organization

delete /orgs/{org}

Deletes an organization and all its repositories.

The organization login will be unavailable for 90 days after deletion.

Please review the Terms of Service regarding account deletion before using this endpoint:

https://docs.github.com/enterprise-server@3.9/site-policy/github-terms/github-terms-of-service

org

string

required

The organization name. The name is not case sensitive.

Response

Examples Schema

Accepted

null

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Forbidden

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

No schema

message

string

documentation_url

string

url

string

status

string

message

string

documentation_url

string

url

string

status

string

Update an organization

patch /orgs/{org}

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

org

string

required

The organization name. The name is not case sensitive.

billing_email

string

Billing email address. This address is not publicized.

company

string

The company name.

email

string

The publicly visible email address.

twitter_username

string

The Twitter username of the company.

location

string

The location.

name

string

The shorthand name of the company.

description

string

The description of the company.

has_organization_projects

boolean

Whether an organization can use organization projects.

has_repository_projects

boolean

Whether repositories that belong to the organization can use repository projects.

default_repository_permission

string

Default permission level members have for organization repositories.

Default
"read"
Enum
  • read
  • write
  • admin
  • none

members_can_create_repositories

boolean

Whether of non-admin organization members can create repositories. Note: A parameter can override this parameter. See members_allowed_repository_creation_type in this table for details.

Default
true

members_can_create_internal_repositories

boolean

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+. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation.

members_can_create_private_repositories

boolean

Whether organization members can create private repositories, which are visible to organization members with permission. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation.

members_can_create_public_repositories

boolean

Whether organization members can create public repositories, which are visible to anyone. For more information, see "Restricting repository creation in your organization" in the GitHub Help documentation.

members_allowed_repository_creation_type

string

Specifies which types of repositories non-admin organization members can create. 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.

Enum
  • all
  • private
  • none

members_can_create_pages

boolean

Whether organization members can create GitHub Pages sites. Existing published sites will not be impacted.

Default
true

members_can_fork_private_repositories

boolean

Whether organization members can fork private organization repositories.

Default
false

web_commit_signoff_required

boolean

Whether contributors to organization repositories are required to sign off on commits they make through GitHub's web interface.

Default
false

blog

string

Example
"\"http://github.blog\""

advanced_security_enabled_for_new_repositories

boolean

Whether GitHub Advanced Security is automatically enabled for new repositories.

To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."

You can check which security and analysis features are currently enabled by using a GET /orgs/{org} request.

dependabot_alerts_enabled_for_new_repositories

boolean

Whether Dependabot alerts is automatically enabled for new repositories.

To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."

You can check which security and analysis features are currently enabled by using a GET /orgs/{org} request.

dependabot_security_updates_enabled_for_new_repositories

boolean

Whether Dependabot security updates is automatically enabled for new repositories.

To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."

You can check which security and analysis features are currently enabled by using a GET /orgs/{org} request.

dependency_graph_enabled_for_new_repositories

boolean

Whether dependency graph is automatically enabled for new repositories.

To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."

You can check which security and analysis features are currently enabled by using a GET /orgs/{org} request.

secret_scanning_enabled_for_new_repositories

boolean

Whether secret scanning is automatically enabled for new repositories.

To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."

You can check which security and analysis features are currently enabled by using a GET /orgs/{org} request.

secret_scanning_push_protection_enabled_for_new_repositories

boolean

Whether secret scanning push protection is automatically enabled for new repositories.

To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "Managing security managers in your organization."

You can check which security and analysis features are currently enabled by using a GET /orgs/{org} request.

secret_scanning_push_protection_custom_link_enabled

boolean

Whether a custom link is shown to contributors who are blocked from pushing a secret by push protection.

secret_scanning_push_protection_custom_link

string

If secret_scanning_push_protection_custom_link_enabled is true, the URL that will be displayed to contributors who are blocked from pushing a secret.

Request

{
  "billing_email": "mona@github.com",
  "company": "GitHub",
  "email": "mona@github.com",
  "twitter_username": "github",
  "location": "San Francisco",
  "name": "github",
  "description": "GitHub, the company.",
  "default_repository_permission": "read",
  "members_can_create_repositories": true,
  "members_allowed_repository_creation_type": "all"
}

Response

Examples Schema

Response

{
  "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,
    "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_create_public_pages": true,
  "members_can_create_private_pages": true,
  "members_can_fork_private_repositories": false,
  "web_commit_signoff_required": false,
  "updated_at": "2014-03-03T18:58:10Z",
  "dependency_graph_enabled_for_new_repositories": false,
  "dependabot_alerts_enabled_for_new_repositories": false,
  "dependabot_security_updates_enabled_for_new_repositories": false,
  "advanced_security_enabled_for_new_repositories": false,
  "secret_scanning_enabled_for_new_repositories": false,
  "secret_scanning_push_protection_enabled_for_new_repositories": false,
  "secret_scanning_push_protection_custom_link": false,
  "secret_scanning_push_protection_custom_link_enabled": "https://github.com/octo-org/octo-repo/blob/main/im-blocked.md"
}

Validation failed

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Conflict

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

login

string

required

Example
"github"

id

int

required

Example
1

node_id

string

required

Example
"MDEyOk9yZ2FuaXphdGlvbjE="

url

string

uri

required

Example
"https://api.github.com/orgs/github"

repos_url

string

uri

required

Example
"https://api.github.com/orgs/github/repos"

events_url

string

uri

required

Example
"https://api.github.com/orgs/github/events"

hooks_url

string

required

Example
"https://api.github.com/orgs/github/hooks"

issues_url

string

required

Example
"https://api.github.com/orgs/github/issues"

members_url

string

required

Example
"https://api.github.com/orgs/github/members{/member}"

public_members_url

string

required

Example
"https://api.github.com/orgs/github/public_members{/member}"

avatar_url

string

required

Example
"https://github.com/images/error/octocat_happy.gif"

description

string or null

required

Example
"A great organization"

name

string

Example
"github"

company

string

Example
"GitHub"

blog

string

uri

Example
"https://github.com/blog"

location

string

Example
"San Francisco"

email

string

email

Example
"octocat@github.com"

twitter_username

string or null

Example
"github"

is_verified

boolean

Example
true

has_organization_projects

boolean

required

Example
true

has_repository_projects

boolean

required

Example
true

public_repos

int

required

Example
2

public_gists

int

required

Example
1

followers

int

required

Example
20

following

int

required

Example
0

html_url

string

uri

required

Example
"https://github.com/octocat"

created_at

string

date-time

required

Example
"2008-01-14T04:33:35Z"

type

string

required

Example
"Organization"

total_private_repos

int

Example
100

owned_private_repos

int

Example
100

private_gists

int or null

Example
81

disk_usage

int or null

Example
10000

collaborators

int or null

Example
8

billing_email

string or null

email

Example
"org@example.com"

plan

object (plan)

name

string

required

space

int

required

private_repos

int

required

filled_seats

int

seats

int

default_repository_permission

string or null

members_can_create_repositories

boolean or null

Example
true

two_factor_requirement_enabled

boolean or null

Example
true

members_allowed_repository_creation_type

string

Example
"all"

members_can_create_public_repositories

boolean

Example
true

members_can_create_private_repositories

boolean

Example
true

members_can_create_internal_repositories

boolean

Example
true

members_can_create_pages

boolean

Example
true

members_can_create_public_pages

boolean

Example
true

members_can_create_private_pages

boolean

Example
true

members_can_fork_private_repositories

boolean or null

Example
false

web_commit_signoff_required

boolean

Example
false

updated_at

string

date-time

required

advanced_security_enabled_for_new_repositories

boolean

Whether GitHub Advanced Security is enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

dependabot_alerts_enabled_for_new_repositories

boolean

Whether GitHub Advanced Security is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

dependabot_security_updates_enabled_for_new_repositories

boolean

Whether dependabot security updates are automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

dependency_graph_enabled_for_new_repositories

boolean

Whether dependency graph is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

secret_scanning_enabled_for_new_repositories

boolean

Whether secret scanning is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

secret_scanning_push_protection_enabled_for_new_repositories

boolean

Whether secret scanning push protection is automatically enabled for new repositories and repositories transferred to this organization.

This field is only visible to organization owners or members of a team with the security manager role.

Example
false

secret_scanning_push_protection_custom_link_enabled

boolean

Whether a custom link is shown to contributors who are blocked from pushing a secret by push protection.

Example
false

secret_scanning_push_protection_custom_link

string or null

An optional URL string to display to contributors who are blocked from pushing a secret.

Example
"https://github.com/test-org/test-repo/blob/main/README.md"

One Of

Validation Error

object (Validation Error)

Validation Error

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

Validation Error Simple

object (Validation Error Simple)

Validation Error Simple

message

string

required

documentation_url

string

required

errors

array[string]

string

message

string

documentation_url

string

url

string

status

string

Get announcement banner for organization

get /orgs/{org}/announcement

Gets the announcement banner currently set for the organization. Only returns the announcement banner set at the organization level. Organization members may also see an enterprise-level announcement banner. To get an announcement banner displayed at the enterprise level, use the enterprise-level endpoint.

org

string

required

The organization name. The name is not case sensitive.

Response

Examples Schema

Response

{
  "announcement": "Very **important** announcement about _something_.",
  "expires_at": "2021-01-01T00:00:00.000+00:00",
  "user_dismissible": false
}

announcement

string or null

required

The announcement text in GitHub Flavored Markdown. For more information about GitHub Flavored Markdown, see "Basic writing and formatting syntax."

Example
"Very **important** announcement about _something_."

expires_at

string or null

date-time

required

The time at which the announcement expires. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. To set an announcement that never expires, omit this parameter, set it to null, or set it to an empty string.

Example
"\"2021-01-01T00:00:00.000-07:00\""

user_dismissible

boolean or null

required

Whether an announcement can be dismissed by the user.

Default
false
Example
false

Remove announcement banner from organization

delete /orgs/{org}/announcement

Removes the announcement banner currently set for the organization.

org

string

required

The organization name. The name is not case sensitive.

Response

Examples Schema

Response

Empty response

No schema

Set announcement banner for organization

patch /orgs/{org}/announcement

Sets the announcement banner to display for the organization.

org

string

required

The organization name. The name is not case sensitive.

announcement

string or null

required

The announcement text in GitHub Flavored Markdown. For more information about GitHub Flavored Markdown, see "Basic writing and formatting syntax."

Example
"Very **important** announcement about _something_."

expires_at

string or null

date-time

The time at which the announcement expires. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. To set an announcement that never expires, omit this parameter, set it to null, or set it to an empty string.

Example
"\"2021-01-01T00:00:00.000-07:00\""

Request

{
  "announcement": "Very **important** announcement about _something_.",
  "expires_at": "2021-01-01T00:00:00.000+00:00",
  "user_dismissible": false
}

Response

Examples Schema

Response

{
  "announcement": "Very **important** announcement about _something_.",
  "expires_at": "2021-01-01T00:00:00.000+00:00",
  "user_dismissible": false
}

announcement

string or null

required

The announcement text in GitHub Flavored Markdown. For more information about GitHub Flavored Markdown, see "Basic writing and formatting syntax."

Example
"Very **important** announcement about _something_."

expires_at

string or null

date-time

required

The time at which the announcement expires. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. To set an announcement that never expires, omit this parameter, set it to null, or set it to an empty string.

Example
"\"2021-01-01T00:00:00.000-07:00\""

user_dismissible

boolean or null

required

Whether an announcement can be dismissed by the user.

Default
false
Example
false

Get the audit log for an organization

get /orgs/{org}/audit-log

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

To use this endpoint, you must be an organization owner, and you must use an access token with the read:audit_log 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."

org

string

required

The organization name. The name is not case sensitive.

phrase

string

A search phrase. For more information, see Searching the audit log.

include

string

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.

Enum
  • web
  • git
  • all

after

string

A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.

before

string

A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.

order

string

The order of audit log events. To list newest events first, specify desc. To list oldest events first, specify asc.

The default is desc.

Enum
  • desc
  • asc

per_page

int

The number of results per page (max 100).

Default
30

page

int

Page number of the results to fetch.

Default
1

Response

Examples Schema

Response

[
  {
    "actor_ip": "88.123.45.123",
    "from": "pull_requests#merge",
    "device_cookie": null,
    "actor": "mona-admin",
    "actor_id": 7,
    "repo": "octo-org/octo-repo",
    "repo_id": 17,
    "business": "github",
    "business_id": 1,
    "org": "octo-org",
    "org_id": 8,
    "action": "pull_request.merge",
    "@timestamp": 1635940599755,
    "created_at": 1635940599755,
    "operation_type": "modify",
    "actor_location": {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "region": "ENG",
      "region_name": "England",
      "city": "Louth",
      "postal_code": "LN11",
      "location": {
        "lat": 53.4457,
        "lon": 0.141
      }
    },
    "data": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "method": "POST",
      "request_id": "e4dabc4d-ba16-4bca-1234-649be7ae1188",
      "server_id": "5d17aab5-fd9f-abcd-a820-16bed246441b",
      "request_category": "other",
      "controller_action": "merge",
      "url": "https://example.com/octo-org/octo-repo/pull/1/merge",
      "client_id": 322299977.1635936,
      "referrer": "https://example.com/octo-org/octo-repo/pull/1",
      "actor_session": 1,
      "pull_request_id": 1,
      "category_type": "Resource Management"
    }
  },
  {
    "actor_ip": "88.123.45.123",
    "from": "pull_request_review_events#create",
    "device_cookie": null,
    "actor": "mona-admin",
    "actor_id": 7,
    "business_id": 1,
    "org_id": 8,
    "action": "pull_request_review.submit",
    "@timestamp": 1635940593079,
    "created_at": 1635940593079,
    "operation_type": "modify",
    "actor_location": {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "region": "ENG",
      "region_name": "England",
      "city": "Louth",
      "postal_code": "LN11",
      "location": {
        "lat": 53.4457,
        "lon": 0.141
      }
    },
    "data": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "method": "PUT",
      "request_id": "c0f63bb7-17b6-4796-940c-12345c5a581b",
      "server_id": "2abc1234-f651-43e3-9696-e942ad5f8c89",
      "request_category": "other",
      "controller_action": "create",
      "url": "https://example.com/octo-org/octo-repo/pull/1/reviews",
      "client_id": 322299977.1635936,
      "referrer": "https://example.com/octo-org/octo-repo/pull/1/files",
      "actor_session": 1,
      "spammy": false,
      "pull_request_id": 1,
      "body": null,
      "allowed": true,
      "id": 1,
      "state": 40,
      "issue_id": 1,
      "review_id": 1,
      "category_type": "Resource Management"
    }
  },
  {
    "actor_ip": "88.123.45.123",
    "from": "pull_requests#create",
    "device_cookie": null,
    "actor": "mona",
    "actor_id": 9,
    "user_id": 9,
    "repo": "octo-org/octo-repo",
    "repo_id": 17,
    "business": "github",
    "business_id": 1,
    "org": "octo-org",
    "org_id": 8,
    "action": "pull_request.create",
    "@timestamp": 1635940554161,
    "created_at": 1635940554161,
    "operation_type": "create",
    "actor_location": {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "region": "ENG",
      "region_name": "England",
      "city": "Louth",
      "postal_code": "LN11",
      "location": {
        "lat": 53.4457,
        "lon": 0.141
      }
    },
    "data": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "method": "POST",
      "request_id": "2773abeb-477f-4ebf-a017-f8e8a206c305",
      "server_id": "796e3115-4ce8-4606-8fd0-99ea57a2e12b",
      "request_category": "other",
      "controller_action": "create",
      "url": "https://example.com/octo-org/octo-repo/pull/create?base=octo-org%3Amain&head=mona%3Apatch-1",
      "client_id": 386351111.163594,
      "referrer": "https://example.com/octo-org/octo-repo/compare/main...mona:patch-1",
      "actor_session": 2,
      "pull_request_id": 1,
      "category_type": "Resource Management"
    }
  }
]

array[object]

object

@timestamp

int

The time the audit log event occurred, given as a Unix timestamp.

action

string

The name of the action that was performed, for example user.login or repo.create.

active

boolean

active_was

boolean

actor

string

The actor who performed the action.

actor_id

int

The id of the actor who performed the action.

actor_location

object (actor_location)

country_name

string

data

object (data)

org_id

int

user_id

int

business_id

int

blocked_user

string

The username of the account being blocked.

business

string

config

array[object]

object

config_was

array[object]

object

content_type

string

operation_type

string

created_at

int

The time the audit log event was recorded, given as a Unix timestamp.

deploy_key_fingerprint

string

_document_id

string

A unique identifier for an audit event.

emoji

string

events

array[object]

object

events_were

array[object]

object

explanation

string

fingerprint

string

hook_id

int

limited_availability

boolean

message

string

name

string

old_user

string

openssh_public_key

string

org

string

previous_visibility

string

read_only

boolean

repo

string

The name of the repository.

repository

string

The name of the repository.

repository_public

boolean

target_login

string

team

string

transport_protocol

int

The type of protocol (for example, HTTP or SSH) used to transfer Git data.

transport_protocol_name

string

A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data.

user

string

The user that was affected by the action performed (if available).

visibility

string

The repository visibility, for example public or private.

List custom repository roles in an organization

get /orgs/{org}/custom-repository-roles

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.

To use this endpoint the authenticated user must be an administrator of the organization or of a repository of the organization and must use an access token with the admin:org or repo scope. GitHub Apps must have the organization_custom_roles:read or organization_administration:read organization permission to use this endpoint.

For more information on custom repository roles, see "About custom repository roles."

org

string

required

The organization name. The name is not case sensitive.

Response

Examples Schema

Response - list of custom role names

{
  "total_count": 2,
  "custom_roles": [
    {
      "id": 8030,
      "name": "Security Engineer",
      "description": "Able to contribute code and maintain the security pipeline",
      "base_role": "maintain",
      "permissions": [
        "delete_alerts_code_scanning"
      ],
      "organization": {
        "login": "github",
        "id": 9919,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
        "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/github",
        "html_url": "https://github.com/github",
        "followers_url": "https://api.github.com/users/github/followers",
        "following_url": "https://api.github.com/users/github/following{/other_user}",
        "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/github/subscriptions",
        "organizations_url": "https://api.github.com/users/github/orgs",
        "repos_url": "https://api.github.com/users/github/repos",
        "events_url": "https://api.github.com/users/github/events{/privacy}",
        "received_events_url": "https://api.github.com/users/github/received_events",
        "type": "Organization",
        "site_admin": false
      },
      "created_at": "2022-07-04T22:19:11Z",
      "updated_at": "2022-07-04T22:20:11Z"
    },
    {
      "id": 8031,
      "name": "Community manager",
      "description": "Able to handle all the community interactions without being able to contribute code",
      "base_role": "read",
      "permissions": [
        "mark_as_duplicate",
        "manage_settings_pages",
        "manage_settings_wiki",
        "set_social_preview",
        "edit_repo_metadata",
        "toggle_discussion_comment_minimize"
      ],
      "organization": {
        "login": "github",
        "id": 9919,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
        "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/github",
        "html_url": "https://github.com/github",
        "followers_url": "https://api.github.com/users/github/followers",
        "following_url": "https://api.github.com/users/github/following{/other_user}",
        "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/github/subscriptions",
        "organizations_url": "https://api.github.com/users/github/orgs",
        "repos_url": "https://api.github.com/users/github/repos",
        "events_url": "https://api.github.com/users/github/events{/privacy}",
        "received_events_url": "https://api.github.com/users/github/received_events",
        "type": "Organization",
        "site_admin": false
      },
      "created_at": "2022-07-05T12:01:11Z",
      "updated_at": "2022-07-05T12:20:11Z"
    }
  ]
}

total_count

int

The number of custom roles in this organization

Example
3

custom_roles

array[object (Organization Custom Repository Role)]

Organization Custom Repository Role

object (Organization Custom Repository Role)

Custom repository roles created by organization administrators

id

int

required

The unique identifier of the custom role.

name

string

required

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

required

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

required

A list of additional permissions included in this role.

string

organization

object (organization)

required

A GitHub user.

name

string or null

email

string or null

login

string

required

Example
"octocat"

id

int

required

Example
1

node_id

string

required

Example
"MDQ6VXNlcjE="

avatar_url

string

uri

required

Example
"https://github.com/images/error/octocat_happy.gif"

gravatar_id

string or null

required

Example
"41d064eb2195891e12d0413f63227ea7"

url

string

uri

required

Example
"https://api.github.com/users/octocat"

html_url

string

uri

required

Example
"https://github.com/octocat"

followers_url

string

uri

required

Example
"https://api.github.com/users/octocat/followers"

following_url

string

required

Example
"https://api.github.com/users/octocat/following{/other_user}"

gists_url

string

required

Example
"https://api.github.com/users/octocat/gists{/gist_id}"

starred_url

string

required

Example
"https://api.github.com/users/octocat/starred{/owner}{/repo}"

subscriptions_url

string

uri

required

Example
"https://api.github.com/users/octocat/subscriptions"

organizations_url

string

uri

required

Example
"https://api.github.com/users/octocat/orgs"

repos_url

string

uri

required

Example
"https://api.github.com/users/octocat/repos"

events_url

string

required

Example
"https://api.github.com/users/octocat/events{/privacy}"

received_events_url

string

uri

required

Example
"https://api.github.com/users/octocat/received_events"

type

string

required

Example
"User"

site_admin

boolean

required

starred_at

string

Example
"\"2020-07-09T00:17:55Z\""

created_at

string

date-time

required

updated_at

string

date-time

required

Create a custom repository role

post /orgs/{org}/custom-repository-roles

Creates a custom repository role that can be used by all repositories owned by the organization.

To use this endpoint, the authenticated user must be an administrator for the organization and must use an personal access token (classic) with admin:org scope or a fine-grained personal access token with the organization_custom_roles:write organization permission.

For more information on custom repository roles, see "About custom repository roles."

org

string

required

The organization name. The name is not case sensitive.

name

string

required

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

required

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

required

A list of additional permissions included in this role.

string

Request

{
  "name": "Labeler",
  "description": "A role for issue and pull request labelers",
  "base_role": "read",
  "permissions": [
    "add_label"
  ]
}

Response

Examples Schema

Response

{
  "id": 8030,
  "name": "Security Engineer",
  "description": "Able to contribute code and maintain the security pipeline",
  "base_role": "maintain",
  "permissions": [
    "delete_alerts_code_scanning"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:20:11Z"
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

id

int

required

The unique identifier of the custom role.

name

string

required

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

required

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

required

A list of additional permissions included in this role.

string

organization

object (organization)

required

A GitHub user.

name

string or null

email

string or null

login

string

required

Example
"octocat"

id

int

required

Example
1

node_id

string

required

Example
"MDQ6VXNlcjE="

avatar_url

string

uri

required

Example
"https://github.com/images/error/octocat_happy.gif"

gravatar_id

string or null

required

Example
"41d064eb2195891e12d0413f63227ea7"

url

string

uri

required

Example
"https://api.github.com/users/octocat"

html_url

string

uri

required

Example
"https://github.com/octocat"

followers_url

string

uri

required

Example
"https://api.github.com/users/octocat/followers"

following_url

string

required

Example
"https://api.github.com/users/octocat/following{/other_user}"

gists_url

string

required

Example
"https://api.github.com/users/octocat/gists{/gist_id}"

starred_url

string

required

Example
"https://api.github.com/users/octocat/starred{/owner}{/repo}"

subscriptions_url

string

uri

required

Example
"https://api.github.com/users/octocat/subscriptions"

organizations_url

string

uri

required

Example
"https://api.github.com/users/octocat/orgs"

repos_url

string

uri

required

Example
"https://api.github.com/users/octocat/repos"

events_url

string

required

Example
"https://api.github.com/users/octocat/events{/privacy}"

received_events_url

string

uri

required

Example
"https://api.github.com/users/octocat/received_events"

type

string

required

Example
"User"

site_admin

boolean

required

starred_at

string

Example
"\"2020-07-09T00:17:55Z\""

created_at

string

date-time

required

updated_at

string

date-time

required

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

message

string

documentation_url

string

url

string

status

string

Get a custom repository role

get /orgs/{org}/custom-repository-roles/{role_id}

Gets a custom repository role that is available to all repositories owned by the organization.

To use this endpoint the authenticated user must be an administrator of the organization or of a repository of the organization and must use an access token with the admin:org or repo scope. GitHub Apps must have the organization_custom_roles:read or organization_administration:read organization permission to use this endpoint.

For more information on custom repository roles, see "About custom repository roles."

org

string

required

The organization name. The name is not case sensitive.

role_id

int

required

The unique identifier of the role.

Response

Examples Schema

Response

{
  "id": 8030,
  "name": "Security Engineer",
  "description": "Able to contribute code and maintain the security pipeline",
  "base_role": "maintain",
  "permissions": [
    "delete_alerts_code_scanning"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:20:11Z"
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

id

int

required

The unique identifier of the custom role.

name

string

required

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

required

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

required

A list of additional permissions included in this role.

string

organization

object (organization)

required

A GitHub user.

name

string or null

email

string or null

login

string

required

Example
"octocat"

id

int

required

Example
1

node_id

string

required

Example
"MDQ6VXNlcjE="

avatar_url

string

uri

required

Example
"https://github.com/images/error/octocat_happy.gif"

gravatar_id

string or null

required

Example
"41d064eb2195891e12d0413f63227ea7"

url

string

uri

required

Example
"https://api.github.com/users/octocat"

html_url

string

uri

required

Example
"https://github.com/octocat"

followers_url

string

uri

required

Example
"https://api.github.com/users/octocat/followers"

following_url

string

required

Example
"https://api.github.com/users/octocat/following{/other_user}"

gists_url

string

required

Example
"https://api.github.com/users/octocat/gists{/gist_id}"

starred_url

string

required

Example
"https://api.github.com/users/octocat/starred{/owner}{/repo}"

subscriptions_url

string

uri

required

Example
"https://api.github.com/users/octocat/subscriptions"

organizations_url

string

uri

required

Example
"https://api.github.com/users/octocat/orgs"

repos_url

string

uri

required

Example
"https://api.github.com/users/octocat/repos"

events_url

string

required

Example
"https://api.github.com/users/octocat/events{/privacy}"

received_events_url

string

uri

required

Example
"https://api.github.com/users/octocat/received_events"

type

string

required

Example
"User"

site_admin

boolean

required

starred_at

string

Example
"\"2020-07-09T00:17:55Z\""

created_at

string

date-time

required

updated_at

string

date-time

required

message

string

documentation_url

string

url

string

status

string

Delete a custom repository role

delete /orgs/{org}/custom-repository-roles/{role_id}

Deletes a custom role from an organization. Once the custom role has been deleted, any user, team, or invitation with the deleted custom role will be reassigned the inherited role.

To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with admin:org scope. GitHub Apps must have the organization_custom_roles:write organization permission to use this endpoint.

For more information about custom repository roles, see "About custom repository roles."

org

string

required

The organization name. The name is not case sensitive.

role_id

int

required

The unique identifier of the role.

Response

Examples Schema

Response

Empty response

No schema

Update a custom repository role

patch /orgs/{org}/custom-repository-roles/{role_id}

Updates a custom repository role that can be used by all repositories owned by the organization.

To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with admin:org scope. GitHub Apps must have the organization_custom_roles:write organization permission to use this endpoint.

For more information about custom repository roles, see "About custom repository roles."

org

string

required

The organization name. The name is not case sensitive.

role_id

int

required

The unique identifier of the role.

name

string

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

A list of additional permissions included in this role.

string

Request

{
  "name": "Labeler",
  "description": "A role for issue and PR labelers",
  "base_role": "read",
  "permissions": [
    "add_label",
    "remove_label"
  ]
}

Response

Examples Schema

Response

{
  "id": 8030,
  "name": "Security Engineer",
  "description": "Able to contribute code and maintain the security pipeline",
  "base_role": "maintain",
  "permissions": [
    "delete_alerts_code_scanning"
  ],
  "organization": {
    "login": "github",
    "id": 9919,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
    "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/github",
    "html_url": "https://github.com/github",
    "followers_url": "https://api.github.com/users/github/followers",
    "following_url": "https://api.github.com/users/github/following{/other_user}",
    "gists_url": "https://api.github.com/users/github/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/github/subscriptions",
    "organizations_url": "https://api.github.com/users/github/orgs",
    "repos_url": "https://api.github.com/users/github/repos",
    "events_url": "https://api.github.com/users/github/events{/privacy}",
    "received_events_url": "https://api.github.com/users/github/received_events",
    "type": "Organization",
    "site_admin": false
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:20:11Z"
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

id

int

required

The unique identifier of the custom role.

name

string

required

The name of the custom role.

description

string or null

A short description about who this role is for or what permissions it grants.

base_role

string

required

The system role from which this role inherits permissions.

Enum
  • read
  • triage
  • write
  • maintain

permissions

array[string]

required

A list of additional permissions included in this role.

string

organization

object (organization)

required

A GitHub user.

name

string or null

email

string or null

login

string

required

Example
"octocat"

id

int

required

Example
1

node_id

string

required

Example
"MDQ6VXNlcjE="

avatar_url

string

uri

required

Example
"https://github.com/images/error/octocat_happy.gif"

gravatar_id

string or null

required

Example
"41d064eb2195891e12d0413f63227ea7"

url

string

uri

required

Example
"https://api.github.com/users/octocat"

html_url

string

uri

required

Example
"https://github.com/octocat"

followers_url

string

uri

required

Example
"https://api.github.com/users/octocat/followers"

following_url

string

required

Example
"https://api.github.com/users/octocat/following{/other_user}"

gists_url

string

required

Example
"https://api.github.com/users/octocat/gists{/gist_id}"

starred_url

string

required

Example
"https://api.github.com/users/octocat/starred{/owner}{/repo}"

subscriptions_url

string

uri

required

Example
"https://api.github.com/users/octocat/subscriptions"

organizations_url

string

uri

required

Example
"https://api.github.com/users/octocat/orgs"

repos_url

string

uri

required

Example
"https://api.github.com/users/octocat/repos"

events_url

string

required

Example
"https://api.github.com/users/octocat/events{/privacy}"

received_events_url

string

uri

required

Example
"https://api.github.com/users/octocat/received_events"

type

string

required

Example
"User"

site_admin

boolean

required

starred_at

string

Example
"\"2020-07-09T00:17:55Z\""

created_at

string

date-time

required

updated_at

string

date-time

required

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

message

string

documentation_url

string

url

string

status

string

List organization webhooks

get /orgs/{org}/hooks

org

string

required

The organization name. The name is not case sensitive.

per_page

int

The number of results per page (max 100).

Default
30

page

int

Page number of the results to fetch.

Default
1

Response

Examples Schema

Response

[
  {
    "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"
  }
]

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

array[object (Org Hook)]

Org Hook

object (Org Hook)

Org Hook

id

int

required

Example
1

url

string

uri

required

Example
"https://api.github.com/orgs/octocat/hooks/1"

ping_url

string

uri

required

Example
"https://api.github.com/orgs/octocat/hooks/1/pings"

deliveries_url

string

uri

Example
"https://api.github.com/orgs/octocat/hooks/1/deliveries"

name

string

required

Example
"web"

events

array[string]

required

Example
[ "push", "pull_request" ]

string

active

boolean

required

Example
true

config

object (config)

required

url

string

Example
"\"http://example.com/2\""

insecure_ssl

string

Example
"\"0\""

content_type

string

Example
"\"form\""

secret

string

Example
"\"********\""

updated_at

string

date-time

required

Example
"2011-09-06T20:39:23Z"

created_at

string

date-time

required

Example
"2011-09-06T17:26:27Z"

type

string

required

Link

string

message

string

documentation_url

string

url

string

status

string

Create an organization webhook

post /orgs/{org}/hooks

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

org

string

required

The organization name. The name is not case sensitive.

name

string

required

Must be passed as "web".

config

object (config)

required

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

url

string

uri

required

The URL to which the payloads will be delivered.

Example
"https://example.com/webhook"

content_type

string

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

Example
"\"json\""

secret

string

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

Example
"\"********\""

insecure_ssl

One Of

string

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

Example
"\"0\""

number

username

string

Example
"\"kdaigle\""

password

string

Example
"\"password\""

events

array[string]

Determines what events the hook is triggered for. Set to ["*"] to receive all possible events.

Default
["push"]

string

active

boolean

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

Default
true

Request

{
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook",
    "content_type": "json"
  }
}

Response

Examples Schema

Response

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

Validation failed, or the endpoint has been spammed.

{
  "message": "string",