API reference¶

Customer DKS API only: https://dks-api.apps.door.cloud + paths under /v1/catalog and /v1/public/clusters. This page is the customer API contract: every route, header, status code, and schema is listed below. There is no interactive try-it page or downloadable schema file for the customer API.

Who can do this: member = GET (and kubeconfig). super_admin = every mutation below. See Authentication.

Base URL in examples: https://dks-api.apps.door.cloud.

Headers¶

Catalog¶

Query: zone (default abidjan). Unknown zone → 400.

Clusters¶

List query: zone, page (≥1), size (1–100, default 20), include_deleted (bool). Delete query: force (bool) — tear down Door hub environments first.

Create aliases: exposureMode / exposure_mode, networkMode / network_mode.

State¶

Query: since (≥0, default 0), timeout_seconds (0–60, default 25). Header X-State-Version. 404 if no snapshot yet.

Kubeconfig¶

Query: format=plain (default, file download) or format=json. 409 unless phase is ControlPlaneReady or Provisioned.

Node pools¶

Add/scale/delete require Provisioned (409 otherwise). size is not on PATCH.

Nodes¶

GET nodes: 409 if not Provisioned; 503 if inventory unavailable. Always 200 with possibly empty items when allowed (cold / stale flags).

Elastic IPs¶

No public bind/unbind. See Elastic IPs.

Firewall rules¶

POST/DELETE items include cluster_id; GET items do not. No phase field.

There is no firewall editor in the console and Maya cannot create rules. Example, office network to HTTPS:

curl -sS -X POST \
  "https://dks-api.apps.door.cloud/v1/public/clusters/${CLUSTER_ID}/firewall-rules" \
  -H "Authorization: Bearer $DOOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "office-https",
    "protocol": "tcp",
    "port_min": 443,
    "cidrs": ["203.0.113.0/24"]
  }'

Success is 202. port_max defaults to port_min. ICMP echo uses "protocol": "icmp" and omits the ports (type 8, code 0).

Errors¶

Error body shape¶

Most 4xx/5xx responses look like:

{ "detail": "cluster 3f9c1a2e-7b4d-4c58-9e21-5d6f8a0b1c2d not found" }

detail is a string for handler-raised errors.

422 validation uses an array:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "String should match pattern …",
      "type": "string_pattern_mismatch"
    }
  ]
}

HTTP status codes (public API)¶

These are the codes /v1/public/clusters… and /v1/catalog return.

400 Bad Request¶

401 Unauthorized¶

402 Payment Required¶

Prepaid organizations only (enterprise invoice orgs skip this gate).

403 Forbidden¶

You are authenticated but not allowed.

List/get as member is allowed. Kubeconfig download is allowed for member unless your operator has tightened that setting.

404 Not Found¶

A cluster that exists in another organization typically returns 403, not 404. The list endpoint is org-scoped and will not show it.

409 Conflict¶

422 Unprocessable Content¶

Schema or merged pool bounds: extra fields (extra="forbid"), missing required fields, count/auto_scale/min_nodes/max_nodes combination, empty PATCH (at least one of: tags, description or pool fields), count=0 without autoscaling.

502 Bad Gateway¶

Auth or Door hub checks failed (for example hub environments could not be torn down on ?force=true). Retry shortly. If it persists, contact Door support with the cluster id.

503 Service Unavailable¶

500 Internal Server Error¶

Unexpected server failure (including a kubeconfig that cannot be decrypted or rewritten). Retry once, then contact support with the cluster id. Do not send tokens.

Kubeconfig returns 202 in a loop¶

202 means a fetch was queued. Response includes retry_after_seconds (platform default 5) and header Retry-After. Call the same GET again after that delay. Need ControlPlaneReady or Provisioned (409 otherwise). If 202 continues for many minutes after Provisioned, contact support with the cluster id.

Exposure PATCH 400 vs 409¶

Not Provisioned → 400. Another change still applying → 409, retry.

Schema appendix¶

Field names match JSON. Create/exposure also accept camelCase aliases where noted. additionalProperties: false on these models.

PublicCatalogResponse¶

schema_version string (catalog.public.v1). zone PublicZoneResponse. kubernetes_versions[] PublicKubernetesVersionResponse. control_plane_options[] PublicControlPlaneOptionResponse (informational; do not send on create). active_control_plane_option_id string | null. machine_tiers[] PublicMachineTierResponse. constraints PublicCatalogConstraintsResponse. defaults PublicCatalogDefaultsResponse. copy object of strings. pricing PublicZonePricingResponse | null.

PublicZoneResponse: id, display_name, region_label (string | null).

