> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Change alias
> Change an alias. The hostname and the CDN resource of an alias cannot be changed; delete the alias and create a new one instead.
Set `active` to `false` to stop serving the alias; certificate issuance stops, though an attempt already being processed completes. Set it back to `true` to resume. Resuming an alias without a valid Let's Encrypt certificate starts a new issuance attempt, which is rate-limited, so it cannot be combined with `automated` in one request. A renewal stopped by the pause is started again by the scheduled renewal after the alias is resumed.
For an alias with your own certificate, pass a new certificate ID in `ssl_id` to replace it. The new certificate must cover the alias hostname.
Pass `automated` to switch how the certificate is managed. Switching to your own certificate takes effect at once and the Let's Encrypt certificate issued for the alias is removed. Switching to a Let's Encrypt certificate starts an issuance attempt while your certificate keeps being served, and the alias starts serving the new certificate once it is issued; if the attempt fails, `ssl_status` becomes `failed` and your certificate keeps being served. The certificate mode cannot be changed while the alias is paused — resume it first.
Pass `challenge_type` to change how the Let's Encrypt certificate's domain is validated. It cannot be changed while the alias is paused, or together with `active`. While no valid certificate is served, the change cancels the running issuance attempt and starts a new one; this is rate-limited like resuming, and is refused while that attempt is being processed. Otherwise the new method is used from the next attempt.
This endpoint is in beta. BETA
## OpenAPI
````yaml /api-reference/services_docs_mintlify_enriched/cdn_api.yaml patch /cdn/aliases/{alias_id}
openapi: 3.1.0
info:
title: Gcore OpenAPI – CDN API
description: >-
This OpenAPI is an aggregated OpenAPI specification that unifies all Gcore
products into a single file. It covers Cloud, CDN, DNS, WAAP, DDoS
Protection, Object Storage, Streaming, and FastEdge services.
version: cbe2bf61926c
servers:
- url: https://api.gcore.com
security:
- APIKey: []
tags:
- name: CDN service
description: Information about the current state of the CDN service in your account.
- name: CDN resources
- name: Origins
- name: Rules
description: >-
Rules allow to set up custom settings for certain file types or paths.
By default, the rule inherits all options values from the related CDN
resource.
Each option in rule settings can be in one of the following states:
- **Inherit** - Option is not added to the rule. Option inherits its value
from the CDN resource settings. In this case, the option value is
**null**.
- **ON** - Option is added to the rule and enabled. Option values
configured in the rule will override values from the CDN resource
settings.
- **OFF** - Option is added to the rule and disabled. Option will be
turned off.
- name: Rule templates
- name: Presets
description: >-
A preset is a predefined set of CDN resource or rule settings that can be
applied to an object in a single request.
Once a preset is applied to an object, the options included in the preset
cannot be edited on that object until the preset is unapplied.
- name: SSL certificates
- name: Let's Encrypt certificates
- name: CA certificates
- name: Aliases
description: >-
An alias is a hostname you own that is served with the settings of one of
your CDN resources and with
its own SSL certificate. Aliases must be enabled for your account.
- name: CDN activity logs
description: |-
Get the history of users requests to CDN.
It contains requests made both via the API and via the control panel.
The following methods are not tracked in the activity logs:
- HEAD
- OPTIONS
- name: Log viewer
description: >-
Log viewer provides you with general information about CDN operation. This
information does not contain all possible
sets of fields and restricted by time. To receive full data, use Logs
Uploader.
- name: Logs uploader
description: >-
Logs uploader allows you to upload logs with desired format to desired
storages.
Consists of three main parts:
- **Policies** - rules that define which logs are uploaded and how they
are uploaded.
- **Targets** - destinations where logs are uploaded.
- **Configs** - combinations of logs uploader policies, targets and
resources to which they are applied.
- name: Tools
- name: Statistics
description: >-
Consumption statistics is updated in near real-time as a standard
practice.
However, the frequency of updates can vary, but they are typically
available within a 24-hour period.
Exceptions, such as maintenance periods, may delay data beyond 24 hours
until servers resume and fill in the missing statistics.
- name: Advanced analytics
description: >-
Advanced analytics allows to get statistics about unique visitors,
traffic, and requests for countries, directories, browsers, devices, and
operation systems for up to 90 days starting from today.
Advanced analytics API is based on the [GraphQL
framework](https://graphql.org/).
Advanced analytics API has one single endpoint:
https://api.gcore.com/cdn/advanced/v2/query
You can pass the query parameters as a JSON object in the payload of a
POST request to this endpoint.
You can use curl to make requests to the Advanced analytics API.
Alternatively, you can use a GraphQL client
to construct queries and pass requests to the Advanced analytics API.
You can write queries in GraphQL much like in SQL: specify the data set
(CDN resource), the metrics
to retrieve (such as unique visitors and traffic), and filter or group by
dimensions (for example, a country).
- name: Origin shielding
- name: IP addresses list
- name: Purge history
paths:
/cdn/aliases/{alias_id}:
patch:
tags:
- Aliases
summary: Change alias
description: >-
Change an alias. The hostname and the CDN resource of an alias cannot be
changed; delete the alias and create a new one instead.
Set `active` to `false` to stop serving the alias; certificate issuance
stops, though an attempt already being processed completes. Set it back
to `true` to resume. Resuming an alias without a valid Let's Encrypt
certificate starts a new issuance attempt, which is rate-limited, so it
cannot be combined with `automated` in one request. A renewal stopped by
the pause is started again by the scheduled renewal after the alias is
resumed.
For an alias with your own certificate, pass a new certificate ID in
`ssl_id` to replace it. The new certificate must cover the alias
hostname.
Pass `automated` to switch how the certificate is managed. Switching to
your own certificate takes effect at once and the Let's Encrypt
certificate issued for the alias is removed. Switching to a Let's
Encrypt certificate starts an issuance attempt while your certificate
keeps being served, and the alias starts serving the new certificate
once it is issued; if the attempt fails, `ssl_status` becomes `failed`
and your certificate keeps being served. The certificate mode cannot be
changed while the alias is paused — resume it first.
Pass `challenge_type` to change how the Let's Encrypt certificate's
domain is validated. It cannot be changed while the alias is paused, or
together with `active`. While no valid certificate is served, the change
cancels the running issuance attempt and starts a new one; this is
rate-limited like resuming, and is refused while that attempt is being
processed. Otherwise the new method is used from the next attempt.
operationId: change-alias
parameters:
- $ref: '#/components/parameters/alias_id_parameter'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeAlias'
responses:
'200':
description: Successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AliasDetail'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/CommonValidationError'
'403':
description: Aliases are not enabled for your account.
'404':
description: The alias does not exist.
'429':
description: >-
Too many certificate issuance attempts have been started for the
alias.
x-codeSamples:
- lang: Python
source: |-
import os
from gcore import Gcore
client = Gcore(
api_key=os.environ.get("GCORE_API_KEY"), # This is the default and can be omitted
)
alias_detail = client.cdn.aliases.update(
alias_id=0,
)
print(alias_detail)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/G-Core/gcore-go\"\n\t\"github.com/G-Core/gcore-go/cdn\"\n\t\"github.com/G-Core/gcore-go/option\"\n)\n\nfunc main() {\n\tclient := gcore.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\taliasDetail, err := client.CDN.Aliases.Update(\n\t\tcontext.TODO(),\n\t\t0,\n\t\tcdn.AliasUpdateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", aliasDetail)\n}\n"
components:
parameters:
alias_id_parameter:
in: path
name: alias_id
description: Alias ID.
required: true
schema:
type: integer
schemas:
ChangeAlias:
type: object
properties:
active:
type: boolean
description: >-
Whether the alias is enabled.
Possible values:
- `true` – The alias is enabled.
- `false` – The alias is paused and is not served. Certificate
issuance stops, though an attempt already being processed completes.
example: false
automated:
type: boolean
description: >-
How the alias certificate is managed. Change it to switch the alias
between a Let's Encrypt certificate and your own. Cannot be changed
while the alias is paused.
Possible values:
- `true` – Switch to a Let's Encrypt certificate. `ssl_id` must be
omitted. The current certificate keeps being served until the new
one is issued.
- `false` – Switch to your own certificate. `ssl_id` is required and
is served immediately.
example: true
challenge_type:
allOf:
- $ref: '#/components/schemas/AliasChallengeType'
description: >-
Domain validation method used to issue the Let's Encrypt
certificate. Available for an alias with `automated` set to `true`,
and together with `automated` set to `true` to switch to a Let's
Encrypt certificate. Cannot be changed while the alias is paused, or
together with `active`.
While no valid certificate is served, the running issuance attempt
is cancelled and a new one is started with the new method. Otherwise
the new method is used from the next attempt.
ssl_id:
type: integer
description: >-
ID of your own SSL certificate to serve for the alias instead of the
current one. The certificate must cover the alias hostname; a Let's
Encrypt certificate issued for one of your CDN resources cannot be
used. Available for an alias with `automated` set to `false`, and
together with `automated` set to `false` to switch to your own
certificate.
example: 891
AliasDetail:
allOf:
- $ref: '#/components/schemas/Alias'
- type: object
properties:
ssl_provisioning:
type: object
nullable: true
description: >-
DNS record needed for Let's Encrypt domain validation of the
alias hostname. It is `null` when `automated` is `false`, and
when `challenge_type` is `dns_01` until a delegation record has
been prepared for the hostname.
properties:
acme_delegation:
allOf:
- $ref: '#/components/schemas/AliasCnameRecord'
description: >-
CNAME record to create so validation can be completed for
the hostname. Returned when `challenge_type` is `dns_01`.
http_validation:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/AliasCnameRecord'
description: >-
CNAME record pointing the alias hostname to your CDN CNAME.
Returned when `challenge_type` is `http_01`; `null` until a
CDN CNAME is assigned to your account.
example:
cname_name: shop.example.com
cname_target: cl-1a2b3c.cdn.example.net
CommonValidationError:
title: Other Errors
type: object
properties:
errors:
type: object
description: This object contains error descriptions per field from your request.
properties:
field_name:
type: array
description: Error list for specific field.
items:
type: string
description: Error description
example:
- Error description.
AliasChallengeType:
type: string
description: >-
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/`.
enum:
- dns_01
- http_01
example: http_01
Alias:
type: object
properties:
id:
type: integer
description: Alias ID.
example: 123
cname:
type: string
description: Alias hostname. Cannot be changed after creation.
example: shop.example.com
resource_id:
type: integer
description: >-
ID of the CDN resource whose settings the alias is served with.
Cannot be changed after creation.
example: 4567
automated:
type: boolean
description: >-
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.
example: true
challenge_type:
type: string
nullable: true
allOf:
- $ref: '#/components/schemas/AliasChallengeType'
description: >-
Domain validation method used to issue the Let's Encrypt certificate
for the alias. `null` when `automated` is `false`.
ssl_id:
type: integer
nullable: true
description: ID of the SSL certificate served for the alias.
example: 890
active:
type: boolean
description: |-
Whether you have enabled the alias.
Possible values:
- `true` – The alias is enabled.
- `false` – The alias is paused and is not served.
example: true
enabled:
type: boolean
description: >-
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.
example: true
status:
$ref: '#/components/schemas/AliasStatus'
ssl_status:
$ref: '#/components/schemas/AliasSslStatus'
ssl_validity_not_after:
type: string
nullable: true
description: >-
Date and time when the served certificate expires (ISO 8601/RFC 3339
format, UTC). `null` while no certificate is served.
example: '2027-01-01T10:00:00Z'
created:
type: string
description: >-
Date and time when the alias was created (ISO 8601/RFC 3339 format,
UTC).
example: '2026-09-01T10:00:00Z'
updated:
type: string
description: >-
Date and time when the alias was last changed (ISO 8601/RFC 3339
format, UTC).
example: '2026-09-01T10:05:00Z'
AliasCnameRecord:
type: object
properties:
cname_name:
type: string
description: Hostname to create the CNAME record for.
example: _acme-challenge.shop.example.com
cname_target:
type: string
description: Value the CNAME record must point to.
example: 0a1b2c3d4e5f6789.le-challenges.example.net
AliasStatus:
type: string
description: >-
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.
enum:
- inactive
- pending
- http_only
- active
example: active
AliasSslStatus:
type: string
nullable: true
description: >-
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.
enum:
- pending
- issued
- failed
example: issued
securitySchemes:
APIKey:
description: >-
API key for authentication. Make sure to include the word `apikey`,
followed by a single space and then your token.
Example: `apikey 1234_abcdef`
type: apiKey
in: header
name: Authorization
````