Developers / Getting started
Getting Started
Welcome to the Reservory developer documentation. Learn how to integrate bookings, manage customers, and build on top of our platform.
What is Reservory?
Reservory is the operating system for attraction operators — escape rooms, laser tag, trampoline parks, axe throwing, climbing gyms, mini-golf, and beyond.
We provide booking management, customer data, waivers, payments, and reporting. The REST API, webhooks and embeddable widget let you take bookings on your own site and build integrations.
Authentication
Reservory supports two authentication models:
- Tenant API Keys: For reading bookings, customers, products and availability (
/api/v1, read scope), operator actions (cancel bookings, check-in customers, write scope) and webhook subscriptions (admin key). Create keys at/dashboard/settings/developers(admin). Use asAuthorization: Bearer rsv_* - Anonymous + Idempotency: For customer-facing booking flow (hold slot, confirm, payment intent). Rate-limited per IP or per token.
- Signed Tokens: For waiver signing and payment-intent auth. HMAC-SHA256, 1-14 day expiry depending on use.
Rate Limits
All endpoints are rate-limited. Anon (no API key) endpoints have per-IP limits. Tenant API key endpoints enforce plan-based limits.
Per-IP Limits (Anonymous Endpoints)
Each endpoint has its own per-IP limit to prevent abuse:
| Endpoint | Auth | Limit |
|---|---|---|
POST /api/bookings/hold | Anon | 10/min per IP |
POST /api/bookings | Anon | 5/min per IP |
POST /api/reviews/[token] | Anon | 3/24h per IP |
POST /api/widget/track | Anon | 60/min per IP |
| Other anon endpoints | Anon | See route file |
| Any operator endpoint | Operator JWT | None (RLS gated) |
Plan-Based Limits (API Key Only)
When authenticating with a tenant API key (Authorization: Bearer rsv_*), requests are subject to plan-based rate limits on both per-minute (burst) and per-hour (sustained) windows. Both windows must pass — whichever hits first returns 429. API keys require a Pro or Enterprise plan; other plans receive 403 plan_required.
| Plan | Per-Minute | Per-Hour |
|---|---|---|
| Pro | 300 | 20,000 |
| Enterprise | 1,000 | Unlimited |
Note: Anon endpoints have their own per-IP limits (see table above). The plan-based limits apply only to API key callers.
Rate-Limit Response Headers
When rate-limited (429 response):
- Anon endpoints: Returns
Retry-After: N(seconds to wait before retrying) - API key endpoints: Returns all four headers:
Retry-After: 45 X-RateLimit-Limit: 300 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1716170400 X-RateLimit-Window: minute
Quick Start: Embed Bookings
The fastest way to add Reservory bookings to your site is the embeddable widget. Register your site origin under Settings → Booking widget first, then add one line to your HTML:
<script type="module" src="https://app.reservory.com/widget.js"></script>
<reservory-booking tenant="your-tenant-slug" experience="your-product-slug"
api-base="https://app.reservory.com"></reservory-booking>The widget is a Web Component that handles the full booking flow — slot selection, customer info, waivers, and Stripe payment. Use your deployment's public Supabase URL and anon key. Never put a service-role key in this markup.
Integration Patterns
Build custom integrations using the supported REST API:
- Zapier: Cancel bookings, check in customers, sync to CRM. Use tenant API key auth.
- Custom Backend: Fetch available slots, create holds, confirm bookings, manage customers. Use REST endpoints.
- Mobile App: REST discovery and booking creation, with signed booking tokens for payment and status checks.
- Webhooks: Listen for booking events (created, confirmed, cancelled, refunded) and sync to your CRM, email platform, or analytics tool.
Next Steps
- API Reference — explore all endpoints with curl + JavaScript examples
- Webhooks — set up real-time event subscriptions