TBBNMerchantDocs
Available

Messages

get/v1/conversations

Your conversations about members' listings — items you asked about, and your own items people asked you about — newest first. 

curl -X GET https://api.tbbnetwork.com/v1/conversations \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Example 200 response
[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "role": "BUYER",
    "listing": {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "title",
      "image": null,
      "status": "status"
    },
    "counterpart": {
      "name": null
    },
    "lastMessageAt": "2026-07-01T12:00:00Z",
    "lastMessagePreview": "lastMessagePreview",
    "unread": false
  }
]

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/inbox

Every conversation you're in — about items, on your trades, and with Spaces, as a guest or a host — newest first, with what's unread in each. 

curl -X GET https://api.tbbnetwork.com/v1/inbox \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Example 200 response
[
  {
    "kind": "ITEM",
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "title",
    "withName": null,
    "preview": "preview",
    "lastMessageAt": "2026-07-01T12:00:00Z",
    "unread": 1,
    "href": "href"
  }
]

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/inbox/summary

How many messages you haven't read, in total and by kind

curl -X GET https://api.tbbnetwork.com/v1/inbox/summary \
  -H "Authorization: Bearer <session access token>" \

Response (200)

FieldTypeRequired
unreadinteger—
unreadThreadsinteger—
itemsinteger—
tradesinteger—
spacesinteger—
Example 200 response
{
  "unread": 1,
  "unreadThreads": 1,
  "items": 1,
  "trades": 1,
  "spaces": 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/conversations/unread-count

How many of your conversations have messages you haven't read

curl -X GET https://api.tbbnetwork.com/v1/conversations/unread-count \
  -H "Authorization: Bearer <session access token>" \

Response (200)

FieldTypeRequired
totalinteger—
Example 200 response
{
  "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..."
  }
}
get/v1/conversations/listings/{listingId}

Your conversation about a listing, if you've started one

curl -X GET https://api.tbbnetwork.com/v1/conversations/listings/{listingId} \
  -H "Authorization: Bearer <session access token>" \

Parameters

listingIdpathrequired

Response (200)

FieldTypeRequired
conversationIdstring,null (uuid)—
Example 200 response
{
  "conversationId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

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..."
  }
}
post/v1/conversations/listings/{listingId}

Ask the person who listed an item about it. Carries on your conversation about it if you have one. A member's own listing only — not a store's. 

curl -X POST https://api.tbbnetwork.com/v1/conversations/listings/{listingId} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "body"
}'

Parameters

listingIdpathrequired

Request body

FieldTypeRequired
bodystringyes

Response (201)

FieldTypeRequired
conversationIdstring (uuid)—
messageListingConversationMessage—
Example 201 response
{
  "conversationId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "message": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "mine": false,
    "body": null,
    "hidden": false,
    "createdAt": "2026-07-01T12:00:00Z"
  }
}

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/conversations/{id}

A conversation and its messages, oldest first. Reading it marks it read for you.

curl -X GET https://api.tbbnetwork.com/v1/conversations/{id} \
  -H "Authorization: Bearer <session access token>" \

Parameters

idpathrequired

Response (200)

FieldTypeRequired
idstring (uuid)—
roleBUYER | SELLER—
listingobject—
counterpartobject—
messagesobject[]—
Example 200 response
{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "BUYER",
  "listing": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "title",
    "image": null,
    "status": "status",
    "listingType": "listingType",
    "currency": "USD",
    "originalPrice": 1,
    "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "country": null
  },
  "counterpart": {
    "name": null
  },
  "messages": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "mine": false,
      "body": null,
      "hidden": false,
      "createdAt": "2026-07-01T12:00:00Z"
    }
  ]
}

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..."
  }
}
post/v1/conversations/{id}/messages

Reply in a conversation about a listing

curl -X POST https://api.tbbnetwork.com/v1/conversations/{id}/messages \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "body"
}'

Parameters

idpathrequired

Request body

FieldTypeRequired
bodystringyes

Response (201)

FieldTypeRequired
idstring (uuid)—
mineboolean—
bodystringnull—
hiddenboolean—
createdAtstring (date-time)—
Example 201 response
{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "mine": false,
  "body": null,
  "hidden": false,
  "createdAt": "2026-07-01T12:00:00Z"
}

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..."
  }
}
post/v1/messages

Send a message on a trade — the sender is derived from the caller's own session

curl -X POST https://api.tbbnetwork.com/v1/messages \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "body": "body"
}'

Parameters

Request body

FieldTypeRequired
tradeSessionIdstring (uuid)yes
bodystringyes

Response (201)

FieldTypeRequired
idstring (uuid)—
tradeSessionIdstring (uuid)—
senderSellerIdstring (uuid)—
bodystring—
statusVISIBLE | HIDDEN | REMOVED—
createdAtstring (date-time)—
Example 201 response
{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "senderSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "body": "body",
  "status": "VISIBLE",
  "createdAt": "2026-07-01T12:00:00Z"
}

Possible errors

422Rejected — the message body appears to contain contact/off-platform information

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/messages/{tradeSessionId}

List a trade's visible messages, oldest first — caller must be one of its two sellers

curl -X GET https://api.tbbnetwork.com/v1/messages/{tradeSessionId} \
  -H "Authorization: Bearer <session access token>" \

Parameters

tradeSessionIdpathrequired

Response (200)

Example 200 response
[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "senderSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "body": "body",
    "status": "VISIBLE",
    "createdAt": "2026-07-01T12:00:00Z"
  }
]

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..."
  }
}
post/v1/messages/{id}/report

Report a message. It is hidden while TBBN reviews it. Caller must be a party to the message's trade.

curl -X POST https://api.tbbnetwork.com/v1/messages/{id}/report \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer requested cancellation."
}'

Parameters

idpathrequired

Request body

FieldTypeRequired
reasonstringyes

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