TBBNSpaceDocs

API Reference

TBBN Platform API — v0.1.0

TBBN infrastructure API — the identity federation, listing exchange, matching, offer/trade-session management, and checkout-orchestration surface your platform integrates against: Auth, Merchants, Businesses, API Keys, Sellers/Identity, Listings, Catalog, Media, Directory, Search, Trade Engine (settlement), Currency, Localization, Matching, Recommendations, Offers, Trade Sessions, Checkout, Billing, Notifications, Webhooks, Reputation, Analytics, Space, and Sandbox.

Production — sandbox vs. live is determined by which API key prefix you present (sk_sandbox_... or sk_live_...), not a different host or URL.: https://api.tbbnetwork.com

Resources

Every area of the API, with its endpoint count.

Space

Available

45 endpoints

All endpoints

post/v1/space/branches/{branchId}/spacesHost creates a Space (a bookable room within this Branch) — requires a team role that manages Spaces at this location (owner, Admin, Account manager or Operations). Verification is not required; an unverified Business can create a Space exactly like a verified one (it just shows an "Unverified" badge publicly). Verification instead gates Merchant creation, a separate resource.
get/v1/space/branches/{branchId}/spacesList a Branch's Spaces. Returns the full Space shape (including icalToken/ externalCalendarUrl/wifiInstructions/allowedEmails/allowedEmailDomains) only to that Business's team members who can see this location's bookings; every other caller — including unauthenticated — gets SpacePublicView instead, which never includes those fields.
get/v1/space/spaces/{id}Get a Space. Returns the full Space shape (including icalToken/externalCalendarUrl/ wifiInstructions/allowedEmails/allowedEmailDomains) only to the owning Business's team members who can see this location's bookings; every other caller — including unauthenticated — gets SpacePublicView instead, which never includes those fields. 404s for a non-owner if the Space isn't currently visible to them at all (DRAFT/DISABLED, or a visibility restriction they don't satisfy), rather than confirming the id exists.
patch/v1/space/spaces/{id}Update a Space's profile/visibility (owner-role only). Once the owning Business's verificationStatus is VERIFIED, also requires a step-up token scoped to "space:update" — see POST /v1/auth/step-up/confirm.
delete/v1/space/spaces/{id}Delete a Space (owner-role only)
post/v1/space/spaces/{spaceId}/pricingHost sets per-service-type pricing for a Space (owner role only)
get/v1/space/spaces/{spaceId}/pricingList a Space's pricing
post/v1/space/businesses/{businessId}/connect-accountBusiness opens its Stripe Connect payout account (ADMIN role or owner). One account per Business, shared by every Branch it runs.
post/v1/space/bookingsCreate a Space booking. With a member session, books and starts payment. With a Space API key, books only the key's own Business's Spaces (another Business's Space is 404): a key in INTERNAL_FREE mode (the default) makes a free, confirmed internal reservation and returns bookingUrl; a key in CHARGE_BOOKER mode returns paymentUrl or consentUrl. A test key (sk_space_sandbox_) makes a test booking (livemode false): never charged, never holding the Space, nobody notified, and its link opens a test page where consent and payment are simulated. A Space with opening hours and a booking length is booked in slots: scheduledAt must be the start of an AVAILABLE slot from GET /v1/space/spaces/{id}/availability. Otherwise the booking is refused with 400 and a code saying why — NOT_A_BOOKING_TIME, SLOT_FULL, SLOT_BLOCKED, SLOT_TOO_SOON, SLOT_TOO_FAR or SLOT_PAST — a message naming the next open times, and details.nextAvailable, the next few slot starts.
get/v1/space/bookingsList bookings for a branch or Space (host calendar — any team member of the owning Business who can see that location), for a trader (only their own), or for a headless-booking Business (any team role). With a Space API key: bookings at the key's own Spaces, filtered by spaceId, branchId, from and to. Host and key views never include PINs, check-in codes or link tokens.
post/v1/space/bookings/{id}/consentPublic, token-gated — accepts a headless booking's required consent step, moving it from AWAITING_CONSENT to PENDING_PAYMENT and returning a paymentUrl.
post/v1/space/bookings/{id}/confirmEither the trader or the host confirms the exchange happened — this is what makes the payout eligible to go out (nothing pays out at checkout/payment-clearing time). The payout itself is created here but disbursed in the next weekly batch (Mondays, 08:00 America/Los_Angeles), not at the moment this call completes.
post/v1/space/bookings/{id}/cancelTrader cancels (or a Space API key cancels a booking it made). An internal reservation, or a booking that hasn't been paid, is simply cancelled. A paid booking is refunded in full if it's within the Space's cancellationPolicy window; outside it, the booking still cancels but is not refunded, and the host is paid as if it had been confirmed.
post/v1/space/bookings/{id}/verify-check-inHost/reception enters the check-in code a Coworking space guest showed up with.
post/v1/space/bookings/{id}/verify-dropoff-pinHost front desk, drop-off bookings. Checks the PIN the person dropping off gives in person. Refused (409) until that person has added a photo of the item through the handover; the host takes no photo. Every party is emailed.
post/v1/space/bookings/{id}/verify-pickup-pinHost front desk, drop-off bookings. Checks the PIN the person picking up gives in person, once they have added a photo of the item, and completes the booking. Every party is emailed.
get/v1/space/bookings/{id}/handoverA drop-off booking's handover — status, photos, timeline
post/v1/space/bookings/{id}/handover/photosAdd a drop-off or pickup photo of the item
get/v1/space/pickupsDrop-offs the signed-in member is picking up
post/v1/space/bookings/{id}/recipient/respondAccept or decline picking up a drop-off
put/v1/space/bookings/{id}/recipientChange who picks up a drop-off
get/v1/space/test-bookingsA Business's test-mode bookings
get/v1/space/test-bookings/{id}A test booking, for its hosted test page
post/v1/space/test-bookings/{id}/simulateSimulate the booker giving consent, paying, or the payment failing
post/v1/space/bookings/{id}/no-showHost/reception marks a paid, unconfirmed WORKSPACE booking a no-show once its scheduled time has passed and nobody checked in. Pays the host, does not refund the trader.
post/v1/space/bookings/{id}/approveHost/reception approves a pending request-to-book, moving AWAITING_APPROVAL to PENDING_PAYMENT and creating the Stripe intent.
post/v1/space/bookings/{id}/declineHost/reception declines a pending request-to-book. Nothing was charged.
post/v1/space/bookings/recurringBooks the same WORKSPACE slot weekly across N occurrences — each an independent SpaceBooking sharing a recurringSeriesId, priced and paid separately. Session-authenticated only; no headless equivalent yet.
post/v1/space/bookings/recurring/{seriesId}/cancelCancels every still-cancellable, not-yet-occurred booking in a recurring series — the trader who made it only. A past or already-completed occurrence is left alone.
get/v1/space/spaces/{id}/calendar.icsPublic, token-gated ICS calendar feed of this Space's busy windows — subscribe a calendar app directly to this URL. No TBBN session; guarded only by the unguessable token in Space.icalToken. Event summaries are generic ("Booked") and never carry guest names, companies, or payment details.
post/v1/space/spaces/{id}/calendar/syncHost-only — fetches Space.externalCalendarUrl on demand rather than waiting for the scheduled 15-minute poll, parses its busy windows, and stores them as Space.externalBusyRanges.
get/v1/space/spaces/{id}/availabilityA Space's bookable slots. Each open day is divided into slots of the Space's booking length, from opening time, while a whole booking fits before closing (open 8:00 to 17:00 with 30-minute bookings: 8:00–8:30, 8:30–9:00 … 16:30–17:00); a booking a day or longer has one slot a day, starting at opening. Each slot has its spots left and a state — AVAILABLE, FULL, BLOCKED (the host isn't taking bookings), TOO_SOON (inside the minimum notice), TOO_FAR (beyond how far ahead the Space takes bookings) or PAST. Days are CLOSED (not open that weekday), UNAVAILABLE (a closed date) or OPEN. A Space without hours and a booking length answers scheduled false.
get/v1/space/branches/{branchId}/scheduleA location's schedule for its team (bookings.view): each Space's slots for the days asked (7 by default, at most 62) with the bookings holding each slot — first name, status, spot, whether checked in — and the host's blocked times. canManage says whether the caller may block times.
post/v1/space/spaces/{id}/blocked-timesBlock a time on a Space's schedule — a slot, a break, a private event (spaces.manage). New bookings can't start or run into it; bookings already made aren't changed. At most 31 days per block; use blackout dates for longer closures.
post/v1/space/spaces/{id}/blocked-times/removeRemove every blocked time that overlaps the given time (spaces.manage).
get/v1/space/branches/{branchId}/spot-boardA location's spot board — for each Space, who should be in each spot right now, who's next, and who's arriving in the next 24 hours, plus whether it's open now. For the host's team (bookings.view). Guests are shown by first name only.
get/v1/space/branches/{branchId}/payoutsHost payout history for a branch
get/v1/space/searchSpace search — filterable by country/region/postalCode/lat+lng+radiusMiles/category/ capacity/amenity/free-text query. Without a credential it returns public Spaces. With a Space API key it returns only that key's own Business's live Spaces, of any visibility, and applies the key's saved defaults and pinned locations.
get/v1/branches/nearby-spacesTBBN Spaces within radiusMiles (default 200) of a point — the marketplace's own listing-time Space picker (use /v1/space/search for unbounded search). Public; a marketplace-member session additionally unlocks any RESTRICTED_EMAIL Space matching their verified email.
post/v1/space/api-keysBusiness owner creates a Space API key
get/v1/space/api-keysList a Business's Space API keys (owner-only)
post/v1/space/api-keys/{id}/rotateRotate a Space API key's secret (owner-only) — keyPrefix changes, businessId does not
delete/v1/space/api-keys/{id}Revoke a Space API key (owner-only)
patch/v1/space/api-keys/{id}/configSet a Space API key's filter defaults and pinned Spaces (owner-only)
get/v1/space/bookings/{id}/payment-infoBacks the hosted payment page (space.tbbnetwork.com/pay/:id) — authorized either by a matching token (headless booking, no session) or a marketplace-member session naming this booking's own bookedByUserId. Returns a safe display subset only.