Chat messages

Messages are filed under topics (just General for now), each with threads one level deep: a reply to a reply joins its root's thread, in its topic. Without a topic, a request is General's. Messages and replies arrive live as chat events on the event stream, each naming its topic. Where the AI moderation is on, every message is checked before it is posted: Moderation.

List topics #

GET/api/chat/topics

The live topics, in their order, each with its newest message's id and time: a page keeps the last id it read per topic and shows the others as unread. New and archived topics come as chat events {type: "topic", topic, archived}.

Example request #

curl 'https://raresats.net/api/chat/topics'

const response = await fetch('https://raresats.net/api/chat/topics');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/chat/topics").json()

Response 200 #

{
  "topics": [
    {
      "id": "general",
      "name": "General",
      "description": "Anything rare-sat: say gm, ask, share a find.",
      "position": 0,
      "created_at": 1790900000,
      "last_message_id": 1044,
      "last_activity_at": 1790949460
    },
    {
      "id": "market",
      "name": "Market & prices",
      "description": "Listings, offers, floors and what things sell for.",
      "position": 1,
      "created_at": 1790900000,
      "last_message_id": 1042,
      "last_activity_at": 1790949400
    }
  ]
}

Errors #

{error, code}; see Errors for every code.

Create a topic (admin) #

POST/api/chat/topics

An admin session creates a topic, last in the list. Only admins may: topic names are not run through the AI moderation (an admin's text never is), but follow a message's text rules (NFC, no control, zero-width or bidi characters) and its link rule. An id is never reused, an archived topic's included, except a retired one's (a topic the defaults once seeded and no longer name): it comes back as the new topic, its messages with it. At most 50 topics. Pages are told with a chat event {type: "topic", topic, archived: false}. Logged.

Request body #

content-type: application/json

Example request #

curl -X POST 'https://raresats.net/api/chat/topics' \
  -H 'content-type: application/json' \
  -d '{
  "id": "runes",
  "name": "Runes",
  "description": "Runes on rare sats, and what they do to a sat'\''s value."
}'

const response = await fetch('https://raresats.net/api/chat/topics', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    "id": "runes",
    "name": "Runes",
    "description": "Runes on rare sats, and what they do to a sat's value."
  })
});
const data = await response.json();

import requests

data = requests.post("https://raresats.net/api/chat/topics", json={
    "id": "runes",
    "name": "Runes",
    "description": "Runes on rare sats, and what they do to a sat's value."
}).json()

Response 200 #

Errors #

{error, code}; see Errors for every code.

Archive a topic (admin) #

DELETE/api/chat/topics/{id}

An admin session archives a topic: it leaves the list and takes no new messages or replies (404 unknown_topic); its messages stay in the store. General cannot be archived. Pages are told with a chat event {type: "topic", topic, archived: true}. Logged.

Path parameters #

Example request #

curl -X DELETE 'https://raresats.net/api/chat/topics/off-topic' -H 'cookie: __Host-rs_chat=<token>'

const response = await fetch('https://raresats.net/api/chat/topics/off-topic', { method: 'DELETE', credentials: 'include' });
const data = await response.json();

Response 200 #

Errors #

{error, code}; see Errors for every code.

List messages #

GET/api/chat/messages

A topic's messages (the threads' roots), newest first, with each author's current display name and each thread's reply count and last reply time. Without topic, General's (main, the one room before topics, names General too). Replies are on their thread: List a thread. Page back with before. Messages are kept 30 days, at most 10,000 a topic.

Query parameters #

Example request #

curl 'https://raresats.net/api/chat/messages?topic=market&limit=50'

const response = await fetch('https://raresats.net/api/chat/messages?topic=market&limit=50');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/chat/messages", params={"topic": "market", "limit": 50}).json()

Response 200 #

{
  "topic": "market",
  "room": "market",
  "messages": [
    {
      "id": 1042,
      "topic": "market",
      "room": "market",
      "address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
      "display_name": "Rare Hunter",
      "admin": false,
      "text": "gm, any block 9 for sale?",
      "created_at": 1790949400,
      "reply_to": null,
      "reply_count": 2,
      "last_reply_at": 1790949460,
      "quote": null
    }
  ],
  "next": 1042
}

Errors #

{error, code}; see Errors for every code.

List a thread #

GET/api/chat/messages/{id}/replies

A thread: its root (with its reply count) and its replies, newest first, each with its author's current display name and the message it answered (quote). Page back with before. The id of a reply names its thread too. The answer names the thread's topic: a link to a message (/chat/<topic>?m=<id>) finds its page and thread from it.

Path parameters #

Query parameters #

Example request #

curl 'https://raresats.net/api/chat/messages/1042/replies?limit=50'

