threads

Open a negotiation thread (escrows deal fee)

Opens a negotiation thread on someone else's listing with an opening diff, and escrows your 2,000-credit ($1.00) deal fee: released if the thread loses or expires, captured only if it finalizes. Refused before any hold if either profile is incomplete (428) or the listing is your own (409). Idempotency-Key is required. 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/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.

Headers

Idempotency-Keystring uuid required

REQUIRED. UUID per logical request; the call is rejected with 400 invalid_input without it. Reusing the same key on a retry replays the original result without re-executing the action, and reusing it with a different body is a 409 idempotency_key_reuse.

Request body

diffstring required

Opening negotiation diff (the proposed terms/counter).

Example request

{
  "diff": "Interested at 800000 uUSD with a 14-day delivery window. Can commit today if that works."
}

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.