pages_domains.md 7 KB
Newer Older
1 2 3 4 5 6
# Pages domains API

Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/features/pages/).

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.

7 8 9 10
## List all pages domains

Get a list of all pages domains. The user must have admin permissions.

Evan Read's avatar
Evan Read committed
11
```text
12 13 14 15
GET /pages/domains
```

```bash
16
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/pages/domains
17 18 19 20 21 22 23
```

```json
[
  {
    "domain": "ssl.domain.example",
    "url": "https://ssl.domain.example",
24
    "project_id": 1337,
25 26 27 28 29 30 31 32
    "certificate": {
      "expired": false,
      "expiration": "2020-04-12T14:32:00.000Z"
    }
  }
]
```

33 34 35 36
## List pages domains

Get a list of project pages domains. The user must have permissions to view pages domains.

Evan Read's avatar
Evan Read committed
37
```text
38 39 40 41 42 43 44 45
GET /projects/:id/pages/domains
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |

```bash
46
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains
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
```

```json
[
  {
    "domain": "www.domain.example",
    "url": "http://www.domain.example"
  },
  {
    "domain": "ssl.domain.example",
    "url": "https://ssl.domain.example",
    "certificate": {
      "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
      "expired": false,
      "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----",
      "certificate_text": "Certificate:\n\n"
    }
  }
]
```

## Single pages domain

Get a single project pages domain. The user must have permissions to view pages domains.

Evan Read's avatar
Evan Read committed
72
```text
73 74 75 76 77 78 79 80 81
GET /projects/:id/pages/domains/:domain
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `domain`  | string         | yes      | The domain                               |

```bash
82
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example
83 84 85 86 87 88 89 90 91 92
```

```json
{
  "domain": "www.domain.example",
  "url": "http://www.domain.example"
}
```

```bash
93
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
```

```json
{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n\n"
  }
}
```

## Create new pages domain

Creates a new pages domain. The user must have permissions to create new pages domains.

Evan Read's avatar
Evan Read committed
113
```text
114 115 116 117 118 119 120 121 122 123 124
POST /projects/:id/pages/domains
```

| Attribute     | Type           | Required | Description                              |
| ------------- | -------------- | -------- | ---------------------------------------- |
| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `domain`      | string         | yes      | The domain                               |
| `certificate` | file/string    | no       | The certificate in PEM format with intermediates following in most specific to least specific order.|
| `key`         | file/string    | no       | The certificate key in PEM format.       |

```bash
125
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains
126 127 128
```

```bash
129
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
```

```json
{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n\n"
  }
}
```

## Update pages domain

Updates an existing project pages domain. The user must have permissions to change an existing pages domains.

Evan Read's avatar
Evan Read committed
149
```text
150 151 152 153 154 155 156 157 158 159 160
PUT /projects/:id/pages/domains/:domain
```

| Attribute     | Type           | Required | Description                              |
| ------------- | -------------- | -------- | ---------------------------------------- |
| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `domain`      | string         | yes      | The domain                               |
| `certificate` | file/string    | no       | The certificate in PEM format with intermediates following in most specific to least specific order.|
| `key`         | file/string    | no       | The certificate key in PEM format.       |

```bash
161
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
162 163 164
```

```bash
165
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
```

```json
{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n\n"
  }
}
```

## Delete pages domain

Deletes an existing project pages domain.

Evan Read's avatar
Evan Read committed
185
```text
186 187 188 189 190 191 192 193 194
DELETE /projects/:id/pages/domains/:domain
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `domain`  | string         | yes      | The domain                               |

```bash
195
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example
196
```