Previews
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).
Scope: read:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
The sandbox's preview endpoints
application/json- response
Response envelope for the endpoint list.
endpoints*array<>curl -X GET 'https://example.com/sandboxes/string/endpoints'{ "endpoints": [ { "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "port": 0, "public": true, "url": "string" } ]}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).
Scope: write:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
application/json- body
port*integerint32public?booleanEndpoint created
application/json- response
One preview endpoint on the wire (with the computed URL).
created_at*stringdate-timeid*stringuuidport*integerIn-VM TCP port the endpoint exposes.
int32public*booleanAccess mode: true = the proxy skips auth, false = a credential is
required (per-VM token or owning project API key).
url*stringHost-based preview URL, <scheme>://<port>-<vm_id>.<domain>/.
curl -X POST 'https://example.com/sandboxes/string/endpoints' \ -H 'Content-Type: application/json' \ -d '{ "port": 0}'{ "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "port": 0, "public": true, "url": "string"}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).
Scope: write:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
eid*stringpreview endpoint id
uuidapplication/json- body
public*booleanUpdated endpoint
application/json- response
One preview endpoint on the wire (with the computed URL).
created_at*stringdate-timeid*stringuuidport*integerIn-VM TCP port the endpoint exposes.
int32public*booleanAccess mode: true = the proxy skips auth, false = a credential is
required (per-VM token or owning project API key).
url*stringHost-based preview URL, <scheme>://<port>-<vm_id>.<domain>/.
curl -X PATCH 'https://example.com/sandboxes/string/endpoints/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{ "public": true}'{ "created_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "port": 0, "public": true, "url": "string"}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).
Scope: write:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
eid*stringpreview endpoint id
uuidEndpoint removed (or was already gone)
curl -X DELETE 'https://example.com/sandboxes/string/endpoints/497f6eca-6276-4993-bfeb-53cbbbba6f08'Semantic bridge (ported from the Daytona facade): the upstream contract
is "any listening port can be previewed" with no registration step; ours is
opt-in per (vm_id, port) and fail-closed. This route honours the former
without weakening the latter — the port becomes previewable, but only to a
caller presenting the token. It never silently makes a port public.
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).
Scope: write:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
port*integerin-VM TCP port (1..65535)
int32Preview URL + access token (endpoint auto-registered as private if new)
application/json- response
A preview URL + its access token (GET /sandboxes/{id}/ports/{port}/preview-url).
token*stringPer-sandbox preview access token — send as x-daytona-preview-token
(the header the proxy validates). During the data-plane compat window
this is the stable HMAC token; once the deployment flips compat off
it is a short-lived sandbox JWT
scoped to exactly this port (PLAN-SANDBOX-TOKEN-JWT.md D9) — re-fetch
this route (or mint via POST /sandboxes/{id}/access-token) when it
expires.
url*stringHost-based preview URL, <scheme>://<port>-<vm_id>.<domain>/.
curl -X GET 'https://example.com/sandboxes/string/ports/0/preview-url'{ "token": "string", "url": "string"}Every call mints a NEW token (Daytona semantics: links are per-recipient so
they revoke independently). Like the stateless preview-url route, minting
auto-registers the (vm_id, port) endpoint as PRIVATE (idempotent — the
signed link does not bypass the endpoint opt-in, plan D3), and the URL is
built against the VM's REGION preview domain. write:sandboxes for the same
reason as preview_url: this mutates AND hands out a data-plane credential.
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).
Scope: write:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
port*integerin-VM TCP port (1..65535)
int32expires_in_secs?integerLink lifetime in seconds (default 60; 400 outside
1..=deployment-configured limit, default 7 days).
int64Signed preview URL (endpoint auto-registered as private if new)
application/json- response
A signed preview link (GET /sandboxes/{id}/ports/{port}/signed-preview-url).
expires_at*stringWhen the link stops resolving (natural expiry).
date-timetoken*stringThe plaintext signed token (s + 32 hex). Returned exactly once, here;
only its hash is stored. Needed separately from url for the expire
route.
url*stringHost-based preview URL, <scheme>://<port>-<token>.<domain>/ — the
token replaces the sandbox id in the hostname, so the link reveals no
sandbox identity.
curl -X GET 'https://example.com/sandboxes/string/ports/0/signed-preview-url'{ "expires_at": "2019-08-24T14:15:22Z", "token": "string", "url": "string"}Idempotent by design: 204 on a real revocation AND on any no-match —
unknown/already-expired token, or a token that belongs to a different
(vm_id, port) than the authenticated route (not yours to expire, treated as
no-match rather than disclosed). 404 only for the sandbox-ownership
failure. The :token path param is the plaintext credential — never logged
(spans record the matched route template, not the raw path).
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).
Scope: write:sandboxes
id*stringsandbox id (region-tagged external id or bare UUID)
port*integerin-VM TCP port the link was minted for
int32token*stringthe plaintext signed token to revoke
Link revoked (or was already gone / not a match — idempotent)
curl -X POST 'https://example.com/sandboxes/string/ports/0/signed-preview-url/string/expire'