PlaceFull API

PlaceFull is a booking platform for studios and service businesses. Use the REST API to manage catalog, availability, bookings, payments, memberships, and customer records — or embed the public storefront surface for self-serve booking.

All successful responses use a { "data": … } envelope. Money amounts are integer minor units (cents). Timestamps are ISO-8601 strings in UTC.

Base URLs

EnvironmentURL
Productionhttps://placefull.ai
Localhttp://localhost:3000

Use the Production or Local server selector above when trying requests in this reference.

Authentication

PlaceFull accepts two credential types:

  1. Session bearer — passwordless login for operators and customers.
  2. API key — machine access for integrations and MCP (bk_… prefix).

Passwordless session

Step 1 — request a verification code

curl -sS -X POST https://placefull.ai/auth/challenges \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","channel":"email_code"}'

Response data.challengeId identifies the challenge. The code is delivered by email (or SMS when enabled).

Step 2 — verify and receive a session token

curl -sS -X POST https://placefull.ai/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"challengeId":"<challenge-id>","code":"123456"}'

Step 3 — send the token on authenticated requests

curl -sS https://placefull.ai/me/profile \
  -H 'Authorization: Bearer <sessionToken>'

Session tokens expire. Repeat the flow when you receive 401 unauthorized.

API key

Create a key with POST /businesses/{businessId}/api-keys (session auth, business.manage). The plaintext bk_ key is returned once. Send it as a Bearer token on feature-gated /businesses/* routes:

curl -sS https://placefull.ai/businesses/<business-id>/customers \
  -H 'Authorization: Bearer bk_your_api_key_here'

That example needs feature crm.view. API keys are not accepted on /me/*, POST /businesses, or the api-keys routes themselves — a key cannot mint its own successor. Gated operator routes also require the feature named in each operation's description (for example booking.manage).

Agents

Point an agent host at this base URL.

WhatURL
MCP (Streamable HTTP)POST https://placefull.ai/mcp
Server cardhttps://placefull.ai/.well-known/mcp.json
Agent guidehttps://placefull.ai/llms.txt
OAuth metadatahttps://placefull.ai/.well-known/oauth-authorization-server
Operator setup (console)https://placefull.ai/app/settings?show=integrations

Claude (recommended): paste https://placefull.ai/mcp into Settings → Connectors → Add custom connector → Connect → sign in with the operator email. OAuth 2.1 + PKCE — no API key.

Cursor / CI: create a bk_ API key and send Authorization: Bearer bk_… on POST /mcp.

Unauthenticated POST /mcp returns 401 with WWW-Authenticate pointing at protected-resource metadata so clients discover OAuth automatically.

API surfaces

SurfacePrefixAudience
Operator API/businesses/…, /offerings/…, /locations/…, …Operators and integrations managing a business
Storefront API/storefront/…Public embeddable booking widgets
Customer self-service/me/…Signed-in customers managing their profile and bookings

Storefront routes are public read (no auth) except booking hold and confirm, which require a customer session. Storefront routes are rate limited — see below.

Errors

Errors return a non-2xx status with this envelope:

{
  "error": {
    "code": "validation",
    "message": "email is required",
    "details": {}
  }
}
CodeHTTPMeaning
validation400Invalid input
unauthorized401Missing or invalid credentials
forbidden403Authenticated but not permitted (missing feature or role)
not_found404Resource does not exist
conflict409State conflict (capacity, duplicate, or concurrent hold lost)
too_many_requests429Rate limit exceeded
internal_error500Unexpected server error

Rate limits

Storefront routes (/storefront/…) are limited to 480 requests per minute per visitor by default (STOREFRONT_RATE_LIMIT_MAX / STOREFRONT_RATE_LIMIT_WINDOW_MS). The visitor is the cf-connecting-ip header when it is a single IP, otherwise the connection address. Cart and other unauthenticated storefront writes have a separate limit of 60 per minute (STOREFRONT_WRITE_RATE_LIMIT_MAX). When exceeded, the API returns 429 too_many_requests with a Retry-After header (seconds until the window resets). Operator routes are not globally rate limited in v1.

Pagination

Offset pagination — CRM customer list (GET /businesses/:id/customers):

Cursor pagination — storefront offering lists (GET /storefront/locations/:id/offerings), the Products list (GET /businesses/:id/products), and one option's stock ledger (GET /products/:productId/variants/:variantId/stock):

Versioning

info.version tracks the REST contract. Breaking changes (removed fields, renamed paths, semantic changes) bump the major version. Additive changes (new optional fields, new endpoints) are minor. The MCP surface is versioned separately via tool schemas.

Download this spec from /openapi.json to generate clients or import into Postman.

Endpoints

Every operation, grouped as the interactive reference groups them. Exact request and response schemas, examples and the required feature for each gated operation are in the OpenAPI document: https://placefull.ai/openapi.json. Interactive reference with "try it": https://placefull.ai/docs.

Platform

system — Process health and platform status

auth — Passwordless authentication

person — Person identities

access — Team roles and feature gates

Operator API

business — Business profiles and settings

location — Physical locations

catalog — Spaces, team, and offerings

products — Products, their options, and the stock ledger

availability — Schedule projection and bookable slots

booking — Operator booking lifecycle

commerce — Payments, balances, and Stripe Connect

crm — Customer records and export

customers — Customer lists and the messages sent to them

membership — Plans, benefits, and pricing

waitlist — Waitlists for full dates

chat — Operator chat — an LLM agent over the intent tools

Storefront API

storefront — Public embeddable booking surface

me — Customer self-service for the signed-in person

Agents

MCP (Streamable HTTP): POST https://placefull.ai/mcp · server card: https://placefull.ai/.well-known/mcp.json · agent guide: https://placefull.ai/llms.txt