--- title: "Create alias" method: POST path: "/cdn/aliases" tags: ["Aliases"] --- # Create alias `POST /cdn/aliases` ## Request - Base URL: `https://api.gcore.com` - URL: `https://api.gcore.com/cdn/aliases` - Auth: HTTP apikey Create an alias: a hostname you own that is served with the settings of one of your CDN resources and with its own SSL certificate. By default, a Let's Encrypt certificate is issued for the alias automatically. Choose how its domain is validated with `challenge_type`. To use your own certificate instead, pass its ID in `ssl_id`. The certificate must cover the alias hostname; a Let's Encrypt certificate issued for one of your CDN resources cannot be used. The hostname must be unique across all CDN resources, additional CNAMEs and aliases. The DNS record the hostname needs for Let's Encrypt domain validation is returned in `ssl_provisioning` of the alias details. ## Request body - CreateAlias - `cname` string, required: Alias hostname. Wildcard hostnames are not supported. - `resource_id` integer, required: ID of the CDN resource whose settings the alias is served with. - `ssl_id` integer, nullable: ID of your own SSL certificate to serve for the alias. The certificate must cover the alias hostname. 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. Possible values: - `true` – A Let's Encrypt certificate is issued and renewed automatically. `ssl_id` must be omitted. - `false` – Your own certificate referenced by `ssl_id`, if any, is served. - `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.`, 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/`. - `active` boolean: Whether the alias is enabled. Defaults to `true`. ## Response `201` Successful. - Alias - `id` integer: Alias ID. - `cname` string: Alias hostname. Cannot be changed after creation. - `resource_id` integer: ID of the CDN resource whose settings the alias is served with. Cannot be changed after creation. - `automated` boolean: How the alias certificate is managed. Can be changed while the alias is served. Possible values: - `true` – A Let's Encrypt certificate is issued and renewed automatically. - `false` – The certificate referenced by `ssl_id`, if any, was added by you. - `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.`, 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/`. - `ssl_id` integer, nullable: ID of the SSL certificate served for the alias. - `active` boolean: Whether you have enabled the alias. Possible values: - `true` – The alias is enabled. - `false` – The alias is paused and is not served. - `enabled` boolean: Whether the alias is enabled by the system. Follows the state of the CDN resource. Possible values: - `true` – The alias can be served. - `false` – The alias is not served because its CDN resource is not active. - `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. - `ssl_validity_not_after` string, nullable: Date and time when the served certificate expires (ISO 8601/RFC 3339 format, UTC). `null` while no certificate is served. - `created` string: Date and time when the alias was created (ISO 8601/RFC 3339 format, UTC). - `updated` string: Date and time when the alias was last changed (ISO 8601/RFC 3339 format, UTC). ## 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`: 1 warning, 4 info - added the new `http_only` enum value to the `status` response property for the response status `201` - added the new optional request property `challenge_type` - added the optional property `challenge_type` to the response with the `201` status - removed the `ssl_error` enum value from the `status` response property for the response status `201` - …1 more - **2026-09-28** `9b685d687b49`: 1 breaking, 2 info - the response property `ssl_id` became nullable for the status `201` - added the optional property `ssl_status` to the response with the `201` status - added the optional property `ssl_validity_not_after` to the response with the `201` status - **2026-09-15** `adafd38a196b`: 1 info - endpoint added [Operation history](https://skmtc.dev/g-core/apis/gcore-openapi/changes/cdn/aliases/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)