Sign Up
Docs v2.0

Reservations

GET /reservations — the organization's leases, newest first (open ones plus those ended in the last 30 days).

GET
/reservations

Authorization

headerAuthorizationBearer <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

Response Body

The organization's leases

application/json
  1. response

GET /reservations response.

reservations*array<>
curl -X GET 'https://example.com/reservations'
{  "reservations": [    {      "activated_at": "2019-08-24T14:15:22Z",      "auto_renew": true,      "created_at": "2019-08-24T14:15:22Z",      "end_reason": "string",      "ended_at": "2019-08-24T14:15:22Z",      "id": "string",      "lease_generation": 0,      "leasing_since": "2019-08-24T14:15:22Z",      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",      "origin": "string",      "period_end": "2019-08-24T14:15:22Z",      "period_hours": 0,      "period_n": 0,      "period_start": "2019-08-24T14:15:22Z",      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",      "region": "string",      "reissued_at": "2019-08-24T14:15:22Z",      "renewal_error": "string",      "renewal_pending": true,      "runner_id": "string",      "slots_used": 0,      "status": "string",      "vms_per_mac": 0    }  ]}

POST /reservations — lease one Mac in a region for the caller's organization. Charges the first period, then publishes the lease to the region's unleased Macs; period 1 starts when a Mac claims it.

POST
/reservations

Authorization

headerAuthorizationBearer <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

Header Parameters

Idempotency-Key*string

Required. Unique per organization; a replay with the same body returns the existing lease

Request Body

application/json
  1. body

POST /reservations body.

auto_renew?|

Renew the lease near each period end while a macOS sandbox is active on it. Defaults to the organization's auto-reserve setting.

region*string

Region slug whose Macs to lease from.

vms_per_mac?|

