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 11 12 13 14 15
## List all pages domains

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

```http
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 37 38 39 40 41 42 43 44 45
## List pages domains

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

```http
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 72 73 74 75 76 77 78 79 80 81
```

```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.

```http
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 113 114 115 116 117 118 119 120 121 122 123 124
```

```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.

```http
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 149 150 151 152 153 154 155 156 157 158 159 160
```

```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.

```http
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 185 186 187 188 189 190 191 192 193 194
```

```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.

```http
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
```