Besmi·Developers

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

  1. 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.
  2. ii.
    Make a request. Pass the key as a Bearer token. Every endpoint is scoped to your business. You never specify businessId.
  3. 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.

Header
Authorization: Bearer bsk_live_…
Key format
bsk_live_ prefix · 24 random bytes (url-safe base64) · ~40 characters total
Scopes
read for GET endpoints · write for POST / PATCH. Keys made in Settings carry both.
Storage
Besmi stores only a SHA-256 hash + a 16-character prefix for lookup. Plaintext surfaces exactly once on creation. If you lose a key, generate a new one.
Revocation
Revoke it from Settings → Developer. Requests with a revoked key return 401 on the next call.
Treat keys as production credentials. Each key inherits your business's full read & write scope. Don't embed in client-side JavaScript or commit to git. Use environment variables and rotate on team changes.

Endpoints

Base URL: https://besmi.com

GET/api/v1/business

Read 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 */ }
  }
}
GET/api/v1/services

List 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":          []
    }
  ]
}
GET/api/v1/availability

Get 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

date
string
YYYY-MM-DD in the business's timezone
durationMinutes
number
Service duration. Default 60. Range 0–480.
staffId
string
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" }
  ]
}
GET/api/v1/appointments

List 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

from
string
ISO 8601, inclusive lower bound on startAt
to
string
ISO 8601, exclusive upper bound on startAt
status
string
Comma-separated subset of pending,confirmed,cancelled,noshow
staffId
string
One team member's appointments, or unassigned
limit
number
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_…"
POST/api/v1/appointments

Create 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" }
  }'
GET/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_…"
PATCH/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" }'
GET/api/v1/customers

List customers

Returns customer records, optionally filtered by a name / email / phone substring.

Query parameters

q
string
Case-insensitive substring filter
limit
number
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.

Building a whole site? The full Storefront API reference has every request and response, the errors, deposits with Stripe.js, returning clients, posts and blogs, classes, the academy, static hosting and a go-live checklist.
Base URL
https://besmi.com/api/storefront/v1
Header
Besmi-Key: bpk_live_… (or ?key=). An Authorization header or a secret key (bsk_, sk_, rk_) is refused with 400.
Keys
Made by the owner or an Admin in Settings → Your own website (or by her AI connector, with 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.
CORS
Websites are exact origins (no paths or wildcards). A browser request gets 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.
Plan
Icon. Below Icon every call answers 402 PLAN_REQUIRED. Classes need Icon too.
Rate limits
Per visitor (key + IP): 240 reads a minute, 90 availability calls a minute, 30 code, gift card and discount checks per 10 minutes, 20 booking calls an hour, 60 finalize calls per 10 minutes. Over the limit: 429 RATE_LIMITED with Retry-After.
Changes
Every 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.
On Besmi
The API never takes a payment for products, gift cards, memberships or academy programs, and never moves or cancels a visit. Each answer gives the link to her Besmi page for those (manageUrl, giftShop.url, product url, joinUrl, checkoutUrl).
Errors
JSON { 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.

Endpoint

https://besmi.com/api/mcp

Auth

OAuth 2.1 with PKCE. No API key. The owner approves the connection once.

Tools

76 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)

Protocol

Streamable HTTP, protocol 2025-11-25 (and older); MCP Apps page-preview view at ui://besmi/page-preview

Scopes

read (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.

Discovery

401 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).

Clients

Dynamic client registration (RFC 7591) at /api/oauth/register. Public clients only: authorization code + PKCE S256, refresh tokens, revocation at /api/oauth/revoke.

Plans

Connecting 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_overviewread
list_servicesread
list_teamread
get_hoursread

Schedule and availability

get_scheduleread
get_upcomingread
get_pending_requestsread
check_availabilityread
find_next_availabilityread
block_timebook · writes
set_day_offbook · writes
set_special_hoursbook · writes

Bookings

create_appointmentbook · writes
confirm_appointmentbook · writes
reschedule_appointmentbook · writes
cancel_appointmentbook · writes
mark_no_showbook · writes

Clients

find_clientread
list_clientsread
get_client_historyread
update_clientmanage · writes
get_birthdaysread
get_reviewsread
request_card_on_filemanage · writes

Money (read only)

get_salesread
get_payoutsread

Gift cards and loyalty

list_gift_cardsread
get_gift_cardread
issue_gift_cardmanage · writes
void_gift_cardmanage · writes
resend_gift_cardmanage · writes
get_loyaltyread
adjust_loyalty_stampsmanage · writes

Inbox and waitlist

get_needs_youread
get_conversationread
reply_to_clientbook · writes
mark_handledbook · writes
get_waitlistread
offer_openings_to_waitlistbook · writes
remove_from_waitlistbook · writes

Marketing

list_discountsread
create_discountmanage · writes
set_discount_activemanage · writes
preview_audienceread
list_audiencesread
create_audiencemanage · writes
list_automationsread
create_automationmanage · writes
set_automation_enabledmanage · writes
draft_broadcastread

Marketing email

get_email_marketingread
get_email_campaignread
count_email_audienceread
create_email_campaignmanage · writes
update_email_campaignmanage · writes
send_test_emailmanage · writes
schedule_email_campaignmanage · writes
stop_email_campaignmanage · writes
delete_email_campaignmanage · writes
set_email_signupmanage · writes

Page designer

get_design_guideread
get_page_designread
render_pageread
review_page_designread
get_page_sectionread
update_page_designdesign · writes
edit_page_sectionsdesign · writes
set_page_photodesign · writes
apply_lookdesign · writes
add_page_imagedesign · writes
create_page_artdesign · writes
publish_page_draftdesign · writes
discard_page_draftdesign · writes
revert_page_designdesign · writes

Her own website

get_website_apiread
manage_website_keysmanage · writes

Owners 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.

400

Bad Request: malformed body, invalid date, missing required field

401

Unauthorized: missing, invalid, or revoked key

403

Forbidden: key lacks the required scope

404

Not Found: resource doesn't exist or belongs to another business

500

Internal: 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.