Regions
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Geo groups and the Global root with active member counts
application/json- response
[index: integer]?A cached Geo group or the Global root (Earth, ID earth): a broad placement
selector expanded to one Edge descendant at create time. Geo groups are
arbitrary abstract groups of Macros, not geographic constraints. The
global_regions catalog and this DTO retain their technical names. id is the
slug (shares the create-time region selector namespace with regions.id; a
DB trigger forbids collisions).
curl -X GET 'https://example.com/global-regions'[ { "id": "string", "member_count": 0, "name": "string", "selectable": true }]AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Macro regions with eligible member counts
application/json- response
[index: integer]?A cached macro-region row (PLAN-REGION-HIERARCHY.md): the public selector for exactly ONE workload cell, sitting between a Geo group and the Edge regions that cell serves.
cell_id is the deployment's stable cell identity — the key the request
router's directory is indexed by — not a URL and not the serving process's
deployment role. Both it and id are immutable: re-pointing either would
move future placement to a different database.
curl -X GET 'https://example.com/macro-regions'[ { "cell_id": "string", "eligible_local_region_count": 0, "global_region_id": "string", "id": "string", "name": "string", "selectable": true }]The structured counterpart of GET /macro-regions for clients that only
need to know which regions exist and how they nest. A Macro region
dedicated to another organization is never listed. The catalog describes
topology, not capacity or health: a listed Macro can still refuse a create
it has no capacity or matching hardware for.
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Macro region IDs grouped by Geo group under the Global root; an empty platform is a 200 with an empty global object
application/json- response
The platform's region catalog: the Macro regions a caller may target, grouped by Geo group under the Global root (PLAN-REGION-CATALOG.md).
global*The Global root. Keys are Geo group IDs (us, eu, …); each value
lists that group's Macro region IDs, sorted. A Macro region is one
workload cell, and its ID is a valid create-time region selector. Geo
groups with no Macro region the caller may target are omitted.
curl -X GET 'https://example.com/region-catalog'{ "global": { "property1": [ "string" ], "property2": [ "string" ] }}Every id here is a valid create-time region selector (the levels share one
namespace, guarded by database triggers). The response separates three
different facts about each node, and a client gates on the right one:
local_region_count— structural descendants, disabled ones included.eligible_local_region_count— descendants the FLEET may place in (active, routable, opted into broad placement). Gate what you show on this; it does not depend on which API answered.selectable— this API's local broad-execution eligibility, or an Edge's direct routability. A separately configured workload router has its own request path; router-aware clients combine that path with the positive fleet count rather than this API's local served scope.
Counts are inventory, never capacity: a selectable node can still be
refused by class-aware narrowing, artifact locality or admission.
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
The region hierarchy, one node per level
application/json- response
The region hierarchy as flat, typed nodes (PLAN-REGION-HIERARCHY.md).
One response carries every level — Global (Earth), Geo groups, Macro regions (one cell each) and Edge regions — with each node naming its parent, so a client rebuilds the tree without the payload repeating an Edge region under each of its ancestors.
nodes*array<>schema_version*integerResponse shape version. Bumped when the node contract changes, so a client can refuse a shape it does not understand instead of guessing.
int320 <= valuecurl -X GET 'https://example.com/region-hierarchy'{ "nodes": [ { "auto_placement_enabled": true, "cell_id": "string", "child_count": 0, "eligible_local_region_count": 0, "id": "string", "level": "global", "local_region_count": 0, "macro_region_id": "string", "name": "string", "parent_id": "string", "selectable": true, "status": "string" } ], "schema_version": 0}Rows are filtered to active AND routable ones: the dashboard fans its
sandbox list out over this catalog's api_base_urls, so a row whose URL no
client can build a request from is a wasted (and possibly slow-failing) leg
on every list, forever — see RegionInfo::is_routable. The row still exists
and still resolves for placement; it is only kept out of the catalog handed
to clients.
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Active Edge regions
application/json- response
[index: integer]?A cached region row. id is the slug (also the Daytona target and the
runner's region identifier).
curl -X GET 'https://example.com/regions'[ { "api_base_url": "string", "auto_placement_enabled": true, "gpu_runners_allow_linux": true, "id": "string", "is_default": true, "macro_region_id": "string", "name": "string", "preview_domain": "string", "status": "string", "toolbox_proxy_url": "string" }]