Use this API to administer and use GitLab Pages, including managing custom domains.

GitLab Pages must be enabled to use these endpoints.

List all Pages domains

GET /api/v4/pages/domains

Lists all Pages domains on the instance. You must have administrator access to the instance.

Parameters

NameTypeDescription
domain
Query		StringDomain of the GitLab Pages site to filter on
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesPagesDomainBasic
400Bad Request—

Retrieve Pages settings for a project

GET /api/v4/projects/{id}/pages

Retrieves Pages settings for a specified project. You must have the Maintainer or Owner role for the project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
401Unauthorized—
404Not Found—

Update Pages settings for a project

PATCH /api/v4/projects/{id}/pages

Updates Pages settings for a specified project. You must have the Maintainer or Owner role for the project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
pages_https_onlyBooleanIf true, forces HTTPS
pages_primary_domainStringPrimary domain, from the existing assigned domains, to redirect all Pages requests to. Introduced in GitLab 17.8
pages_unique_domain_enabledBooleanIf true, uses a unique domain

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
401Unauthorized—
404Not Found—

Unpublish Pages

DELETE /api/v4/projects/{id}/pages

Unpublishes Pages from a specified project. You must have the Maintainer or Owner role for the project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
401Unauthorized—
404Not Found—

List all Pages domains in a project

GET /api/v4/projects/{id}/pages/domains

Lists all Pages domains in a specified project. You must have permissions to view Pages domains.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesPagesDomain
400Bad Request—
404Not Found—

Create Pages domain

POST /api/v4/projects/{id}/pages/domains

Creates a Pages domain in a specified project. You must have permissions to create Pages domains.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
auto_ssl_enabledBooleanIf true, enables automatic generation of SSL certificates issued by Let’s Encrypt for custom domains
Default: false
certificateString (binary) or stringCertificate in PEM format with intermediates following in most specific to least specific order
domain
Required		StringCustom domain
keyString (binary) or stringCertificate key in PEM format
user_provided_certificateStringAll or none of user_provided_certificate, user_provided_key must be provided
user_provided_keyStringAll or none of user_provided_certificate, user_provided_key must be provided

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesPagesDomain
400Bad Request—
404Not Found—

Retrieve a Pages domain

GET /api/v4/projects/{id}/pages/domains/{domain}

Retrieves a Pages domain from a specified project. You must have permissions to view Pages domains.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
domain
Path, required		StringCustom domain

Responses

CodeDescriptionSchema
200OKAPIEntitiesPagesDomain
400Bad Request—
404Not Found—

Update Pages domain

PUT /api/v4/projects/{id}/pages/domains/{domain}

Updates a specified Pages domain in a project. You must have permissions to change an existing Pages domain.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
domain
Path, required		StringCustom domain

Request body (application/json)

PropertyTypeDescription
auto_ssl_enabledBooleanIf true, enables automatic generation of SSL certificates issued by Let’s Encrypt for custom domains
certificateString (binary) or stringCertificate in PEM format with intermediates following in most specific to least specific order
keyString (binary) or stringCertificate key in PEM format

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not Found—

Delete Pages domain

DELETE /api/v4/projects/{id}/pages/domains/{domain}

Deletes a specified Pages domain in a project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
domain
Path, required		StringCustom domain

Responses

CodeDescriptionSchema
204Resource deleted—
400Bad Request—
404Not Found—

Verify Pages domain

PUT /api/v4/projects/{id}/pages/domains/{domain}/verify

Verifies a specified Pages domain in a project. You must have permissions to update Pages domains.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
domain
Path, required		StringCustom domain to verify

Responses

CodeDescriptionSchema
200OKAPIEntitiesPagesDomain
400Bad Request—
404Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesPagesDomain

PropertyTypeDescription
auto_ssl_enabledString—
certificateAPIEntitiesPagesDomainCertificate—
domainString—
enabled_untilString—
urlString—
verification_codeString—
verifiedString—

APIEntitiesPagesDomainBasic

PropertyTypeDescription
auto_ssl_enabledString—
certificate_expirationAPIEntitiesPagesDomainCertificateExpiration—
domainString—
enabled_untilString—
project_idString—
urlString—
verification_codeString—
verifiedString—

APIEntitiesPagesDomainCertificate

PropertyTypeDescription
certificateString—
certificate_textString—
expiredString—
subjectString—

APIEntitiesPagesDomainCertificateExpiration

PropertyTypeDescription
expirationString—
expiredString—
←
REST API / Geo
REST API / Group import and export
→