Version 2.1.1792967583 · latest Download OpenAPI Markdown

Certificates

Uploaded or automatically issued HTTPS certificates. They can be bound to sites; a certificate in use by a site cannot be deleted or disabled.

certsCertificatesAuthentication: User (some parameters admin only)14 endpoints

List certificates

GET/api/v2/certs

Authentication: User (some parameters admin only)

Query parameters

Field	Type	Required	Description
page	integer	—	Page number, starting from 1 Default `1`
page_size	integer	—	Items per page Default `20`
sort	string	—	Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_id	integer	—	Admin only: filter by tenant. Ignored for tenant credentials, which only see their own tenant's data
name	string	—	Name contains.
domain	string	—	SAN contains (part of a domain or IP).
scope	string	—	site = site certificate; ip = platform IP certificate; panel = panel certificate (used by the controller's HTTPS listener). Values `["site","ip","panel"]`
enabled	boolean	—	Whether enabled
expire_days	integer	—	Only list certificates expiring within N days (including expired ones).
id	integer	—	Exact certificate ID match.
ids	string	—	Comma-separated certificate IDs (at most 200); matches any of them. Combined with id as an intersection.
des	string	—	Remark contains.
type	string	—	Certificate type. Values `["custom","lets","zerossl","zerossl_api"]`
dns_api_id	integer	—	Certificates using this DNS API credential.
domains	string	—	Comma-separated domains or IPs; matches certificates whose SAN contains any of them (exact match).
issue_state	string	—	ACME issuance state (uploaded certificates have none). Values `["pending","running","issued","failed"]`
kind	string	—	domain = SAN contains a domain; ip = SAN is all IPs. Values `["domain","ip"]`

Create certificate

POST/api/v2/certs

Authentication: User (some parameters admin only)

Query parameters

Field	Type	Required	Description
tenant_id	integer	—	Admin only: filter by tenant. Ignored for tenant credentials, which only see their own tenant's data

Request body application/json

Field	Type	Required	Description
acme	CertAcmeSummary	—	Issuance state summary (carried by certificate GET and list). Present only for issued certificates (type=lets/zerossl/zerossl_api); uploaded certificates (custom) do not have this field. See GET /certs/{id}/acme for the full state (challenge type, ARI window, etc.).
cert	string	—	Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key).
des	string	—	Description
enabled	boolean	—	Whether enabled
key	string	—	Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key.
name	string	Required	Name
scope	string	—	Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate. Values `["site","ip","panel"]`
type	string	—	custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.

Get ACME issuance states in batch

GET/api/v2/certs/acme-states

Authentication: User (some parameters admin only)

Query parameters

Field	Type	Required	Description
ids	string	Required	Certificate IDs, comma-separated, at most 200.

Batch-create ACME certificates

POST/api/v2/certs/batch

Authentication: User (some parameters admin only)

Query parameters

Field	Type	Required	Description
tenant_id	integer	—	Admin only: filter by tenant. Ignored for tenant credentials, which only see their own tenant's data

Request body application/json

Field	Type	Required	Description
acme_account_id	integer	—	Account to issue with (same as acme.acme_account_id in POST /certs); if omitted, the tenant's enabled account for the type is used first, then the platform's.
auto_renew	boolean	—	Defaults to true if omitted.
des	string	—	Description
dns_api_id	integer	—	DNS API credential used for DNS-01 validation (for ACME certificates).
items	CertAcme[]	Required	Issuance states.
type	string	—	custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.

Batch reissue or renew ACME certificates

POST/api/v2/certs/batch-issue

Authentication: User (some parameters admin only)

Request body application/json

Field	Type	Required	Description
ids	integer[]	Required	Certificate IDs.

List IPs eligible for ZeroSSL certificates

GET/api/v2/certs/zerossl-ips

Authentication: User (some parameters admin only)

Query parameters

Field	Type	Required	Description
tenant_id	integer	—	Admin only: filter by tenant. Ignored for tenant credentials, which only see their own tenant's data

Get certificate

GET/api/v2/certs/{id}

Authentication: User (some parameters admin only)

Update certificate

PUT/api/v2/certs/{id}

Authentication: User (some parameters admin only)

Request body application/json

Field	Type	Required	Description
acme	CertAcmeSummary	—	Issuance state summary (carried by certificate GET and list). Present only for issued certificates (type=lets/zerossl/zerossl_api); uploaded certificates (custom) do not have this field. See GET /certs/{id}/acme for the full state (challenge type, ARI window, etc.).
cert	string	—	Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key).
des	string	—	Description
enabled	boolean	—	Whether enabled
key	string	—	Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key.
name	string	Required	Name
scope	string	—	Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate. Values `["site","ip","panel"]`
type	string	—	custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.

Delete certificate

DELETE/api/v2/certs/{id}

Authentication: User (some parameters admin only)

Get certificate ACME issuance status

GET/api/v2/certs/{id}/acme

Authentication: User (some parameters admin only)

Update certificate auto-renewal switch

PUT/api/v2/certs/{id}/acme

Authentication: User (some parameters admin only)

Request body application/json

Field	Type	Required	Description
auto_renew	boolean	Required	Defaults to true if omitted.

Bind certificate to sites

