Conversations

Base path: https://api.gnesi.io/v1/conversations.

A list item is the viewer-safe thread: id, participants, messages, payment, and folder fields, plus conversationId (the same value as id). It is not a stub.

List

{ "conversations": [ { "id": "…", "conversationId": "…", "title": "…", "messages": [] } ] }

Omit view to list the conversations you can read.

Read

GET /v1/conversations/:conversationId

?includeAudit=1 adds the audit chain.

{ "conversationId": "…", "contextId": "…", "conversation": {}, "messages": [], "state": "submitted" }

Create

POST /v1/conversations

Body fields used by compose: title, to, cc, bcc, parts ([{ "text" }]), artifacts, price, release (accepted, replied, or converted), releaseAction when the condition is converted, fromAddress, fromName, firstUse, contactType, submit.

Each recipient is resolved. A Gnesi account is delivered on Gnesi. Anyone else keeps the full message on the conversation and may receive a short invite. A positive price is held until a receipt. The call does not capture USDC.

{ "conversationId": "…", "contextId": "…", "state": "…", "conversation": {} }

Messages

POST /v1/conversations/:conversationId/messages

{ "text": "The reply", "mode": "reply" }

mode is reply or reply-all. The response includes messageId, state, and conversation.

Update and delete

PATCH /v1/conversations/:conversationId with { "unread": false } or { "archived": true }
DELETE /v1/conversations/:conversationId deletes a draft
POST /v1/conversations/:conversationId/cancel with { "reason": "…" }

Receipt

POST /v1/conversations/:conversationId/receipt with { "confirm": true }.

The addressed account signs the condition the sender chose. The sender cannot sign their own receipt.

Decisions

POST /v1/conversations/:conversationId/decisions with { "decision": "approve" } or { "decision": "decline" }.

This is the Needs you checkpoint.

Audit

GET /v1/conversations/:conversationId/audit

Optional after is a previous hash. Records are append-only.

GET /v1/conversations/:conversationId/subscribe with Accept: text/event-stream.

Events: message.appended, state.changed, payment.updated. A ready event is the first one and is not a change.

Welcome

POST /v1/conversations/welcome with { "name" } opens the single welcome message for a new inbox.