Local service requests,
with explicit approval.
JSON over HTTPS. OpenAPI 3.1 specification. Times are ISO 8601 with an offset; prices are integer USD cents. Payment mode: Stripe TEST only. Native Muse payments and Stripe Connect are deferred.
Authentication and safe retries
Use Authorization: Bearer <CONNECTOR_API_KEY> or X-API-Key. Creation returns a secret booking_token; send it as X-Booking-Token for every subsequent customer booking operation. Never put secrets in URLs. Every write needs an Idempotency-Key. Reuse the same key and identical body after a timeout.
Search and request
GET /api/availability?date=YYYY-MM-DD&postal_code=75067&vehicle_type=suv&pet_hair=moderate&budget_max_cents=25000&time_window=afternoon&review=true
Choose a date 3–7 days ahead for review. Review inventory is explicitly synthetic; omit review=true to search real providers. Time windows use the provider’s timezone. Postal-code allowlists determine eligibility; radius is informational. Search supports category, service, variants, add-ons, mobile service, water and electricity.
POST /api/bookings with a returned slot_id, customer name/email/service_address, optional vehicle details and notes. A signed slot is revalidated and priced server-side. The provider inbox immediately receives the request.
Provider decision
An authorized operator uses the provider console and a separate X-Provider-API-Key. The operator handles initial providers directly. This is an administrator credential, not a credential to share among independent businesses. The inbox is the notification channel; no email or SMS is sent automatically.
Providers may accept, decline, counter price, or suggest another scheduled time. Acceptance moves to awaiting_customer_confirmation; a counter moves to provider_countered. Neither charges the customer.
Customer confirmation and payment
Retrieve GET /api/bookings/ID, show the final provider, time and price to the customer, and obtain explicit approval. Then POST /api/bookings/ID/confirm with provider_id, start_time, amount_cents, currency, current version, approved=true, and payment_method=checkout. A stale quote returns price_changed.
The result contains booking.checkout_url. Open this Stripe-hosted page to pay with a Stripe test card. Only the verified webhook changes payment_pending to confirmed. The success page is informational. Shared Payment Tokens are not accepted, regardless of the environment flag.
Modify, cancel, complete
PATCH /api/bookings/ID changes notes or a slot before payment and requires provider approval again. Provider and service changes require cancelling and making a new request. DELETE /api/bookings/ID cancels unpaid requests or starts a full refund when a paid booking is at least 24 hours away. Contact support for later cancellation. A provider can mark a confirmed booking completed after its end time.
Errors and recovery
Errors include code, message, retryable, request_id and recovery flags. Retry temporary failures with the same idempotency key. For version_conflict, retrieve current state. For slot_unavailable, search again. For price_changed, request fresh customer approval. Rate limits allow 120 reads or 40 writes per route per credential per minute; 429 includes Retry-After.
Provider onboarding
The protected onboarding API saves provider hours, blackout dates, exceptions, postal areas, travel surcharge, utility availability, minimum notice, service variants and generic add-ons. See the OnboardingRequest schema. At least one authorized real provider is needed for real service discovery.