Base path: /api/v1. Every response is JSON. Errors use:
{ "error": { "code": "content_rejected", "message": "...", "field": "content" } }The ingest endpoint accepts a closed set of fields. Anything else is refused before the record reaches the index, so message content cannot be stored even by mistake:
- A request carrying
content,body,text,message,plaintext,payload,data,ciphertext,subject,preview,attachmentorattachmentsfails with400 content_rejected. - Any other unrecognised field fails with
400 unknown_field. - No response includes message content, and
contentAvailableis alwaysfalse.
Records one encrypted message. Requires Content-Type: application/json.
| Field | Type | Required | Notes |
|---|---|---|---|
ciphertextHash |
string | yes | 64 lowercase hex chars. Digest of the encrypted payload, computed on the client |
size |
integer | yes | Ciphertext length in bytes, 1..CHATSCAN_MAX_CIPHERTEXT_BYTES |
protocol |
string | no | C7 (default), C7G, ETH, X11 |
channelHash |
string | no | 64 hex chars. Opaque conversation identifier |
nonce |
string | no | Up to 64 hex chars. Distinguishes repeat sends of an identical ciphertext |
fee |
number | no | Non-negative fee paid for inclusion |
appVersion |
string | no | Up to 32 chars of [A-Za-z0-9._+-] |
anchorTxid |
string | on CDCI | 64 hex chars. The CDCI transaction whose OP_RETURN carries this record's commitment. Required when CDCI_REQUIRE_ANCHOR=true |
Authentication: none while CHATSCAN_INGEST_KEYS is unset. Once set, send
Authorization: Bearer <key> or X-ChatScan-Key: <key>.
201 Created - the record was admitted:
{
"ref": "d700bc90...27a8/42",
"hash": "d700bc90...27a8",
"id": 42,
"status": "confirmed",
"rejectionReason": null,
"commitment": "7c1d...9e",
"anchor": {
"txid": "7b19...c4",
"outputIndex": 1,
"blockHash": "00000a...f1",
"blockHeight": 184203,
"confirmations": 2,
"chainlock": false,
"finality": "confirmed",
"verifiedAt": "2026-08-06T12:00:00.000Z"
},
"explorerUrl": "/tx/d700bc90...27a8/42",
"record": { "...": "see the record object below" }
}status is confirmed when the anchor is already in a CDCI block, and pending while it is still in the mempool or the
node has not been reached yet.
202 Accepted - the submission was well formed but violated chain policy. It is still indexed, with
status: "rejected" and a rejectionReason of:
| Reason | Cause |
|---|---|
replay-detected |
This ciphertext digest and nonce were already recorded |
protocol-size-exceeded |
size is over the protocol's ceiling |
anchor-missing |
No anchorTxid, while the node requires one |
anchor-not-found |
The CDCI node does not know that transaction (it needs -txindex=1) |
anchor-mismatch |
The transaction's OP_RETURN commits to a different submission |
Other statuses: 400 validation failure, 401 bad ingest key, 413 body over CHATSCAN_MAX_REQUEST_BYTES,
429 over CHATSCAN_INGEST_RATE_PER_MINUTE.
Returns the commitment for a submission that has not been sent yet, so a client can publish the anchor first. Takes the
same fields as POST /api/v1/records (anchorTxid optional and ignored).
{
"chainId": "cdci:main",
"preimage": "chatscan/1:cdci:main|3f2a...b1|1024|C7||",
"commitment": "7c1d...9e",
"marker": "CS1",
"opReturnPayload": "4353317c1d...9e",
"opReturnScript": "6a234353317c1d...9e",
"note": "Publish this payload in an OP_RETURN output on the CDCI chain, then submit the record with the transaction id as \"anchorTxid\"."
}The derivation is documented in CDCI.md; a client can compute it offline.
The same instructions for a record already indexed, plus its current anchor state.
Newest first. Query: limit (1-100, default 25), offset, status (pending, confirmed, rejected),
protocol, channel (64 hex chars).
{ "total": 128, "limit": 25, "offset": 0, "records": [ { "...": "record object" } ] }The record object for one reference. 400 invalid_ref if the reference is malformed, 404 if it is unknown.
{
"record": {
"ref": "d700bc90...27a8/42",
"hash": "d700bc90...27a8",
"id": 42,
"commitment": "7c1d...9e",
"ciphertextHash": "3f2a...b1",
"size": 1024,
"protocol": "C7",
"protocolLabel": "Protocol C7",
"channelHash": "9c81...0e",
"fee": 0.00042,
"appVersion": "cc-1.0",
"status": "confirmed",
"rejectionReason": null,
"receivedAt": "2026-08-06T12:00:00.000Z",
"confirmedAt": "2026-08-06T12:00:15.000Z",
"blockHeight": 184203,
"blockHash": "00000a...f1",
"indexInBlock": null,
"anchor": {
"txid": "7b19...c4",
"outputIndex": 1,
"blockHash": "00000a...f1",
"blockHeight": 184203,
"confirmations": 2,
"chainlock": false,
"finality": "confirmed",
"verifiedAt": "2026-08-06T12:00:00.000Z"
},
"encrypted": true,
"contentAvailable": false
}
}anchor.finality is mempool, confirmed, final, chainlocked or unknown. anchor is null on the local
development chain, where indexInBlock is used instead.
Newest first, from the CDCI node. Query: limit (1-100, default 10), offset. Answers 502 cdci_unavailable when the
node cannot be reached.
One block plus the message records it carries - anchored in it on CDCI, sealed into it on the local chain.
{
"block": {
"source": "cdci",
"height": 184203,
"hash": "00000a...f1",
"previousHash": "00000b...c4",
"nextHash": "00000c...02",
"merkleRoot": "7de1...aa",
"timestamp": "2026-08-06T12:00:15.000Z",
"algorithm": "x11",
"difficulty": 1543.219,
"chainwork": "000000000000000000000000000000000000000000000000000000000f4240",
"nonce": 431,
"bits": "1e0ffff0",
"version": 536870912,
"txCount": 12,
"sizeBytes": 24576,
"confirmations": 9,
"chainlock": true,
"totalFees": null,
"sealedBy": null,
"recordRefs": null
},
"records": [ { "...": "record object" } ]
}source is cdci or local. totalFees, sealedBy and recordRefs are local-chain fields; chainwork, bits,
confirmations and chainlock come from CDCI.
Resolves a {HASH}/{ID-number} reference, a 64-hex record hash, block hash or anchor transaction id, a block height, or
a record ID-number. kind is one of record-ref, record-hash, block-hash, anchor-txid, number, empty,
unsupported.
{
"query": "1",
"kind": "number",
"results": [{ "type": "record", "url": "/tx/d700bc90...27a8/1", "record": { "...": "" } }]
}Network snapshot: backend, chain state, height, tip hash, fee estimate, unconfirmed count and bytes, throughput, 24-hour totals, per-record averages, anchoring settings, supported protocols, and the privacy statement. This is what the dashboard header renders.
status is online, syncing or offline on CDCI (degraded and paused apply to the local chain). The chain
object holds the node's own figures - chain, blocks, headers, bestBlockHash, difficulty, chainwork, peers,
subversion, mempool, chainlock - plus reachable and error when the node cannot be reached.
Just the chain state from /api/v1/status, without the record aggregates.
The eleven X11 rounds in CDCI HashX11 order, with the digest bound to each slot, and a note on what these hashes are
used for. In cdci mode block hashes come from the node, not from here.
Server-sent events. Emits status on connect and on a heartbeat, record when a message is indexed, and block when
one is sealed. Payloads are the same public objects used elsewhere, so no content is ever streamed.
curl -N http://localhost:3000/api/v1/streamLiveness probe: { "status": "ok", "uptimeSeconds": 42 }.