GitHub Enterprise administration

Get statistics

There are a variety of types to choose from:

These statistics are cached and will be updated approximately every 10 minutes.

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprise/stats/TYPE

JavaScript (@octokit/core.js)

await octokit.request('GET /enterprise/stats/{type}', {
  type: 'type'
})

Default response

Status: 200 OK

{
  "repos": {
    "total_repos": 212,
    "root_repos": 194,
    "fork_repos": 18,
    "org_repos": 51,
    "total_pushes": 3082,
    "total_wikis": 15
  },
  "hooks": {
    "total_hooks": 27,
    "active_hooks": 23,
    "inactive_hooks": 4
  },
  "pages": {
    "total_pages": 36
  },
  "orgs": {
    "total_orgs": 33,
    "disabled_orgs": 0,
    "total_teams": 60,
    "total_team_members": 314
  },
  "users": {
    "total_users": 254,
    "admin_users": 45,
    "suspended_users": 21
  },
  "pulls": {
    "total_pulls": 86,
    "merged_pulls": 60,
    "mergeable_pulls": 21,
    "unmergeable_pulls": 3
  },
  "issues": {
    "total_issues": 179,
    "open_issues": 83,
    "closed_issues": 96
  },
  "milestones": {
    "total_milestones": 7,
    "open_milestones": 6,
    "closed_milestones": 1
  },
  "gists": {
    "total_gists": 178,
    "private_gists": 151,
    "public_gists": 25
  },
  "comments": {
    "total_commit_comments": 6,
    "total_gist_comments": 28,
    "total_issue_comments": 366,
    "total_pull_request_comments": 30
  }
}

List global webhooks

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  https://api.github.com/admin/hooks

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/hooks', {
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 200 OK

[
  {
    "type": "Global",
    "id": 1,
    "name": "web",
    "active": true,
    "events": [
      "organization",
      "user"
    ],
    "config": {
      "url": "https://example.com",
      "content_type": "json",
      "insecure_ssl": "0",
      "secret": "********"
    },
    "updated_at": "2017-12-07T00:14:59Z",
    "created_at": "2017-12-07T00:14:59Z",
    "url": "https://api.github.com/admin/hooks/1",
    "ping_url": "https://api.github.com/admin/hooks/1/pings"
  }
]

Preview notice

application/vnd.github.superpro-preview+json

Create a global webhook

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  https://api.github.com/admin/hooks \
  -d '{"name":"name","config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/hooks', {
  name: 'name',
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 201 Created

{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Preview notice

application/vnd.github.superpro-preview+json

Get a global webhook

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  https://api.github.com/admin/hooks/42

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 200 OK

{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Preview notice

application/vnd.github.superpro-preview+json

Update a global webhook

Parameters that are not provided will be overwritten with the default value or removed if no default exists.

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  https://api.github.com/admin/hooks/42 \
  -d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/hooks/{hook_id}', {
  hook_id: 42,
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default response

Status: 200 OK

{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "form",
    "insecure_ssl": "0"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Preview notice

application/vnd.github.superpro-preview+json

Delete a global webhook

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  https://api.github.com/admin/hooks/42

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default Response

Status: 204 No Content

Preview notice

application/vnd.github.superpro-preview+json

Ping a global webhook

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

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  https://api.github.com/admin/hooks/42/pings

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/hooks/{hook_id}/pings', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Default Response

Status: 204 No Content

Preview notice

application/vnd.github.superpro-preview+json

Update LDAP mapping for a team

Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.

If you pass the hellcat-preview media type, you can also update the LDAP mapping of a child team.

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/ldap/teams/42/mapping \
  -d '{"ldap_dn":"ldap_dn"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/ldap/teams/{team_id}/mapping', {
  team_id: 42,
  ldap_dn: 'ldap_dn'
})

Default response

Status: 200 OK

{
  "ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com",
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://api.github.com/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "parent": null
}

Preview notice

application/vnd.github.hellcat-preview+json

Sync LDAP mapping for a team

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/ldap/teams/42/sync

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/ldap/teams/{team_id}/sync', {
  team_id: 42
})

Response

Status: 201 Created

{
  "status": "queued"
}

Update LDAP mapping for a user

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/ldap/users/USERNAME/mapping \
  -d '{"ldap_dn":"ldap_dn"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/ldap/users/{username}/mapping', {
  username: 'username',
  ldap_dn: 'ldap_dn'
})

Default response

Status: 200 OK

{
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com",
  "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
}

Sync LDAP mapping for a user

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/ldap/users/USERNAME/sync

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/ldap/users/{username}/sync', {
  username: 'username'
})

