TBBN.Space API docs

API Reference

TBBN Platform API — v0.1.0

Trade By Barter Network infrastructure API. This document fully specifies the Phase 0-13 working surface: Auth, Merchants, API Keys, Sellers/Identity, Listings, Catalog, Media, Directory, Search, Trade Engine (settlement), Currency, Localization, Matching, Recommendations, Offers, Reservations, Trade Sessions, Checkout, Billing, Notifications, Webhooks, Audit, Moderation, Fraud, Reputation, Analytics, Feature Flags, and Sandbox — see docs/api/openapi-workflow.md.

Production: https://api.tbbnetwork.comSandbox: https://sandbox-api.tbbnetwork.comLocal dev (via api-gateway): http://localhost:3000

Live resources

Fully implemented — see the matching service's README for how it's tested.

Space

WORKING

24 endpoints

All live endpoints

post/v1/space/branches/{branchId}/spacesHost creates a Space (a bookable room within this Branch, Phase 34) — requires ACCOUNT_MANAGER+ role and a VERIFIED Business.
get/v1/space/branches/{branchId}/spacesList a Branch's Spaces
get/v1/space/spaces/{id}Get a Space
patch/v1/space/spaces/{id}Update a Space's profile/visibility (owner-role only)
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, Phase 34 — was per-branch)
get/v1/space/spaces/{spaceId}/pricingList a Space's pricing
post/v1/space/commission-rates/{branchId}Ops-only in practice — sets TBBN's commission percentage for one branch. Absent, the platform default applies (DEFAULT_COMMISSION_PERCENT in space-service).
post/v1/space/branches/{branchId}/connect-accountHost starts Stripe Connect payout onboarding for a branch (owner-only)
post/v1/space/bookingsCreate a Space booking and initiate payment. Standalone — bookable by any Marketplace member for any reason, not gated on a TBBN listing or trade.
get/v1/space/bookingsList bookings for a branch or Space (host calendar), for a trader, or for a headless-booking Business
post/v1/space/bookings/{id}/consentPublic, token-gated (Phase 34) — 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}/payment-webhookUnauthenticated by design — mirrors checkout-service's own payment-webhook shape (a pre-existing simplification in this codebase). Marks PAID and notifies the host only now, per §7.3.
post/v1/space/bookings/{id}/confirmEither the trader or the host confirms the exchange happened — triggers payout immediately (§11: payout is deferred until confirmation, not payment-clearing).
post/v1/space/bookings/{id}/cancelTrader cancels — only allowed while still PENDING_PAYMENT (no refund flow yet)
get/v1/space/branches/{branchId}/payoutsHost payout history for a branch
get/v1/space/searchGlobal Space discovery — filterable by country/region/postalCode/lat+lng+radiusMiles/ free-text query, unbounded unless radiusMiles is given. Public; presenting a valid sk_space_* API key (Authorization: Bearer) applies that key's saved filter defaults and pinned "primary results." Only spaceStatus=SPACE_ENABLED Branches are ever returned — this pass's de-facto verification gate, see the SpaceApiKey guide.
get/v1/branches/nearby-spacesTBBN Spaces within radiusMiles (default 200) of a point — the marketplace's own listing-time Space picker (Phase 31), deliberately separate from the global, unbounded /v1/space/search (Phase 32). Public; a marketplace-member session additionally unlocks any RESTRICTED_EMAIL Space matching their verified email (Phase 34).
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 (Phase 34). Returns a safe display subset only.