Pages

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}/pages

    Parameters

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

    Code samples

    Shell

    curl \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages

    JavaScript (@octokit/core.js)

    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 Found

    Notes

    • Works with GitHub Apps

    Create a GitHub Pages site

    Configures a GitHub Pages site. For more information, see "About GitHub Pages."

    post /repos/{owner}/{repo}/pages

    Parameters

    Name	Type	In	Description
    accept	string	header	Setting to application/vnd.github.v3+json is recommended.
    owner	string	path
    repo	string	path
    source	object	body	Required. The source branch and directory used to publish your Pages site.
    Properties of the source object 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 / or /docs. Default: /

    Code samples

    Shell

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

    JavaScript (@octokit/core.js)

    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 Conflict

    Validation failed

    Status: 422 Unprocessable Entity

    Notes

    • Works with GitHub Apps

    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}/pages

    Parameters

    Name	Type	In	Description
    accept	string	header	Setting to application/vnd.github.v3+json is recommended.
    owner	string	path
    repo	string	path
    cname	string or nullable	body	Specify a custom domain for the repository. Sending a null value will remove the custom domain. For more about custom domains, see "Using a custom domain with GitHub Pages."
    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 true, the site is accessible to anyone on the internet. If set to false, the site will only be accessible to users who have at least read access to the repository that published the site. This includes anyone in your Enterprise if the repository is set to internal visibility. This feature is only available to repositories in an organization on an Enterprise plan.
    source		body

    Code samples

    Shell

    curl \
      -X PUT \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages \
      -d '{"cname":"cname"}'

    JavaScript (@octokit/core.js)

    await octokit.request('PUT /repos/{owner}/{repo}/pages', {
      owner: 'octocat',
      repo: 'hello-world',
      cname: 'cname'
    })
    

    Response

    Status: 204 No Content

    Bad Request

    Status: 400 Bad Request

    Validation failed

    Status: 422 Unprocessable Entity

    Notes

    • Works with GitHub Apps

    Delete a GitHub Pages site

    delete /repos/{owner}/{repo}/pages

    Parameters

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

    Code samples

    Shell

    curl \
      -X DELETE \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages

    JavaScript (@octokit/core.js)

    await octokit.request('DELETE /repos/{owner}/{repo}/pages', {
      owner: 'octocat',
      repo: 'hello-world'
    })
    

    Response

    Status: 204 No Content

    Resource not found

    Status: 404 Not Found

    Validation failed

    Status: 422 Unprocessable Entity

    Notes

    • Works with GitHub Apps

    List GitHub Pages builds

    get /repos/{owner}/{repo}/pages/builds

    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

    Code samples

    Shell

    curl \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages/builds

    JavaScript (@octokit/core.js)

    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

    • Works with GitHub Apps

    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/builds

    Parameters

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

    Code samples

    Shell

    curl \
      -X POST \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages/builds

    JavaScript (@octokit/core.js)

    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

    • Works with GitHub Apps

    Get latest Pages build

    get /repos/{owner}/{repo}/pages/builds/latest

    Parameters

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

    Code samples

    Shell

    curl \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages/builds/latest

    JavaScript (@octokit/core.js)

    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

    • Works with GitHub Apps

    Get GitHub Pages build

    get /repos/{owner}/{repo}/pages/builds/{build_id}

    Parameters

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

    Code samples

    Shell

    curl \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages/builds/42

    JavaScript (@octokit/core.js)

    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

    • Works with GitHub Apps

    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/health

    Parameters

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

    Code samples

    Shell

    curl \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/octocat/hello-world/pages/health

    JavaScript (@octokit/core.js)

    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 Accepted

    Custom domains are not available for GitHub Pages

    Status: 400 Bad Request

    Resource not found

    Status: 404 Not Found

    There isn't a CNAME for this page

    Status: 422 Unprocessable Entity

    Notes

    • Works with GitHub Apps