Skip to content
Keptslot
Start free

List bookings

GET
/v1/bookings
 
curl --request GET \
  --url 'https://api.keptslot.com/v1/bookings?limit=50' \
  --header 'Authorization: Bearer <token>'

This endpoint lists the bookings of the workspace, newest first. It pages with a cursor.

If next_cursor is not null, more bookings exist. Send that value back as cursor to read the next page.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “ Query Parameters ”
limit
integer
default: 50 <= 200

The page size. The default is 50 and the maximum is 200. A value that is not a positive number gives the default.

cursor
string

The next_cursor value from the previous page.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

One page of bookings.

Media type application/json
object
data
required
Array<object>
object
id
required
string format: uuid
staff_id
required
string format: uuid
service_id
required
string format: uuid
customer_id
required
string format: uuid
starts_at
required
string format: date-time
ends_at
required
string format: date-time
status
required
string
access_token

The customer’s manage link token. It is present only on the response that creates the booking. Store it then. No later response repeats it.

string
hold_expires_at

When this booking stops holding its slot. It is present only while the booking is on a hold, and absent otherwise.

Show this time rather than counting a fixed number of minutes from now. The window differs between a booking waiting on a code and one waiting on a card, and it is longer for a card because a 3DS redirect goes to the customer’s bank and back.

string format: date-time
payment

Present only when the service takes a payment, and only on the response that creates the booking. The key is absent for a service that takes no payment. It is never null, so a client can test for the key itself.

Use these fields to mount Stripe’s Payment Element on the connected account and confirm the payment. The client secret works once, for this booking.

object
client_secret
required
string
amount_cents
required

What this booking costs, in the smallest unit of the currency. It is a snapshot taken when the booking was made. Changing the service’s price later never changes it.

integer
currency
required
string
connected_account_id
required

The business’s Stripe account. Pass it as stripeAccount when you construct Stripe.js.

string
next_cursor
required

Null on the last page.

string | null
Example generated 
{
  "data": [
    {
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "staff_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "service_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "customer_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "starts_at": "2026-04-15T12:00:00Z",
      "ends_at": "2026-04-15T12:00:00Z",
      "status": "example",
      "access_token": "example",
      "hold_expires_at": "2026-04-15T12:00:00Z",
      "payment": {
        "client_secret": "example",
        "amount_cents": 1,
        "currency": "example",
        "connected_account_id": "example"
      }
    }
  ],
  "next_cursor": "example"
}

401

Section titled “ 401 ”

The key is missing, malformed or revoked.

Media type application/json
object
error
required
object
type
required

A stable machine-readable code. Match on this.

string
message
required

A sentence for a person. Do not match on this.

string
param

The field that caused the refusal, if one field did.

string
dimension

The plan limit that refused the request. It is present only on a 402, and only for a secret key or an account key. See the errors guide.

string
used

The current count for that dimension. It is present only on a 402, and only for an account key. It is absent when the refusal has no count to report. Absent and zero are different answers.

integer format: int64
limit

The cap for that dimension. It is present only on a 402, and only for an account key. A cap of zero is a real value.

integer format: int64
Example generated 
{
  "error": {
    "type": "example",
    "message": "example",
    "param": "example",
    "dimension": "example",
    "used": 1,
    "limit": 1
  }
}

422

Section titled “ 422 ”

The request body or the query is not valid.

Media type application/json
object
error
required
object
type
required

A stable machine-readable code. Match on this.

string
message
required

A sentence for a person. Do not match on this.

string
param

The field that caused the refusal, if one field did.

string
dimension

The plan limit that refused the request. It is present only on a 402, and only for a secret key or an account key. See the errors guide.

string
used

The current count for that dimension. It is present only on a 402, and only for an account key. It is absent when the refusal has no count to report. Absent and zero are different answers.

integer format: int64
limit

The cap for that dimension. It is present only on a 402, and only for an account key. A cap of zero is a real value.

integer format: int64
Example generated 
{
  "error": {
    "type": "example",
    "message": "example",
    "param": "example",
    "dimension": "example",
    "used": 1,
    "limit": 1
  }
}