Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Reading the Calendar

The calendar is how you plan. It answers, per 15-minute interval:
  1. How much GB can I still reserve here?
  2. How much do I already hold here?
  3. What's the policy cap I'm working under?
The calendar never holds capacity — it's a snapshot. Write validation is always authoritative.

Request

curl
curl "https://app.opencomputer.dev/api/capacity/calendar?from=2026-04-29T02:00:00Z&to=2026-04-29T04:00:00Z" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"
Query paramRequiredNotes
fromyesWindow start, aligned to 15 minutes, UTC.
toyesWindow end, aligned to 15 minutes, UTC.

Response

json
{
  "from":      "2026-04-29T02:00:00Z",
  "to":        "2026-04-29T04:00:00Z",
  "resource":  "memory_gb",
  "intervals": [
    {
      "startsAt": "2026-04-29T02:00:00Z",
      "endsAt":   "2026-04-29T02:15:00Z",
      "reservationLimitGb": 300,
      "reservedGb": 80,
      "reservableGb": 220
    }
  ]
}

Top-level fields

FieldMeaning
from, toThe query window, echoed back.
resourceAlways memory_gb in v1.
intervalsOne row per 15-minute interval in the window.

Per-interval fields

FieldMeaning
startsAt, endsAtThe 15-minute UTC interval.
reservationLimitGbMaximum GB this org may commit in this interval (your max_memory_gb).
reservedGbTotal GB this org already has reserved in this interval.
reservableGbAdditional GB the server would currently accept. This is the number to plan against.
The server enforces a 30-minute minimum lead time between now and a reservation's startsAt. Intervals starting sooner are returned in the calendar (so you can see your existing commitments) but the write endpoint rejects new reservations against them.

reservableGb is the planning field

Everything you need to decide "can I reserve 50 GB at 02:00?" is in reservableGb. The other fields are context:
  • reservationLimitGb minus reservedGb is your remaining headroom under your org's per-interval cap. The server may still reduce reservableGb below that headroom because of platform-level capacity.
  • reservedGb lets you confirm what you already hold without a separate call to GET /api/capacity/reservations.

The calendar is a snapshot, not a hold

The calendar reflects state at the moment the request was served. Capacity can change between read and write — another tenant (or you, in another tab) may reserve in the meantime.
This is fine. Writes are atomic and validation is authoritative: if capacity moved, the write returns capacity_not_available and you read again.

Race patterns

Plan then write

text
GET  /api/capacity/calendar                       → reservableGb: 220
POST /api/capacity/reservations  capacityGb: 80   → applied

Plan then write, lost race

text
GET  /api/capacity/calendar                       → reservableGb: 48
POST /api/capacity/reservations  capacityGb: 80   → rejected with reservableGb: 28
On rejection, read the calendar again and either:
  • Re-submit with the actual current reservableGb, or
  • Accept a smaller amount via multiple writes at different intervals, or
  • Bail out — not all demand fits.
V1 does not accept a "reserve up to N, at least M" shape. Keep retries explicit in client code.

Multi-interval request, partial conflict

text
POST /api/capacity/reservations
  intervals: [
    02:00 → 02:15, 80 GB
    02:15 → 02:30, 80 GB    # only 30 available
  ]
→ rejected; nothing reserved
Multi-interval writes are atomic. If any interval fails, none are reserved. Split your request if you want partial success.

Choosing the window

The calendar accepts arbitrary from–to ranges aligned to the 15-minute grid. Practical guidance:
  • For interactive planning UIs, pull a day or a week at a time; render a heatmap of reservableGb.
  • For scheduled reservation scripts, query just the intervals you're about to write — don't pull a week if you only need two hours.
  • For large time ranges, expect the response to scale linearly (4 × hours rows). Chunk your queries if you need months.

What the calendar does not tell you

  • Past reservation events. Use GET /api/capacity/reservations for the audit log.
  • Other customers' commitments. Numbers are org-scoped.
  • Future limit changes. Your reservationLimitGb reflects current policy.

Where to go next

Reserving capacity
The write flow, idempotency, atomicity.
Concepts
Vocabulary: intervals, reservations, the log.
Get calendar endpoint
Full request/response reference.