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_id": "string", "reissued_at": "2019-08-24T14:15:22Z", "renewal_error": "string", "renewal_pending": true, "resources_used": { "cores": 0, "disk_mib": 0, "memory_mib": 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_id*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 cores, memory and disk space for sandboxes of this reservation's Mac, set at purchase. Null when unknown; such a reservation accepts 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 when model information is unavailable; such a reservation accepts no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the reservation was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create or start
under the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began to wait for a Mac: at its first charge, or when it moved after a Mac failure. Kept after a Mac takes it.
date-timeperiod_end?|When the reservation ends unless renewed. Absent until a Mac first takes the reservation; period 1 starts then, so the wait 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_id*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after a Mac failure.
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*The cores, memory and disk space in use on this reservation's Mac.
Paused sandboxes and sandboxes with status deleting count.
slots_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_id": "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_id": "string", "reissued_at": "2019-08-24T14:15:22Z", "renewal_error": "string", "renewal_pending": true, "resources_used": { "cores": 0, "disk_mib": 0, "memory_mib": 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, or fewer left under the organization's Mac reservation limit, but at least min_count, the request reserves as many as it can.
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_id*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_id": "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_id": "string", "reissued_at": "2019-08-24T14:15:22Z", "renewal_error": "string", "renewal_pending": true, "resources_used": { "cores": 0, "disk_mib": 0, "memory_mib": 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 cores, memory and disk space for sandboxes of this reservation's Mac, set at purchase. Null when unknown; such a reservation accepts 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 when model information is unavailable; such a reservation accepts no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the reservation was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create or start
under the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began to wait for a Mac: at its first charge, or when it moved after a Mac failure. Kept after a Mac takes it.
date-timeperiod_end?|When the reservation ends unless renewed. Absent until a Mac first takes the reservation; period 1 starts then, so the wait 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_id*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after a Mac failure.
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*The cores, memory and disk space in use on this reservation's Mac.
Paused sandboxes and sandboxes with status deleting count.
slots_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_id": "string", "reissued_at": "2019-08-24T14:15:22Z", "renewal_error": "string", "renewal_pending": true, "resources_used": { "cores": 0, "disk_mib": 0, "memory_mib": 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 cores, memory and disk space for sandboxes of this reservation's Mac, set at purchase. Null when unknown; such a reservation accepts 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 when model information is unavailable; such a reservation accepts no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the reservation was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create or start
under the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began to wait for a Mac: at its first charge, or when it moved after a Mac failure. Kept after a Mac takes it.
date-timeperiod_end?|When the reservation ends unless renewed. Absent until a Mac first takes the reservation; period 1 starts then, so the wait 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_id*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after a Mac failure.
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*The cores, memory and disk space in use on this reservation's Mac.
Paused sandboxes and sandboxes with status deleting count.
slots_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_id": "string", "reissued_at": "2019-08-24T14:15:22Z", "renewal_error": "string", "renewal_pending": true, "resources_used": { "cores": 0, "disk_mib": 0, "memory_mib": 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 cores, memory and disk space for sandboxes of this reservation's Mac, set at purchase. Null when unknown; such a reservation accepts 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 when model information is unavailable; such a reservation accepts no new sandbox.
org_id*stringThe organization ID.
uuidorigin*MacReservationOriginHow the reservation was bought: explicit by POST /reservations or a
create with reservation: "new", and auto by a macOS create or start
under the organization's auto-reserve setting.
"explicit""auto"pending_mac_started_at?|When the reservation last began to wait for a Mac: at its first charge, or when it moved after a Mac failure. Kept after a Mac takes it.
date-timeperiod_end?|When the reservation ends unless renewed. Absent until a Mac first takes the reservation; period 1 starts then, so the wait 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_id*stringThe reservation region.
reissued_at?|Set when the reservation moved to another Mac after a Mac failure.
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*The cores, memory and disk space in use on this reservation's Mac.
Paused sandboxes and sandboxes with status deleting count.
slots_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_id": "string", "reissued_at": "2019-08-24T14:15:22Z", "renewal_error": "string", "renewal_pending": true, "resources_used": { "cores": 0, "disk_mib": 0, "memory_mib": 0 }, "slots_used": 0, "status": "pending_charge"}