chat

The shychat API is a thin proxy over the shychat-v1 ABCI state machine. It exposes mailbox lifecycle, message dispatch and retrieval, and delivery close paths. The same routes serve shyrest-v1 deployments with surface_model: "mail".

Base URL

Configured via shyconfig.api.base_url. All paths below are relative to that base.

Authentication

All endpoints require Authorization: Bearer <token>. The sub claim is the input to identityHash derivation for List 2.

Privacy contract

GET /api/messages/dispatches enforces ownerUid at the SQL query layer — only the authenticated participant's dispatches are returned. No path returns dispatches across participants.

Endpoint summary

Method	Path	Description
GET	/api/messages/mailboxes	List mailboxes accessible to the caller
POST	/api/messages/mailboxes	Create a mailbox (period open)
GET	/api/messages/mailboxes/:mailboxId	Get a mailbox record
POST	/api/messages/dispatches	Dispatch a message (atomic List 1 + List 2 write)
POST	/api/messages/mailboxes/:mailboxId/close	Close a mailbox + KMS attestation
POST	/api/messages/mailboxes/:mailboxId/receipt	Write delivery receipt (off-chain)
GET	/api/messages/mailboxes/:mailboxId/receipt	Read delivery receipt
GET	/api/messages/activity	Caller's activity log
POST	/api/messages/period-close	Trigger period close
DELETE	/api/messages/dispatches/:dispatchId	Withdraw a dispatch (bilateral removal)
PUT	/api/messages/dispatches/:dispatchId	Update a dispatch (direction change)
GET	/api/messages/dispatches	List caller's dispatches
GET	/api/messages/mailboxes/:mailboxId/dispatches	List dispatches in a mailbox
GET	/api/messages/ledger/count/:scopingId	Count-match query for a scoping ID

POST /api/messages/dispatches

Broadcasts a MessageDispatch transaction — an atomic two-list write.

{
  "mailbox_id": "mbx-001",
  "message_nonce": "<32-byte hex>",
  "sealed_body": "<AES-GCM ciphertext>",
  "sealed_subject": "<AES-GCM ciphertext>",
  "content_class": "report",
  "audit_mode": "delivery_commitment_only",
  "sender_pub_key": "<Ed25519 hex>",
  "sender_sig": "<Sign(sk_s, nonce + ':' + mailbox_id)>",
  "idv_attestation": { ... }
}

Response: { "message_id": "<H(nonce)>" }

sealed_body and sealed_subject must be AES-GCM encrypted before submission. Readable content is never stored in canonical state.

DELETE /api/messages/dispatches/:dispatchId

Bilateral withdrawal: removes List 1 message entry and List 2 identity entry atomically. Count-match preserved.

GET /api/messages/ledger/count/:scopingId

Returns { "list1_count": N, "list2_count": N } for a mailbox scoping ID. Used to verify count-match independently.