Skip to main content
There are two write-side endpoints: POST to commit, GET to audit. Both work in terms of intervals and integer GB; there are no individual blocks or unit IDs. Reservations compose at 15-minute granularity, so a multi-hour or multi-day commitment is just a list of contiguous (or non-contiguous) intervals. Reserve precisely the windows your workload occupies — there’s no minimum block size beyond the interval itself, and no requirement to reserve continuously through periods you won’t use.

​
Make a reservation

One call commits capacity to one or more 15-minute intervals. Atomic across the whole request — either every interval is reserved, or nothing is.
curl
curl -X POST https://app.opencomputer.dev/api/capacity/reservations \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -H "Idempotency-Key: nightly-batch-2026-04-29" \
  -H "Content-Type: application/json" \
  -d '{
    "intervals": [
      { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
      { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
    ]
  }'
Response (success): 
{
  "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
  "createdAt": "2026-04-28T18:00:05Z",
  "intervals": [
    { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
    { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
  ]
}

​
Validation

The server rejects malformed requests with 400 Bad Request and a plain text error message:
RuleFailure
startsAt / endsAt UTC and 15-minute alignedMisaligned values rejected.
endsAt == startsAt + 15 minutesMulti-interval spans rejected — enumerate intervals instead.
capacityGb is a positive multiple of 4Other values rejected. The grain is 1 GB-hour (= 4 GB × 15 min).
startsAt >= now + 30 minutesLead-time violation rejected.

​
Capacity shortfall (409)

When the request is well-formed but doesn’t fit available capacity, the server returns 409 capacity_not_available with a list of every problematic interval, so the client can retry with adjusted numbers in a single round-trip: 
{
  "error": "capacity_not_available",
  "intervals": [
    {
      "startsAt": "2026-04-29T02:00:00Z",
      "requestedGb": 80,
      "reservableGb": 28,
      "reason": "insufficient_capacity"
    }
  ]
}
reason is one of:
reasonMeaning
insufficient_capacityRequest exceeds current reservableGb for the interval (either the platform-side limit or your org’s max_memory_gb).
concurrent_writeAnother reservation for the same interval committed first; retry with the updated reservableGb.

​
Idempotency

Both reservation writes accept an Idempotency-Key header. The server stores the key with a hash of the request body and the response. Retries return the cached response, even if the original write succeeded.
BehaviorResponse
Same key, same bodyCached response from the first call.
Same key, different body409 idempotency_key_conflict.
No keyRequest processed normally; retries are the client’s problem.
Build keys from a deterministic name for the operation, e.g. reserve-nightly-2026-04-29, so a client retry sends the same key.

​
Cancellation does not exist

Reservations are non-refundable. Once committed, capacity is permanent for that interval. There is no DELETE, no cancel endpoint, no transfer to a different interval. The hedge: book conservatively, only what you’re confident you’ll run, and let on-demand absorb the variability above.

​
List your reservations

The audit list. Returns every reservation event you’ve made in the time window, in reverse-chronological order.
curl
curl "https://app.opencomputer.dev/api/capacity/reservations?from=2026-04-01T00:00:00Z&to=2026-05-01T00:00:00Z" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"
Response: 
{
  "from": "2026-04-01T00:00:00Z",
  "to":   "2026-05-01T00:00:00Z",
  "reservations": [
    {
      "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
      "createdAt": "2026-04-28T18:00:05Z",
      "intervals": [
        { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
        { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
      ]
    }
  ],
  "nextCursor": null
}
Query paramRequiredMeaning
fromyesReturn reservations whose createdAt >= from.
toyesReturn reservations whose createdAt < to.
cursornoPagination cursor from a previous response’s nextCursor.
limitnoMax reservations per page. Server applies a ceiling.
For end-of-month reconciliation, list reservations and group totals by interval. The calendar gives you the current per-interval state; the list gives you the history of how it got there.

​
Concurrency and atomicity

OperationAtomic acrossOn failure
POST /reservationsAll intervals in the requestNothing reserved.
Parallel writes to the same interval from the same org serialize on the server. Whichever request commits first claims the remaining capacity; later requests see the updated reservableGb in their validation error.

​
Where to go next

Usage and overage

How reserved capacity consumes actual usage.

Reading the calendar

Plan before you commit.

API reference

Every endpoint with full request/response shapes.