Reservations
AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
limit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of reservations
application/json- response
GET /reservations response.
next_cursor?|The cursor for the next page, or null on the last page.
reservations*array<>The reservations in this page.
curl -X GET 'https://example.com/reservations'{ "next_cursor": "string", "reservations": [ { "activated_at": "2019-08-24T14:15:22Z", "auto_renew": true, "capacity": null, "created_at": "2019-08-24T14:15:22Z", "end_reason": null, "ended_at": "2019-08-24T14:15:22Z", "id": "string", "model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "origin": "explicit", "pending_mac_started_at": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "period_n": 0, "period_seconds": 0, "period_started_at": "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, "resources_used": { "disk_mib": 0, "memory_mib": 0, "vcpus": 0 }, "sandboxes_per_mac": 0, "slots_used": 0, "status": "pending_charge" } ]}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
Idempotency-Key*stringUnique per organization. A replay with the same body returns the existing reservation
application/json- body
POST /reservations body.
auto_renew?|Renew the reservation near each period end while a macOS sandbox is active on it. Defaults to the organization's auto-reserve setting.
model?|Mac model slug from GET /mac-models. Omitted, null, or blank uses the region's default model, initially m4-10c-16g. If that model is unavailable, the purchase fails; it never upgrades to another model.
region*stringRegion slug whose Macs to reserve. Blank or local names no region:
when this API serves exactly one region with Macs, the reservation is
made there; otherwise the project, organization, then platform default
applies.
The reservation, unchanged
application/json- response
A Mac reservation.
activated_at?|When the reservation became active.
date-timeauto_renew*booleanThe reservation renews itself shortly before period_end (an hour by
default) while a macOS sandbox is active on it; an idle reservation lapses
instead.
capacity?|The reserved model's CPU, memory, and sandbox disk room. Fixed at purchase. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
created_at*stringWhen the reservation was created.
date-timeend_reason?|Why the reservation ended, or null while it is live.
ended_at?|When the reservation ended.
date-timeid*stringThe reservation ID.
model?|The reserved Mac model. Fixed at purchase, including renewal and replacement. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the lease was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create under
the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began waiting for a Mac: at its first charge, or when it moved after its Mac was lost. Kept after a Mac claims it.
date-timeperiod_end?|When the reservation 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).
date-timeperiod_n*integerThe current paid period (1-based).
int32period_seconds*integerThe period length in seconds.
int64period_started_at?|When the current period started.
date-timeproject_id*stringThe project whose key bought the reservation. The reservation serves
every project of the organization; this project's monthly budget gates
its renewals, manual and automatic, which answer
PROJECT_BUDGET_EXCEEDED while the project is held.
uuidregion*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after its Mac was lost.
date-timerenewal_error?|Why the renewal of the next period failed (billing refused it, or the
balance was too low); the reservation ends at period_end unless renewed by
hand. Null when no renewal has failed.
renewal_pending*booleanA renewal charge is still waiting for billing's answer.
resources_used*CPU and memory held by the sandboxes on this reservation's Mac, including paused sandboxes and sandboxes still being deleted, and the disk its sandboxes hold, stopped sandboxes included. Sandboxes that no Mac has claimed yet are not counted.
sandboxes_per_mac*integerMost sandboxes this reservation's Mac runs at once, subject to CPU, memory, and disk fit. Stopped sandboxes do not count. 0 when the reservation takes no new sandbox: its capacity is null, or fits no minimum-sized sandbox.
int32slots_used*integermacOS sandboxes currently occupying this reservation's Mac.
int64status*MacReservationStatusThe reservation status.
"pending_charge""pending_mac""active""ending""released""failed"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, "capacity": null, "created_at": "2019-08-24T14:15:22Z", "end_reason": null, "ended_at": "2019-08-24T14:15:22Z", "id": "string", "model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "origin": "explicit", "pending_mac_started_at": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "period_n": 0, "period_seconds": 0, "period_started_at": "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, "resources_used": { "disk_mib": 0, "memory_mib": 0, "vcpus": 0 }, "sandboxes_per_mac": 0, "slots_used": 0, "status": "pending_charge"}Reserves up to 100 Macs of one model in one region. Each reserved Mac is one reservation with its own period and charge.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
Idempotency-Key*stringUnique per organization. A replay with the same body returns the same reservations
application/json- body
POST /reservations/bulk body.
auto_renew?|Renew each reservation near each period end while a macOS sandbox is active on it. Defaults to the organization's auto-reserve setting.
count*integerHow many Macs to reserve, 1 to 100.
int32min_count?|The fewest Macs to accept, 1 to count. Omitted means count: all or nothing. With fewer than count Macs free but at least min_count, the request reserves as many as are free.
int32model?|Mac model slug from GET /mac-models. Omitted, null, or blank uses the region's default model, initially m4-10c-16g. If that model is unavailable, the purchase fails; it never upgrades to another model.
region*stringRegion slug whose Macs to reserve. Blank or local names no region:
when this API serves exactly one region with Macs, the reservations are
made there; otherwise the project, organization, then platform default
applies.
The reservation batch, unchanged
application/json- response
The reservations one bulk purchase created.
requested*integerThe request's count.
int32reservations*array<>The created reservations, one per reserved Mac, each with its own ID, period and charge.
reserved*integerHow many reservations this request created, from min_count to count. A reservation whose charge did not succeed counts here and shows status failed with end reason charge_failed.
int32curl -X POST 'https://example.com/reservations/bulk' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "count": 0, "region": "string"}'{ "requested": 0, "reservations": [ { "activated_at": "2019-08-24T14:15:22Z", "auto_renew": true, "capacity": null, "created_at": "2019-08-24T14:15:22Z", "end_reason": null, "ended_at": "2019-08-24T14:15:22Z", "id": "string", "model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "origin": "explicit", "pending_mac_started_at": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "period_n": 0, "period_seconds": 0, "period_started_at": "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, "resources_used": { "disk_mib": 0, "memory_mib": 0, "vcpus": 0 }, "sandboxes_per_mac": 0, "slots_used": 0, "status": "pending_charge" } ], "reserved": 0}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
id*stringThe reservation ID
The reservation
application/json- response
A Mac reservation.
activated_at?|When the reservation became active.
date-timeauto_renew*booleanThe reservation renews itself shortly before period_end (an hour by
default) while a macOS sandbox is active on it; an idle reservation lapses
instead.
capacity?|The reserved model's CPU, memory, and sandbox disk room. Fixed at purchase. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
created_at*stringWhen the reservation was created.
date-timeend_reason?|Why the reservation ended, or null while it is live.
ended_at?|When the reservation ended.
date-timeid*stringThe reservation ID.
model?|The reserved Mac model. Fixed at purchase, including renewal and replacement. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the lease was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create under
the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began waiting for a Mac: at its first charge, or when it moved after its Mac was lost. Kept after a Mac claims it.
date-timeperiod_end?|When the reservation 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).
date-timeperiod_n*integerThe current paid period (1-based).
int32period_seconds*integerThe period length in seconds.
int64period_started_at?|When the current period started.
date-timeproject_id*stringThe project whose key bought the reservation. The reservation serves
every project of the organization; this project's monthly budget gates
its renewals, manual and automatic, which answer
PROJECT_BUDGET_EXCEEDED while the project is held.
uuidregion*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after its Mac was lost.
date-timerenewal_error?|Why the renewal of the next period failed (billing refused it, or the
balance was too low); the reservation ends at period_end unless renewed by
hand. Null when no renewal has failed.
renewal_pending*booleanA renewal charge is still waiting for billing's answer.
resources_used*CPU and memory held by the sandboxes on this reservation's Mac, including paused sandboxes and sandboxes still being deleted, and the disk its sandboxes hold, stopped sandboxes included. Sandboxes that no Mac has claimed yet are not counted.
sandboxes_per_mac*integerMost sandboxes this reservation's Mac runs at once, subject to CPU, memory, and disk fit. Stopped sandboxes do not count. 0 when the reservation takes no new sandbox: its capacity is null, or fits no minimum-sized sandbox.
int32slots_used*integermacOS sandboxes currently occupying this reservation's Mac.
int64status*MacReservationStatusThe reservation status.
"pending_charge""pending_mac""active""ending""released""failed"curl -X GET 'https://example.com/reservations/string'{ "activated_at": "2019-08-24T14:15:22Z", "auto_renew": true, "capacity": null, "created_at": "2019-08-24T14:15:22Z", "end_reason": null, "ended_at": "2019-08-24T14:15:22Z", "id": "string", "model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "origin": "explicit", "pending_mac_started_at": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "period_n": 0, "period_seconds": 0, "period_started_at": "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, "resources_used": { "disk_mib": 0, "memory_mib": 0, "vcpus": 0 }, "sandboxes_per_mac": 0, "slots_used": 0, "status": "pending_charge"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
id*stringThe reservation ID
application/json- body
PATCH /reservations/{id} body.
auto_renew*booleanRenew the reservation near each period end while a macOS sandbox is active
on it; off lets it lapse at period_end.
The reservation
application/json- response
A Mac reservation.
activated_at?|When the reservation became active.
date-timeauto_renew*booleanThe reservation renews itself shortly before period_end (an hour by
default) while a macOS sandbox is active on it; an idle reservation lapses
instead.
capacity?|The reserved model's CPU, memory, and sandbox disk room. Fixed at purchase. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
created_at*stringWhen the reservation was created.
date-timeend_reason?|Why the reservation ended, or null while it is live.
ended_at?|When the reservation ended.
date-timeid*stringThe reservation ID.
model?|The reserved Mac model. Fixed at purchase, including renewal and replacement. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the lease was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create under
the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began waiting for a Mac: at its first charge, or when it moved after its Mac was lost. Kept after a Mac claims it.
date-timeperiod_end?|When the reservation 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).
date-timeperiod_n*integerThe current paid period (1-based).
int32period_seconds*integerThe period length in seconds.
int64period_started_at?|When the current period started.
date-timeproject_id*stringThe project whose key bought the reservation. The reservation serves
every project of the organization; this project's monthly budget gates
its renewals, manual and automatic, which answer
PROJECT_BUDGET_EXCEEDED while the project is held.
uuidregion*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after its Mac was lost.
date-timerenewal_error?|Why the renewal of the next period failed (billing refused it, or the
balance was too low); the reservation ends at period_end unless renewed by
hand. Null when no renewal has failed.
renewal_pending*booleanA renewal charge is still waiting for billing's answer.
resources_used*CPU and memory held by the sandboxes on this reservation's Mac, including paused sandboxes and sandboxes still being deleted, and the disk its sandboxes hold, stopped sandboxes included. Sandboxes that no Mac has claimed yet are not counted.
sandboxes_per_mac*integerMost sandboxes this reservation's Mac runs at once, subject to CPU, memory, and disk fit. Stopped sandboxes do not count. 0 when the reservation takes no new sandbox: its capacity is null, or fits no minimum-sized sandbox.
int32slots_used*integermacOS sandboxes currently occupying this reservation's Mac.
int64status*MacReservationStatusThe reservation status.
"pending_charge""pending_mac""active""ending""released""failed"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, "capacity": null, "created_at": "2019-08-24T14:15:22Z", "end_reason": null, "ended_at": "2019-08-24T14:15:22Z", "id": "string", "model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "origin": "explicit", "pending_mac_started_at": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "period_n": 0, "period_seconds": 0, "period_started_at": "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, "resources_used": { "disk_mib": 0, "memory_mib": 0, "vcpus": 0 }, "sandboxes_per_mac": 0, "slots_used": 0, "status": "pending_charge"}Charges the next period of an active reservation; period_end moves out by one period on the same Mac. A retry with the same idempotency key never charges twice.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
id*stringThe reservation ID
Idempotency-Key*stringUnique per reservation renewal. A replay returns the reservation without charging another period
The reservation
application/json- response
A Mac reservation.
activated_at?|When the reservation became active.
date-timeauto_renew*booleanThe reservation renews itself shortly before period_end (an hour by
default) while a macOS sandbox is active on it; an idle reservation lapses
instead.
capacity?|The reserved model's CPU, memory, and sandbox disk room. Fixed at purchase. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
created_at*stringWhen the reservation was created.
date-timeend_reason?|Why the reservation ended, or null while it is live.
ended_at?|When the reservation ended.
date-timeid*stringThe reservation ID.
model?|The reserved Mac model. Fixed at purchase, including renewal and replacement. Null on reservations bought before Mac models were recorded; such a reservation takes no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the lease was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create under
the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began waiting for a Mac: at its first charge, or when it moved after its Mac was lost. Kept after a Mac claims it.
date-timeperiod_end?|When the reservation 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).
date-timeperiod_n*integerThe current paid period (1-based).
int32period_seconds*integerThe period length in seconds.
int64period_started_at?|When the current period started.
date-timeproject_id*stringThe project whose key bought the reservation. The reservation serves
every project of the organization; this project's monthly budget gates
its renewals, manual and automatic, which answer
PROJECT_BUDGET_EXCEEDED while the project is held.
uuidregion*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after its Mac was lost.
date-timerenewal_error?|Why the renewal of the next period failed (billing refused it, or the
balance was too low); the reservation ends at period_end unless renewed by
hand. Null when no renewal has failed.
renewal_pending*booleanA renewal charge is still waiting for billing's answer.
resources_used*CPU and memory held by the sandboxes on this reservation's Mac, including paused sandboxes and sandboxes still being deleted, and the disk its sandboxes hold, stopped sandboxes included. Sandboxes that no Mac has claimed yet are not counted.
sandboxes_per_mac*integerMost sandboxes this reservation's Mac runs at once, subject to CPU, memory, and disk fit. Stopped sandboxes do not count. 0 when the reservation takes no new sandbox: its capacity is null, or fits no minimum-sized sandbox.
int32slots_used*integermacOS sandboxes currently occupying this reservation's Mac.
int64status*MacReservationStatusThe reservation status.
"pending_charge""pending_mac""active""ending""released""failed"curl -X POST 'https://example.com/reservations/string/renew' \ -H 'Idempotency-Key: string'{ "activated_at": "2019-08-24T14:15:22Z", "auto_renew": true, "capacity": null, "created_at": "2019-08-24T14:15:22Z", "end_reason": null, "ended_at": "2019-08-24T14:15:22Z", "id": "string", "model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "origin": "explicit", "pending_mac_started_at": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "period_n": 0, "period_seconds": 0, "period_started_at": "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, "resources_used": { "disk_mib": 0, "memory_mib": 0, "vcpus": 0 }, "sandboxes_per_mac": 0, "slots_used": 0, "status": "pending_charge"}