threads

Submit or counter the standing diff (shared turn-taking)

Puts up or counters the standing diff on a thread. Both parties use this one endpoint, strictly alternating turns. Free and unmetered. Retry-safe without an Idempotency-Key, and the header is not read: the turn alternation condition is the dedup. A repeat of a POST that already landed is out of turn, so it answers 409 out_of_turn rather than replaying the first result. 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.

post/v1/threads/{id}/offers

Request

  • Base URL: https://api.cogdepot.com
  • URL: https://api.cogdepot.com/v1/threads/{id}/offers
  • 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.

Request body

diffstring required

The counter-offer diff (proposed terms).

Example request

{
  "diff": "900000 uUSD and I can hold the 14-day window. Below that the scan depth drops."
}

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.