We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the Actions REST API page.

GitHub Enterprise administration

You can use these endpoints to administer your enterprise.

Endpoint URLs

REST API endpoints—except Management Console API endpoints— are prefixed with the following URL:

http(s)://[hostname]/api/v3

Management Console API endpoints are only prefixed with a hostname:

http(s)://hostname/

Authentication

Your GitHub Enterprise Server installation's API endpoints accept the same authentication methods as the GitHub.com API. You can authenticate yourself with OAuth tokens (which can be created using the Authorizations API) or basic authentication. OAuth tokens must have the site_admin OAuth scope when used with Enterprise-specific endpoints.

Enterprise administration API endpoints are only accessible to authenticated GitHub Enterprise Server site administrators, except for the Management Console API, which requires the Management Console password.

Version information

The current version of your enterprise is returned in the response header of every API: X-GitHub-Enterprise-Version: enterprise-server@3.3.0 You can also read the current version by calling the meta endpoint.

Admin stats

The Admin Stats API provides a variety of metrics about your installation. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Get all statistics

get /enterprise/stats/all

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/all

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/all

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Get comment statistics

get /enterprise/stats/comments

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/comments

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/comments

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get gist statistics

get /enterprise/stats/gists

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/gists

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/gists

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get hooks statistics

get /enterprise/stats/hooks

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/hooks

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/hooks

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get issue statistics

get /enterprise/stats/issues

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/issues

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/issues

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get milestone statistics

get /enterprise/stats/milestones

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/milestones

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/milestones

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get organization statistics

get /enterprise/stats/orgs

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/orgs

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/orgs

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get pages statistics

get /enterprise/stats/pages

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/pages

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/pages

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get pull request statistics

get /enterprise/stats/pulls

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/pulls

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/pulls

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get repository statistics

get /enterprise/stats/repos

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/repos

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/repos

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Get users statistics

get /enterprise/stats/users

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/stats/users

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/stats/users

Response

Status: 200

Status codes

HTTP Status Code	Description
`200`	OK

Gets the current message and expiration date of the global announcement banner in your enterprise.

get /enterprise/announcement

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/announcement

JavaScript @octokit/core.js

await octokit.request('GET /enterprise/announcement', {})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/announcement

Default response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Sets the message and expiration time for the global announcement banner in your enterprise.

patch /enterprise/announcement

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`announcement`	string	body	Required. The announcement text in GitHub Flavored Markdown. For more information about GitHub Flavored Markdown, see "Basic writing and formatting syntax."
`expires_at`	string or null	body	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

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/announcement

JavaScript @octokit/core.js

await octokit.request('PATCH /enterprise/announcement', {})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/announcement

Default response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Removes the global announcement banner in your enterprise.

delete /enterprise/announcement

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/announcement

JavaScript @octokit/core.js

await octokit.request('DELETE /enterprise/announcement', {})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/announcement

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Audit log

Get the audit log for an enterprise

Gets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the admin:enterprise scope.

get /enterprises/{enterprise}/audit-log

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`enterprise`	string	path	The slug version of the enterprise name. You can also substitute this value with the enterprise id.
`phrase`	string	query	A search phrase. For more information, see Searching the audit log.
`after`	string	query	A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.
`before`	string	query	A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.
`order`	string	query	The order of audit log events. To list newest events first, specify `desc`. To list oldest events first, specify `asc`. The default is `desc`.
`page`	integer	query	Page number of the results to fetch. Default: `1`
`per_page`	integer	query	Results per page (max 100) Default: `30`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/audit-log

JavaScript @octokit/core.js

