Skip to content
Bookrail

Ask for a test key

POST
/v1/signups

Sends a confirmation link to the address. The answer is the same whether or not that address already has an account: the collision is reported at confirmation time, to whoever can read the mailbox. No API key.

Request Body required

Section titled “Request Body required ”
object
email
required
string format: email
Example
you@example.com
client
required

Where the request came from. cli waits for the key on a poll; web is handed it in the confirm response.

string
Allowed values: cli web
account_name
string
>= 1 characters <= 200 characters
project_name
string
>= 1 characters <= 200 characters
default_timezone

IANA time zone name.

string
Example
Europe/Rome
default_currency

Three letter ISO 4217 currency code.

string
/^[A-Z]{3}$/
Example
EUR
accept_terms

I accept the Terms of Service and the Data Processing Agreement on behalf of my business. Required, and true: a sign up without it is refused with 400 terms_not_accepted.

boolean
approve_clauses

I specifically approve the clauses listed in Section 17 of the Terms (Articles 1341 and 1342 of the Italian Civil Code). Required, and true.

boolean
via

The platform or campaign that sent the person here, as a slug: lower case letters, digits and hyphens, at most 32. The website passes on ?via=; the CLI sends --via or BOOKRAIL_VIA. A value of any other shape is ignored, never refused.

string
/^[a-z0-9-]{1,32}$/
Example
lovable
agent

The coding agent that launched the CLI, detected by the CLI from the environment variables each agent documents. Any other value is ignored, never refused.

string
Allowed values: claude-code codex copilot cursor gemini-cli

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Success.

object
id
required

Identifier of a signup, prefixed with sgn_.

string
/^sgn_[0-9a-f]{32}$/
Example
sgn_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: signup
status
required
string
Allowed values: pending confirmed claimed email_taken expired
email

Echoed back so a client can show where the message went.

string
expires_at

When the confirmation link stops working.

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

Only for client: "cli", and only in the answer that created the sign up: the token the terminal claims its key with.

string
delivered_to

Present when the key went to a waiting terminal instead of into this response.

string
Allowed values: cli
account
object
id
required

Identifier of a account, prefixed with acct_.

string
/^acct_[0-9a-f]{32}$/
Example
acct_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: account
name
required
string
project
object
id
required

Identifier of a project, prefixed with proj_.

string
/^proj_[0-9a-f]{32}$/
Example
proj_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: project
name
required
string
default_timezone
required
string
default_currency
required
string
api_key

The test key alone. The same object as the test entry of api_keys.

object
id
required

Identifier of a api_key, prefixed with key_.

string
/^key_[0-9a-f]{32}$/
Example
key_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: api_key
environment
required
string
Allowed values: test
kind
required
string
Allowed values: secret
prefix
required
string
api_keys

The keys the sign up created: one test and one live, both secret, with no scopes and no tenant. A sign up confirmed before 24 September 2026 has the test one only.

Array<object>
object
id
required

Identifier of a api_key, prefixed with key_.

string
/^key_[0-9a-f]{32}$/
Example
key_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: api_key
environment
required
string
Allowed values: test live
kind
required
string
Allowed values: secret
prefix
required
string
secret_key

The test key, in clear text. Shown once: in the confirm of a browser, or in the first successful claim of a terminal. It is stored as a SHA-256 hash and cannot be shown again.

string
Example
sk_test_...
live_secret_key

The live key, in clear text, shown once and at the same moment as secret_key. It books for real and counts against the free plan of the account, which refuses new live bookings at its monthly threshold with 402 plan_limit_reached.

string
Example
sk_live_...

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

400

Section titled “400 ”

Error codes: invalid_body, parameter_invalid, parameter_missing, terms_not_accepted, 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
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

429

Section titled “429 ”

Error codes: signup_rate_limited.

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
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

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
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

502

Section titled “502 ”

Error codes: signup_email_failed.

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
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

503

Section titled “503 ”

Error codes: signup_disabled.

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
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.