Response

Status: 201 Created

{
  "status": "queued"
}

Get license information

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprise/settings/license

JavaScript (@octokit/core.js)

await octokit.request('GET /enterprise/settings/license')

Default response

Status: 200 OK

{
  "seats": 1400,
  "seats_used": 1316,
  "seats_available": 84,
  "kind": "standard",
  "days_until_expiration": 365,
  "expire_at": "2016/02/06 12:41:52 -0600"
}

Get the configuration status

This endpoint allows you to check the status of the most recent configuration process:

Note that you may need to wait several seconds after you start a process before you can check its status.

The different statuses are:

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/configcheck

JavaScript (@octokit/core.js)

await octokit.request('GET /setup/api/configcheck')

Default response

Status: 200 OK

{
  "status": "running",
  "progress": [
    {
      "status": "DONE",
      "key": "Appliance core components"
    },
    {
      "status": "DONE",
      "key": "GitHub utilities"
    },
    {
      "status": "DONE",
      "key": "GitHub applications"
    },
    {
      "status": "CONFIGURING",
      "key": "GitHub services"
    },
    {
      "status": "PENDING",
      "key": "Reloading appliance services"
    }
  ]
}

Start a configuration process

This endpoint allows you to start a configuration process at any time for your updated settings to take effect:

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/configure

JavaScript (@octokit/core.js)

await octokit.request('POST /setup/api/configure')

Response

Status: 202 Accepted

Get the maintenance status

Check your installation's maintenance status:

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/maintenance

JavaScript (@octokit/core.js)

await octokit.request('GET /setup/api/maintenance')

Default response

Status: 200 OK

{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15 => 34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Enable or disable maintenance mode

The possible values for enabled are true and false. When it's false, the attribute when is ignored and the maintenance mode is turned off. when defines the time period when the maintenance was enabled.

The possible values for when are now or any date parseable by mojombo/chronic.

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/maintenance \
  -d '{"maintenance":"maintenance"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /setup/api/maintenance', {
  maintenance: 'maintenance'
})

Default response

Status: 200 OK