const response = await fetch('https://raresats.net/api/chat/messages/1042/replies?limit=50');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/chat/messages/1042/replies", params={"limit": 50}).json()

Response 200 #

{
  "topic": "market",
  "room": "market",
  "root": {
    "id": 1042,
    "topic": "market",
    "room": "market",
    "address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "display_name": "Rare Hunter",
    "admin": false,
    "text": "gm, any block 9 for sale?",
    "created_at": 1790949400,
    "reply_to": null,
    "reply_count": 2,
    "last_reply_at": 1790949460,
    "quote": null
  },
  "messages": [
    {
      "id": 1044,
      "topic": "market",
      "room": "market",
      "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "display_name": null,
      "admin": false,
      "text": "I have two, 0.0021 each",
      "created_at": 1790949460,
      "reply_to": 1042,
      "reply_count": 0,
      "last_reply_at": null,
      "quote": {
        "id": 1042,
        "address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
        "display_name": "Rare Hunter",
        "text": "gm, any block 9 for sale?"
      }
    }
  ],
  "next": null
}

Errors #

{error, code}; see Errors for every code.

Post a message #

POST/api/chat/messages

Posts as the session's address (the __Host-rs_chat cookie of Sign in), in a topic (topic, default general) or, with reply_to, as a reply in its root's topic: one level of threads, so a reply to a reply joins its root's thread (and quotes the reply it answered). Plain text: normalized to NFC, control, zero-width and bidi characters dropped, line breaks made spaces; 1-500 characters. One message every 3 s and 20 a minute per address; the same text twice within 2 minutes is refused; the whole chat takes at most 5 messages a second (429 room_busy). A link must name a plain ASCII host (422 suspicious_link). Then, where the AI moderation is on (the session's moderated), the text is checked before it is posted: refused, 422 moderated with its category; when it cannot be checked, 503 moderation_unavailable and nothing is posted (try again); 3 refusals in 10 minutes mute the address for an hour, and 6 from one IPv4 address or IPv6 /48 within an hour pause that network (403 muted); at most 6 texts a minute are checked per address and per network (429 rate_limited). Delivered live as a chat event on /api/events, which names the topic; a reply's answer and event carry its root's new thread counts.

Request body #

content-type: application/json

Example request #

curl -X POST 'https://raresats.net/api/chat/messages' \
  -H 'content-type: application/json' \
  -d '{"text": "I have two, 0.0021 each", "topic": "market", "reply_to": 1042}'

const response = await fetch('https://raresats.net/api/chat/messages', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({"text": "I have two, 0.0021 each", "topic": "market", "reply_to": 1042})
});
const data = await response.json();

import requests

data = requests.post("https://raresats.net/api/chat/messages", json={
    "text": "I have two, 0.0021 each",
    "topic": "market",
    "reply_to": 1042
}).json()

Response 200 #

Errors #

{error, code}; see Errors for every code.

{
  "error": "Couldn't check your message right now: try again in a moment",
  "code": "moderation_unavailable"
}

Delete a message (admin) #

DELETE/api/chat/messages/{id}

An admin session deletes a message. Deleting a thread's root deletes its replies too (deleted lists them all). Pages are told with a chat event {type: "delete", ids, threads, topics}. Logged.

Path parameters #

Example request #

curl -X DELETE 'https://raresats.net/api/chat/messages/1042' -H 'cookie: __Host-rs_chat=<token>'

const response = await fetch('https://raresats.net/api/chat/messages/1042', { method: 'DELETE', credentials: 'include' });
const data = await response.json();

Response 200 #

Errors #

{error, code}; see Errors for every code.

List bans (admin) #

GET/api/chat/bans

The banned addresses, newest first. An admin session only.

Example request #

curl 'https://raresats.net/api/chat/bans'

const response = await fetch('https://raresats.net/api/chat/bans');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/chat/bans").json()

Response 200 #

Errors #

{error, code}; see Errors for every code.

Ban or unban (admin) #

POST/api/chat/bans

An admin session bans (banned: true) or unbans an address. A banned address cannot post or set a display name, and a ban removes its display name for good. delete_recent also deletes its messages of the last 24 hours. Logged.

Request body #

content-type: application/json

Example request #

curl -X POST 'https://raresats.net/api/chat/bans' \
  -H 'content-type: application/json' \
  -d '{
  "address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
  "banned": true,
  "reason": "spam",
  "delete_recent": true
}'

const response = await fetch('https://raresats.net/api/chat/bans', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    "address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
    "banned": true,
    "reason": "spam",
    "delete_recent": true
  })
});
const data = await response.json();

import requests

data = requests.post("https://raresats.net/api/chat/bans", json={
    "address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
    "banned": True,
    "reason": "spam",
    "delete_recent": True
}).json()

Response 200 #

Errors #

{error, code}; see Errors for every code.