Skip to main content

We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the new Branches, Collaborators, Commits, Deployments, GitHub Pages, Releases, Metrics, Webhooks REST API pages.

Pages

The GitHub Pages API allows you to interact with GitHub Pages sites and build information.

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


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


      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


      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


      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


      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


      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


      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


      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