cdnca

API reference

/v1/regions

6 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/regionsList platform regionsSession
POST/v1/regionsCreate a platform regionSession
GET/v1/regions/{id}Get a platform regionSession
PUT/v1/regions/{id}—Session
PATCH/v1/regions/{id}Replace the editable fields of a platform regionSession
DELETE/v1/regions/{id}Delete an unused platform regionSession

Contract file：api/control-regions.openapi.yaml

Operation details

GET /v1/regions

List platform regions

operationId
listPlatformRegions
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：regions.read

Parameters

listPlatformRegions Parameters
NameInTypeRequiredDescription
limitqueryintegerNoLegacy selector mode. Zero returns the complete platform catalog and cannot be combined with page or page_size.
pagequeryintegerNoTable page number. Enables paginated mode together with page_size.
page_sizequeryintegerNoTable page size. Enables paginated mode together with page.
searchquerystringNoLiteral case-insensitive match against name and description.

Responses

listPlatformRegions Responses
StatusDescription
200Stable list ordered by sort value and immutable short ID

Fields：count: integer(int64) data: array<Region>

400Request validation failed (regions_validation_error)
401Authentication is required (regions_unauthenticated)
403Required region permission is missing (regions_permission_denied)
503Region catalog is unavailable (regions_unavailable)

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/regions

Create a platform region

operationId
createPlatformRegion
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：regions.manage

Parameters

createPlatformRegion Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringYes—

Request body

application/json · Required：Yes

createPlatformRegion Request body
NameTypeRequiredDescription
namestringYes—
country_codestringNoISO 3166-1 alpha-2 country code, "" = not set (market conditional origins map node regions by it).
province_codestringNoGB/T 2260 province-level code, only with country_code CN; "" = whole country / not set.
descriptionstringYes—
l2_check_portintegerYes—
sortintegerYes—

Responses

createPlatformRegion Responses
StatusDescription
201Region created or an exact completed request replayed

Fields：id: string name: string code: string country_code: string province_code: string description: string l2_check_port: integer sort: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Request validation failed (regions_validation_error)
401Authentication is required (regions_unauthenticated)
403Required region permission is missing (regions_permission_denied)
409Region name
503Region catalog is unavailable (regions_unavailable)

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/regions/{id}

Get a platform region

operationId
getPlatformRegion
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：regions.read

Parameters

getPlatformRegion Parameters
NameInTypeRequiredDescription
idpathstringYes—

Responses

getPlatformRegion Responses
StatusDescription
200Current region

Fields：id: string name: string code: string country_code: string province_code: string description: string l2_check_port: integer sort: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Request validation failed (regions_validation_error)
401Authentication is required (regions_unauthenticated)
403Required region permission is missing (regions_permission_denied)
404Region does not exist (regions_not_found)
503Region catalog is unavailable (regions_unavailable)

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

PUT /v1/regions/{id}

operationId
replacePlatformRegion
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

replacePlatformRegion Parameters
NameInTypeRequiredDescription
idpathstringYes—

↑ Back to list

PATCH /v1/regions/{id}

Replace the editable fields of a platform region

operationId
updatePlatformRegion
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：regions.manage

Parameters

updatePlatformRegion Parameters
NameInTypeRequiredDescription
idpathstringYes—
If-MatchheaderstringYesExact strong ETag revision read from the current region.
Idempotency-KeyheaderstringYes—

Request body

application/json · Required：Yes

updatePlatformRegion Request body
NameTypeRequiredDescription
namestringYes—
country_codestringNoISO 3166-1 alpha-2 country code, "" = not set (market conditional origins map node regions by it).
province_codestringNoGB/T 2260 province-level code, only with country_code CN; "" = whole country / not set.
descriptionstringYes—
l2_check_portintegerYes—
sortintegerYes—

Responses

updatePlatformRegion Responses
StatusDescription
200Region updated or an exact completed request replayed

Fields：id: string name: string code: string country_code: string province_code: string description: string l2_check_port: integer sort: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Request validation failed (regions_validation_error)
401Authentication is required (regions_unauthenticated)
403Required region permission is missing (regions_permission_denied)
404Region does not exist (regions_not_found)
409Region name
412Region revision changed (regions_revision_conflict)
428If-Match is required (regions_precondition_required)
503Region catalog is unavailable (regions_unavailable)

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
  • 428 A precondition is missing: read the resource and send If-Match (or the required proof).
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

DELETE /v1/regions/{id}

Delete an unused platform region

operationId
deletePlatformRegion
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：regions.manage

Parameters

deletePlatformRegion Parameters
NameInTypeRequiredDescription
idpathstringYes—
If-MatchheaderstringYesExact strong ETag revision read from the current region.
Idempotency-KeyheaderstringYes—

Responses

deletePlatformRegion Responses
StatusDescription
204Region deleted or an exact completed request replayed
400Request validation failed (regions_validation_error)
401Authentication is required (regions_unauthenticated)
403Required region permission is missing (regions_permission_denied)
404Region does not exist (regions_not_found)
409Region name
412Region revision changed (regions_revision_conflict)
428If-Match is required (regions_precondition_required)
503Region catalog is unavailable (regions_unavailable)

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
  • 428 A precondition is missing: read the resource and send If-Match (or the required proof).
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list