macOS VMs this lease allows at once (1 or 2; default 2, Apple's limit).

Formatint32

Response Body

Idempotent replay of an existing lease

application/json
  1. response

A Mac lease.

activated_at?|
Formatdate-time
auto_renew*boolean

The lease renews itself shortly before period_end (an hour by default) while a macOS sandbox is active on it; an idle lease lapses instead.

created_at*string
Formatdate-time
end_reason?|

expired | released | charge_failed | not_accepted | reissued | operator.

ended_at?|
Formatdate-time
id*string

External reservation id (region-tagged).

lease_generation*integer
Formatint64
leasing_since?|
Formatdate-time
org_id*string
Formatuuid
origin*string

explicit (bought by POST /reservations or a create with reservation: "new") | auto (bought by a macOS create under the organization's auto-reserve setting).

period_end?|

When the lease ends unless renewed. Absent until a Mac first claims it (period 1 starts at the claim, so waiting for a Mac is not paid time).

Formatdate-time
period_hours*integer

The period length in hours.

Formatint32
period_n*integer

The current paid period (1-based).

Formatint32
period_start?|
Formatdate-time
project_id*string

The project whose key bought the lease. The lease serves every project of the org; this project's monthly budget gates its renewals, manual and automatic (project_budget_exceeded while the project is held).

Formatuuid
region*string
reissued_at?|

Set when the lease moved to another Mac after its Mac was lost.

Formatdate-time
renewal_error?|

Why the renewal of the next period failed (billing refused it, or the balance was too low); the lease ends at period_end unless renewed by hand. Null when no renewal has failed.

renewal_pending*boolean

A renewal charge is still waiting for billing's answer.

runner_id?|

The Mac holding the lease; absent until a Mac claims it.

slots_used*integer

macOS VMs currently occupying this lease's Mac.

Formatint64
status*string

pending_charge | leasing | active | ending | released | failed.

vms_per_mac*integer
Formatint32
curl -X POST 'https://example.com/reservations' \  -H 'Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "region": "string"}'
{  "activated_at": "2019-08-24T14:15:22Z",  "auto_renew": true,  "created_at": "2019-08-24T14:15:22Z",  "end_reason": "string",  "ended_at": "2019-08-24T14:15:22Z",  "id": "string",  "lease_generation": 0,  "leasing_since": "2019-08-24T14:15:22Z",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "origin": "string",  "period_end": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_n": 0,  "period_start": "2019-08-24T14:15:22Z",  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "region": "string",  "reissued_at": "2019-08-24T14:15:22Z",  "renewal_error": "string",  "renewal_pending": true,  "runner_id": "string",  "slots_used": 0,  "status": "string",  "vms_per_mac": 0}

GET /reservations/{id} — one lease.

GET
/reservations/{id}

Authorization

headerAuthorizationBearer <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

Path Parameters

id*string

External reservation id

Response Body

The lease

application/json
  1. response

A Mac lease.

activated_at?|
Formatdate-time
auto_renew*boolean

The lease renews itself shortly before period_end (an hour by default) while a macOS sandbox is active on it; an idle lease lapses instead.

created_at*string
Formatdate-time
end_reason?|

expired | released | charge_failed | not_accepted | reissued | operator.

ended_at?|
Formatdate-time
id*string

External reservation id (region-tagged).

lease_generation*integer
Formatint64
leasing_since?|
Formatdate-time
org_id*string
Formatuuid
origin*string

explicit (bought by POST /reservations or a create with reservation: "new") | auto (bought by a macOS create under the organization's auto-reserve setting).

period_end?|

When the lease ends unless renewed. Absent until a Mac first claims it (period 1 starts at the claim, so waiting for a Mac is not paid time).

Formatdate-time
period_hours*integer

The period length in hours.

Formatint32
period_n*integer

The current paid period (1-based).

Formatint32
period_start?|
Formatdate-time
project_id*string

The project whose key bought the lease. The lease serves every project of the org; this project's monthly budget gates its renewals, manual and automatic (project_budget_exceeded while the project is held).

Formatuuid
region*string
reissued_at?|

Set when the lease moved to another Mac after its Mac was lost.

Formatdate-time
renewal_error?|

Why the renewal of the next period failed (billing refused it, or the balance was too low); the lease ends at period_end unless renewed by hand. Null when no renewal has failed.

renewal_pending*boolean

A renewal charge is still waiting for billing's answer.

runner_id?|

The Mac holding the lease; absent until a Mac claims it.

slots_used*integer

macOS VMs currently occupying this lease's Mac.

Formatint64
status*string

pending_charge | leasing | active | ending | released | failed.

vms_per_mac*integer
Formatint32
curl -X GET 'https://example.com/reservations/string'
{  "activated_at": "2019-08-24T14:15:22Z",  "auto_renew": true,  "created_at": "2019-08-24T14:15:22Z",  "end_reason": "string",  "ended_at": "2019-08-24T14:15:22Z",  "id": "string",  "lease_generation": 0,  "leasing_since": "2019-08-24T14:15:22Z",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "origin": "string",  "period_end": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_n": 0,  "period_start": "2019-08-24T14:15:22Z",  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "region": "string",  "reissued_at": "2019-08-24T14:15:22Z",  "renewal_error": "string",  "renewal_pending": true,  "runner_id": "string",  "slots_used": 0,  "status": "string",  "vms_per_mac": 0}

PATCH /reservations/{id} — turn a live lease's auto-renew on or off. Turning it on needs the `macos_sandboxes` flag; turning it off works without it, so an organization whose flag is off can let a lease lapse.

PATCH
/reservations/{id}

Authorization

headerAuthorizationBearer <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

Path Parameters

id*string

External reservation id

Request Body

application/json
  1. body

PATCH /reservations/{id} body.

auto_renew*boolean

Renew the lease near each period end while a macOS sandbox is active on it; off lets it lapse at period_end.

Response Body

The updated lease

application/json
  1. response

A Mac lease.

activated_at?|
Formatdate-time
auto_renew*boolean

The lease renews itself shortly before period_end (an hour by default) while a macOS sandbox is active on it; an idle lease lapses instead.

created_at*string
Formatdate-time
end_reason?|

expired | released | charge_failed | not_accepted | reissued | operator.

ended_at?|
Formatdate-time
id*string

External reservation id (region-tagged).

lease_generation*integer
Formatint64
leasing_since?|
Formatdate-time
org_id*string
Formatuuid
origin*string

explicit (bought by POST /reservations or a create with reservation: "new") | auto (bought by a macOS create under the organization's auto-reserve setting).

period_end?|

When the lease ends unless renewed. Absent until a Mac first claims it (period 1 starts at the claim, so waiting for a Mac is not paid time).

Formatdate-time
period_hours*integer

The period length in hours.

Formatint32
period_n*integer

The current paid period (1-based).

Formatint32
period_start?|
Formatdate-time
project_id*string

The project whose key bought the lease. The lease serves every project of the org; this project's monthly budget gates its renewals, manual and automatic (project_budget_exceeded while the project is held).

Formatuuid
region*string
reissued_at?|

Set when the lease moved to another Mac after its Mac was lost.

Formatdate-time
renewal_error?|

Why the renewal of the next period failed (billing refused it, or the balance was too low); the lease ends at period_end unless renewed by hand. Null when no renewal has failed.

renewal_pending*boolean

A renewal charge is still waiting for billing's answer.

runner_id?|

The Mac holding the lease; absent until a Mac claims it.

slots_used*integer

macOS VMs currently occupying this lease's Mac.

Formatint64
status*string

pending_charge | leasing | active | ending | released | failed.

vms_per_mac*integer
Formatint32
curl -X PATCH 'https://example.com/reservations/string' \  -H 'Content-Type: application/json' \  -d '{  "auto_renew": true}'
{  "activated_at": "2019-08-24T14:15:22Z",  "auto_renew": true,  "created_at": "2019-08-24T14:15:22Z",  "end_reason": "string",  "ended_at": "2019-08-24T14:15:22Z",  "id": "string",  "lease_generation": 0,  "leasing_since": "2019-08-24T14:15:22Z",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "origin": "string",  "period_end": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_n": 0,  "period_start": "2019-08-24T14:15:22Z",  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "region": "string",  "reissued_at": "2019-08-24T14:15:22Z",  "renewal_error": "string",  "renewal_pending": true,  "runner_id": "string",  "slots_used": 0,  "status": "string",  "vms_per_mac": 0}

POST /reservations/{id}/renew — charge the next period of an active lease; on acknowledgement `period_end` moves out by one period on the same Mac. The manual path; an `auto_renew` lease renews itself while a sandbox is active on it.

POST
/reservations/{id}/renew

Authorization

headerAuthorizationBearer <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

Path Parameters

id*string

External reservation id

Response Body

Renewed, or renewal pending while billing answers (renewal_pending)

application/json
  1. response

A Mac lease.

activated_at?|
Formatdate-time
auto_renew*boolean

The lease renews itself shortly before period_end (an hour by default) while a macOS sandbox is active on it; an idle lease lapses instead.

created_at*string
Formatdate-time
end_reason?|

expired | released | charge_failed | not_accepted | reissued | operator.

ended_at?|
Formatdate-time
id*string

External reservation id (region-tagged).

lease_generation*integer
Formatint64
leasing_since?|
Formatdate-time
org_id*string
Formatuuid
origin*string

explicit (bought by POST /reservations or a create with reservation: "new") | auto (bought by a macOS create under the organization's auto-reserve setting).

period_end?|

When the lease ends unless renewed. Absent until a Mac first claims it (period 1 starts at the claim, so waiting for a Mac is not paid time).

Formatdate-time
period_hours*integer

The period length in hours.

Formatint32
period_n*integer

The current paid period (1-based).

Formatint32
period_start?|
Formatdate-time
project_id*string

The project whose key bought the lease. The lease serves every project of the org; this project's monthly budget gates its renewals, manual and automatic (project_budget_exceeded while the project is held).

Formatuuid
region*string
reissued_at?|

Set when the lease moved to another Mac after its Mac was lost.

Formatdate-time
renewal_error?|

Why the renewal of the next period failed (billing refused it, or the balance was too low); the lease ends at period_end unless renewed by hand. Null when no renewal has failed.

renewal_pending*boolean

A renewal charge is still waiting for billing's answer.

runner_id?|

The Mac holding the lease; absent until a Mac claims it.

slots_used*integer

macOS VMs currently occupying this lease's Mac.

Formatint64
status*string

pending_charge | leasing | active | ending | released | failed.

vms_per_mac*integer
Formatint32
curl -X POST 'https://example.com/reservations/string/renew'
{  "activated_at": "2019-08-24T14:15:22Z",  "auto_renew": true,  "created_at": "2019-08-24T14:15:22Z",  "end_reason": "string",  "ended_at": "2019-08-24T14:15:22Z",  "id": "string",  "lease_generation": 0,  "leasing_since": "2019-08-24T14:15:22Z",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "origin": "string",  "period_end": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_n": 0,  "period_start": "2019-08-24T14:15:22Z",  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "region": "string",  "reissued_at": "2019-08-24T14:15:22Z",  "renewal_error": "string",  "renewal_pending": true,  "runner_id": "string",  "slots_used": 0,  "status": "string",  "vms_per_mac": 0}

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free