POST/api/v2/certs/{id}/bind

Authentication: User (some parameters admin only)

Request body application/json

Field	Type	Required	Description
site_ids	integer[]	Required	Sites using this certificate.

Reissue ACME certificate

POST/api/v2/certs/{id}/issue

Authentication: User (some parameters admin only)

Export certificate private key

POST/api/v2/certs/{id}/private-key

Authentication: User (some parameters admin only)

Request body application/json

Field	Type	Required	Description
password	string	—	Current login password.
totp_code	string	—	Current 6-digit TOTP code; the account must have TOTP enabled.

Certificates object

Field	Type	Required	Description
acme	CertAcmeSummary	—	Issuance state summary (carried by certificate GET and list). Present only for issued certificates (type=lets/zerossl/zerossl_api); uploaded certificates (custom) do not have this field. See GET /certs/{id}/acme for the full state (challenge type, ARI window, etc.). read-only
acme_account_id	integer	—	Account to issue with (same as acme.acme_account_id in POST /certs); if omitted, the tenant's enabled account for the type is used first, then the platform's.
ari_end	string	—	End of the renewal window suggested by the CA via ARI.
ari_start	string	—	Renewal window suggested by the CA via ARI; null = none given by the CA, renew cert.acme.renew_before_days days before expiry.
auto_renew	boolean	—	Defaults to true if omitted.
cert	string	—	Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key). read-only
cert_id	integer	—	Certificate ID.
challenge	string	—	Validation method: http-01, dns-01, or http-file (ZeroSSL file validation for zerossl_api). Values `["http-01","dns-01","http-file"]`
created_at	string	—	Created at read-only
des	string	—	Description
dns_api_id	integer	—	DNS API credential used for DNS-01 validation (for ACME certificates).
enabled	boolean	—	Whether enabled
err_times	integer	—	Number of failures in the current round.
failed	integer	—	Number of failed items.
fingerprint	string	—	SHA-256 fingerprint of the leaf certificate (lowercase hex). read-only
id	integer	—	Record ID read-only
ids	integer[]	Required	Certificate IDs.
issued_at	string	—	Time of the last successful issuance.
issuer	string	—	Certificate issuer. read-only
items	CertAcme[]	—	Issuance states.
key	string	—	Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key.
last_error	string	—	Last error
name	string	—	Name
names	string[]	—	SANs (domains, wildcard domains or IPs); falls back to CN when there is no SAN. read-only
next_try_at	string	—	After a renewal ends in failure, the earliest time the renewal scan will retry.
not_after	string	—	Certificate expiry time. read-only
not_before	string	—	Time the certificate becomes valid. read-only
ocsp	boolean	—	The leaf certificate carries an OCSP URL (nodes can staple). read-only
ok	integer	—	Number of items queued for issuance.
password	string	—	Current login password.
renewing	boolean	—	The current round is a renewal (the old certificate stays in use on failure).
scope	string	—	Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate. Values `["site","ip","panel"]`
site_ids	integer[]	—	Sites using this certificate. read-only
state	string	—	pending = queued or waiting to retry; running = issuing; issued = issued; failed = retries exhausted (alert sent). Values `["pending","running","issued","failed"]`
tenant_id	integer	—	Owning tenant; null = platform IP certificate. read-only
totp_code	string	—	Current 6-digit TOTP code; the account must have TOTP enabled.
type	string	—	custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.
updated_at	string	—	Updated at read-only
version	integer	—	Certificate content version; incremented on each replacement. read-only
zerossl_order_id	string	—	Current ZeroSSL order ID of a zerossl_api certificate; empty = no order yet.
zerossl_order_state	string	—	ZeroSSL order status (draft, pending_validation, issued, cancelled, etc.); empty = no order yet.

curl

# List certificates
curl "https://panel.example.com/api/v2/certs" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Create certificate
curl -X POST "https://panel.example.com/api/v2/certs" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get ACME issuance states in batch
curl "https://panel.example.com/api/v2/certs/acme-states" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Batch-create ACME certificates
curl -X POST "https://panel.example.com/api/v2/certs/batch" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"domains":["a.example.com"]},{"domains":["b.example.com","www.b.example.com"]}],"type":"lets"}'

# Batch reissue or renew ACME certificates
curl -X POST "https://panel.example.com/api/v2/certs/batch-issue" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":[1]}'

# List IPs eligible for ZeroSSL certificates
curl "https://panel.example.com/api/v2/certs/zerossl-ips" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get certificate
curl "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Update certificate
curl -X PUT "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Delete certificate
curl -X DELETE "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get certificate ACME issuance status
curl "https://panel.example.com/api/v2/certs/{id}/acme" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Update certificate auto-renewal switch
curl -X PUT "https://panel.example.com/api/v2/certs/{id}/acme" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew":false}'

# Bind certificate to sites
curl -X POST "https://panel.example.com/api/v2/certs/{id}/bind" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_ids":[1]}'

# Reissue ACME certificate
curl -X POST "https://panel.example.com/api/v2/certs/{id}/issue" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Export certificate private key
curl -X POST "https://panel.example.com/api/v2/certs/{id}/private-key" \
  -H "X-API-Key: $GOCDN_API_KEY"