PublicKubernetesVersionResponse: id, label, recommended bool, support_channel string | null.

PublicControlPlaneOptionResponse: id, display_name, description, recommended. Informational only — you do not send a control-plane choice on create. Ignore any extra fields on this object.

PublicMachineTierResponse: id, display_name, description | null, spec (vcpu, memory_gib, disk_gib ints), recommended bool.

PublicClusterNameConstraintResponse: pattern, min_length, max_length.

PublicNodePoolsConstraintResponse: min, max, min_nodes_per_pool, max_nodes_per_pool.

PublicCatalogDefaultsResponse: network_mode intranet | internet, exposure_mode public | private.

PublicZonePricingResponse: zone_id, label, currency, hours_per_day | null, hours_per_month | null, items[] (id, label, unit, unit_price, unit_price_day | null, unit_price_month | null).

PublicClusterCreateRequest¶

Required: name, organization, zone, kubernetes_version, node_pools (1–20 PublicNodePoolRequest). Optional: exposureMode / exposure_mode, networkMode / network_mode, description (max 16384), tags (max 64 DNS labels).

PublicNodePoolRequest: name (default default), size (tier id), count (default 1, 0–200), auto_scale (default false), min_nodes, max_nodes, labels object, tags object.

PublicClusterUpdateRequest¶

Optional: tags (replaces array, max 64), description (null clears). At least one key. No name.

PublicClusterExposurePatchRequest¶

Required: exposureMode / exposure_mode = public | private.

PublicClusterResponse¶

PublicClusterListResponse: items[], total, page, size, total_pages.

HubRegistrationResponse: status pending | registered | failed, registered_at | null, reason | null (sanitized).

DefaultEnvironmentResponse: status pending | ready | failed, ready_at | null, reason | null.

PublicProgress: lifecycle, step (PublicProgressStep | null), title, message, percent 0–100 | null, health ok | degraded.

PublicProgressStep: index ≥1, total ≥1 (5 on create), label.

PublicClusterStatusResponse¶

schema_version, cluster_id, state_version, phase, progress, health, operations[] (PublicOperationResponse: kind, phase, progress_pct | null, started_at | null, completed_at | null).

PublicNodePoolResponse¶

id, name, size (tier id), count, auto_scale, min_nodes | null, max_nodes | null, labels, tags, root_volume_size_gib, lifecycle active | deleting.

PublicNodePoolListResponse: schema_version (nodepool.public.v1), cluster_id, items[], total.

PublicNodePoolCreateRequest: name required, plus the same sizing fields as PublicNodePoolRequest (no default name).

PublicNodePoolPatchRequest: optional count, auto_scale, min_nodes, max_nodes, labels, tags. No size.

PublicNodeResponse¶

name, pool | null, status (Pending, Provisioning, Provisioned, Running, Deleting, Deleted, Failed, Unknown), kubernetes_version | null, ready bool, created_at | null, deleted_at | null.

PublicNodeListResponse: schema_version (node.public.v1), cluster_id, items[], total, cold, stale, next_refresh_at | null.

PublicNodeDeletePendingResponse: schema_version (node.public.v1), cluster_id, node_name.

PublicElasticIpCreateRequest¶

Optional name, exposure (private | public | null).

PublicElasticIpResponse¶

schema_version (elastic_ip.public.v1), id, cluster_id, name | null, exposure, address, status, created_at, updated_at, deleted_at | null.

PublicElasticIpListResponse: schema_version, cluster_id, items[], total.

FirewallRuleCreateRequest¶

Required protocol. Optional port_min, port_max, cidrs, name, description.

PublicFirewallRuleResponse¶

id, name | null, protocol, port_min, port_max, cidrs[], description | null, created_at, updated_at, deleted_at | null.

PublicFirewallRuleListResponse: schema_version (firewall_rule.public.v1), cluster_id, items[], total.

FirewallRuleResponse (POST/DELETE): same fields plus cluster_id.

PublicKubeconfigResponse¶

schema_version (kubeconfig.public.v1), cluster_id, cluster_name, kubeconfig (YAML string), plaintext_size, fetched_at, received_at.

PublicKubeconfigPendingResponse: schema_version, cluster_id, message (kubeconfig fetch requested), retry_after_seconds.

HTTPValidationError (422)¶

detail: array of { loc, msg, type, … }. Handler errors use {"detail": "<string>"}.

Related¶

• Overview · Getting started · Auth
• Catalog · Lifecycle · Node pools · Kubeconfig
• Exposure · Elastic IPs · Firewall
• Errors · Limits