Available

Directory

get/v1/directory/listings

Public global-directory listing read. Only GLOBAL/BOTH-visibility listings ever appear here — PRIVATE and ENTERPRISE never do. See the Glossary guide "Global vs Private vs Both vs Enterprise".

curl -X GET https://api.tbbnetwork.com/v1/directory/listings \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

category	query	optional
q	query	optional
swap	query	optional
sort	query	optional
buy	query	optional
minPrice	query	optional
maxPrice	query	optional
seller	query	optional
page	query	optional
matchFor	query	optional
kind	query	optional
make	query	optional
subcategory	query	optional
brand	query	optional
minYear	query	optional
maxYear	query	optional
minBedrooms	query	optional
offering	query	optional

Response (200)

Field	Type	Required
data	object[]	—
nextCursor	stringnull	—
total	integer	—
page	integer	—
pageCount	integer	—
matchedFor	objectnull	—
categories	object[]	—
subcategories	object[]	—

Example 200 response

{
  "data": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantListingRef": null,
      "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "title",
      "category": "category",
      "subcategory": null,
      "brand": null,
      "model": null,
      "size": null,
      "condition": null,
      "year": null,
      "originalPrice": 1,
      "currency": "USD",
      "visibility": "PRIVATE",
      "status": "ACTIVE",
      "listingType": "SALE",
      "deliveryMethod": "LOCAL_PICKUP",
      "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "city": null,
      "region": null,
      "locationLabel": null,
      "locationCountry": null,
      "sellerIdentityVerified": false,
      "publicNow": false,
      "notPublicReason": "PENDING_REVIEW",
      "kind": "GOODS",
      "details": null,
      "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "sellerStoreSlug": null,
      "viewerIsOwner": false,
      "merchantItemUrl": null,
      "requestedAmount": null,
      "willingToPay": null,
      "note": null,
      "images": [],
      "wants": [],
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-01T12:00:00Z",
      "syncedAt": "2026-07-01T12:00:00Z",
      "deletedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "nextCursor": null,
  "total": 1,
  "page": 1,
  "pageCount": 1,
  "matchedFor": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "title"
  },
  "categories": [
    {
      "category": "category",
      "count": 1
    }
  ],
  "subcategories": [
    {
      "subcategory": "subcategory",
      "count": 1
    }
  ]
}

get/v1/directory/storefronts/{slug}

A member's public storefront: their name, bio, photo, whether they've verified their identity, reputation, completed swaps and general location, and the items they listed themselves (never a store's listings of their items) — public ones only, 24 a page.

curl -X GET https://api.tbbnetwork.com/v1/directory/storefronts/{slug} \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

slug	path	required
page	query	optional

Response (200)

Field	Type	Required
storefront	object	—
listings	object[]	—
total	integer	—
page	integer	—
pageCount	integer	—

Example 200 response

{
  "storefront": {
    "slug": "example-slug",
    "name": "Acme Co.",
    "bio": null,
    "avatarUrl": null,
    "identityVerified": false,
    "reputationScore": null,
    "memberSince": "2026-07-01T12:00:00Z",
    "completedSwaps": 1,
    "location": null
  },
  "listings": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantListingRef": null,
      "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "title",
      "category": "category",
      "subcategory": null,
      "brand": null,
      "model": null,
      "size": null,
      "condition": null,
      "year": null,
      "originalPrice": 1,
      "currency": "USD",
      "visibility": "PRIVATE",
      "status": "ACTIVE",
      "listingType": "SALE",
      "deliveryMethod": "LOCAL_PICKUP",
      "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "city": null,
      "region": null,
      "locationLabel": null,
      "locationCountry": null,
      "sellerIdentityVerified": false,
      "publicNow": false,
      "notPublicReason": "PENDING_REVIEW",
      "kind": "GOODS",
      "details": null,
      "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "sellerStoreSlug": null,
      "viewerIsOwner": false,
      "merchantItemUrl": null,
      "requestedAmount": null,
      "willingToPay": null,
      "note": null,
      "images": [],
      "wants": [],
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-01T12:00:00Z",
      "syncedAt": "2026-07-01T12:00:00Z",
      "deletedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageCount": 1
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/directory/listings/{id}

Get a single listing from the public global directory

curl -X GET https://api.tbbnetwork.com/v1/directory/listings/{id} \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
merchantId	string,null (uuid)	—
merchantListingRef	stringnull	—
sellerId	string (uuid)	—
title	string	—
category	string	—
subcategory	stringnull	—
brand	stringnull	—
model	stringnull	—
size	stringnull	—
condition	stringnull	—
year	integernull	—
originalPrice	number	—
currency	string	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE \| DELETED	—
listingType	SALE \| TRADE \| BOTH	—
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH \|	—
preferredSpaceBranchId	string,null (uuid)	—
city	stringnull	—
region	stringnull	—
locationLabel	stringnull	—
locationCountry	stringnull	—
sellerIdentityVerified	boolean	—
publicNow	boolean	—
notPublicReason	PENDING_REVIEW \| NOT_LAUNCHED \| NOT_ACTIVE \|	—
kind	GOODS \| VEHICLE \| PROPERTY \| SERVICE \| TICKET	—
details	object	—
preferredSpaceId	string,null (uuid)	—
sellerStoreSlug	stringnull	—
viewerIsOwner	boolean	—
merchantItemUrl	string,null (uri)	—
requestedAmount	numbernull	—
willingToPay	numbernull	—
note	stringnull	—
images	string[]	—
wants	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
syncedAt	string (date-time)	—
deletedAt	string,null (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantListingRef": null,
  "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "title",
  "category": "category",
  "subcategory": null,
  "brand": null,
  "model": null,
  "size": null,
  "condition": null,
  "year": null,
  "originalPrice": 1,
  "currency": "USD",
  "visibility": "PRIVATE",
  "status": "ACTIVE",
  "listingType": "SALE",
  "deliveryMethod": "LOCAL_PICKUP",
  "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "city": null,
  "region": null,
  "locationLabel": null,
  "locationCountry": null,
  "sellerIdentityVerified": false,
  "publicNow": false,
  "notPublicReason": "PENDING_REVIEW",
  "kind": "GOODS",
  "details": null,
  "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerStoreSlug": null,
  "viewerIsOwner": false,
  "merchantItemUrl": null,
  "requestedAmount": null,
  "willingToPay": null,
  "note": null,
  "images": [
    "value"
  ],
  "wants": [
    {
      "kind": "GOODS",
      "details": {
        "make": "Toyota",
        "yearMin": 2015,
        "mileageMax": 100000,
        "mileageUnit": "km"
      },
      "category": "category",
      "subcategory": null,
      "brand": null,
      "note": null,
      "minCondition": "New",
      "imageUrl": null
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "syncedAt": "2026-07-01T12:00:00Z",
  "deletedAt": "2026-07-01T12:00:00Z"
}

Possible errors

404	Not found, or not GLOBAL/BOTH visibility