Reserving Capacity

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:

Rule	Failure
`startsAt` / `endsAt` UTC and 15-minute aligned	Misaligned values rejected.
`endsAt == startsAt + 15 minutes`	Multi-interval spans rejected — enumerate intervals instead.
`capacityGb` is a positive multiple of 4	Other values rejected. The grain is 1 GB-hour (= 4 GB × 15 min).
`startsAt >= now + 30 minutes`	Lead-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:

`reason`	Meaning
`insufficient_capacity`	Request exceeds current `reservableGb` for the interval (either the platform-side limit or your org’s `max_memory_gb`).
`concurrent_write`	Another 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.

Behavior	Response
Same key, same body	Cached response from the first call.
Same key, different body	`409 idempotency_key_conflict`.
No key	Request 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 param	Required	Meaning
`from`	yes	Return reservations whose `createdAt >= from`.
`to`	yes	Return reservations whose `createdAt < to`.
`cursor`	no	Pagination cursor from a previous response’s `nextCursor`.
`limit`	no	Max 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

Operation	Atomic across	On failure
`POST /reservations`	All intervals in the request	Nothing 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.

Getting Started

Sandboxes

Reserved Capacity

Agent SDK

Hosted Agents

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Make a reservation

Validation

Capacity shortfall (409)

Idempotency

Cancellation does not exist

List your reservations

Concurrency and atomicity

Where to go next

Usage and overage

Reading the calendar

API reference

​Make a reservation

​Validation

​Capacity shortfall (409)

​Idempotency

​Cancellation does not exist

​List your reservations

​Concurrency and atomicity

​Where to go next

Usage and overage

Reading the calendar

API reference

Make a reservation

Validation

Capacity shortfall (409)

Idempotency

Cancellation does not exist

List your reservations

Concurrency and atomicity

Where to go next