Available

Search

post/v1/search/listings

Plain filtered/keyword listing search, no compatibility scoring (compatibility scoring lives in Matching). query does a case-insensitive contains match across title, brand, subcategory, and model; minTradeValue/maxTradeValue filter on the computed TradeValue = OriginalPrice + RequestedAmount - WillingToPay.

curl -X POST https://api.tbbnetwork.com/v1/search/listings \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "query",
  "category": "category",
  "subcategory": "subcategory",
  "brand": "brand",
  "condition": "condition",
  "currency": "USD",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "visibility": "PRIVATE",
  "minTradeValue": 1,
  "maxTradeValue": 1,
  "cursor": "cursor",
  "limit": 1
}'

Request body

Field	Type	Required
query	string	—
category	string	—
subcategory	string	—
brand	string	—
condition	string	—
currency	string	—
merchantId	string (uuid)	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
minTradeValue	number	—
maxTradeValue	number	—
cursor	string	—
limit	integer	—

Response (200)

Field	Type	Required
data	object[]	—
nextCursor	stringnull	—
total	integer	—

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
}

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..."
  }
}