Skip to content
Bookrail

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

Create a policy

POST
/v1/policies

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
name
required
string
>= 1 characters <= 200 characters
cancellation
Array<object>
<= 20 items
object
before
required

How long before the start the tier applies, as a duration: seconds, minutes, hours or days.

string
/^(\d+)([smhd])$/
Example
24h
refund_percent
number
<= 100
fee
integer
reschedule
Array<object>
<= 20 items
object
before
required

How long before the start the tier applies, as a duration: seconds, minutes, hours or days.

string
/^(\d+)([smhd])$/
Example
24h
refund_percent
number
<= 100
fee
integer
deposit
object
type
required
string
Allowed values: percent fixed
value
required
number
due
string
Allowed values: at_booking
payment_timing
string
Allowed values: at_booking before_start after_service none
payment_deadline
string | null
<= 50 characters
no_show
object
charge_percent
number
<= 100
grace_minutes
integer
<= 1440
auto_mark
boolean
mark_after
string
<= 50 characters
hold_duration_seconds
integer
>= 30 <= 86400
max_active_bookings_per_customer
integer | null
> 0
require_customer_confirmation
boolean
require_provider_confirmation
boolean
auto_start
boolean
auto_complete
boolean
max_reschedules
integer | null
<= 100
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 policy, prefixed with pol_.

string
/^pol_[0-9a-f]{32}$/
Example
pol_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: policy
name
required
string
cancellation
required

Refund tiers, as stored: { before, refund_percent?, fee? }. An empty list refunds nothing.

Array<object>
object
key
additional properties
reschedule
required

Reschedule fee tiers, as stored.

Array<object>
object
key
additional properties
deposit
required

Deposit rule, as stored. null when unset.

object | null
payment_timing
required
string
Allowed values: at_booking before_start after_service none
payment_deadline
required
string | null
no_show
required

No-show rule, as stored. null when unset.

object | null
hold_duration_seconds
required
integer
max_active_bookings_per_customer
required
integer | null
require_customer_confirmation
required
boolean
require_provider_confirmation
required
boolean
auto_start
required
boolean
auto_complete
required
boolean
max_reschedules
required
integer | 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

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