Pages API | GitLab Docs

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

Use this API to administer and use GitLab Pages.

The GitLab Pages feature must be enabled to use these endpoints.

Unpublish Pages

Unpublishes and removes Pages from the specified project.

Prerequisites:

You must have the Maintainer or Owner role for the project.

DELETE /projects/:id/pages

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

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

Retrieve Pages settings for a project

Retrieves Pages settings for a specified project.

Prerequisites:

You must have the Maintainer or Owner role for the project.

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or 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 --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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

Updates Pages settings for the specified project.

Prerequisites:

You must have the Maintainer or Owner role for the project.

PATCH /projects/:id/pages

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or 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
}