Pages API

Tier: Free, Premium, Ultimate Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Endpoints for managing GitLab Pages.

The GitLab Pages feature must be enabled to use these endpoints. Find out more about administering and using the feature.

Unpublish Pages

Prerequisites:

  • You must have administrator access to the instance.

Remove Pages. 

DELETE /projects/:id/pages
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project 
curl --request 'DELETE' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages"

Get Pages settings for a project

History

Prerequisites:

  • You must have at least the Maintainer role for the project.

List Pages settings for the project. 

GET /projects/:id/pages

Supported attributes:

Attribute Type Required Description
id integer/string Yes The ID or URL-encoded path of the project

If successful, returns 200 and the following response attributes:

Attribute Type Description
url string URL to access this project’s Pages.
is_unique_domain_enabled boolean If unique domain is enabled.
force_https boolean true if the project is set to force HTTPS.
deployments[] array List of current active deployments.
primary_domain string Primary domain to redirect all Pages requests to. Introduced in GitLab 17.8.
deployments[] attribute Type Description
created_at date Date deployment was created.
url string URL for this deployment.
path_prefix string Path prefix of this deployment when using parallel deployments.
root_directory string Root directory.

Example request: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages"

Example response: 

{
  "url": "http://html-root-4160ce5f0e9a6c90ccb02755b7fc80f5a2a09ffbb1976cf80b653.pages.gdk.test:3010",
  "is_unique_domain_enabled": true,
  "force_https": false,
  "deployments": [
    {
      "created_at": "2024-01-05T18:58:14.916Z",
      "url": "http://html-root-4160ce5f0e9a6c90ccb02755b7fc80f5a2a09ffbb1976cf80b653.pages.gdk.test:3010/",
      "path_prefix": "",
      "root_directory": null
    },
    {
      "created_at": "2024-01-05T18:58:46.042Z",
      "url": "http://html-root-4160ce5f0e9a6c90ccb02755b7fc80f5a2a09ffbb1976cf80b653.pages.gdk.test:3010/mr3",
      "path_prefix": "mr3",
      "root_directory": null
    }
  ],
  "primary_domain": null
}

Update Pages settings for a project

History

Prerequisites:

  • You must have administrator access to the instance.

Update Pages settings for the project. 

PATCH /projects/:id/pages

Supported attributes:

Attribute Type Required Description
id integer/string Yes The ID or URL-encoded path of the project
pages_unique_domain_enabled boolean No Whether to use unique domain
pages_https_only boolean No Whether to force HTTPs
pages_primary_domain string No Set the primary domain from the existing assigned domains to redirect all Pages requests to. Introduced in GitLab 17.8.

If successful, returns 200 and the following response attributes:

Attribute Type Description
url string URL to access this project’s Pages.
is_unique_domain_enabled boolean If unique domain is enabled.
force_https boolean true if the project is set to force HTTPS.
deployments[] array List of current active deployments.
primary_domain string Primary domain to redirect all Pages requests to. Introduced in GitLab 17.8.
deployments[] attribute Type Description
created_at date Date deployment was created.
url string URL for this deployment.
path_prefix string Path prefix of this deployment when using parallel deployments.
root_directory string Root directory.

Example request: 

curl --request PATCH \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/pages" \
  --form 'pages_unique_domain_enabled=true' \
  --form 'pages_https_only=true' \
  --form 'pages_primary_domain=https://custom.example.com'

Example response: 

{
  "url": "http://html-root-4160ce5f0e9a6c90ccb02755b7fc80f5a2a09ffbb1976cf80b653.pages.gdk.test:3010",
  "is_unique_domain_enabled": true,
  "force_https": false,
  "deployments": [
    {
      "created_at": "2024-01-05T18:58:14.916Z",
      "url": "http://html-root-4160ce5f0e9a6c90ccb02755b7fc80f5a2a09ffbb1976cf80b653.pages.gdk.test:3010/",
      "path_prefix": "",
      "root_directory": null
    },
    {
      "created_at": "2024-01-05T18:58:46.042Z",
      "url": "http://html-root-4160ce5f0e9a6c90ccb02755b7fc80f5a2a09ffbb1976cf80b653.pages.gdk.test:3010/mr3",
      "path_prefix": "mr3",
      "root_directory": null
    }
  ],
  "primary_domain": null
}