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

History

Prerequisites:

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

Remove Pages.

DELETE /projects/:id/pages
AttributeTypeRequiredDescription
idinteger/stringyesThe 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:

AttributeTypeRequiredDescription
idinteger/stringYesThe ID or URL-encoded path of the project

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
urlstringURL to access this project’s Pages.
is_unique_domain_enabledbooleanIf unique domain is enabled.
force_httpsbooleantrue if the project is set to force HTTPS.
deployments[]arrayList of current active deployments.
primary_domainstringPrimary domain to redirect all Pages requests to. Introduced in GitLab 17.8.
deployments[] attributeTypeDescription
created_atdateDate deployment was created.
urlstringURL for this deployment.
path_prefixstringPath prefix of this deployment when using parallel deployments.
root_directorystringRoot 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 at least the Maintainer role for the project.

Update Pages settings for the project.

PATCH /projects/:id/pages

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringYesThe ID or URL-encoded path of the project
pages_unique_domain_enabledbooleanNoWhether to use unique domain
pages_https_onlybooleanNoWhether to force HTTPs
pages_primary_domainstringNoSet 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:

AttributeTypeDescription
urlstringURL to access this project’s Pages.
is_unique_domain_enabledbooleanIf unique domain is enabled.
force_httpsbooleantrue if the project is set to force HTTPS.
deployments[]arrayList of current active deployments.
primary_domainstringPrimary domain to redirect all Pages requests to. Introduced in GitLab 17.8.
deployments[] attributeTypeDescription
created_atdateDate deployment was created.
urlstringURL for this deployment.
path_prefixstringPath prefix of this deployment when using parallel deployments.
root_directorystringRoot 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
}