Skip to content
Bookrail

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

Create a service

POST
/v1/services

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
expand[]

Related objects to inline. Repeat the parameter, or send a comma separated list. Accepts: requirements.

Array<string>
Allowed values: requirements

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
name
required
string
>= 1 characters <= 200 characters
description
string | null
<= 5000 characters
duration
integer
> 0 <= 525600
duration_options
Array<integer>
>= 1 items <= 20 items
duration_range
object
min
required
integer
> 0
max
required
integer
> 0
capacity_per_booking
integer
> 0 <= 100000
buffer_before
integer
<= 1440
buffer_after
integer
<= 1440
slot_interval
integer | null
> 0 <= 1440
align_to
string | null
Allowed values: hour half_hour schedule_start
price
object
amount
required
integer
currency
required

Three letter ISO 4217 currency code.

string
/^[A-Z]{3}$/
Example
EUR
pricing_rules
Array<object>
<= 100 items
object
when
required
object
days
Array<string>
>= 1 items <= 7 items
Allowed values: mon tue wed thu fri sat sun
time_from
string
/^([01]\d|2[0-3]):([0-5]\d)$/
time_to
string
/^([01]\d|2[0-3]):([0-5]\d)$/
date_from
string
/^\d{4}-\d{2}-\d{2}$/
date_to
string
/^\d{4}-\d{2}-\d{2}$/
resource_id
string
/^res_[0-9a-f]{32}$/
duration_min
integer
> 0 <= 525600
price
integer
<= 2147483647
price_add
integer
>= -2147483647 <= 2147483647
price_multiplier
number
> 0 <= 1000
label
string
>= 1 characters <= 60 characters
policy_id

Identifier of a policy, prefixed with pol_.

string
/^pol_[0-9a-f]{32}$/
Example
pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
booking_window
object
min_notice_minutes
integer
<= 525600
max_advance_days
integer
<= 3650
allow_recurring
boolean
allow_multi_day
boolean
buffer_sharing
boolean
allow_split
boolean
requirements
Array<object>
<= 20 items
object
resource_id

Identifier of a resource, prefixed with res_.

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

Identifier of a resource_group, prefixed with rg_.

string
/^rg_[0-9a-f]{32}$/
Example
rg_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
quantity
integer
> 0 <= 1000
consumes
string
Allowed values: per_unit whole
role
string | null
>= 1 characters <= 50 characters
tenant_id
string | null
>= 1 characters <= 200 characters
metadata

Free-form key/value pairs stored with the object and returned untouched.

object
key
additional properties

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Created.

object
id
required

Identifier of a service, prefixed with svc_.

string
/^svc_[0-9a-f]{32}$/
Example
svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: service
name
required
string
description
required
string | null
duration
required
integer | null
duration_options
required
array | null
duration_range
required
object
min
required
integer
max
required
integer
capacity_per_booking
required
integer
buffer_before
required
integer
buffer_after
required
integer
slot_interval
required
integer | null
align_to
required
string | null
Allowed values: hour half_hour schedule_start
price
required

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

object
amount
required
integer
currency
required
string
pricing_rules
required

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.

Array<object>
<= 100 items
object
when
required
object
days
Array<string>
>= 1 items <= 7 items
Allowed values: mon tue wed thu fri sat sun
time_from
string
/^([01]\d|2[0-3]):([0-5]\d)$/
time_to
string
/^([01]\d|2[0-3]):([0-5]\d)$/
date_from
string
/^\d{4}-\d{2}-\d{2}$/
date_to
string
/^\d{4}-\d{2}-\d{2}$/
resource_id
string
/^res_[0-9a-f]{32}$/
duration_min
integer
> 0 <= 525600
price
integer
<= 2147483647
price_add
integer
>= -2147483647 <= 2147483647
price_multiplier
number
> 0 <= 1000
label
string
>= 1 characters <= 60 characters
policy_id
required

Identifier of a policy, prefixed with pol_.

string | null
/^pol_[0-9a-f]{32}$/
Example
pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
booking_window
required

{ min_notice_minutes?, max_advance_days? }, as stored.

object | null
allow_recurring
required
boolean
allow_multi_day
required
boolean
buffer_sharing
required
boolean
allow_split
required
boolean
requirement_ids
required
Array<string>
tenant_id
required

Optional tenant this object belongs to, for multi-tenant customers.

string | null
metadata
required

Free-form key/value pairs stored with the object and returned untouched.

object
key
additional properties
environment
required

The environment of the API key that created the object.

string
Allowed values: test live
created_at
required

ISO 8601 instant in UTC.

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

ISO 8601 instant in UTC.

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

Present only with expand[]=requirements.

Array<object>
object
id
required

Identifier of a service_requirement, prefixed with sreq_.

string
/^sreq_[0-9a-f]{32}$/
Example
sreq_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: service_requirement
service_id
required

Identifier of a service, prefixed with svc_.

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

Identifier of a resource, prefixed with res_.

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

Identifier of a resource_group, prefixed with rg_.

string | null
/^rg_[0-9a-f]{32}$/
Example
rg_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
quantity
required
integer
consumes
required
string
Allowed values: per_unit whole
role
required
string | null

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, parameter_invalid, parameter_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

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