---
title: "Add aliases in bulk"
method: POST
path: "/cdn/aliases/add"
tags: ["Aliases"]
---

# Add aliases in bulk

`POST /cdn/aliases/add`

## Request

- Base URL: `https://api.gcore.com`
- URL: `https://api.gcore.com/cdn/aliases/add`
- Auth: HTTP apikey

Create up to 1000 aliases for one CDN resource in a single request.

The request is atomic: if any item is invalid, nothing is created and the errors are returned per item, in the same order as the request items. An item whose hostname is already an alias of the same CDN resource is reported in `exists` and left unchanged.

The aliases limit of your account is checked against the items that would be created.

## Request body

- AliasesAddPayload
  - `resource_id` integer, required: ID of the CDN resource whose settings the aliases are served with.
  - `items` AliasBulkItem[], required: Aliases to create.
    - `cname` string, required: Alias hostname.
    - `ssl_id` integer, nullable: ID of your own SSL certificate to serve for the alias. A Let's Encrypt certificate issued for one of your CDN resources cannot be used. Omit it to have a Let's Encrypt certificate issued automatically.
    - `automated` boolean: How the alias certificate is managed. Defaults to `true` when `ssl_id` is omitted and to `false` when `ssl_id` is passed.
    - `challenge_type` 'dns_01' | 'http_01': Domain validation method used to issue the Let's Encrypt certificate for the alias. Possible values: - `dns_01` – Validation via a CNAME record for `_acme-challenge.<alias hostname>`, shown in `ssl_provisioning.acme_delegation`. - `http_01` – Validation via an HTTP request to the alias hostname. The alias hostname must point to your CDN CNAME, shown in `ssl_provisioning.http_validation`. The request is served with the settings of the alias's CDN resource, so they must not block or redirect `/.well-known/acme-challenge/`.

## Response `200`

Successful.

- AliasesAddResponse
  - `created` AliasBulkItemResult[]: Aliases created by this request.
    - `id` integer: Alias ID.
    - `cname` string: Alias hostname.
    - `status` 'inactive' | 'pending' | 'http_only' | 'active': Alias status. Possible values: - `inactive` – The alias or its CDN resource is disabled; the alias is not served. - `pending` – The alias configuration has not reached the CDN yet. - `http_only` – The alias is served over HTTP only. - `active` – The alias is served over HTTP and HTTPS.
    - `ssl_status` 'pending' | 'issued' | 'failed', nullable: Outcome of the certificate we manage for the alias. Possible values: - `pending` – A certificate attempt is in progress, or was stopped by pausing the alias and starts again after it is resumed. - `issued` – The latest attempt succeeded. - `failed` – The latest attempt ended without a certificate. - `null` – No certificate is managed for the alias: the alias uses a certificate you provided, or is automated and has never opened an attempt.
  - `exists` AliasBulkItemResult[]: Items whose hostname was already an alias of the CDN resource. Nothing was changed for them.
    - `id` integer: Alias ID.
    - `cname` string: Alias hostname.
    - `status` 'inactive' | 'pending' | 'http_only' | 'active': Alias status. Possible values: - `inactive` – The alias or its CDN resource is disabled; the alias is not served. - `pending` – The alias configuration has not reached the CDN yet. - `http_only` – The alias is served over HTTP only. - `active` – The alias is served over HTTP and HTTPS.
    - `ssl_status` 'pending' | 'issued' | 'failed', nullable: Outcome of the certificate we manage for the alias. Possible values: - `pending` – A certificate attempt is in progress, or was stopped by pausing the alias and starts again after it is resumed. - `issued` – The latest attempt succeeded. - `failed` – The latest attempt ended without a certificate. - `null` – No certificate is managed for the alias: the alias uses a certificate you provided, or is automated and has never opened an attempt.

## Other responses

- `400`: Validation failed, or the aliases limit of your account is reached.
- `403`: Aliases are not enabled for your account.

## Changes

- **2026-10-21** `d034c0d6d6ff`: 2 warning, 5 info
  - added the new `http_only` enum value to the `created/items/status` response property for the response status `200`
  - added the new `http_only` enum value to the `exists/items/status` response property for the response status `200`
  - added the new optional request property `items/items/challenge_type`
  - removed the `ssl_error` enum value from the `created/items/status` response property for the response status `200`
  - …3 more
- **2026-09-28** `9b685d687b49`: 2 info
  - added the optional property `created/items/ssl_status` to the response with the `200` status
  - added the optional property `exists/items/ssl_status` to the response with the `200` status
- **2026-09-15** `adafd38a196b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/g-core/apis/gcore-openapi/changes/cdn/aliases/add/post.md)

---

[API](https://skmtc.dev/g-core/apis/gcore-openapi.md) - [All operations](https://skmtc.dev/g-core/apis/gcore-openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/g-core/apis/gcore-openapi/revisions/a2b772345f3a?raw)