Skip to content
Bookrail

Search is only available in production builds. Try building and previewing the site to test it out locally.

Search availability over a window

POST
/v1/availability

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
Bookrail-Version

The dated API version to speak. Defaults to 2026-09-01; an unsupported value is a 400.

string
Example
2026-09-01
Bookrail-Actor

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.

string
Allowed values: mcp cli sdk dashboard
Idempotency-Key

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.

string
>= 1 characters <= 255 characters

Request Body required

Section titled “Request Body required ”
object
service_id
required

Identifier of a service, prefixed with svc_.

string
/^svc_[0-9a-f]{32}$/
Example
svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
from
required

ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.

string format: date-time
Example
2026-09-08T07:00:00Z
to
required

ISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.

string format: date-time
Example
2026-09-08T07:00:00Z
quantity
integer
> 0 <= 100000
resource_ids
Array<string>
>= 1 items <= 500 items
customer_id

Identifier of a customer, prefixed with cus_.

string
/^cus_[0-9a-f]{32}$/
Example
cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
timezone

IANA time zone name.

string
Example
Europe/Rome
granularity
string
Allowed values: slots ranges
explain
boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success.

object
object
required
string
Allowed values: availability
service_id
required

Identifier of a service, prefixed with svc_.

string
/^svc_[0-9a-f]{32}$/
Example
svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
timezone
required
string
granularity
required
string
Allowed values: slots ranges
slots
required
Array<object>
object
object
required
string
Allowed values: availability_slot
start
required

ISO 8601 instant in UTC.

string format: date-time
Example
2026-09-08T07:00:00Z
end
required

ISO 8601 instant in UTC.

string format: date-time
Example
2026-09-08T07:00:00Z
duration_minutes
required

null for a ranges entry.

integer | null
available_capacity
required
integer
price
required

Amount in the minor unit of the currency (cents for EUR).

object
amount
required
integer
currency
required
string
price_rule
required

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.

object
index
required

Position in service.pricing_rules.

integer
label
required

The rule label, when it has one.

string | null
resource_options
required
Array<object>
object
resources
required
Array<object>
object
resource_id
required

Identifier of a resource, prefixed with res_.

string
/^res_[0-9a-f]{32}$/
Example
res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
role
required
string | null
capacity_used
required
integer
min_duration_minutes

ranges only: shortest bookable length inside the interval.

integer
max_duration_minutes

ranges only: longest bookable length; may exceed end - start.

integer
next_available
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
reason

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.

object
code
required
string
message
required
string
explain

Present only with explain: true.

Array<object>
object
at
required

ISO 8601 instant in UTC.

string format: date-time
Example
2026-09-08T07:00:00Z
reasons
required
Array<object>
object
code
required
string
Allowed values: outside_schedule exception_closed blocked occupied buffer min_notice max_advance capacity customer_limit
message
required
string
resource_id

Identifier of a resource, prefixed with res_.

string
/^res_[0-9a-f]{32}$/
Example
res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
ref_id

Bare identifier of the booking, hold, block or exception responsible; code says which.

string
explain_notes

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.

Array<object>
object
code
required
string
Allowed values: pricing_rule_ignored
message
required
string
index
required

Position in service.pricing_rules of the rule the note is about.

integer
explain_truncated

Present only with explain: true.

boolean

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string
Idempotent-Replayed

true when the body is the stored answer of an earlier request with the same Idempotency-Key.

string

400

Section titled “400 ”

Error codes: idempotency_key_reused, invalid_body, invalid_range, parameter_invalid, parameter_missing, range_too_large, service_without_duration, timezone_missing, unsupported_api_version.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

401

Section titled “401 ”

Error codes: invalid_api_key, invalid_authorization_header, missing_api_key, revoked_api_key.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

404

Section titled “404 ”

Error codes: resource_missing.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

409

Section titled “409 ”

Error codes: idempotency_key_in_progress.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

500

Section titled “500 ”

Error codes: internal_error.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string