{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15 => 34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Get settings

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/settings

JavaScript (@octokit/core.js)

await octokit.request('GET /setup/api/settings')

Default response

Status: 200 OK

{
  "enterprise": {
    "private_mode": false,
    "public_pages": false,
    "subdomain_isolation": true,
    "signup_enabled": false,
    "github_hostname": "ghe.local",
    "identicons_host": "dotcom",
    "http_proxy": null,
    "auth_mode": "default",
    "expire_sessions": false,
    "admin_password": null,
    "configuration_id": 1401777404,
    "configuration_run_count": 4,
    "avatar": {
      "enabled": false,
      "uri": ""
    },
    "customer": {
      "name": "GitHub",
      "email": "stannis@themannis.biz",
      "uuid": "af6cac80-e4e1-012e-d822-1231380e52e9",
      "secret_key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
      "public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nmI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....\n-----END PGP PUBLIC KEY BLOCK-----\n"
    },
    "license": {
      "seats": 0,
      "evaluation": false,
      "perpetual": false,
      "unlimited_seating": true,
      "support_key": "ssh-rsa AAAAB3N....",
      "ssh_allowed": true,
      "cluster_support": false,
      "expire_at": "2016-04-27T00:00:00-07:00"
    },
    "github_ssl": {
      "enabled": false,
      "cert": null,
      "key": null
    },
    "ldap": {
      "host": null,
      "port": 0,
      "base": [],
      "uid": null,
      "bind_dn": null,
      "password": null,
      "method": "Plain",
      "search_strategy": "detect",
      "user_groups": [],
      "admin_group": null,
      "virtual_attribute_enabled": false,
      "recursive_group_search": false,
      "posix_support": true,
      "user_sync_emails": false,
      "user_sync_keys": false,
      "user_sync_interval": 4,
      "team_sync_interval": 4,
      "sync_enabled": false,
      "reconciliation": {
        "user": null,
        "org": null
      },
      "profile": {
        "uid": "uid",
        "name": null,
        "mail": null,
        "key": null
      }
    },
    "cas": {
      "url": null
    },
    "saml": {
      "sso_url": null,
      "certificate": null,
      "certificate_path": null,
      "issuer": null,
      "idp_initiated_sso": false,
      "disable_admin_demote": false
    },
    "github_oauth": {
      "client_id": "12313412",
      "client_secret": "kj123131132",
      "organization_name": "Homestar Runners",
      "organization_team": "homestarrunners/characters"
    },
    "smtp": {
      "enabled": true,
      "address": "smtp.example.com",
      "authentication": "plain",
      "port": "1234",
      "domain": "blah",
      "username": "foo",
      "user_name": "mr_foo",
      "enable_starttls_auto": true,
      "password": "bar",
      "discard-to-noreply-address": true,
      "support_address": "enterprise@github.com",
      "support_address_type": "email",
      "noreply_address": "noreply@github.com"
    },
    "ntp": {
      "primary_server": "0.pool.ntp.org",
      "secondary_server": "1.pool.ntp.org"
    },
    "timezone": null,
    "snmp": {
      "enabled": false,
      "community": ""
    },
    "syslog": {
      "enabled": false,
      "server": null,
      "protocol_name": "udp"
    },
    "assets": null,
    "pages": {
      "enabled": true
    },
    "collectd": {
      "enabled": false,
      "server": null,
      "port": 0,
      "encryption": null,
      "username": null,
      "password": null
    },
    "mapping": {
      "enabled": true,
      "tileserver": null,
      "basemap": "company.map-qsz2zrvs",
      "token": null
    },
    "load_balancer": null
  },
  "run_list": [
    "recipe[enterprise-configure]"
  ]
}

Set settings

For a list of the available settings, see the Get settings endpoint.

Parameters

Code samples

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/settings \
  -d '{"settings":"settings"}'

JavaScript (@octokit/core.js)

await octokit.request('PUT /setup/api/settings', {
  settings: 'settings'
})

Default Response

Status: 204 No Content

Get all authorized SSH keys

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/settings/authorized-keys

JavaScript (@octokit/core.js)

await octokit.request('GET /setup/api/settings/authorized-keys')

Default response

Status: 200 OK

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Add an authorized SSH key

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/settings/authorized-keys \
  -d '{"authorized_key":"authorized_key"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Default response

Status: 201 Created

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Remove an authorized SSH key

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/settings/authorized-keys \
  -d '{"authorized_key":"authorized_key"}'

JavaScript (@octokit/core.js)

await octokit.request('DELETE /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Default response

Status: 200 OK

[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Create a GitHub license

When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license:

Note that you need to POST to /setup/api/configure to start the actual configuration process.

When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:

1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
2. If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.

For a list of the available settings, see the Get settings endpoint.

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/start \
  -d '{"license":"license"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /setup/api/start', {
  license: 'license'
})

Response

Status: 202 Accepted

Upgrade a license

This API upgrades your license and also triggers the configuration process:

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/setup/api/upgrade \
  -d '{"license":"license"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /setup/api/upgrade', {
  license: 'license'
})

Response

Status: 202 Accepted

Create an organization

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/organizations \
  -d '{"login":"login","admin":"admin"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/organizations', {
  login: 'login',
  admin: 'admin'
})

Default response

Status: 201 Created

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

Update an organization name

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/organizations/ORG \
  -d '{"login":"login"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/organizations/{org}', {
  org: 'org',
  login: 'login'
})

Response

Status: 202 Accepted

{
  "message": "Job queued to rename organization. It may take a few minutes to complete.",
  "url": "https://<hostname>/api/v3/organizations/1"
}

List pre-receive hooks for an organization

List all pre-receive hooks that are enabled or testing for this organization as well as any disabled hooks that can be configured at the organization level. Globally disabled pre-receive hooks that do not allow downstream configuration are not listed.

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/orgs/ORG/pre-receive-hooks

JavaScript (@octokit/core.js)

await octokit.request('GET /orgs/{org}/pre-receive-hooks', {
  org: 'org',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
    "allow_downstream_configuration": true
  }
]

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

Get a pre-receive hook for an organization

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/orgs/ORG/pre-receive-hooks/42

JavaScript (@octokit/core.js)

await octokit.request('GET /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

Update pre-receive hook enforcement for an organization

For pre-receive hooks which are allowed to be configured at the org level, you can set enforcement and allow_downstream_configuration

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/orgs/ORG/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42",
  "allow_downstream_configuration": false
}

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

Remove pre-receive hook enforcement for an organization

Removes any overrides for this hook at the org level for this org.

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/orgs/ORG/pre-receive-hooks/42

JavaScript (@octokit/core.js)

