1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
---
stage: Plan
group: Knowledge
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Pages API
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
Endpoints for managing [GitLab Pages](../user/project/pages/index.md).
The GitLab Pages feature must be enabled to use these endpoints. Find out more about [administering](../administration/pages/index.md) and [using](../user/project/pages/index.md) the feature.
## Unpublish Pages
Prerequisites:
- You must have administrator access to the instance.
Remove Pages.
```plaintext
DELETE /projects/:id/pages
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
```shell
curl --request 'DELETE' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages"
```
## Get Pages settings for a project
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436932) in GitLab 16.8.
Prerequisites:
- You must have at least the Maintainer role for the project.
List Pages settings for the project.
```plaintext
GET /projects/:id/pages
```
Supported attributes:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
If successful, returns [`200`](rest/troubleshooting.md#status-codes) 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](../user/project/pages/introduction.md) is enabled. |
| `force_https` | boolean | `true` if the project is set to force HTTPS. |
| `deployments[]` | array | List of current active deployments. |
| `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](../user/project/pages/index.md#parallel-deployments). |
| `root_directory` | string | Root directory. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages"
```
Example response:
```json
{
"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
}
]
}
```
## Update Pages settings for a project
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147227) in GitLab 17.0.
Prerequisites:
- You must have administrator access to the instance.
Update Pages settings for the project.
```plaintext
PATCH /projects/:id/pages
```
Supported attributes:
| Attribute | Type | Required | Description |
| --------------------------------| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `pages_unique_domain_enabled` | boolean | No | Whether to use unique domain |
| `pages_https_only` | boolean | No | Whether to force HTTPs |
If successful, returns [`200`](rest/troubleshooting.md#status-codes) 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](../user/project/pages/introduction.md) is enabled. |
| `force_https` | boolean | `true` if the project is set to force HTTPS. |
| `deployments[]` | array | List of current active deployments. |
| `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](../user/project/pages/index.md#parallel-deployments). |
| `root_directory` | string | Root directory. |
Example request:
```shell
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'
```
Example response:
```json
{
"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
}
]
}
```
|