await octokit.request('GET /enterprises/{enterprise}/audit-log', {
  enterprise: 'ENTERPRISE'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprises/ENTERPRISE/audit-log

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Global webhooks

Global webhooks are installed on your enterprise. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your enterprise. Global webhooks can subscribe to the organization, user, repository, team, member, membership, fork, and ping event types.

This API is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it. To learn how to configure global webhooks, see About global webhooks.

List global webhooks

get /admin/hooks

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/hooks

JavaScript @octokit/core.js

await octokit.request('GET /admin/hooks', {})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/hooks

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Create a global webhook

post /admin/hooks

Parameters

Name Type In Description

accept

string

header

Setting toapplication/vnd.github.v3+json is recommended.

name

string

body

Required. Must be passed as "web".

config

object

body

Required. Key/value pairs to provide settings for this webhook.

Properties of theconfigobject

Name (Type)	Description
`url` (string)	Required. The URL to which the payloads will be delivered.
`content_type` (string)	The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
`secret` (string)	If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the `X-Hub-Signature` header.
`insecure_ssl` (string)	Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.

events

array of strings

body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active

boolean

body

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

Default:

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/hooks \
  -d '{"name":"web","events":["organization","user"],"config":{"url":"https://example.com/webhook","content_type":"json","secret":"secret"}}'

JavaScript @octokit/core.js

await octokit.request('POST /admin/hooks', {
  name: 'web',
  events: [
    'organization',
    'user'
  ],
  config: {
    url: 'https://example.com/webhook',
    content_type: 'json',
    secret: 'secret'
  }
})

Response

Status: 201

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

Status codes

HTTP Status Code	Description
`201`	Created

Get a global webhook

get /admin/hooks/{hook_id}

Parameters

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

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID

JavaScript @octokit/core.js

await octokit.request('GET /admin/hooks/{hook_id}', {
  hook_id: 'HOOK_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/hooks/HOOK_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Update a global webhook

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

patch /admin/hooks/{hook_id}

Parameters

Name Type In Description

accept

string

header

Setting toapplication/vnd.github.v3+json is recommended.

hook_id integer path

config

object

body

Key/value pairs to provide settings for this webhook.

Properties of theconfigobject

Name (Type)	Description
`url` (string)	Required. The URL to which the payloads will be delivered.
`content_type` (string)	The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
`secret` (string)	If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the `X-Hub-Signature` header.
`insecure_ssl` (string)	Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.

events

array of strings

body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active

boolean

body

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

Default:

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID \
  -d '{"events":["organization"],"config":{"url":"https://example.com/webhook"}}'

JavaScript @octokit/core.js

await octokit.request('PATCH /admin/hooks/{hook_id}', {
  hook_id: 'HOOK_ID',
  events: [
    'organization'
  ],
  config: {
    url: 'https://example.com/webhook'
  }
})

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Delete a global webhook

delete /admin/hooks/{hook_id}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID

JavaScript @octokit/core.js

await octokit.request('DELETE /admin/hooks/{hook_id}', {
  hook_id: 'HOOK_ID'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/hooks/HOOK_ID

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Ping a global webhook

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

post /admin/hooks/{hook_id}/pings

Parameters

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

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID/pings

JavaScript @octokit/core.js

await octokit.request('POST /admin/hooks/{hook_id}/pings', {
  hook_id: 'HOOK_ID'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/hooks/HOOK_ID/pings

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

LDAP

You can use the LDAP API to update account relationships between a GitHub Enterprise Server user or team and its linked LDAP entry or queue a new synchronization.

With the LDAP mapping endpoints, you're able to update the Distinguished Name (DN) that a user or team maps to. Note that the LDAP endpoints are generally only effective if your GitHub Enterprise Server appliance has LDAP Sync enabled. The Update LDAP mapping for a user endpoint can be used when LDAP is enabled, even if LDAP Sync is disabled.

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.

patch /admin/ldap/teams/{team_id}/mapping

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`team_id`	integer	path
`ldap_dn`	string	body	Required. The distinguished name (DN) of the LDAP entry to map to a team.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/ldap/teams/TEAM_ID/mapping \
  -d '{"ldap_dn":"cn=Enterprise Ops,ou=teams,dc=github,dc=com"}'

JavaScript @octokit/core.js

await octokit.request('PATCH /admin/ldap/teams/{team_id}/mapping', {
  team_id: 'TEAM_ID',
  ldap_dn: 'cn=Enterprise Ops,ou=teams,dc=github,dc=com'
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/ldap/teams/TEAM_ID/mapping \
  -f ldap_dn='cn=Enterprise Ops,ou=teams,dc=github,dc=com'

Response

Status: 200

{
  "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://github.com/orgs/github/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "parent": null
}

Status codes

HTTP Status Code	Description
`200`	OK

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.

post /admin/ldap/teams/{team_id}/sync

Parameters

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

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/ldap/teams/TEAM_ID/sync

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/ldap/teams/TEAM_ID/sync

Response

Status: 201

{
  "status": "queued"
}

Status codes

HTTP Status Code	Description
`201`	Created

Update LDAP mapping for a user

patch /admin/ldap/users/{username}/mapping

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`username`	string	path
`ldap_dn`	string	body	Required. The distinguished name (DN) of the LDAP entry to map to a team.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/ldap/users/USERNAME/mapping \
  -d '{"ldap_dn":"uid=asdf,ou=users,dc=github,dc=com"}'

JavaScript @octokit/core.js

await octokit.request('PATCH /admin/ldap/users/{username}/mapping', {
  username: 'USERNAME',
  ldap_dn: 'uid=asdf,ou=users,dc=github,dc=com'
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/ldap/users/USERNAME/mapping \
  -f ldap_dn='uid=asdf,ou=users,dc=github,dc=com'

Response

Status: 200

{
  "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,
  "name": "monalisa octocat",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "hireable": false,
  "bio": "There once was...",
  "twitter_username": "monatheoctocat",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z",
  "private_gists": 81,
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "disk_usage": 10000,
  "collaborators": 8,
  "two_factor_authentication": true,
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20,
    "collaborators": 0
  }
}

Status codes

HTTP Status Code	Description
`200`	OK

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.

post /admin/ldap/users/{username}/sync

Parameters

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

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/ldap/users/USERNAME/sync

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/ldap/users/USERNAME/sync

Response

Status: 201

{
  "status": "queued"
}

Status codes

HTTP Status Code	Description
`201`	Created

License

The License API provides information on your Enterprise license. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Get license information

get /enterprise/settings/license

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/enterprise/settings/license

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /enterprise/settings/license

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Management console

The Management Console API helps you manage your GitHub Enterprise Server installation.

You must explicitly set the port number when making API calls to the Management Console. If TLS is enabled on your enterprise, the port number is 8443; otherwise, the port number is 8080.

If you don't want to provide a port number, you'll need to configure your tool to automatically follow redirects.

You may also need to add the -k flag when using curl, since GitHub Enterprise Server uses a self-signed certificate before you add your own TLS certificate.

Authentication

You need to pass your Management Console password as an authentication token to every Management Console API endpoint except /setup/api/start.

Use the api_key parameter to send this token with each request. For example:

$ curl -L 'https://hostname:admin_port/setup/api?api_key=your-amazing-password'

You can also use standard HTTP authentication to send this token. For example:

$ curl -L -u "api_key:your-amazing-password" 'https://hostname:admin_port/setup/api'

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:

Status	Description
`PENDING`	The job has not started yet
`CONFIGURING`	The job is running
`DONE`	The job has finished correctly
`FAILED`	The job has finished unexpectedly

get /setup/api/configcheck

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/configcheck

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/configcheck

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Start a configuration process

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

post /setup/api/configure

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/configure

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/configure

Response

Status: 202

Status codes

HTTP Status Code	Description
`202`	Accepted

Get the maintenance status

Check your installation's maintenance status:

get /setup/api/maintenance

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/maintenance

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/maintenance

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Enable or disable maintenance mode

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/maintenance

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`maintenance`	string	body	Required. A JSON string with the attributes `enabled` and `when`. 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.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/maintenance \
   --data-urlencode maintenance={"enabled":true, "when":"now"}

JavaScript @octokit/core.js

await octokit.request('POST /setup/api/maintenance', {
  maintenance: '{"enabled":true, "when":"now"}'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/maintenance \
  -f maintenance='{"enabled":true, "when":"now"}'

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Get settings

Gets the settings for your instance. To change settings, see the Set settings endpoint.

Note: You cannot retrieve the management console password with the Enterprise administration API.

get /setup/api/settings

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/settings

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/settings

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Set settings

Applies settings on your instance. For a list of the available settings, see the Get settings endpoint.

Notes:

The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.
You cannot set the management console password with the Enterprise administration API. Use the ghe-set-password utility to change the management console password. For more information, see "Command-line utilities."

put /setup/api/settings

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`settings`	string	body	Required. A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify. For a list of the available settings, see the Get settings endpoint.

Code samples

Example

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/settings \
   --data-urlencode settings={ "enterprise": { "public_pages": true }}

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method PUT \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/settings \
  -f settings='{ "enterprise": { "public_pages": true }}'

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Get all authorized SSH keys

get /setup/api/settings/authorized-keys

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/settings/authorized-keys

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/settings/authorized-keys

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Add an authorized SSH key

post /setup/api/settings/authorized-keys

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`authorized_key`	string	body	Required. The public SSH key.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/settings/authorized-keys \
   --data-urlencode authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw==

JavaScript @octokit/core.js

await octokit.request('POST /setup/api/settings/authorized-keys', {
  authorized_key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=='
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/settings/authorized-keys \
  -f authorized_key='ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=='

Response

Status: 201

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

Status codes

HTTP Status Code	Description
`201`	Created

Remove an authorized SSH key

delete /setup/api/settings/authorized-keys

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`authorized_key`	string	body	Required. The public SSH key.

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/settings/authorized-keys \
   --data-urlencode authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw==

JavaScript @octokit/core.js

await octokit.request('DELETE /setup/api/settings/authorized-keys', {
  authorized_key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=='
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/settings/authorized-keys \
  -f authorized_key='ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw=='

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

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:

If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
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.

post /setup/api/start

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`license`	string	body	Required. The content of your .ghl license file.
`password`	string	body	You must provide a password only if you are uploading your license for the first time. If you previously set a password through the web interface, you don't need this parameter.
`settings`	string	body	An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/start

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/start

Response

Status: 202

Status codes

HTTP Status Code	Description
`202`	Accepted

Upgrade a license

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

post /setup/api/upgrade

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`license`	string	body	The content of your new .ghl license file.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/setup/api/upgrade

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /setup/api/upgrade

Response

Status: 202

Status codes

HTTP Status Code	Description
`202`	Accepted

Organization pre-receive hooks

The Organization Pre-receive Hooks API allows you to view and modify enforcement of the pre-receive hooks that are available to an organization.

Object attributes

Name	Type	Description
`name`	`string`	The name of the hook.
`enforcement`	`string`	The state of enforcement for the hook on this repository.
`allow_downstream_configuration`	`boolean`	Whether repositories can override enforcement.
`configuration_url`	`string`	URL for the endpoint where enforcement is set.

Possible values for enforcement are enabled, disabled andtesting. disabled indicates the pre-receive hook will not run. enabled indicates it will run and reject any pushes that result in a non-zero status. testing means the script will run but will not cause any pushes to be rejected.

configuration_url may be a link to this endpoint or this hook's global configuration. Only site admins are able to access the global configuration.

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.

get /orgs/{org}/pre-receive-hooks

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`
`direction`	string	query	One of `asc` (ascending) or `desc` (descending). Default: `desc`
`sort`	string	query	The sort order for the response collection. Default: `created`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/pre-receive-hooks

JavaScript @octokit/core.js

await octokit.request('GET /orgs/{org}/pre-receive-hooks', {
  org: 'ORG'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /orgs/ORG/pre-receive-hooks

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

Get a pre-receive hook for an organization

get /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

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

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

JavaScript @octokit/core.js

await octokit.request('GET /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'ORG',
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /orgs/ORG/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

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

patch /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`pre_receive_hook_id`	integer	path	pre_receive_hook_id parameter
`enforcement`	string	body	The state of enforcement for the hook on this repository.
`allow_downstream_configuration`	boolean	body	Whether repositories can override enforcement.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/pre-receive-hooks/PRE_RECEIVE_HOOK_ID \
  -d '{"enforcement":"enabled","allow_downstream_configuration":false}'

JavaScript @octokit/core.js

await octokit.request('PATCH /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'ORG',
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID',
  enforcement: 'enabled',
  allow_downstream_configuration: false
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /orgs/ORG/pre-receive-hooks/PRE_RECEIVE_HOOK_ID \
  -f enforcement='enabled' -F allow_downstream_configuration=false

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

Remove pre-receive hook enforcement for an organization

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

delete /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

JavaScript @octokit/core.js

await octokit.request('DELETE /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'ORG',
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /orgs/ORG/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

Organizations

The Organization Administration API allows you to create organizations on your enterprise. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Create an organization

post /admin/organizations

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`login`	string	body	Required. The organization's username.
`admin`	string	body	Required. The login of the user who will manage this organization.
`profile_name`	string	body	The organization's display name.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/organizations \
  -d '{"login":"github","profile_name":"GitHub, Inc.","admin":"monalisaoctocat"}'

JavaScript @octokit/core.js

await octokit.request('POST /admin/organizations', {
  login: 'github',
  profile_name: 'GitHub, Inc.',
  admin: 'monalisaoctocat'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/organizations \
  -f login='github' -f profile_name='GitHub, Inc.' -f admin='monalisaoctocat'

Response

Status: 201

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

Status codes

HTTP Status Code	Description
`201`	Created

Update an organization name

patch /admin/organizations/{org}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`login`	string	body	Required. The organization's new name.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/organizations/ORG \
  -d '{"login":"the-new-octocats"}'

JavaScript @octokit/core.js

await octokit.request('PATCH /admin/organizations/{org}', {
  org: 'ORG',
  login: 'the-new-octocats'
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/organizations/ORG \
  -f login='the-new-octocats'

Response

Status: 202

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

Status codes

HTTP Status Code	Description
`202`	Accepted

Pre-receive environments

The Pre-receive Environments API allows you to create, list, update and delete environments for pre-receive hooks. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Object attributes

Pre-receive Environment

Name	Type	Description
`name`	`string`	The name of the environment as displayed in the UI.
`image_url`	`string`	URL to the tarball that will be downloaded and extracted.
`default_environment`	`boolean`	Whether this is the default environment that ships with GitHub Enterprise Server.
`download`	`object`	This environment's download status.
`hooks_count`	`integer`	The number of pre-receive hooks that use this environment.

Pre-receive Environment Download

Name	Type	Description
`state`	`string`	The state of the most recent download.
`downloaded_at`	`string`	The time when the most recent download started.
`message`	`string`	On failure, this will have any error messages produced.

Possible values for state are not_started, in_progress, success, failed.

List pre-receive environments

get /admin/pre-receive-environments

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`
`direction`	string	query	One of `asc` (ascending) or `desc` (descending). Default: `desc`
`sort`	string	query	Default: `created`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments

JavaScript @octokit/core.js

await octokit.request('GET /admin/pre-receive-environments', {})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Create a pre-receive environment

post /admin/pre-receive-environments

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`name`	string	body	Required. The new pre-receive environment's name.
`image_url`	string	body	Required. URL from which to download a tarball of this environment.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments \
  -d '{"name":"DevTools Hook Env","image_url":"https://my_file_server/path/to/devtools_env.tar.gz"}'

JavaScript @octokit/core.js

await octokit.request('POST /admin/pre-receive-environments', {
  name: 'DevTools Hook Env',
  image_url: 'https://my_file_server/path/to/devtools_env.tar.gz'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments \
  -f name='DevTools Hook Env' -f image_url='https://my_file_server/path/to/devtools_env.tar.gz'

Response

Status: 201

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

Status codes

HTTP Status Code	Description
`201`	Created

Get a pre-receive environment

get /admin/pre-receive-environments/{pre_receive_environment_id}

Parameters

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

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

JavaScript @octokit/core.js

await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 'PRE_RECEIVE_ENVIRONMENT_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

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.

patch /admin/pre-receive-environments/{pre_receive_environment_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`pre_receive_environment_id`	integer	path
`name`	string	body	This pre-receive environment's new name.
`image_url`	string	body	URL from which to download a tarball of this environment.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

JavaScript @octokit/core.js

await octokit.request('PATCH /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 'PRE_RECEIVE_ENVIRONMENT_ID'
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK
`422`	Client Errors

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

delete /admin/pre-receive-environments/{pre_receive_environment_id}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

JavaScript @octokit/core.js

await octokit.request('DELETE /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 'PRE_RECEIVE_ENVIRONMENT_ID'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content
`422`	Client Errors

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

post /admin/pre-receive-environments/{pre_receive_environment_id}/downloads

Parameters

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

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID/downloads

JavaScript @octokit/core.js

await octokit.request('POST /admin/pre-receive-environments/{pre_receive_environment_id}/downloads', {
  pre_receive_environment_id: 'PRE_RECEIVE_ENVIRONMENT_ID'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID/downloads

Response

Status: 202

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

Status codes

HTTP Status Code	Description
`202`	Accepted
`422`	Client Errors

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.

get /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest

Parameters

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

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID/downloads/latest

JavaScript @octokit/core.js

await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest', {
  pre_receive_environment_id: 'PRE_RECEIVE_ENVIRONMENT_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID/downloads/latest

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Pre-receive hooks

The Pre-receive Hooks API allows you to create, list, update and delete pre-receive hooks. It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Object attributes

Pre-receive Hook

Name	Type	Description
`name`	`string`	The name of the hook.
`script`	`string`	The script that the hook runs.
`script_repository`	`object`	The GitHub repository where the script is kept.
`environment`	`object`	The pre-receive environment where the script is executed.
`enforcement`	`string`	The state of enforcement for this hook.
`allow_downstream_configuration`	`boolean`	Whether enforcement can be overridden at the org or repo level.

List pre-receive hooks

get /admin/pre-receive-hooks

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`
`direction`	string	query	One of `asc` (ascending) or `desc` (descending). Default: `desc`
`sort`	string	query	One of `created` (when the repository was starred) or `updated` (when it was last pushed to) or `name`. Default: `created`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks

JavaScript @octokit/core.js

await octokit.request('GET /admin/pre-receive-hooks', {})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-hooks

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Create a pre-receive hook

post /admin/pre-receive-hooks

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`name`	string	body	Required. The name of the hook.
`script`	string	body	Required. The script that the hook runs.
`script_repository`	object	body	Required. The GitHub repository where the script is kept.
`environment`	object	body	Required. The pre-receive environment where the script is executed.
`enforcement`	string	body	The state of enforcement for this hook. default: `disabled`
`allow_downstream_configuration`	boolean	body	Whether enforcement can be overridden at the org or repo level. default: `false`

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks \
  -d '{"name":"Check Commits","script":"scripts/commit_check.sh","enforcement":"disabled","allow_downstream_configuration":false,"script_repository":{"full_name":"DevIT/hooks"},"environment":{"id":2}}'

JavaScript @octokit/core.js

await octokit.request('POST /admin/pre-receive-hooks', {
  name: 'Check Commits',
  script: 'scripts/commit_check.sh',
  enforcement: 'disabled',
  allow_downstream_configuration: false,
  script_repository: {
    full_name: 'DevIT/hooks'
  },
  environment: {
    id: 2
  }
})

Response

Status: 201

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

Status codes

HTTP Status Code	Description
`201`	Created

Get a pre-receive hook

get /admin/pre-receive-hooks/{pre_receive_hook_id}

Parameters

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

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

JavaScript @octokit/core.js

await octokit.request('GET /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Update a pre-receive hook

patch /admin/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`pre_receive_hook_id`	integer	path	pre_receive_hook_id parameter
`name`	string	body	The name of the hook.
`script`	string	body	The script that the hook runs.
`script_repository`	object	body	The GitHub repository where the script is kept.
`environment`	object	body	The pre-receive environment where the script is executed.
`enforcement`	string	body	The state of enforcement for this hook.
`allow_downstream_configuration`	boolean	body	Whether enforcement can be overridden at the org or repo level.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID \
  -d '{"name":"Check Commits","environment":{"id":1},"allow_downstream_configuration":true}'

JavaScript @octokit/core.js

await octokit.request('PATCH /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID',
  name: 'Check Commits',
  environment: {
    id: 1
  },
  allow_downstream_configuration: true
})

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Delete a pre-receive hook

delete /admin/pre-receive-hooks/{pre_receive_hook_id}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

JavaScript @octokit/core.js

await octokit.request('DELETE /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Repository pre-receive hooks

The Repository Pre-receive Hooks API allows you to view and modify enforcement of the pre-receive hooks that are available to a repository.

Object attributes

Name	Type	Description
`name`	`string`	The name of the hook.
`enforcement`	`string`	The state of enforcement for the hook on this repository.
`configuration_url`	`string`	URL for the endpoint where enforcement is set.

configuration_url may be a link to this repository, it's organization owner or global configuration. Authorization to access the endpoint at configuration_url is determined at the owner or site admin level.

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.

get /repos/{owner}/{repo}/pre-receive-hooks

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`
`direction`	string	query	One of `asc` (ascending) or `desc` (descending). Default: `desc`
`sort`	string	query	Default: `created`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/pre-receive-hooks

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks', {
  owner: 'OWNER',
  repo: 'REPO'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /repos/OWNER/REPO/pre-receive-hooks

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

Get a pre-receive hook for a repository

get /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`pre_receive_hook_id`	integer	path	pre_receive_hook_id parameter

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'OWNER',
  repo: 'REPO',
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /repos/OWNER/REPO/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

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

patch /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`pre_receive_hook_id`	integer	path	pre_receive_hook_id parameter
`enforcement`	string	body	The state of enforcement for the hook on this repository.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/pre-receive-hooks/PRE_RECEIVE_HOOK_ID \
  -d '{"enforcement":"enabled"}'

JavaScript @octokit/core.js

await octokit.request('PATCH /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'OWNER',
  repo: 'REPO',
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID',
  enforcement: 'enabled'
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /repos/OWNER/REPO/pre-receive-hooks/PRE_RECEIVE_HOOK_ID \
  -f enforcement='enabled'

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

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.

delete /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`pre_receive_hook_id`	integer	path	pre_receive_hook_id parameter

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

JavaScript @octokit/core.js

await octokit.request('DELETE /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'OWNER',
  repo: 'REPO',
  pre_receive_hook_id: 'PRE_RECEIVE_HOOK_ID'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /repos/OWNER/REPO/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

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

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	Responds with effective values inherited from owner and/or global level.

Notes

Works with GitHub Apps

Users

The User Administration API allows you to suspend, unsuspend, promote, and demote users on your enterprise. It is only available to authenticated site administrators. Normal users will receive a 403 response if they try to access it.

List public keys

get /admin/keys

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`
`direction`	string	query	One of `asc` (ascending) or `desc` (descending). Default: `desc`
`sort`	string	query	Default: `created`
`since`	string	query	Only show public keys accessed after the given time.

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/keys

JavaScript @octokit/core.js

await octokit.request('GET /admin/keys', {})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/keys

Response

Status: 200

[
  {
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "id": 2,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  },
  {
    "key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234",
    "id": 3,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  }
]

Status codes

HTTP Status Code	Description
`200`	OK

Delete a public key

delete /admin/keys/{key_ids}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/keys/KEY_IDS

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/keys/KEY_IDS

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

List personal access tokens

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

get /admin/tokens

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/tokens

JavaScript @octokit/core.js

await octokit.request('GET /admin/tokens', {})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/tokens

Response

Status: 200

[
  {
    "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": "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "Ae178B4a",
    "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
  }
]

Status codes

HTTP Status Code	Description
`200`	OK

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.

delete /admin/tokens/{token_id}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/tokens/TOKEN_ID

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/tokens/TOKEN_ID

Response

Status: 204

Status codes

HTTP Status Code	Description
`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.

post /admin/users

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`login`	string	body	Required. The user's username.
`email`	string	body	Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For details on built-in and centrally-managed authentication, see the the GitHub authentication guide.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/users \
  -d '{"login":"monalisa","email":"octocat@github.com"}'

JavaScript @octokit/core.js

await octokit.request('POST /admin/users', {
  login: 'monalisa',
  email: 'octocat@github.com'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/users \
  -f login='monalisa' -f email='octocat@github.com'

Response

Status: 201

{
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false
}

Status codes

HTTP Status Code	Description
`201`	Created

Update the username for a user

patch /admin/users/{username}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`username`	string	path
`login`	string	body	Required. The user's new username.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME \
  -d '{"login":"thenewmonalisa"}'

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/users/USERNAME \
  -f login='thenewmonalisa'

Response

Status: 202

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

Status codes

HTTP Status Code	Description
`202`	Accepted

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.

delete /admin/users/{username}

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/users/USERNAME

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Create an impersonation OAuth token

post /admin/users/{username}/authorizations

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`username`	string	path
`scopes`	array of strings	body	A list of scopes.

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/users/USERNAME/authorizations

Response when getting an existing impersonation OAuth token

Status: 200

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_last_eight": "Ae178B4a",
  "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",
  "expires_at": "2011-10-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/users/USERNAME/authorizations

Response when creating a new impersonation OAuth token

Status: 201

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_last_eight": "Ae178B4a",
  "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",
  "expires_at": "2011-10-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Status codes

HTTP Status Code	Description
`200`	Response when getting an existing impersonation OAuth token
`201`	Response when creating a new impersonation OAuth token

Delete an impersonation OAuth token

delete /admin/users/{username}/authorizations

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /admin/users/USERNAME/authorizations

Response

Status: 204

Status codes

HTTP Status Code	Description
`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."

put /users/{username}/site_admin

Parameters

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

Code samples

Example

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/site_admin

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method PUT \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /users/USERNAME/site_admin

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

Demote a site administrator

You can demote any user account except your own.

delete /users/{username}/site_admin

Parameters

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

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/site_admin

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /users/USERNAME/site_admin

Response

Status: 204

Status codes

HTTP Status Code	Description
`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."

put /users/{username}/suspended

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`username`	string	path
`reason`	string	body	The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a `reason`, it will default to "Suspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

Code samples

Example

Shell

curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/suspended

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method PUT \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /users/USERNAME/suspended

Response

Status: 204

Status codes

HTTP Status Code	Description
`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.

delete /users/{username}/suspended

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`username`	string	path
`reason`	string	body	The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a `reason`, it will default to "Unsuspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/suspended

JavaScript @octokit/core.js

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

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  --hostname HOSTNAME \
  /users/USERNAME/suspended

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content

GitHub Enterprise administration

In this article

Endpoint URLs

Authentication

Version information

Admin stats

Get all statistics

Example

Response

Status codes

Get comment statistics

Example

Response

Status codes

Get gist statistics

Example

Response

Status codes

Get hooks statistics

Example

Response

Status codes

Get issue statistics

Example

Response

Status codes

Get milestone statistics

Example

Response

Status codes

Get organization statistics

Example

Response

Status codes

Get pages statistics

Example

Response

Status codes

Get pull request statistics

Example

Response

Status codes

Get repository statistics

Example

Response

Status codes

Get users statistics

Example

Response

Status codes

Get the global announcement banner

Example

Default response

Status codes

Set the global announcement banner

Example

Default response

Status codes

Remove the global announcement banner

Example

Response

Status codes

Audit log

Get the audit log for an enterprise

Example

Response

Status codes

Global webhooks

List global webhooks

Example

Response

Status codes

Create a global webhook

Example

Response

Status codes

Get a global webhook

Example

Response

Status codes