The GitHub Pages API retrieves information about your GitHub Pages configuration, and the statuses of your builds. Information about the site and the builds can only be accessed by authenticated owners, even if the websites are public. For more information, see "About GitHub Pages."
In GitHub Pages API endpoints with a status key in their response, the value can be one of:
null: The site has yet to be built.queued: The build has been requested but not yet begun.building:The build is in progress.built: The site has been built.errored: Indicates an error occurred during the build.
In GitHub Pages API endpoints that return GitHub Pages site information, the JSON responses include these fields:
html_url: The absolute URL (including scheme) of the rendered Pages site. For example,https://username.github.io.source: An object that contains the source branch and directory for the rendered Pages site. This includes:branch: The repository branch used to publish your site's source files. For example, main or gh-pages.path: The repository directory from which the site publishes. Will be either/or/docs.
Get a GitHub Pages site
get /repos/{owner}/{repo}/pagesParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages await octokit.request('GET /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world'
})Response
Status: 200 OK {
"url": "https://api.github.com/repos/github/developer.github.com/pages",
"status": "built",
"cname": "developer.github.com",
"custom_404": false,
"html_url": "https://developer.github.com",
"source": {
"branch": "master",
"path": "/"
},
"public": true,
"https_certificate": {
"state": "approved",
"description": "Certificate is approved",
"domains": [
"developer.github.com"
],
"expires_at": "2021-05-22"
},
"https_enforced": true
}Resource not found
Status: 404 Not FoundNotes
Create a GitHub Pages site
Configures a GitHub Pages site. For more information, see "About GitHub Pages."
post /repos/{owner}/{repo}/pagesParameters
| Name | Type | In | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
accept | string | header | Setting to | ||||||
owner | string | path | |||||||
repo | string | path | |||||||
source | object | body | Required. The source branch and directory used to publish your Pages site. | ||||||
Properties of the | |||||||||
| Name (Type) | Description |
|---|---|
branch (string) | Required. The repository branch used to publish your site's source files. |
path (string) | The repository directory that includes the source files for the Pages site. Allowed paths are |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages \
-d '{"source":{"branch":"branch","path":"path"}}' await octokit.request('POST /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world',
source: {
branch: 'branch',
path: 'path'
}
})Response
Status: 201 Created {
"url": "https://api.github.com/repos/github/developer.github.com/pages",
"status": "built",
"cname": "developer.github.com",
"custom_404": false,
"html_url": "https://developer.github.com",
"source": {
"branch": "master",
"path": "/"
},
"public": true,
"https_certificate": {
"state": "approved",
"description": "Certificate is approved",
"domains": [
"developer.github.com"
],
"expires_at": "2021-05-22"
},
"https_enforced": true
}Conflict
Status: 409 ConflictValidation failed
Status: 422 Unprocessable EntityNotes
Update information about a GitHub Pages site
Updates information for a GitHub Pages site. For more information, see "About GitHub Pages.
put /repos/{owner}/{repo}/pagesParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path | |
cname | string or null | body | Specify a custom domain for the repository. Sending a |
https_enforced | boolean | body | Specify whether HTTPS should be enforced for the repository. |
public | boolean | body | Configures access controls for the GitHub Pages site. If public is set to |
source | body |
Code samples
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages \
-d '{"cname":"cname"}' await octokit.request('PUT /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world',
cname: 'cname'
})Response
Status: 204 No ContentBad Request
Status: 400 Bad RequestValidation failed
Status: 422 Unprocessable EntityNotes
Delete a GitHub Pages site
delete /repos/{owner}/{repo}/pagesParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path |
Code samples
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages await octokit.request('DELETE /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world'
})Response
Status: 204 No ContentResource not found
Status: 404 Not FoundValidation failed
Status: 422 Unprocessable EntityNotes
List GitHub Pages builds
get /repos/{owner}/{repo}/pages/buildsParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path | |
per_page | integer | query | Results per page (max 100) Default: |
page | integer | query | Page number of the results to fetch. Default: |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages/builds await octokit.request('GET /repos/{owner}/{repo}/pages/builds', {
owner: 'octocat',
repo: 'hello-world'
})Response
Status: 200 OK [
{
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
"status": "built",
"error": {
"message": null
},
"pusher": {
"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
},
"commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
"duration": 2104,
"created_at": "2014-02-10T19:00:49Z",
"updated_at": "2014-02-10T19:00:51Z"
}
]Notes
Request a GitHub Pages build
You can request that your site be built from the latest revision on the default branch. This has the same effect as pushing a commit to your default branch, but does not require an additional commit. Manually triggering page builds can be helpful when diagnosing build warnings and failures.
Build requests are limited to one concurrent build per repository and one concurrent build per requester. If you request a build while another is still in progress, the second request will be queued until the first completes.
post /repos/{owner}/{repo}/pages/buildsParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages/builds await octokit.request('POST /repos/{owner}/{repo}/pages/builds', {
owner: 'octocat',
repo: 'hello-world'
})Response
Status: 201 Created {
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/latest",
"status": "queued"
}Notes
Get latest Pages build
get /repos/{owner}/{repo}/pages/builds/latestParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages/builds/latest await octokit.request('GET /repos/{owner}/{repo}/pages/builds/latest', {
owner: 'octocat',
repo: 'hello-world'
})Response
Status: 200 OK {
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
"status": "built",
"error": {
"message": null
},
"pusher": {
"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
},
"commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
"duration": 2104,
"created_at": "2014-02-10T19:00:49Z",
"updated_at": "2014-02-10T19:00:51Z"
}Notes
Get GitHub Pages build
get /repos/{owner}/{repo}/pages/builds/{build_id}Parameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path | |
build_id | integer | path |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages/builds/42 await octokit.request('GET /repos/{owner}/{repo}/pages/builds/{build_id}', {
owner: 'octocat',
repo: 'hello-world',
build_id: 42
})Response
Status: 200 OK {
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
"status": "built",
"error": {
"message": null
},
"pusher": {
"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
},
"commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
"duration": 2104,
"created_at": "2014-02-10T19:00:49Z",
"updated_at": "2014-02-10T19:00:51Z"
}Notes
Get a DNS health check for GitHub Pages
Gets a health check of the DNS settings for the CNAME record configured for a repository's GitHub Pages.
The first request to this endpoint returns a 202 Accepted status and starts an asynchronous background task to get the results for the domain. After the background task completes, subsequent requests to this endpoint return a 200 OK status with the health check results in the response.
Users must have admin or owner permissions. GitHub Apps must have the pages:write and administration:write permission to use this endpoint.
get /repos/{owner}/{repo}/pages/healthParameters
| Name | Type | In | Description |
|---|---|---|---|
accept | string | header | Setting to |
owner | string | path | |
repo | string | path |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pages/health await octokit.request('GET /repos/{owner}/{repo}/pages/health', {
owner: 'octocat',
repo: 'hello-world'
})Response
Status: 200 OK {
"domain": {
"host": "example.com",
"uri": "http://example.com/",
"nameservers": "default",
"dns_resolves": true,
"is_proxied": false,
"is_cloudflare_ip": false,
"is_fastly_ip": false,
"is_old_ip_address": false,
"is_a_record": true,
"has_cname_record": false,
"has_mx_records_present": false,
"is_valid_domain": true,
"is_apex_domain": true,
"should_be_a_record": true,
"is_cname_to_github_user_domain": false,
"is_cname_to_pages_dot_github_dot_com": false,
"is_cname_to_fastly": false,
"is_pointed_to_github_pages_ip": true,
"is_non_github_pages_ip_present": false,
"is_pages_domain": false,
"is_served_by_pages": true,
"is_valid": true,
"reason": null,
"responds_to_https": true,
"enforces_https": true,
"https_error": null,
"is_https_eligible": true,
"caa_error": null
},
"alt_domain": {
"host": "www.example.com",
"uri": "http://www.example.com/",
"nameservers": "default",
"dns_resolves": true,
"is_proxied": false,
"is_cloudflare_ip": false,
"is_fastly_ip": false,
"is_old_ip_address": false,
"is_a_record": true,
"has_cname_record": false,
"has_mx_records_present": false,
"is_valid_domain": true,
"is_apex_domain": true,
"should_be_a_record": true,
"is_cname_to_github_user_domain": false,
"is_cname_to_pages_dot_github_dot_com": false,
"is_cname_to_fastly": false,
"is_pointed_to_github_pages_ip": true,
"is_non_github_pages_ip_present": false,
"is_pages_domain": false,
"is_served_by_pages": true,
"is_valid": true,
"reason": null,
"responds_to_https": true,
"enforces_https": true,
"https_error": null,
"is_https_eligible": true,
"caa_error": null
}
}Empty response
Status: 202 AcceptedCustom domains are not available for GitHub Pages
Status: 400 Bad RequestResource not found
Status: 404 Not FoundThere isn't a CNAME for this page
Status: 422 Unprocessable Entity