await octokit.request('DELETE /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

List pre-receive environments

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/pre-receive-environments', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

[
  {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 14,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "not_started",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  }
]

Preview notice

application/vnd.github.eye-scream-preview

Create a pre-receive environment

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments \
  -d '{"name":"name","image_url":"image_url"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/pre-receive-environments', {
  name: 'name',
  image_url: 'image_url',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 201 Created

{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "not_started",
    "downloaded_at": null,
    "message": null
  }
}

Preview notice

application/vnd.github.eye-scream-preview

Get a pre-receive environment

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments/42

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Preview notice

application/vnd.github.eye-scream-preview

Update a pre-receive environment

You cannot modify the default environment. If you attempt to modify the default environment, you will receive a 422 Unprocessable Entity response.

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments/42 \
  -d '{"name":"name"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Client errors

Status: 422 Unprocessable Entity

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

Preview notice

application/vnd.github.eye-scream-preview

Delete a pre-receive environment

If you attempt to delete an environment that cannot be deleted, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

• Cannot modify or delete the default environment
• Cannot delete environment that has hooks
• Cannot delete environment when download is in progress

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments/42

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default Response

Status: 204 No Content

Client errors

Status: 422 Unprocessable Entity

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

Preview notice

application/vnd.github.eye-scream-preview

Start a pre-receive environment download

Triggers a new download of the environment tarball from the environment's image_url. When the download is finished, the newly downloaded tarball will overwrite the existing environment.

If a download cannot be triggered, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

• Cannot modify or delete the default environment
• Can not start a new download when a download is in progress

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments/42/downloads

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/pre-receive-environments/{pre_receive_environment_id}/downloads', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 202 Accepted

{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "not_started",
  "downloaded_at": null,
  "message": null
}

Client errors

Status: 422 Unprocessable Entity

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Can not start a new download when a download is in progress"
    }
  ]
}

Preview notice

application/vnd.github.eye-scream-preview

Get the download status for a pre-receive environment

In addition to seeing the download status at the "Get a pre-receive environment" endpoint, there is also this separate endpoint for just the download status.

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-environments/42/downloads/latest

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "success",
  "downloaded_at": "2016-05-26T07:42:53-05:00",
  "message": null
}

Preview notice

application/vnd.github.eye-scream-preview

List pre-receive hooks

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-hooks

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/pre-receive-hooks', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

[
  {
    "id": 1,
    "name": "Check Commits",
    "enforcement": "disabled",
    "script": "scripts/commmit_check.sh",
    "script_repository": {
      "id": 595,
      "full_name": "DevIT/hooks",
      "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
      "html_url": "https://github.example.com/DevIT/hooks"
    },
    "environment": {
      "id": 2,
      "name": "DevTools Hook Env",
      "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
      "html_url": "https://github.example.com/admin/pre-receive-environments/2",
      "default_environment": false,
      "created_at": "2016-05-20T11:35:45-05:00",
      "hooks_count": 1,
      "download": {
        "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
        "state": "success",
        "downloaded_at": "2016-05-26T07:42:53-05:00",
        "message": null
      }
    },
    "allow_downstream_configuration": false
  }
]

Preview notice

application/vnd.github.eye-scream-preview

Create a pre-receive hook

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-hooks \
  -d '{"name":"name","script":"script","script_repository":{},"environment":{}}'

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/pre-receive-hooks', {
  name: 'name',
  script: 'script',
  script_repository: {},
  environment: {},
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 201 Created

{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

Preview notice

application/vnd.github.eye-scream-preview

Get a pre-receive hook

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-hooks/42

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

Preview notice

application/vnd.github.eye-scream-preview

Update a pre-receive hook

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-hooks/42 \
  -d '{"name":"name"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": true
}

Preview notice

application/vnd.github.eye-scream-preview

Delete a pre-receive hook

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/admin/pre-receive-hooks/42

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default Response

Status: 204 No Content

Preview notice

application/vnd.github.eye-scream-preview

List pre-receive hooks for a repository

List all pre-receive hooks that are enabled or testing for this repository as well as any disabled hooks that are allowed to be enabled at the repository level. Pre-receive hooks that are disabled at a higher level and are not configurable will not be listed.

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/repos/octocat/hello-world/pre-receive-hooks

JavaScript (@octokit/core.js)

await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
  }
]

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

Get a pre-receive hook for a repository

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/repos/octocat/hello-world/pre-receive-hooks/42

JavaScript (@octokit/core.js)

await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

Update pre-receive hook enforcement for a repository

For pre-receive hooks which are allowed to be configured at the repo level, you can set enforcement

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/repos/octocat/hello-world/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/repos/octocat/hello-world/pre-receive-hooks/42"
}

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

Remove pre-receive hook enforcement for a repository

Deletes any overridden enforcement on this repository for the specified hook.

