DocsReservations

Reservations

PREVIEW

API, CLI & MCP preview. Reservation commands require the development client.

Ask
Italian in Manhattan. Two people, Friday at 7 pm. Vegetarian options.
Required details
Diner
Name, country, phone number.
Booking
Location, date, time, party size.
Preferences
Cuisine, budget, dietary or accessibility needs.
Choose
Compare up to six options at a time. Pick a restaurant and an available time.
Confirm
Check the booking summary. Confirm it with your agent to book.

Use it in your app or agent

Request JSON

Use the same fields for the API, CLI file, or create_reservation. Put date, local time, party size, and preferences in request. Do not supply coordinates or a time zone.

reservation.json

{
  "diner": {
    "country": "US",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone_number": "+12125550123"
  },
  "location": {
    "query": "Times Square, New York"
  },
  "request": "Dinner tomorrow for two around 7:30 PM. Quiet Italian, vegetarian choices, about $80 per person."
}

CLI commands · development client

Terminal

shopstack reservation run --file reservation.json
shopstack reservation get RESERVATION_ID
shopstack reservation options RESERVATION_ID --offset 6 --limit 6
shopstack reservation option RESERVATION_ID OPTION_ID
shopstack reservation message RESERVATION_ID --revision N --content "Your reply"
shopstack reservation cancel RESERVATION_ID --revision N

run asks follow-up questions, displays options, and asks you to confirm the exact booking summary. Use the latest returned revision for a message or cancellation.

MCP tools · local preview

create_reservation: Start with the request fields above.
poll_reservation: Read the current turn with reservation_id.
list_reservation_options: Use reservation_id, optional offset and limit for more stored options.
get_reservation_option: Use reservation_id and option_id for photos, provider details, and times.
send_reservation_message: Send reservation_id, expected_revision, and content. Select only current option and time IDs. Send confirmation only after the user agrees to the exact summary.
cancel_reservation: Cancel a confirmed booking with reservation_id and expected_revision.

API routes & state

Paths relative to /v1

POST /reservations
GET  /reservations/{id}
GET  /reservations/{id}/options
GET  /reservations/{id}/options/{option_id}
POST /reservations/{id}/messages
POST /reservations/{id}/cancel

Create returns 201 and a conversation, not a booking. Messages require content and expected_revision; cancellation requires expected_revision. Send an Idempotency-Key with mutations and keep it for retries.

Statuses are active, confirmation_required, confirmed, cancelled, booking_unknown, and cancellation_unknown.

Read the current reservation after a revision conflict. An unknown outcome is not success or failure. Do not submit another booking to resolve it.

More options, status & cancellation

Ask your agent for more restaurants, photos, or times. After booking, ask it to check the reservation or request cancellation.

Reservations

Ask

Choose

Confirm

Use it in your app or agent