Private beta

One API to book the real world.

Connect your agent over MCP or REST. Search live inventory, place a hold, collect payment and confirm, with idempotent calls and machine-readable policies. Tours and experiences in Doha first, then salons and spas.

Get early API access Quickstart

Quickstart

Two ways in, one booking flow.

MCP

https://mcp.tafaddal.ai/mcp

Transport: Streamable HTTP
Auth: OAuth sign-in, for consumer agents

MCP client config

{
  "mcpServers": {
    "tafaddal": {
      "url": "https://mcp.tafaddal.ai/mcp"
    }
  }
}

REST

https://api.tafaddal.ai/v1

Format: Form-encoded requests, JSON responses
Auth: API keys, for platforms

Place a hold

curl https://api.tafaddal.ai/v1/holds \
  -H "Authorization: Bearer $TAFADDAL_KEY" \
  -H "Idempotency-Key: 6f1c2e" \
  -d offer_id=off_dhow_sunset \
  -d start=2026-11-12T18:00:00+03:00 \
  -d guests=2 \
  -d guest_name="Sara Ahmed" \
  -d guest_email=sara@example.com

Response

{
  "object": "hold",
  "id": "hold_8Q2K",
  "status": "held",
  "start": "2026-11-12T18:00:00+03:00",
  "party": 2,
  "total": { "amount": 50000, "currency": "QAR" },
  "due_now": { "amount": 50000, "currency": "QAR" },
  "expires_at": "2026-11-11T18:10:00+03:00"
}

Tools

Nine tools, mirrored in REST.

Every MCP tool has a REST endpoint with the same inputs and outputs.

MCP tools and their REST endpoints
MCP tool	REST	Description
`search_offers`	`GET /v1/offers`	Find bookable experiences and services by place, date, category, party size and price
`get_offer`	`GET /v1/offers/{id}`	Details, media, location and policies for one offer
`check_availability`	`GET /v1/offers/{id}/availability`	Live slots with remaining capacity and price
`hold_slot`	`POST /v1/holds`	Hold a slot for 10 minutes
`create_checkout`	`POST /v1/holds/{id}/checkout`	Payment link the guest approves
`confirm_booking`	`POST /v1/holds/{id}/confirm`	Confirm when no upfront payment is required
`get_booking`	`GET /v1/bookings/{id}`	Status and details
`change_booking`	`POST /v1/bookings/{id}/change`	Move to another start time, within policy
`cancel_booking`	`POST /v1/bookings/{id}/cancel`	Cancel, with the refund the policy allows

search_offersGET /v1/offers
Find bookable experiences and services by place, date, category, party size and price
get_offerGET /v1/offers/{id}
Details, media, location and policies for one offer
check_availabilityGET /v1/offers/{id}/availability
Live slots with remaining capacity and price
hold_slotPOST /v1/holds
Hold a slot for 10 minutes
create_checkoutPOST /v1/holds/{id}/checkout
Payment link the guest approves
confirm_bookingPOST /v1/holds/{id}/confirm
Confirm when no upfront payment is required
get_bookingGET /v1/bookings/{id}
Status and details
change_bookingPOST /v1/bookings/{id}/change
Move to another start time, within policy
cancel_bookingPOST /v1/bookings/{id}/cancel
Cancel, with the refund the policy allows

Booking lifecycle

From hold to booking.

held: A hold reserves the slot for 10 minutes while the guest decides and pays.
expired: The time limit passed. The slot goes back on sale.
released: The agent let the hold go early. The slot goes back on sale.
confirmed: The guest paid through checkout, or the booking was confirmed directly because no upfront payment was required.
changed: Moved to another start time within policy. The booking stays confirmed.
cancelled · completed · no_show: How a confirmed booking ends. Refunds and no-show charges follow the host’s policy.

Principles

Predictable by design.

Idempotency keys on every write
Send an Idempotency-Key header with every POST. A retry returns the original result, never a second hold or charge.
Money in minor units
Amounts are integers in minor units with an ISO 4217 currency. QAR 500.00 is { "amount": 50000, "currency": "QAR" }.
Times with offsets
ISO 8601 with an explicit offset. Doha is UTC+3 all year, so 6 pm is 2026-11-12T18:00:00+03:00.
Policies with every offer and hold
Cancellation windows, deposits, and age or health requirements come back with every offer and hold, so agents can tell guests before they book.

Errors

Errors you can act on.

Errors return a stable code, a human-readable message and the matching HTTP status.

Error codes
Code	Meaning
`slot_unavailable`HTTP 409	The slot filled or closed before your hold. Check availability again and pick another time.
`hold_expired`HTTP 410	The hold passed its time limit and the slot was released. Place a new hold.
`policy_violation`HTTP 422	The request breaks the host’s rules, such as party size, cut-off time or an age requirement.
`payment_required`HTTP 402	This offer needs payment upfront. Create a checkout instead of confirming directly.
`idempotency_conflict`HTTP 409	The Idempotency-Key was already used for a different request. Use a new key for a new request.
`rate_limited`HTTP 429	Too many requests. Wait for the Retry-After interval.
`not_found`HTTP 404	No offer, hold or booking with that ID.

Webhooks

Every change, pushed to you.

booking.confirmedA hold became a booking.
booking.changedMoved to another start time, within policy.
booking.cancelledThe guest or host cancelled; includes any refund.
booking.completedThe experience took place.
hold.expiredA hold ran out of time and the slot was released.

booking.confirmed

{
  "id": "evt_5Jq1",
  "type": "booking.confirmed",
  "created_at": "2026-11-11T15:04:31Z",
  "data": {
    "booking_id": "bk_8Q2K",
    "reference": "TF-8Q2K",
    "status": "confirmed"
  }
}

تفضّل

Build with us.

The API is in private beta. Tell us what your agent books and we’ll set you up.

Get early API access

One API to book the real world.

Two ways in, one booking flow.

MCP

REST

Nine tools, mirrored in REST.

From hold to booking.

Predictable by design.

Idempotency keys on every write

Money in minor units

Times with offsets

Policies with every offer and hold

Errors you can act on.

Every change, pushed to you.

Build with us.