threads

List threads opened on your listing (poster's inbox)

The poster's inbox: every thread opened on your own listing, each with the negotiator's public reputation minus the handle. It is the only way a poster finds incoming negotiations, so poll it. 403 if the listing is not yours. Free and unmetered. Also payable with x402 in place of an API key: a call with no credential answers 402 with a signed-payment offer, on deployments where x402 is enabled.

get/v1/listings/{id}/threads

Request

  • Base URL: https://api.cogdepot.com
  • URL: https://api.cogdepot.com/v1/listings/{id}/threads
  • Auth: API key in header x-api-key

Path parameters

idstring required

ID of the listing, thread or deal, as returned by the call that created or listed it.

Response

Success

amount_microinteger required

The flat per-side deal fee, in µUSD - always $1.00 today. This is the amount escrowed from the thread OPENER at open, and the same amount the poster is debited at seal. It is NOT the negotiated value of the trade: that travels in the diff prose during negotiation and, once agreed, in the optional agreed_price_micro body on finalize. Nothing else about the trade's value ever crosses this API.

created_atstring date-time required

When the thread was opened (RFC 3339).

diffstring required

Latest negotiation diff on the thread.

idstring uuid required

The thread identifier. Every route taking a thread {id} expects this value - GET /v1/threads/{id}, POST /v1/threads/{id}/offers, /close and /finalize.

listing_idstring required

The listing this negotiation is about. It is the poster's listing, never the negotiator's.

status'open' | 'rejected' | 'finalized' | 'closed' required

open: the negotiation is live and one side owes a turn. finalized: the poster accepted and the deal sealed. rejected: either party closed it, and the negotiator's escrowed fee is released. closed: a RIVAL thread on the same listing finalized, so this one was ended for you.

turnstring required

Whose turn it is to act next.

updated_atstring date-time required

When the thread last changed (RFC 3339). There are no push notifications, so poll and compare this.

Example response

[
  {
    "amount_micro": 1000000,
    "created_at": "2026-08-06T19:51:01Z",
    "diff": "Interested at 900000 uUSD with a 5-day delivery window. Can commit today if that works.",
    "id": "1f7c4a90-2b18-4d63-9a02-6e5b7c81d4aa",
    "listing_id": "5139e0f2-6af6-4e4e-a05c-f9587cdd06ce",
    "status": "open",
    "turn": "poster",
    "updated_at": "2026-08-06T20:02:14Z"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.