Responds with effective values inherited from owner and/or global level.

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  https://api.github.com/repos/octocat/hello-world/pre-receive-hooks/42

JavaScript (@octokit/core.js)

await octokit.request('DELETE /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Default response

Status: 200 OK

{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

• Works with GitHub Apps

Preview notice

application/vnd.github.eye-scream-preview

List public keys

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/keys

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/keys')

Default response

Status: 200 OK

[
  {
    "key_id": "012345678912345678",
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "user_id": 232,
    "repository_id": null
  },
  {
    "key_id": "012345678912345678",
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "user_id": null,
    "repository_id": 2333,
    "id": "2",
    "url": "https://api.github.com/repos/octocat/Hello-World/keys/2"
  }
]

Delete a public key

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/keys/KEY_IDS

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/keys/{key_ids}', {
  key_ids: 'key_ids'
})

Default Response

Status: 204 No Content

List personal access tokens

Lists personal access tokens for all users, including admin users.

Parameters

Code samples

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/tokens

JavaScript (@octokit/core.js)

await octokit.request('GET /admin/tokens')

Default response

Status: 200 OK

[
  {
    "id": 2,
    "url": "https://enterprise.octocat.com/api/v3/authorizations/2",
    "app": {
      "name": "My personal access token",
      "url": "https://docs.github.com/enterprise/rest/reference/enterprise-admin#list-personal-access-tokens",
      "client_id": "00000000000000000000"
    },
    "token": "",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "848f9f8a",
    "note": "My personal access token",
    "note_url": null,
    "created_at": "2019-04-24T21:49:02Z",
    "updated_at": "2019-04-24T21:49:02Z",
    "scopes": [
      "admin:business",
      "admin:gpg_key",
      "admin:org",
      "admin:org_hook",
      "admin:pre_receive_hook",
      "admin:public_key",
      "admin:repo_hook",
      "delete_repo",
      "gist",
      "notifications",
      "repo",
      "user",
      "write:discussion"
    ],
    "fingerprint": null
  }
]

Delete a personal access token

Deletes a personal access token. Returns a 403 - Forbidden status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

Parameters

Code samples

Shell

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

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/tokens/{token_id}', {
  token_id: 42
})

Default Response

Status: 204 No Content

Create a user

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat" as the login, a user named "octo-cat" will be created.

If the login name or email address is already associated with an account, the server will return a 422 response.

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/users \
  -d '{"login":"login"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/users', {
  login: 'login'
})

Default response

Status: 201 Created

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

Update the username for a user

Parameters

Code samples

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/users/USERNAME \
  -d '{"login":"login"}'

JavaScript (@octokit/core.js)

await octokit.request('PATCH /admin/users/{username}', {
  username: 'username',
  login: 'login'
})

Response

Status: 202 Accepted

{
  "message": "Job queued to rename user. It may take a few minutes to complete.",
  "url": "https://api.github.com/user/1"
}

Delete a user

Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.

You can delete any user account except your own.

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/users/USERNAME

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/users/{username}', {
  username: 'username'
})

Default Response

Status: 204 No Content

Create an impersonation OAuth token

Parameters

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/users/USERNAME/authorizations \
  -d '{"scopes":["scopes"]}'

JavaScript (@octokit/core.js)

await octokit.request('POST /admin/users/{username}/authorizations', {
  username: 'username',
  scopes: [
    'scopes'
  ]
})

Default response

Status: 201 Created

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Delete an impersonation OAuth token

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/admin/users/USERNAME/authorizations

JavaScript (@octokit/core.js)

await octokit.request('DELETE /admin/users/{username}/authorizations', {
  username: 'username'
})

Default Response

Status: 204 No Content

Promote a user to be a site administrator

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

Parameters

Code samples

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/site_admin

JavaScript (@octokit/core.js)

await octokit.request('PUT /users/{username}/site_admin', {
  username: 'username'
})

Default Response

Status: 204 No Content

Demote a site administrator

You can demote any user account except your own.

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/site_admin

JavaScript (@octokit/core.js)

await octokit.request('DELETE /users/{username}/site_admin', {
  username: 'username'
})

Default Response

Status: 204 No Content

Suspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403 response.

You can suspend any user account except your own.

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

Parameters

Code samples

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/suspended \
  -d '{"reason":"reason"}'

JavaScript (@octokit/core.js)

await octokit.request('PUT /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Default Response

Status: 204 No Content

Unsuspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403 response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.

Parameters

Code samples

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/suspended \
  -d '{"reason":"reason"}'

JavaScript (@octokit/core.js)

await octokit.request('DELETE /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Default Response

Status: 204 No Content