Besmi API · v1
Build on Besmi.
A small, clean API for building custom booking experiences on top of your Besmi business: a marketing site, an internal dashboard, a partner integration, anything. Same auth model, same data, just yours to compose.
Quick start
- i.Generate an API key. Sign in to Besmi, open Settings → Developer, click
New key. Copy the key the moment it appears. Besmi only stores a hash, so it can't be shown again. - ii.Make a request. Pass the key as a Bearer token. Every endpoint is scoped to your business. You never specify
businessId. - iii.Build whatever you want. Custom booking page, mobile app, agency dashboard, scheduled sync: all the same calls.
Your first request
curl https://besmi.com/api/v1/business \
-H "Authorization: Bearer bsk_live_your_key_here"Authentication
Every /api/v1/* endpoint accepts either an API key (recommended for server-to-server) or a Firebase ID token of the studio's owner or an Admin (used by the Besmi first-party UI). Both pass through the same auth pipeline. The businessId is derived from the token, never supplied as a parameter.
Authorization: Bearer bsk_live_…bsk_live_ prefix · 24 random bytes (url-safe base64) · ~40 characters totalread for GET endpoints · write for POST / PATCH. Keys made in Settings carry both.401 on the next call.Endpoints
Base URL: https://besmi.com
/api/v1/businessRead business profile
Returns name, slug, contact, hours, timezone, theme, landing-page modules, and notification preferences. Stripe / Twilio / partner identifiers are scrubbed.
curl https://besmi.com/api/v1/business \
-H "Authorization: Bearer bsk_live_…"Response · 200
{
"business": {
"id": "biz_xxx",
"name": "Your Esthi Bestie",
"slug": "mlc",
"timezone": "America/Los_Angeles",
"contact": { "email": "...", "phone": "..." },
"schedule": { /* working hours */ },
"theme": { /* colors + fonts */ },
"landingPage": { /* modules */ }
}
}/api/v1/servicesList services & categories
Returns every service and category as stored, in display order, including services that aren't bookable online (check bookableOnline). Prices are in dollars.
curl https://besmi.com/api/v1/services \
-H "Authorization: Bearer bsk_live_…"Response · 200
{
"categories": [
{ "id": "cat_xxx", "name": "Lashes", "order": 0 }
],
"services": [
{
"id": "svc_xxx",
"categoryId": "cat_xxx",
"name": "Classic Full Set",
"price": 180,
"durationMinutes": 120,
"bufferMinutes": 15,
"bookableOnline": true,
"addons": []
}
]
}/api/v1/availabilityGet available slots
Returns bookable time slots for a given date and service duration. Accounts for working hours, blocked windows, buffers, the book release date, and existing appointments.
Query parameters
datestring | YYYY-MM-DD in the business's timezone |
durationMinutesnumber | Service duration. Default 60. Range 0–480. |
staffIdstring | One team member's calendar: her own hours when she has them, and only her bookings (and unassigned ones) count as taken |
curl "https://besmi.com/api/v1/availability?date=2026-05-15&durationMinutes=120" \
-H "Authorization: Bearer bsk_live_…"Response · 200
{
"slots": [
{ "start": "2026-05-15T17:00:00.000Z", "end": "2026-05-15T19:00:00.000Z" },
{ "start": "2026-05-15T19:30:00.000Z", "end": "2026-05-15T21:30:00.000Z" }
]
}/api/v1/appointmentsList appointments
Lists appointments for the authenticated business, soonest first, optionally filtered by date range, status and team member. For the next page, pass nextCursor as from (the first row repeats the last one you have). The status and staffId filters apply within each page, so a page can hold fewer than limit rows.
Query parameters
fromstring | ISO 8601, inclusive lower bound on startAt |
tostring | ISO 8601, exclusive upper bound on startAt |
statusstring | Comma-separated subset of pending,confirmed,cancelled,noshow |
staffIdstring | One team member's appointments, or unassigned |
limitnumber | Default 50, max 200 |
curl "https://besmi.com/api/v1/appointments?from=2026-05-01&to=2026-06-01&status=confirmed,pending" \
-H "Authorization: Bearer bsk_live_…"/api/v1/appointmentsCreate an appointment
Writes a new appointment for the authenticated business, exactly as sent. Requires the write scope. Required: serviceId, startAt, endAt, client.firstName and client.email. Optional: staffId, addonIds, status (pending or confirmed, default confirmed), note. It doesn't check availability, set a price or deposit, or message the client. Payment isn't handled here either.
Request body
{
"serviceId": "svc_xxx",
"startAt": "2026-05-15T17:00:00.000Z",
"endAt": "2026-05-15T19:00:00.000Z",
"client": {
"firstName": "Jordan",
"lastName": "Lee",
"email": "jordan@example.com",
"phone": "+15555550100"
},
"addonIds": ["addon_xxx"],
"status": "confirmed",
"note": "Allergic to acrylic"
}curl -X POST https://besmi.com/api/v1/appointments \
-H "Authorization: Bearer bsk_live_…" \
-H "Content-Type: application/json" \
-d '{
"serviceId": "svc_xxx",
"startAt": "2026-05-15T17:00:00.000Z",
"endAt": "2026-05-15T19:00:00.000Z",
"client": { "firstName": "Jordan", "email": "jordan@example.com", "phone": "+15555550100" }
}'/api/v1/appointments/{id}Read one appointment
Fetches a single appointment by id.
curl https://besmi.com/api/v1/appointments/apt_xxx \
-H "Authorization: Bearer bsk_live_…"/api/v1/appointments/{id}Update an appointment
Patch status (pending, confirmed, cancelled, noshow), time (startAt and endAt together), addonIds, staffId (null to unassign), owner note, or client contact. Payment fields are intentionally NOT patchable. Use the dedicated Stripe surfaces so Stripe stays the source of truth.
Request body (any subset)
{
"status": "cancelled",
"startAt": "2026-05-16T17:00:00.000Z",
"endAt": "2026-05-16T19:00:00.000Z",
"addonIds": ["addon_xxx"],
"note": "Client called to reschedule",
"client": { "phone": "+15555550101" }
}curl -X PATCH https://besmi.com/api/v1/appointments/apt_xxx \
-H "Authorization: Bearer bsk_live_…" \
-H "Content-Type: application/json" \
-d '{ "status": "cancelled" }'/api/v1/customersList customers
Returns customer records, optionally filtered by a name / email / phone substring.
Query parameters
qstring | Case-insensitive substring filter |
limitnumber | Default 100, max 500 |
curl "https://besmi.com/api/v1/customers?q=jordan&limit=20" \
-H "Authorization: Bearer bsk_live_…"Your own website (Storefront API)
A studio on the Icon plan can run its own website, with its own design and domain, that shows its artists, menu, open times, reviews, posts and classes and takes bookings, deposits, intake answers and gift cards through Besmi. It books through the same code as the Besmi booking page, so every booking rule applies the same way. This is separate from the API above: it uses a publishable key that is safe in a web page, and it can only do what the public booking page does.
https://besmi.com/api/storefront/v1Besmi-Key: bpk_live_… (or ?key=). An Authorization header or a secret key (bsk_, sk_, rk_) is refused with 400.manage_website_keys), up to 10 at a time. bpk_live_ works from the https websites listed on it; bpk_dev_ also works from http://localhost and 127.0.0.1. Both book real appointments. A new key keeps the old one working for 24 hours.Access-Control-Allow-Origin only for an origin on the key's list, never *; any other origin is 403 ORIGIN_NOT_ALLOWED. A request with no Origin (a server) is allowed.402 PLAN_REQUIRED. Classes need Icon too.429 RATE_LIMITED with Retry-After.GET answers with an ETag. Send it back as If-None-Match and the answer is 304 when nothing changed: a build job can rebuild a static site only when the studio edited something.manageUrl, giftShop.url, product url, joinUrl, checkoutUrl).{ error, code }, sometimes with field or questionId naming what to fix. error is a sentence you can show the client.Endpoints
GET/studio: name, brand, logo, bio (rich and plain), SEO title and description, hours, address and locations, contact, policies and fees, team levels, what the booking form asks (client fields, questions, deposit, waitlist), and her gift card shop
GET/artists[?serviceId=] and /artists/{id or slug}: who takes online bookings, with level, gallery, rating, lowest price and the services she does at her prices
GET/services[?artistId=]: the online menu with categories, options, add-ons, fill windows and each artist's price and length
GET/availability?serviceId=&date= (or &from=&to=, up to 31 days): open times from the booking page's engine. Also artistId, variant, addonIds, withArtists=1, locationId, or items for several services in one visit
GET/reviews[?artistId=][&limit=][&cursor=]: published reviews, first name and last initial only
GET/updates[?kind=][&tag=][&limit=][&offset=] and /updates/{slug}: live posts from Creative (tour stops, classes, offers, news, blog posts), paged, with tag counts, updatedAt for sitemaps, and blog HTML on a post's page
GET/products: her shop (products, options, collections, stock), each linked to its page on Besmi for buying
GET/memberships: membership plans on sale, with benefits, price, terms and each plan's join link
POST/verification/email { email }: emails her a 6-digit code (10 minutes), needed to book
POST/bookings: book one service (serviceId) or 2 to 5 in one visit (items). Answers booked, or deposit_required with a Stripe PaymentIntent on the studio's account
POST/bookings/finalize: after Stripe.js takes the deposit. /bookings/release lets go of a visit's 15-minute hold
POST/bookings/card and /bookings/card/confirm: save a card on file when the booking says cardRequired
POST/waitlist: join the studio's waitlist for one service (when studio.booking.waitlist.enabled)
POST/discounts/check and /gift-cards/check: what a code takes off, a gift card's balance (last 4 only)
GET/classes and /classes/{classId}: published classes, sessions and seats left
POST/classes/{classId}/purchase, /classes/purchases/{purchaseId}/confirm, /classes/{classId}/waitlist: buy a seat, or join a full class's waitlist
GET/classes/inquiry, then POST /classes/inquiry: the months a 'send a request' class offers, and a student's request
GET/academy and /academy/programs/{id or slug}: her online programs, options and prices, rounds and seats left, each option's checkout link
POST/academy/waitlist: join a program's waitlist while it is closed
POST/clients/session: a returning client proves her email once and gets a 90-day client token
GET/clients/me (header Besmi-Client): her name and contact, questions she already answered, and her upcoming visits
Book from your website
const API = "https://besmi.com/api/storefront/v1";
const KEY = "bpk_live_...";
async function besmi(path, body) {
const res = await fetch(API + path, {
method: body ? "POST" : "GET",
headers: { "Besmi-Key": KEY, ...(body && { "Content-Type": "application/json" }) },
body: body && JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, ...data });
return data;
}
const q = new URLSearchParams({ serviceId: "s1", date: "2026-11-03" });
const { slots } = await besmi("/availability?" + q);
await besmi("/verification/email", { email: "ana@example.com" });
const r = await besmi("/bookings", {
serviceId: "s1",
startAt: slots[0].start,
client: { firstName: "Ana", lastName: "Diaz", email: "ana@example.com", phone: "+13035550123" },
answers: {},
consent: { transactional: true, marketing: false },
verification: { email: "ana@example.com", code: "123456" },
});
// r.result: "booked" (201) or "deposit_required" (200, then Stripe.js and /bookings/finalize)MCP connector
Besmi ships an MCP connector. MCP (Model Context Protocol) is the open standard AI assistants use to call external tools, so an assistant such as Claude or ChatGPT can work directly against a Besmi account: read the schedule, book, reschedule and cancel appointments, look up clients, pull stats, manage discounts, and edit the public page.
This is separate from the REST API above. The REST API is for code you write; the MCP connector is for an AI assistant acting on the owner's behalf. It does not use API keys. Connection is authorized by the business owner through OAuth 2.1, and can be revoked at any time from Settings → Connect.
Endpointhttps://besmi.com/api/mcp
AuthOAuth 2.1 with PKCE. No API key. The owner approves the connection once.
Tools76 tools: schedule, hours and locations, availability, bookings (options, add-ons, stylists, standing appointments), clients, sales and payouts (read only), gift cards (free ones only, never sold or refunded) and the loyalty card, the receptionist inbox, waitlist, marketing, marketing email, an AI page designer (drafts, renders, design review, Looks), and her own website's keys (Storefront API)
ProtocolStreamable HTTP, protocol 2025-11-25 (and older); MCP Apps page-preview view at ui://besmi/page-preview
Scopesread (look things up), book (schedule, inbox, waitlist), design (the page, as drafts), manage (client records, gift cards and loyalty, discounts, marketing and marketing email, website keys). The owner sees them on the consent screen.
Discovery401 responses carry WWW-Authenticate pointing at /.well-known/oauth-protected-resource (RFC 9728), which names the authorization server at /.well-known/oauth-authorization-server (RFC 8414).
ClientsDynamic client registration (RFC 7591) at /api/oauth/register. Public clients only: authorization code + PKCE S256, refresh tokens, revocation at /api/oauth/revoke.
PlansConnecting needs a Pro or Icon plan. A few tools also need a feature from a higher plan; tools/list marks those, and calling one returns an upgrade note.
Any MCP client that supports remote servers with OAuth can connect, not only Claude and ChatGPT. Point it at the endpoint and it discovers the rest. Tools are annotated honestly (readOnlyHint, destructiveHint, idempotentHint), failures come back with isError, and results include structuredContent. Design tools also return a PNG of the page so the model can see its work.
Tools (76)
Studio
get_business_overviewStudio overviewreadlist_servicesService menureadlist_teamTeamreadget_hoursHours and locationsreadSchedule and availability
get_scheduleAppointments by datereadget_upcomingNext appointmentsreadget_pending_requestsRequests waiting for approvalreadcheck_availabilityOpen times on a dayreadfind_next_availabilityNext openingsreadblock_timeBlock personal timebook · writesset_day_offDays offbook · writesset_special_hoursSpecial hours for a datebook · writesBookings
create_appointmentBook an appointmentbook · writesconfirm_appointmentApprove a requestbook · writesreschedule_appointmentMove an appointmentbook · writescancel_appointmentCancel or declinebook · writesmark_no_showMark a no-showbook · writesClients
find_clientFind a clientreadlist_clientsRank clientsreadget_client_historyClient profile and historyreadupdate_clientUpdate a clientmanage · writesget_birthdaysBirthdaysreadget_reviewsReviewsreadrequest_card_on_fileAsk a client to save a cardmanage · writesMoney (read only)
get_salesSales and takingsreadget_payoutsBalance and payoutsreadGift cards and loyalty
list_gift_cardsGift cardsreadget_gift_cardOne gift card in fullreadissue_gift_cardGive a gift card freemanage · writesvoid_gift_cardVoid a gift cardmanage · writesresend_gift_cardSend a gift card againmanage · writesget_loyaltyLoyalty cardreadadjust_loyalty_stampsAdd or take off stampsmanage · writesInbox and waitlist
get_needs_youConversations that need the ownerreadget_conversationRead a text conversationreadreply_to_clientReply to a client by textbook · writesmark_handledClear a "Needs you" flagbook · writesget_waitlistWaitlistreadoffer_openings_to_waitlistOffer openings to the waitlistbook · writesremove_from_waitlistRemove from the waitlistbook · writesMarketing
list_discountsDiscount codesreadcreate_discountCreate a discount codemanage · writesset_discount_activeTurn a code on or offmanage · writespreview_audienceCount an audiencereadlist_audiencesSaved audiencesreadcreate_audienceSave an audiencemanage · writeslist_automationsMarketing automationsreadcreate_automationCreate a campaign (switched off)manage · writesset_automation_enabledPause a campaignmanage · writesdraft_broadcastDraft a one-off blastreadMarketing email
get_email_marketingEmail marketingreadget_email_campaignOne email in fullreadcount_email_audienceCount who an email reachesreadcreate_email_campaignWrite a marketing emailmanage · writesupdate_email_campaignEdit a marketing emailmanage · writessend_test_emailSend a test to the ownermanage · writesschedule_email_campaignSend or schedule an emailmanage · writesstop_email_campaignStop an emailmanage · writesdelete_email_campaignDelete a draft emailmanage · writesset_email_signupSet up the sign-up formmanage · writesPage designer
get_design_guideDesign guidereadget_page_designPage designreadrender_pageSee the pagereadreview_page_designDesign reviewreadget_page_sectionOne page section in fullreadupdate_page_designChange the page's lookdesign · writesedit_page_sectionsEdit page sectionsdesign · writesset_page_photoPut a photo on the pagedesign · writesapply_lookApply a Lookdesign · writesadd_page_imageAdd a photo for the pagedesign · writescreate_page_artDraw art for the pagedesign · writespublish_page_draftPublish the draftdesign · writesdiscard_page_draftDiscard the draftdesign · writesrevert_page_designUndo the last published changedesign · writesHer own website
get_website_apiYour own website (Storefront API)readmanage_website_keysMake or change website keysmanage · writesOwners add the connector from Settings, then Connect. New tools under the four existing scopes reach existing connections automatically; only a brand-new scope needs a reconnect. The connector never charges or moves money. Marketing texts never send from it, and a marketing email sends only after the owner says yes to its preview.
Errors
Standard HTTP status codes. The response body is always JSON with an error field on failures.
400Bad Request: malformed body, invalid date, missing required field
401Unauthorized: missing, invalid, or revoked key
403Forbidden: key lacks the required scope
404Not Found: resource doesn't exist or belongs to another business
500Internal: something went wrong on our side. Safe to retry.
WebhooksComing soon
Subscribe to appointment.created, appointment.updated, and customer.created events. HMAC-SHA256 signed (Stripe-style). Email developers@besmi.com if you need this on a timeline.
Help
Question, bug report, or integration request? Email developers@besmi.com. Common questions live in the FAQ; this page is the source of truth for endpoint shapes.