---
title: "Queue a resource booking"
method: POST
path: "/api/resources/book"
tags: ["resources"]
---

# Queue a resource booking

`POST /api/resources/book`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/resources/book`
- Auth: HTTP bearer

Clerk session or agt_ token with `resources:book`. Queues a booking envelope (returns `queued`, not confirmed). IDEMPOTENT: a repeat within 30 days for the exact same start time is recognized (`was_dup: true`); an `Idempotency-Key` additionally replays the first result. Agent callers MUST supply `email`.

## Headers

- `Idempotency-Key` string

## Request body

- BookRequest
  - `resource_id` string, required: e.g. "ft-9" or "printer-prusa-1".
  - `start_iso` string, date-time, required
  - `end_iso` string, date-time, required: After start.
  - `purpose` string: Free text, trimmed + clipped to 600 chars server-side.
  - `email` string: Required for agent callers; optional on the Clerk path.

## Response `200`

Booking queued (or recognized as a duplicate).

- QueueResponse: Shared shape for the queue-and-forget writes (rsvp, book).
  - `ok` boolean, required
  - `queued` boolean, required
  - `was_dup` boolean: True when semantic dedupe recognized this as a repeat within the window.
  - `rate` RateInfo: Per-token rate-limit snapshot returned by write endpoints.
    - `current` integer
    - `remaining` integer
    - `limit` integer
  - `via` 'clerk' | 'agent'
  - `note` string

## Other responses

- `400`: Missing/invalid fields or missing email on the agent path.
- `401`: No auth.
- `403`: Scope/tier not authorized.
- `404`: resource_id not found / not bookable.
- `413`: Body exceeds 8KB.
- `429`: Per-token rate limit exceeded.
- `500`: KV write failed.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)