{ "openapi": "3.1.0", "info": { "title": "Bookrail API", "version": "2026-09-01", "description": "Booking infrastructure: availability, holds, bookings, their life cycle, and the events they emit.\n\nThis document is **generated** from the Zod schemas of the server and proved by a contract guard that\nvalidates every response of the test suite against the schema declared here. In case of a disagreement\nbetween this file and any prose documentation, this file is right.\n\n- Every instant is ISO 8601. Any explicit offset is accepted on input; every instant is returned in UTC.\n- Identifiers are prefixed (`bk_`, `res_`, `svc_`, …); the prefix says what the object is.\n- Lists are cursored: `?limit=&starting_after=`, never an offset, and never a total.\n- Every `POST /v1/...` honours `Idempotency-Key`. The same key within 24 hours replays the same response.", "x-bookrail-app-version": "0.16.0" }, "servers": [ { "url": "https://api.bookrail.dev", "description": "Bookrail cloud." }, { "url": "http://localhost:3000", "description": "A local `pnpm dev`, on the default `PORT`." } ], "tags": [ { "name": "meta", "description": "The specification itself." }, { "name": "project", "description": "The project a key belongs to." }, { "name": "availability", "description": "What can be booked, and when." }, { "name": "locations", "description": "Physical places, each with a time zone." }, { "name": "resources", "description": "What a booking consumes: a person, a room, a court, a piece of equipment." }, { "name": "resource_groups", "description": "Interchangeable resources, with an allocation strategy." }, { "name": "schedules", "description": "Opening hours and calendar exceptions." }, { "name": "services", "description": "What a customer books, with its durations, buffers, price and requirements." }, { "name": "policies", "description": "Cancellation, reschedule, no-show and confirmation rules." }, { "name": "customers", "description": "The people bookings are made for." }, { "name": "holds", "description": "Capacity taken for a few minutes, before it becomes a booking." }, { "name": "bookings", "description": "The booking and its life cycle." }, { "name": "events", "description": "The append-only log of everything that happened." }, { "name": "webhooks", "description": "Delivery endpoints, their signing secret and their delivery log." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/openapi.json": { "get": { "operationId": "openapi.get", "summary": "Fetch this OpenAPI document", "description": "The specification of this API, generated from the same Zod schemas the server validates with. No API key required.", "tags": ["meta"], "security": [], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } } } } }, "/v1/availability": { "post": { "operationId": "availability.search", "summary": "Search availability over a window", "tags": ["availability"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service_id": { "type": "string", "description": "Identifier of a service, prefixed with `svc_`.", "pattern": "^svc_[0-9a-f]{32}$", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "from": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "to": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "minItems": 1, "maxItems": 500 }, "customer_id": { "type": "string", "description": "Identifier of a customer, prefixed with `cus_`.", "pattern": "^cus_[0-9a-f]{32}$", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "granularity": { "type": "string", "enum": ["slots", "ranges"] }, "explain": { "type": "boolean" } }, "required": ["service_id", "from", "to"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `invalid_range`, `parameter_invalid`, `parameter_missing`, `range_too_large`, `service_without_duration`, `timezone_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/availability/check": { "post": { "operationId": "availability.check", "summary": "Check one precise instant", "description": "Feasibility at that instant, not alignment to the grid: a start the search would not offer still gets structured reasons.", "tags": ["availability"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service_id": { "type": "string", "description": "Identifier of a service, prefixed with `svc_`.", "pattern": "^svc_[0-9a-f]{32}$", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "minItems": 1, "maxItems": 500 } }, "required": ["service_id", "start"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityCheck" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `invalid_range`, `parameter_invalid`, `parameter_missing`, `range_too_large`, `service_without_duration`, `timezone_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/availability/next": { "get": { "operationId": "availability.next", "summary": "Find the next bookable slot", "description": "Searches in thirty day windows up to a ninety day horizon, stopping at the first window that contains a slot.", "tags": ["availability"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of a service, prefixed with `svc_`.", "pattern": "^svc_[0-9a-f]{32}$", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "required": true, "name": "service_id", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^[1-9]\\d{0,5}$" }, "required": false, "name": "quantity", "in": "query" }, { "schema": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "required": false, "name": "timezone", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityNext" } } } }, "400": { "description": "Error codes: `invalid_range`, `parameter_invalid`, `parameter_missing`, `range_too_large`, `service_without_duration`, `timezone_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings": { "post": { "operationId": "bookings.create", "summary": "Create a booking", "description": "With `hold_id` it converts the hold instead of taking new capacity. `payment.mode` other than `none`, and any `recurrence`, answer `400 not_yet_supported`.", "tags": ["bookings"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service_id": { "type": "string", "description": "Identifier of a service, prefixed with `svc_`.", "pattern": "^svc_[0-9a-f]{32}$", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "minItems": 1, "maxItems": 500 }, "customer_id": { "type": "string", "description": "Identifier of a customer, prefixed with `cus_`.", "pattern": "^cus_[0-9a-f]{32}$", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "customer": { "type": "object", "properties": { "external_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "email": { "type": ["string", "null"], "maxLength": 320, "format": "email" }, "phone": { "type": ["string", "null"], "minLength": 3, "maxLength": 50 }, "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "locale": { "type": ["string", "null"], "minLength": 2, "maxLength": 20 }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false }, "notes": { "type": ["string", "null"], "maxLength": 5000 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "source": { "type": "string", "enum": ["api", "widget", "portal", "import"] }, "hold_id": { "type": "string", "description": "Identifier of a hold, prefixed with `hold_`.", "pattern": "^hold_[0-9a-f]{32}$", "example": "hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "payment": { "type": ["object", "null"], "properties": { "mode": { "type": "string", "enum": ["none", "deposit", "full", "entitlement"] }, "entitlement_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 } }, "required": ["mode"], "additionalProperties": false }, "recurrence": { "type": ["object", "null"], "additionalProperties": {} } }, "required": ["service_id", "start"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `duration_not_offered`, `hold_mismatch`, `idempotency_key_reused`, `invalid_body`, `not_yet_supported`, `parameter_invalid`, `parameter_missing`, `resource_not_eligible`, `service_without_duration`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `hold_expired`, `hold_not_active`, `idempotency_key_in_progress`, `serialization_failure`, `slot_unavailable`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `customer_limit_reached`, `min_notice_violated`, `outside_booking_window`, `start_not_on_grid`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "bookings.list", "summary": "List bookings", "description": "`from` and `to` filter on `starts_at`: `from` included, `to` excluded.", "tags": ["bookings"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^bk_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Identifier of a customer, prefixed with `cus_`.", "pattern": "^cus_[0-9a-f]{32}$", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "required": false, "name": "customer_id", "in": "query" }, { "schema": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "required": false, "name": "resource_id", "in": "query" }, { "schema": { "type": "string", "description": "Identifier of a service, prefixed with `svc_`.", "pattern": "^svc_[0-9a-f]{32}$", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "required": false, "name": "service_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "held", "pending", "confirmed", "in_progress", "completed", "cancelled", "no_show", "rescheduled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["customer", "allocations.resource"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: customer, allocations.resource." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}": { "get": { "operationId": "bookings.get", "summary": "Retrieve a booking", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["customer", "allocations.resource"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: customer, allocations.resource." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}/cancel": { "post": { "operationId": "bookings.cancel", "summary": "Cancel a booking", "description": "`by` defaults to `customer`. `override_refund_percent` beats every tier, for any `by`. No money moves: the amounts written are expectations.", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": ["string", "null"], "maxLength": 1000 }, "by": { "type": "string", "enum": ["customer", "provider", "system"] }, "override_refund_percent": { "type": ["number", "null"], "minimum": 0, "maximum": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `invalid_transition`, `serialization_failure`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `complete_too_early`, `no_show_too_early`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}/check_in": { "post": { "operationId": "bookings.check_in", "summary": "Check a booking in", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `invalid_transition`, `serialization_failure`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `complete_too_early`, `no_show_too_early`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}/complete": { "post": { "operationId": "bookings.complete", "summary": "Complete a booking", "description": "Allowed from `starts_at` onwards; before that it is `422 complete_too_early`.", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `invalid_transition`, `serialization_failure`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `complete_too_early`, `no_show_too_early`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}/confirm": { "post": { "operationId": "bookings.confirm", "summary": "Confirm a booking", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `invalid_transition`, `serialization_failure`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `complete_too_early`, `no_show_too_early`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}/no_show": { "post": { "operationId": "bookings.no_show", "summary": "Mark a booking as a no-show", "description": "Allowed from `starts_at + policy_snapshot.no_show.grace_minutes` onwards; before that it is `422 no_show_too_early`.", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `invalid_transition`, `serialization_failure`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `complete_too_early`, `no_show_too_early`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bookings/{id}/reschedule": { "post": { "operationId": "bookings.reschedule", "summary": "Reschedule a booking", "description": "Answers with the **new** booking. The old one is one `GET` away through `rescheduled_from_booking_id`. An unavailable slot is a `409` and leaves the old booking intact.", "tags": ["bookings"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the booking." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "minItems": 1, "maxItems": 500 } }, "required": ["start"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Error codes: `duration_not_offered`, `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `resource_not_eligible`, `service_without_duration`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `invalid_transition`, `serialization_failure`, `slot_unavailable`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `complete_too_early`, `customer_limit_reached`, `max_reschedules_reached`, `min_notice_violated`, `no_show_too_early`, `outside_booking_window`, `start_not_on_grid`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/customers": { "post": { "operationId": "customers.create", "summary": "Create or upsert a customer", "description": "With `external_id` the write is an upsert with merge: `201` when the customer is created, `200` when an existing one is updated.", "tags": ["customers"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "email": { "type": ["string", "null"], "maxLength": 320, "format": "email" }, "phone": { "type": ["string", "null"], "minLength": 3, "maxLength": 50 }, "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "locale": { "type": ["string", "null"], "minLength": 2, "maxLength": 20 }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "customers.list", "summary": "List customers", "tags": ["customers"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^cus_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Exact match on the caller’s own identifier." }, "required": false, "name": "external_id", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/customers/{id}": { "get": { "operationId": "customers.get", "summary": "Retrieve a customer", "tags": ["customers"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the customer." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "customers.update", "summary": "Update a customer", "tags": ["customers"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the customer." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "email": { "type": ["string", "null"], "maxLength": 320, "format": "email" }, "phone": { "type": ["string", "null"], "minLength": 3, "maxLength": 50 }, "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "locale": { "type": ["string", "null"], "minLength": 2, "maxLength": 20 }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "customers.delete", "summary": "Delete a customer", "tags": ["customers"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the customer." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events": { "get": { "operationId": "events.list", "summary": "List events", "description": "Ordered by `(txid, seq)` and behind the visibility horizon, so a consumer that has read up to a cursor never later finds a row it stepped over. An event is readable only once every write transaction that started before it has ended.", "tags": ["events"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Event type. Repeatable: `?type[]=booking.created&type[]=booking.cancelled` is the union. Maximum 50 values." }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "description": "Prefixed identifier of the object the event is about." }, "required": false, "name": "object_id", "in": "query" }, { "schema": { "type": "string", "description": "`occurred_at` from this instant, included.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "description": "`occurred_at` up to this instant, excluded.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "to", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events/{id}": { "get": { "operationId": "events.get", "summary": "Retrieve an event", "description": "Not behind the horizon: the caller already holds the identifier.", "tags": ["events"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the event." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/holds": { "post": { "operationId": "holds.create", "summary": "Hold a slot", "description": "Takes the capacity for `ttl`, clamped to thirty minutes by the engine. The answer carries neither `metadata` nor the timestamps: they are read back by `GET /v1/holds/{id}`.", "tags": ["holds"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service_id": { "type": "string", "description": "Identifier of a service, prefixed with `svc_`.", "pattern": "^svc_[0-9a-f]{32}$", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "minItems": 1, "maxItems": 500 }, "customer_id": { "type": "string", "description": "Identifier of a customer, prefixed with `cus_`.", "pattern": "^cus_[0-9a-f]{32}$", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "customer": { "type": "object", "properties": { "external_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "email": { "type": ["string", "null"], "maxLength": 320, "format": "email" }, "phone": { "type": ["string", "null"], "minLength": 3, "maxLength": 50 }, "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "locale": { "type": ["string", "null"], "minLength": 2, "maxLength": 20 }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false }, "notes": { "type": ["string", "null"], "maxLength": 5000 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "source": { "type": "string", "enum": ["api", "widget", "portal", "import"] }, "ttl": { "type": "string", "description": "How long the hold lives, as a duration string (`10m`, `600s`, `1h`). Clamped to 30 minutes by the engine. Defaults to `policy.hold_duration_seconds`.", "pattern": "^([1-9]\\d{0,5})([smh])$", "example": "10m" } }, "required": ["service_id", "start"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoldCreated" } } } }, "400": { "description": "Error codes: `duration_not_offered`, `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `resource_not_eligible`, `service_without_duration`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `serialization_failure`, `slot_unavailable`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: `customer_limit_reached`, `min_notice_violated`, `outside_booking_window`, `start_not_on_grid`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/holds/{id}": { "get": { "operationId": "holds.get", "summary": "Retrieve a hold", "tags": ["holds"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the hold." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hold" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "holds.release", "summary": "Release a hold", "description": "Idempotent: releasing an already released or expired hold is a `200`. Only a hold already converted into a booking answers `409 hold_not_active`.", "tags": ["holds"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the hold." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `hold_not_active`, `serialization_failure`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/locations": { "post": { "operationId": "locations.create", "summary": "Create a location", "tags": ["locations"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "address": { "type": ["object", "null"], "additionalProperties": {} }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["name", "timezone"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "locations.list", "summary": "List locations", "tags": ["locations"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^loc_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/locations/{id}": { "get": { "operationId": "locations.get", "summary": "Retrieve a location", "tags": ["locations"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the location." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "locations.update", "summary": "Update a location", "description": "Changing `timezone` moves the open timeline of every resource that has no zone of its own, so it can emit `booking.orphaned`.", "tags": ["locations"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the location." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "address": { "type": ["object", "null"], "additionalProperties": {} }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "locations.delete", "summary": "Delete a location", "tags": ["locations"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the location." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/policies": { "post": { "operationId": "policies.create", "summary": "Create a policy", "tags": ["policies"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "cancellation": { "type": "array", "items": { "type": "object", "properties": { "before": { "type": "string", "pattern": "^(\\d+)([smhd])$", "description": "How long before the start the tier applies, as a duration: seconds, minutes, hours or days.", "example": "24h" }, "refund_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "fee": { "type": "integer", "minimum": 0 } }, "required": ["before"], "additionalProperties": false }, "maxItems": 20 }, "reschedule": { "type": "array", "items": { "type": "object", "properties": { "before": { "type": "string", "pattern": "^(\\d+)([smhd])$", "description": "How long before the start the tier applies, as a duration: seconds, minutes, hours or days.", "example": "24h" }, "refund_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "fee": { "type": "integer", "minimum": 0 } }, "required": ["before"], "additionalProperties": false }, "maxItems": 20 }, "deposit": { "type": ["object", "null"], "properties": { "type": { "type": "string", "enum": ["percent", "fixed"] }, "value": { "type": "number", "minimum": 0 }, "due": { "type": "string", "enum": ["at_booking"] } }, "required": ["type", "value"], "additionalProperties": false }, "payment_timing": { "type": "string", "enum": ["at_booking", "before_start", "after_service", "none"] }, "payment_deadline": { "type": ["string", "null"], "maxLength": 50 }, "no_show": { "type": ["object", "null"], "properties": { "charge_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "grace_minutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "auto_mark": { "type": "boolean" }, "mark_after": { "type": "string", "maxLength": 50 } }, "additionalProperties": false }, "hold_duration_seconds": { "type": "integer", "minimum": 30, "maximum": 86400 }, "max_active_bookings_per_customer": { "type": ["integer", "null"], "exclusiveMinimum": 0 }, "require_customer_confirmation": { "type": "boolean" }, "require_provider_confirmation": { "type": "boolean" }, "auto_start": { "type": "boolean" }, "auto_complete": { "type": "boolean" }, "max_reschedules": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "policies.list", "summary": "List policies", "tags": ["policies"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^pol_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/policies/{id}": { "get": { "operationId": "policies.get", "summary": "Retrieve a policy", "tags": ["policies"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the policy." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "policies.update", "summary": "Update a policy", "tags": ["policies"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the policy." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "cancellation": { "type": "array", "items": { "type": "object", "properties": { "before": { "type": "string", "pattern": "^(\\d+)([smhd])$", "description": "How long before the start the tier applies, as a duration: seconds, minutes, hours or days.", "example": "24h" }, "refund_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "fee": { "type": "integer", "minimum": 0 } }, "required": ["before"], "additionalProperties": false }, "maxItems": 20 }, "reschedule": { "type": "array", "items": { "type": "object", "properties": { "before": { "type": "string", "pattern": "^(\\d+)([smhd])$", "description": "How long before the start the tier applies, as a duration: seconds, minutes, hours or days.", "example": "24h" }, "refund_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "fee": { "type": "integer", "minimum": 0 } }, "required": ["before"], "additionalProperties": false }, "maxItems": 20 }, "deposit": { "type": ["object", "null"], "properties": { "type": { "type": "string", "enum": ["percent", "fixed"] }, "value": { "type": "number", "minimum": 0 }, "due": { "type": "string", "enum": ["at_booking"] } }, "required": ["type", "value"], "additionalProperties": false }, "payment_timing": { "type": "string", "enum": ["at_booking", "before_start", "after_service", "none"] }, "payment_deadline": { "type": ["string", "null"], "maxLength": 50 }, "no_show": { "type": ["object", "null"], "properties": { "charge_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "grace_minutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "auto_mark": { "type": "boolean" }, "mark_after": { "type": "string", "maxLength": 50 } }, "additionalProperties": false }, "hold_duration_seconds": { "type": "integer", "minimum": 30, "maximum": 86400 }, "max_active_bookings_per_customer": { "type": ["integer", "null"], "exclusiveMinimum": 0 }, "require_customer_confirmation": { "type": "boolean" }, "require_provider_confirmation": { "type": "boolean" }, "auto_start": { "type": "boolean" }, "auto_complete": { "type": "boolean" }, "max_reschedules": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "policies.delete", "summary": "Delete a policy", "tags": ["policies"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the policy." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/project": { "get": { "operationId": "project.get", "summary": "Retrieve the calling project", "description": "Answers \"who am I\": the project the API key belongs to, and the attributes of the key itself. The key is the selector, so there is no identifier to pass.", "tags": ["project"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resource_groups": { "post": { "operationId": "resource_groups.create", "summary": "Create a resource group", "tags": ["resource_groups"], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "enum": ["resources"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: resources." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "selector": { "type": ["object", "null"], "additionalProperties": {} }, "allocation_strategy": { "type": "string", "enum": ["least_busy", "round_robin", "first_available", "priority"] }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "maxItems": 500 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceGroup" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "resource_groups.list", "summary": "List resource groups", "tags": ["resource_groups"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^rg_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["resources"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: resources." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceGroupList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resource_groups/{id}": { "get": { "operationId": "resource_groups.get", "summary": "Retrieve a resource group", "tags": ["resource_groups"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource group." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["resources"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: resources." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceGroup" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "resource_groups.update", "summary": "Update a resource group", "description": "`resource_ids` replaces the whole membership; omitting it leaves it untouched.", "tags": ["resource_groups"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource group." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["resources"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: resources." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "selector": { "type": ["object", "null"], "additionalProperties": {} }, "allocation_strategy": { "type": "string", "enum": ["least_busy", "round_robin", "first_available", "priority"] }, "resource_ids": { "type": "array", "items": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "maxItems": 500 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceGroup" } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "resource_groups.delete", "summary": "Delete a resource group", "tags": ["resource_groups"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource group." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources": { "post": { "operationId": "resources.create", "summary": "Create a resource", "tags": ["resources"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "minLength": 1, "maxLength": 50 }, "location_id": { "type": "string", "description": "Identifier of a location, prefixed with `loc_`.", "pattern": "^loc_[0-9a-f]{32}$", "example": "loc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "schedule_id": { "type": "string", "description": "Identifier of a schedule, prefixed with `sch_`.", "pattern": "^sch_[0-9a-f]{32}$", "example": "sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "capacity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "attributes": { "type": "object", "additionalProperties": {} }, "status": { "type": "string", "enum": ["active", "inactive"] }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "resources.list", "summary": "List resources", "tags": ["resources"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["schedule"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: schedule." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources/{id}": { "get": { "operationId": "resources.get", "summary": "Retrieve a resource", "tags": ["resources"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["schedule"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: schedule." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "resources.update", "summary": "Update a resource", "description": "Touching `capacity`, `status`, `schedule_id` or `location_id` can emit `booking.orphaned` for future bookings the new configuration no longer supports.", "tags": ["resources"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "minLength": 1, "maxLength": 50 }, "location_id": { "type": "string", "description": "Identifier of a location, prefixed with `loc_`.", "pattern": "^loc_[0-9a-f]{32}$", "example": "loc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "schedule_id": { "type": "string", "description": "Identifier of a schedule, prefixed with `sch_`.", "pattern": "^sch_[0-9a-f]{32}$", "example": "sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "capacity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "attributes": { "type": "object", "additionalProperties": {} }, "status": { "type": "string", "enum": ["active", "inactive"] }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `slot_unavailable`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "resources.delete", "summary": "Delete a resource", "description": "Soft delete: bookings and occupancies keep referring to the resource.", "tags": ["resources"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources/{id}/block": { "post": { "operationId": "resources.block", "summary": "Block a period of a resource", "description": "Takes the whole capacity of the resource, so a period that is already booked or held answers `409 slot_unavailable`.", "tags": ["resources"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "to": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "reason": { "type": ["string", "null"], "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["from", "to"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceBlock" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `slot_unavailable`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources/{id}/blocks": { "get": { "operationId": "resources.blocks.list", "summary": "List the blocks of a resource", "description": "Ordered by start, cursored on `(lower(period), id)`. With neither `from` nor `to`, answers the blocks that have not finished yet.", "tags": ["resources"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^blk_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.", "format": "date-time", "example": "2026-09-08T07:00:00Z" }, "required": false, "name": "to", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceBlockList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources/{id}/unblock": { "post": { "operationId": "resources.unblock", "summary": "Remove a block", "tags": ["resources"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the resource." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "block_id": { "type": "string", "description": "Identifier of a resource_block, prefixed with `blk_`.", "pattern": "^blk_[0-9a-f]{32}$", "example": "blk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" } }, "required": ["block_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schedules": { "post": { "operationId": "schedules.create", "summary": "Create a schedule", "tags": ["schedules"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "minItems": 1, "maxItems": 7 }, "start_time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "description": "Local time of day, `HH:MM` or `HH:MM:SS`.", "example": "09:00" }, "end_time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "description": "Local time of day, `HH:MM` or `HH:MM:SS`.", "example": "09:00" }, "valid_from": { "type": ["string", "null"], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, `YYYY-MM-DD`.", "example": "2026-09-08" }, "valid_until": { "type": ["string", "null"], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, `YYYY-MM-DD`.", "example": "2026-09-08" } }, "required": ["days_of_week", "start_time", "end_time"], "additionalProperties": false }, "maxItems": 100 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Schedule" }, { "type": "object" } ] } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "schedules.list", "summary": "List schedules", "tags": ["schedules"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^sch_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schedules/{id}": { "get": { "operationId": "schedules.get", "summary": "Retrieve a schedule", "tags": ["schedules"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the schedule." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Schedule" }, { "type": "object" } ] } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "schedules.update", "summary": "Update a schedule", "description": "`rules` replaces the whole set. Touching `rules` or `timezone` can emit `booking.orphaned`.", "tags": ["schedules"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the schedule." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "description": "IANA time zone name.", "example": "Europe/Rome" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "minItems": 1, "maxItems": 7 }, "start_time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "description": "Local time of day, `HH:MM` or `HH:MM:SS`.", "example": "09:00" }, "end_time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "description": "Local time of day, `HH:MM` or `HH:MM:SS`.", "example": "09:00" }, "valid_from": { "type": ["string", "null"], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, `YYYY-MM-DD`.", "example": "2026-09-08" }, "valid_until": { "type": ["string", "null"], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, `YYYY-MM-DD`.", "example": "2026-09-08" } }, "required": ["days_of_week", "start_time", "end_time"], "additionalProperties": false }, "maxItems": 100 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Schedule" }, { "type": "object" } ] } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "schedules.delete", "summary": "Delete a schedule", "tags": ["schedules"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the schedule." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schedules/{id}/exceptions": { "post": { "operationId": "schedules.exceptions.create", "summary": "Add a calendar exception", "tags": ["schedules"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the schedule." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, `YYYY-MM-DD`.", "example": "2026-09-08" }, "type": { "type": "string", "enum": ["closed", "open"] }, "start_time": { "type": ["string", "null"], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "description": "Local time of day, `HH:MM` or `HH:MM:SS`.", "example": "09:00" }, "end_time": { "type": ["string", "null"], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "description": "Local time of day, `HH:MM` or `HH:MM:SS`.", "example": "09:00" }, "reason": { "type": ["string", "null"], "maxLength": 500 } }, "required": ["date", "type"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleException" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schedules/{id}/exceptions/{eid}": { "delete": { "operationId": "schedules.exceptions.delete", "summary": "Remove a calendar exception", "tags": ["schedules"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the schedule." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Identifier of the exception." }, "required": true, "name": "eid", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/services": { "post": { "operationId": "services.create", "summary": "Create a service", "tags": ["services"], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "enum": ["requirements"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: requirements." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": ["string", "null"], "maxLength": 5000 }, "duration": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "duration_options": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "minItems": 1, "maxItems": 20 }, "duration_range": { "type": "object", "properties": { "min": { "type": "integer", "exclusiveMinimum": 0 }, "max": { "type": "integer", "exclusiveMinimum": 0 } }, "required": ["min", "max"], "additionalProperties": false }, "capacity_per_booking": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "buffer_before": { "type": "integer", "minimum": 0, "maximum": 1440 }, "buffer_after": { "type": "integer", "minimum": 0, "maximum": 1440 }, "slot_interval": { "type": ["integer", "null"], "exclusiveMinimum": 0, "maximum": 1440 }, "align_to": { "type": ["string", "null"], "enum": ["hour", "half_hour", "schedule_start"] }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Three letter ISO 4217 currency code.", "example": "EUR" } }, "required": ["amount", "currency"], "additionalProperties": false }, "pricing_rules": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string", "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] }, "minItems": 1, "maxItems": 7 }, "time_from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "time_to": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "date_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "date_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$" }, "duration_min": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 } }, "additionalProperties": false }, "price": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "price_add": { "type": "integer", "minimum": -2147483647, "maximum": 2147483647 }, "price_multiplier": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "label": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": ["when"], "additionalProperties": false }, "maxItems": 100 }, "policy_id": { "type": "string", "description": "Identifier of a policy, prefixed with `pol_`.", "pattern": "^pol_[0-9a-f]{32}$", "example": "pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "booking_window": { "type": ["object", "null"], "properties": { "min_notice_minutes": { "type": "integer", "minimum": 0, "maximum": 525600 }, "max_advance_days": { "type": "integer", "minimum": 0, "maximum": 3650 } }, "additionalProperties": false }, "allow_recurring": { "type": "boolean" }, "allow_multi_day": { "type": "boolean" }, "buffer_sharing": { "type": "boolean" }, "allow_split": { "type": "boolean" }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "resource_group_id": { "type": "string", "description": "Identifier of a resource_group, prefixed with `rg_`.", "pattern": "^rg_[0-9a-f]{32}$", "example": "rg_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 }, "consumes": { "type": "string", "enum": ["per_unit", "whole"] }, "role": { "type": ["string", "null"], "minLength": 1, "maxLength": 50 } }, "additionalProperties": false }, "maxItems": 20 }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "services.list", "summary": "List services", "tags": ["services"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["requirements"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: requirements." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/services/{id}": { "get": { "operationId": "services.get", "summary": "Retrieve a service", "tags": ["services"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the service." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["requirements"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: requirements." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "services.update", "summary": "Update a service", "description": "`requirements` replaces the whole set; omitting it leaves it untouched.", "tags": ["services"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the service." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["requirements"] }, "description": "Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: requirements." }, "required": false, "name": "expand[]", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": ["string", "null"], "maxLength": 5000 }, "duration": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "duration_options": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "minItems": 1, "maxItems": 20 }, "duration_range": { "type": "object", "properties": { "min": { "type": "integer", "exclusiveMinimum": 0 }, "max": { "type": "integer", "exclusiveMinimum": 0 } }, "required": ["min", "max"], "additionalProperties": false }, "capacity_per_booking": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "buffer_before": { "type": "integer", "minimum": 0, "maximum": 1440 }, "buffer_after": { "type": "integer", "minimum": 0, "maximum": 1440 }, "slot_interval": { "type": ["integer", "null"], "exclusiveMinimum": 0, "maximum": 1440 }, "align_to": { "type": ["string", "null"], "enum": ["hour", "half_hour", "schedule_start"] }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Three letter ISO 4217 currency code.", "example": "EUR" } }, "required": ["amount", "currency"], "additionalProperties": false }, "pricing_rules": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string", "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] }, "minItems": 1, "maxItems": 7 }, "time_from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "time_to": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "date_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "date_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$" }, "duration_min": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 } }, "additionalProperties": false }, "price": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "price_add": { "type": "integer", "minimum": -2147483647, "maximum": 2147483647 }, "price_multiplier": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "label": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": ["when"], "additionalProperties": false }, "maxItems": 100 }, "policy_id": { "type": "string", "description": "Identifier of a policy, prefixed with `pol_`.", "pattern": "^pol_[0-9a-f]{32}$", "example": "pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "booking_window": { "type": ["object", "null"], "properties": { "min_notice_minutes": { "type": "integer", "minimum": 0, "maximum": 525600 }, "max_advance_days": { "type": "integer", "minimum": 0, "maximum": 3650 } }, "additionalProperties": false }, "allow_recurring": { "type": "boolean" }, "allow_multi_day": { "type": "boolean" }, "buffer_sharing": { "type": "boolean" }, "allow_split": { "type": "boolean" }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "Identifier of a resource, prefixed with `res_`.", "pattern": "^res_[0-9a-f]{32}$", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "resource_group_id": { "type": "string", "description": "Identifier of a resource_group, prefixed with `rg_`.", "pattern": "^rg_[0-9a-f]{32}$", "example": "rg_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 }, "consumes": { "type": "string", "enum": ["per_unit", "whole"] }, "role": { "type": ["string", "null"], "minLength": 1, "maxLength": 50 } }, "additionalProperties": false }, "maxItems": 20 }, "tenant_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Error codes: `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "services.delete", "summary": "Delete a service", "description": "Soft delete: past bookings keep pointing at the service they were made for.", "tags": ["services"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the service." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "post": { "operationId": "webhooks.create", "summary": "Register a webhook endpoint", "description": "The only response that ever carries `secret`. An idempotent replay of the same key answers **without** it.", "tags": ["webhooks"], "parameters": [ { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "description": { "type": ["string", "null"], "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "required": ["url"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `invalid_webhook_url`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "webhooks.list", "summary": "List webhook endpoints", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^wh_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "webhooks.get", "summary": "Retrieve a webhook endpoint", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the webhook." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "webhooks.update", "summary": "Update a webhook endpoint", "description": "`status` accepts `active` and `disabled` only: `failing` is an observation of the delivery worker, not a state a customer declares.", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the webhook." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "status": { "type": "string", "enum": ["active", "disabled"] }, "description": { "type": ["string", "null"], "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Error codes: `invalid_body`, `invalid_webhook_url`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "webhooks.delete", "summary": "Delete a webhook endpoint", "description": "Takes the endpoint’s deliveries with it. To stop the traffic and keep the history, set `status: \"disabled\"`.", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the webhook." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "webhooks.deliveries.list", "summary": "List the deliveries of an endpoint", "description": "Newest first, unlike every other list: a delivery log answers \"what just happened\".", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the webhook." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many objects to return, 1 to 100. Defaults to 20.", "example": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$", "description": "Cursor: the `id` of the last object of the previous page." }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "enum": ["pending", "succeeded", "failed"] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Identifier of a event, prefixed with `evt_`.", "pattern": "^evt_[0-9a-f]{32}$", "example": "evt_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "required": false, "name": "event_id", "in": "query" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" } ], "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "description": "Error codes: `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{did}/retry": { "post": { "operationId": "webhooks.deliveries.retry", "summary": "Replay a delivery", "description": "Puts the delivery back at the front of the queue with `attempt` reset and a fresh ladder. Allowed for thirty days after it was created.", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the webhook endpoint." }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Identifier of the delivery." }, "required": true, "name": "did", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `delivery_too_old`, `idempotency_key_in_progress`, `webhook_disabled`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "webhooks.test", "summary": "Send a test delivery", "description": "Delivers synchronously and answers with the delivery, HTTP status and body included. No retry ladder.", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "description": "Identifier of the webhook." }, "required": true, "name": "id", "in": "path" }, { "$ref": "#/components/parameters/BookrailVersion" }, { "$ref": "#/components/parameters/BookrailActor" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true }, "Idempotent-Replayed": { "schema": { "type": "string", "description": "`true` when the body is the stored answer of an earlier request with the same `Idempotency-Key`." }, "required": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "description": "Error codes: `idempotency_key_reused`, `invalid_body`, `parameter_invalid`, `parameter_missing`, `unsupported_api_version`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error codes: `invalid_api_key`, `invalid_authorization_header`, `missing_api_key`, `revoked_api_key`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: `resource_missing`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: `idempotency_key_in_progress`, `webhook_disabled`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: `internal_error`.", "headers": { "Bookrail-Request-Id": { "schema": { "type": "string", "description": "Identifier of this request. Quote it to support." }, "required": true }, "Bookrail-Version": { "schema": { "type": "string", "description": "The API version this response was produced with." }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_test_... / sk_live_...", "description": "A secret API key: `Authorization: Bearer sk_test_...`. Publishable (`pk_`) keys are refused on every endpoint of this document." } }, "schemas": { "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9a-f]{32}$", "description": "Identifier of a api_key, prefixed with `key_`.", "example": "key_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["api_key"] }, "kind": { "type": "string", "enum": ["secret", "publishable"] }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Stored, not yet enforced. An empty list means no restriction." }, "tenant_id": { "type": ["string", "null"], "description": "Optional tenant this object belongs to, for multi-tenant customers." } }, "required": ["id", "object", "kind", "environment", "scopes", "tenant_id"], "additionalProperties": false }, "Availability": { "type": "object", "properties": { "object": { "type": "string", "enum": ["availability"] }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "timezone": { "type": "string" }, "granularity": { "type": "string", "enum": ["slots", "ranges"] }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilitySlot" } }, "next_available": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "reason": { "$ref": "#/components/schemas/AvailabilityReason" }, "explain": { "type": "array", "items": { "$ref": "#/components/schemas/ExplainEntry" }, "description": "Present only with `explain: true`." }, "explain_notes": { "type": "array", "items": { "$ref": "#/components/schemas/ExplainNote" }, "description": "Present only with `explain: true`. What the engine had to ignore to answer, with no instant of its own: today only `pricing_rule_ignored`, a stored pricing rule the strict schema refuses." }, "explain_truncated": { "type": "boolean", "description": "Present only with `explain: true`." } }, "required": ["object", "service_id", "timezone", "granularity", "slots", "next_available"], "additionalProperties": false }, "AvailabilityCheck": { "type": "object", "properties": { "object": { "type": "string", "enum": ["availability_check"] }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": ["integer", "null"] }, "available": { "type": "boolean" }, "available_capacity": { "type": "integer" }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Amount in the minor unit of the currency (cents for EUR)." }, "price_rule": { "type": ["object", "null"], "properties": { "index": { "type": "integer", "description": "Position in `service.pricing_rules`." }, "label": { "type": ["string", "null"], "description": "The rule label, when it has one." } }, "required": ["index", "label"], "additionalProperties": false, "description": "Which `service.pricing_rules` entry produced `price`, if any." }, "resource_options": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceOption" } }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ExplainReason" }, "description": "Present only when `available` is false." }, "reason": { "$ref": "#/components/schemas/AvailabilityReason" } }, "required": [ "object", "service_id", "start", "duration_minutes", "available", "available_capacity", "price", "price_rule", "resource_options" ], "additionalProperties": false }, "AvailabilityNext": { "type": "object", "properties": { "object": { "type": "string", "enum": ["availability_next"] }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "timezone": { "type": "string" }, "next_available": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "slot": { "allOf": [ { "$ref": "#/components/schemas/AvailabilitySlot" }, { "type": ["object", "null"] } ] }, "searched_through": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "object", "service_id", "timezone", "next_available", "slot", "searched_through" ], "additionalProperties": false }, "AvailabilityReason": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false, "description": "Present when the window is well formed but no slot can exist for a reason that covers all of it, e.g. `customer_limit_reached`." }, "AvailabilitySlot": { "type": "object", "properties": { "object": { "type": "string", "enum": ["availability_slot"] }, "start": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "end": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": ["integer", "null"], "description": "`null` for a `ranges` entry." }, "available_capacity": { "type": "integer" }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Amount in the minor unit of the currency (cents for EUR)." }, "price_rule": { "type": ["object", "null"], "properties": { "index": { "type": "integer", "description": "Position in `service.pricing_rules`." }, "label": { "type": ["string", "null"], "description": "The rule label, when it has one." } }, "required": ["index", "label"], "additionalProperties": false, "description": "Which `service.pricing_rules` entry produced `price`. `null` when the flat service price applied. For a `ranges` entry it is the rule of the shortest booking starting at `start`." }, "resource_options": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceOption" } }, "min_duration_minutes": { "type": "integer", "description": "`ranges` only: shortest bookable length inside the interval." }, "max_duration_minutes": { "type": "integer", "description": "`ranges` only: longest bookable length; may exceed `end - start`." } }, "required": [ "object", "start", "end", "duration_minutes", "available_capacity", "price", "price_rule", "resource_options" ], "additionalProperties": false }, "Booking": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^bk_[0-9a-f]{32}$", "description": "Identifier of a booking, prefixed with `bk_`.", "example": "bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["booking"] }, "status": { "type": "string", "enum": [ "held", "pending", "confirmed", "in_progress", "completed", "cancelled", "no_show", "rescheduled" ] }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "customer_id": { "type": ["string", "null"], "pattern": "^cus_[0-9a-f]{32}$", "description": "Identifier of a customer, prefixed with `cus_`.", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "hold_id": { "type": ["string", "null"], "pattern": "^hold_[0-9a-f]{32}$", "description": "Identifier of a hold, prefixed with `hold_`.", "example": "hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "end": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": "integer" }, "timezone": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Amount in the minor unit of the currency (cents for EUR)." }, "price_rule": { "type": ["object", "null"], "properties": { "index": { "type": "integer", "description": "Position in `service.pricing_rules`." }, "label": { "type": ["string", "null"], "description": "The rule label, when it has one." } }, "required": ["index", "label"], "additionalProperties": false, "description": "Which `service.pricing_rules` entry priced this booking, frozen at creation. `null` when the flat service price applied." }, "amount_paid": { "type": "integer" }, "amount_due": { "type": "integer" }, "amount_refunded": { "type": "integer" }, "policy_snapshot": { "type": ["object", "null"], "additionalProperties": {}, "description": "The policy frozen at creation, as stored. `null` when the service had none." }, "source": { "type": "string", "enum": ["api", "widget", "portal", "import"] }, "notes": { "type": ["string", "null"] }, "cancelled_by": { "type": ["string", "null"], "enum": ["customer", "provider", "system"] }, "cancellation_reason": { "type": ["string", "null"] }, "refund_percent": { "type": ["number", "null"] }, "refund_amount_expected": { "type": ["integer", "null"] }, "no_show_charge_expected": { "type": ["integer", "null"] }, "reschedule_fee_expected": { "type": ["integer", "null"] }, "reschedule_count": { "type": "integer" }, "rescheduled_from_booking_id": { "type": ["string", "null"], "pattern": "^bk_[0-9a-f]{32}$", "description": "Identifier of a booking, prefixed with `bk_`.", "example": "bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "rescheduled_to_booking_id": { "type": ["string", "null"], "pattern": "^bk_[0-9a-f]{32}$", "description": "Identifier of a booking, prefixed with `bk_`.", "example": "bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "confirmed_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "checked_in_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "cancelled_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "no_show_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "rescheduled_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "next_transition": { "type": ["string", "null"], "enum": ["start", "complete", "no_show"] }, "next_transition_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAllocation" } }, "tenant_id": { "type": ["string", "null"], "description": "Optional tenant this object belongs to, for multi-tenant customers." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": ["object", "null"], "description": "Present only with `expand[]=customer`." } ] } }, "required": [ "id", "object", "status", "service_id", "customer_id", "hold_id", "start", "end", "duration_minutes", "timezone", "quantity", "price", "price_rule", "amount_paid", "amount_due", "amount_refunded", "policy_snapshot", "source", "notes", "cancelled_by", "cancellation_reason", "refund_percent", "refund_amount_expected", "no_show_charge_expected", "reschedule_fee_expected", "reschedule_count", "rescheduled_from_booking_id", "rescheduled_to_booking_id", "confirmed_at", "checked_in_at", "cancelled_at", "completed_at", "no_show_at", "rescheduled_at", "next_transition", "next_transition_at", "allocations", "tenant_id", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "BookingAllocation": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_allocation"] }, "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "role": { "type": ["string", "null"] }, "capacity_used": { "type": "integer" }, "id": { "type": "string", "pattern": "^ball_[0-9a-f]{32}$", "description": "Present on a booking allocation, absent on the allocations of a hold.", "example": "ball_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/Resource" }, { "type": ["object", "null"], "description": "Present only with `expand[]=allocations.resource`." } ] } }, "required": ["object", "resource_id", "role", "capacity_used"], "additionalProperties": false }, "BookingList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "BookrailActor": { "type": "string", "enum": ["mcp", "cli", "sdk", "dashboard"], "description": "Which Bookrail tool the caller is, recorded as `actor.via` on every event the request writes. A closed list: an unknown value is a 400. Absent means the request declared no tool." }, "BookrailVersion": { "type": "string", "description": "The dated API version to speak. Defaults to `2026-09-01`; an unsupported value is a 400.", "example": "2026-09-01" }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cus_[0-9a-f]{32}$", "description": "Identifier of a customer, prefixed with `cus_`.", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["customer"] }, "external_id": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "phone": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] }, "timezone": { "type": ["string", "null"] }, "locale": { "type": ["string", "null"] }, "tenant_id": { "type": ["string", "null"], "description": "Optional tenant this object belongs to, for multi-tenant customers." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "external_id", "email", "phone", "name", "timezone", "locale", "tenant_id", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "CustomerList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "Deleted": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "description": "The kind of object that was deleted." }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["id", "object", "deleted"], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication", "permission", "not_found", "conflict", "rate_limit", "policy_violation", "payment_required", "internal" ] }, "code": { "type": "string", "description": "Machine readable code. The set is per operation; each response below lists the ones it can produce." }, "message": { "type": "string" }, "param": { "type": "string", "description": "The field or header the error is about, when there is one." }, "doc_url": { "type": "string" }, "request_id": { "type": "string" } }, "required": ["type", "code", "message", "doc_url", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false }, "Event": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Identifier of a event, prefixed with `evt_`.", "example": "evt_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["event"] }, "type": { "type": "string" }, "occurred_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "api_version": { "type": "string" }, "seq": { "type": "integer", "description": "Position in the global event sequence. Not a count: a project’s values have arbitrary gaps." }, "actor": { "type": ["object", "null"], "additionalProperties": {}, "description": "`{type: \"api\", id: \"key_...\", via?: \"mcp\"|\"cli\"|\"sdk\"|\"dashboard\"}` for an HTTP write, `{type: \"system\", id: null}` for an automatic transition, `null` when nobody declared one." }, "data": { "type": "object", "properties": { "object": { "type": ["object", "null"], "additionalProperties": {}, "description": "Snapshot of the object after the change." }, "previous": { "type": ["object", "null"], "additionalProperties": {}, "description": "The fields that changed, or `null` for a creation." } }, "required": ["object", "previous"], "additionalProperties": false }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "type", "occurred_at", "api_version", "seq", "actor", "data", "environment", "created_at" ], "additionalProperties": false }, "EventList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "ExplainEntry": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ExplainReason" } } }, "required": ["at", "reasons"], "additionalProperties": false }, "ExplainNote": { "type": "object", "properties": { "code": { "type": "string", "enum": ["pricing_rule_ignored"] }, "message": { "type": "string" }, "index": { "type": "integer", "description": "Position in `service.pricing_rules` of the rule the note is about." } }, "required": ["code", "message", "index"], "additionalProperties": false }, "ExplainReason": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "outside_schedule", "exception_closed", "blocked", "occupied", "buffer", "min_notice", "max_advance", "capacity", "customer_limit" ] }, "message": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "ref_id": { "type": "string", "description": "Bare identifier of the booking, hold, block or exception responsible; `code` says which." } }, "required": ["code", "message"], "additionalProperties": false }, "Hold": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^hold_[0-9a-f]{32}$", "description": "Identifier of a hold, prefixed with `hold_`.", "example": "hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["hold"] }, "status": { "type": "string", "enum": ["active", "released", "expired", "converted"], "description": "Computed, not copied: a hold whose `expires_at` has passed is `expired` even while its row still says `active`." }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "customer_id": { "type": ["string", "null"], "pattern": "^cus_[0-9a-f]{32}$", "description": "Identifier of a customer, prefixed with `cus_`.", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "booking_id": { "type": ["string", "null"], "pattern": "^bk_[0-9a-f]{32}$", "description": "Identifier of a booking, prefixed with `bk_`.", "example": "bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "end": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": "integer" }, "quantity": { "type": "integer" }, "timezone": { "type": ["string", "null"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Always `null` on read: `holds` has no price column." }, "price_rule": { "type": ["object", "null"], "properties": { "index": { "type": "integer", "description": "Position in `service.pricing_rules`." }, "label": { "type": ["string", "null"], "description": "The rule label, when it has one." } }, "required": ["index", "label"], "additionalProperties": false, "description": "Always `null` on read, for the same reason as `price`." }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAllocation" } }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "status", "service_id", "customer_id", "booking_id", "start", "end", "duration_minutes", "quantity", "timezone", "expires_at", "price", "price_rule", "allocations", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "HoldCreated": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^hold_[0-9a-f]{32}$", "description": "Identifier of a hold, prefixed with `hold_`.", "example": "hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["hold"] }, "status": { "type": "string", "enum": ["active", "released", "expired", "converted"] }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "customer_id": { "type": ["string", "null"], "pattern": "^cus_[0-9a-f]{32}$", "description": "Identifier of a customer, prefixed with `cus_`.", "example": "cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "start": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "end": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "duration_minutes": { "type": "integer" }, "quantity": { "type": "integer" }, "timezone": { "type": "string" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Amount in the minor unit of the currency (cents for EUR)." }, "price_rule": { "type": ["object", "null"], "properties": { "index": { "type": "integer", "description": "Position in `service.pricing_rules`." }, "label": { "type": ["string", "null"], "description": "The rule label, when it has one." } }, "required": ["index", "label"], "additionalProperties": false, "description": "Which `service.pricing_rules` entry made this quote. A hold is not a sale: the booking recomputes it at conversion." }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAllocation" } }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." } }, "required": [ "id", "object", "status", "service_id", "customer_id", "start", "end", "duration_minutes", "quantity", "timezone", "expires_at", "price", "price_rule", "allocations", "environment" ], "additionalProperties": false }, "IdempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Retry-safety key, 1 to 255 characters. The same key within 24 hours replays the first response, errors included, and never produces a second effect." }, "Location": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^loc_[0-9a-f]{32}$", "description": "Identifier of a location, prefixed with `loc_`.", "example": "loc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["location"] }, "name": { "type": "string" }, "timezone": { "type": "string" }, "address": { "type": ["object", "null"], "additionalProperties": {} }, "tenant_id": { "type": ["string", "null"], "description": "Optional tenant this object belongs to, for multi-tenant customers." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "name", "timezone", "address", "tenant_id", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "LocationList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "OpenApiDocument": { "type": "object", "properties": { "openapi": { "type": "string", "enum": ["3.1.0"] }, "info": { "type": "object", "additionalProperties": {} }, "servers": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "tags": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "security": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "paths": { "type": "object", "additionalProperties": {} }, "components": { "type": "object", "additionalProperties": {} } }, "required": ["openapi", "info", "servers", "tags", "security", "paths", "components"], "additionalProperties": false }, "Policy": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pol_[0-9a-f]{32}$", "description": "Identifier of a policy, prefixed with `pol_`.", "example": "pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["policy"] }, "name": { "type": "string" }, "cancellation": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Refund tiers, as stored: `{ before, refund_percent?, fee? }`. An empty list refunds nothing." }, "reschedule": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Reschedule fee tiers, as stored." }, "deposit": { "type": ["object", "null"], "additionalProperties": {}, "description": "Deposit rule, as stored. `null` when unset." }, "payment_timing": { "type": "string", "enum": ["at_booking", "before_start", "after_service", "none"] }, "payment_deadline": { "type": ["string", "null"] }, "no_show": { "type": ["object", "null"], "additionalProperties": {}, "description": "No-show rule, as stored. `null` when unset." }, "hold_duration_seconds": { "type": "integer" }, "max_active_bookings_per_customer": { "type": ["integer", "null"] }, "require_customer_confirmation": { "type": "boolean" }, "require_provider_confirmation": { "type": "boolean" }, "auto_start": { "type": "boolean" }, "auto_complete": { "type": "boolean" }, "max_reschedules": { "type": ["integer", "null"] }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "name", "cancellation", "reschedule", "deposit", "payment_timing", "payment_deadline", "no_show", "hold_duration_seconds", "max_active_bookings_per_customer", "require_customer_confirmation", "require_provider_confirmation", "auto_start", "auto_complete", "max_reschedules", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "PolicyList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "Project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^proj_[0-9a-f]{32}$", "description": "Identifier of a project, prefixed with `proj_`.", "example": "proj_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["project"] }, "name": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "api_version": { "type": "string" }, "default_timezone": { "type": "string" }, "default_currency": { "type": "string" }, "api_key": { "$ref": "#/components/schemas/ApiKey" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "name", "environment", "api_version", "default_timezone", "default_currency", "api_key", "created_at" ], "additionalProperties": false }, "Resource": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["resource"] }, "name": { "type": "string" }, "type": { "type": "string" }, "location_id": { "type": ["string", "null"], "pattern": "^loc_[0-9a-f]{32}$", "description": "Identifier of a location, prefixed with `loc_`.", "example": "loc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "schedule_id": { "type": ["string", "null"], "pattern": "^sch_[0-9a-f]{32}$", "description": "Identifier of a schedule, prefixed with `sch_`.", "example": "sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "capacity": { "type": "integer" }, "attributes": { "type": "object", "additionalProperties": {} }, "status": { "type": "string", "enum": ["active", "inactive"] }, "tenant_id": { "type": ["string", "null"], "description": "Optional tenant this object belongs to, for multi-tenant customers." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "schedule": { "$ref": "#/components/schemas/Schedule" } }, "required": [ "id", "object", "name", "type", "location_id", "schedule_id", "capacity", "attributes", "status", "tenant_id", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "ResourceBlock": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^blk_[0-9a-f]{32}$", "description": "Identifier of a resource_block, prefixed with `blk_`.", "example": "blk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["resource_block"] }, "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "from": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "to": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "reason": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "resource_id", "from", "to", "reason", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "ResourceBlockList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceBlock" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "ResourceGroup": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rg_[0-9a-f]{32}$", "description": "Identifier of a resource_group, prefixed with `rg_`.", "example": "rg_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["resource_group"] }, "name": { "type": "string" }, "selector": { "type": ["object", "null"], "additionalProperties": {} }, "allocation_strategy": { "type": "string", "enum": ["least_busy", "round_robin", "first_available", "priority"] }, "resource_ids": { "type": "array", "items": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" } }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" }, "description": "Present only with `expand[]=resources`." } }, "required": [ "id", "object", "name", "selector", "allocation_strategy", "resource_ids", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "ResourceGroupList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceGroup" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "ResourceList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "ResourceOption": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "role": { "type": ["string", "null"] }, "capacity_used": { "type": "integer" } }, "required": ["resource_id", "role", "capacity_used"], "additionalProperties": false } } }, "required": ["resources"], "additionalProperties": false }, "Schedule": { "type": ["object", "null"], "properties": { "id": { "type": "string", "pattern": "^sch_[0-9a-f]{32}$", "description": "Identifier of a schedule, prefixed with `sch_`.", "example": "sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["schedule"] }, "name": { "type": "string" }, "timezone": { "type": ["string", "null"] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleRule" } }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleException" } }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "name", "timezone", "rules", "exceptions", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false, "description": "Present only with `expand[]=schedule`. `null` when the resource has none." }, "ScheduleException": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^she_[0-9a-f]{32}$", "description": "Identifier of a schedule_exception, prefixed with `she_`.", "example": "she_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["schedule_exception"] }, "schedule_id": { "type": "string", "pattern": "^sch_[0-9a-f]{32}$", "description": "Identifier of a schedule, prefixed with `sch_`.", "example": "sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "date": { "type": "string" }, "type": { "type": "string", "enum": ["closed", "open"] }, "start_time": { "type": ["string", "null"] }, "end_time": { "type": ["string", "null"] }, "reason": { "type": ["string", "null"] } }, "required": [ "id", "object", "schedule_id", "date", "type", "start_time", "end_time", "reason" ], "additionalProperties": false }, "ScheduleList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Schedule" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "ScheduleRule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^shr_[0-9a-f]{32}$", "description": "Identifier of a schedule_rule, prefixed with `shr_`.", "example": "shr_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["schedule_rule"] }, "schedule_id": { "type": "string", "pattern": "^sch_[0-9a-f]{32}$", "description": "Identifier of a schedule, prefixed with `sch_`.", "example": "sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "start_time": { "type": ["string", "null"] }, "end_time": { "type": ["string", "null"] }, "valid_from": { "type": ["string", "null"] }, "valid_until": { "type": ["string", "null"] } }, "required": [ "id", "object", "schedule_id", "days_of_week", "start_time", "end_time", "valid_from", "valid_until" ], "additionalProperties": false }, "Service": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["service"] }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "duration": { "type": ["integer", "null"] }, "duration_options": { "type": ["array", "null"], "items": { "type": "integer" } }, "duration_range": { "type": ["object", "null"], "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false }, "capacity_per_booking": { "type": "integer" }, "buffer_before": { "type": "integer" }, "buffer_after": { "type": "integer" }, "slot_interval": { "type": ["integer", "null"] }, "align_to": { "type": ["string", "null"], "enum": ["hour", "half_hour", "schedule_start"] }, "price": { "type": ["object", "null"], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "additionalProperties": false, "description": "Amount in the minor unit of the currency (cents for EUR)." }, "pricing_rules": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string", "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] }, "minItems": 1, "maxItems": 7 }, "time_from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "time_to": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "date_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "date_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "resource_id": { "type": "string", "pattern": "^res_[0-9a-f]{32}$" }, "duration_min": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 } }, "additionalProperties": false }, "price": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "price_add": { "type": "integer", "minimum": -2147483647, "maximum": 2147483647 }, "price_multiplier": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "label": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": ["when"], "additionalProperties": false }, "maxItems": 100, "description": "Evaluated in order for every slot and frozen on the booking: the first rule whose `when` matches replaces the flat `price`. Empty means the flat price always applies." }, "policy_id": { "type": ["string", "null"], "pattern": "^pol_[0-9a-f]{32}$", "description": "Identifier of a policy, prefixed with `pol_`.", "example": "pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "booking_window": { "type": ["object", "null"], "additionalProperties": {}, "description": "`{ min_notice_minutes?, max_advance_days? }`, as stored." }, "allow_recurring": { "type": "boolean" }, "allow_multi_day": { "type": "boolean" }, "buffer_sharing": { "type": "boolean" }, "allow_split": { "type": "boolean" }, "requirement_ids": { "type": "array", "items": { "type": "string", "pattern": "^sreq_[0-9a-f]{32}$", "description": "Identifier of a service_requirement, prefixed with `sreq_`.", "example": "sreq_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" } }, "tenant_id": { "type": ["string", "null"], "description": "Optional tenant this object belongs to, for multi-tenant customers." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRequirement" }, "description": "Present only with `expand[]=requirements`." } }, "required": [ "id", "object", "name", "description", "duration", "duration_options", "duration_range", "capacity_per_booking", "buffer_before", "buffer_after", "slot_interval", "align_to", "price", "pricing_rules", "policy_id", "booking_window", "allow_recurring", "allow_multi_day", "buffer_sharing", "allow_split", "requirement_ids", "tenant_id", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "ServiceList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "ServiceRequirement": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sreq_[0-9a-f]{32}$", "description": "Identifier of a service_requirement, prefixed with `sreq_`.", "example": "sreq_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["service_requirement"] }, "service_id": { "type": "string", "pattern": "^svc_[0-9a-f]{32}$", "description": "Identifier of a service, prefixed with `svc_`.", "example": "svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "resource_id": { "type": ["string", "null"], "pattern": "^res_[0-9a-f]{32}$", "description": "Identifier of a resource, prefixed with `res_`.", "example": "res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "resource_group_id": { "type": ["string", "null"], "pattern": "^rg_[0-9a-f]{32}$", "description": "Identifier of a resource_group, prefixed with `rg_`.", "example": "rg_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "quantity": { "type": "integer" }, "consumes": { "type": "string", "enum": ["per_unit", "whole"] }, "role": { "type": ["string", "null"] } }, "required": [ "id", "object", "service_id", "resource_id", "resource_group_id", "quantity", "consumes", "role" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9a-f]{32}$", "description": "Identifier of a webhook, prefixed with `wh_`.", "example": "wh_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["webhook"] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types. `[\"*\"]` means everything, future types included." }, "status": { "type": "string", "enum": ["active", "failing", "disabled"] }, "description": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form key/value pairs stored with the object and returned untouched." }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" } }, "required": [ "id", "object", "url", "events", "status", "description", "metadata", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "WebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The signing secret, shown **once**, in the answer to the request that created the endpoint. Absent from an idempotent replay, and from every other response.", "example": "whsec_..." } }, "additionalProperties": false } ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$", "description": "Identifier of a webhook_delivery, prefixed with `whd_`.", "example": "whd_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "object": { "type": "string", "enum": ["webhook_delivery"] }, "webhook_id": { "type": "string", "pattern": "^wh_[0-9a-f]{32}$", "description": "Identifier of a webhook, prefixed with `wh_`.", "example": "wh_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "event_id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Identifier of a event, prefixed with `evt_`.", "example": "evt_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c" }, "status": { "type": "string", "enum": ["pending", "succeeded", "failed"] }, "attempt": { "type": "integer", "description": "Attempts started, not attempts left." }, "response_status": { "type": ["integer", "null"] }, "response_body": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "duration_ms": { "type": ["integer", "null"] }, "scheduled_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "last_attempt_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "next_attempt_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "leased_until": { "type": ["string", "null"], "format": "date-time", "description": "Set only while an attempt is in flight; `next_attempt_at` stays the ladder.", "example": "2026-09-08T07:00:00Z" }, "delivered_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "environment": { "type": "string", "enum": ["test", "live"], "description": "The environment of the API key that created the object." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "ISO 8601 instant in UTC.", "example": "2026-09-08T07:00:00Z" }, "event_type": { "type": ["string", "null"], "description": "Type of the event this delivery carries. Joined in by the listing and by `/test`; absent from the answer of `/retry`." } }, "required": [ "id", "object", "webhook_id", "event_id", "status", "attempt", "response_status", "response_body", "error", "duration_ms", "scheduled_at", "last_attempt_at", "next_attempt_at", "leased_until", "delivered_at", "environment", "created_at", "updated_at" ], "additionalProperties": false }, "WebhookDeliveryList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false }, "WebhookList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false } }, "parameters": { "BookrailActor": { "schema": { "$ref": "#/components/schemas/BookrailActor" }, "required": false, "name": "Bookrail-Actor", "in": "header" }, "BookrailVersion": { "schema": { "$ref": "#/components/schemas/BookrailVersion" }, "required": false, "name": "Bookrail-Version", "in": "header" }, "IdempotencyKey": { "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "required": false, "name": "Idempotency-Key", "in": "header" } } } }