Bot API

This forum exposes a small JSON API so you can write your own bot. It can read the feed and post on your behalf. Every account can create one token from its settings page; no application or approval is needed. All endpoints live under /api/v1 and speak JSON.

Authentication

Generate a token on your settings page under "Bot API". The token is shown once, so copy it immediately. Send it on every request in the Authorization header as a Bearer token.

Authorization: Bearer rnd_your_token_here

A token carries your account's full posting rights and shares its rate limits. Treat it like a password. If it leaks, revoke it from settings and generate a new one. Requests without a valid token receive 401; a banned account receives 403.

Rate limits and validation

Bots are subject to exactly the same limits and content rules as the website: titles up to 300 characters, chat messages up to 500, the same markdown and Marsey rendering, and the same spam guards. Exceeding a limit returns 429. Bad input returns 400 with a JSON body carrying an "error" field. The limits enforced right now are:

Action	Limit	Counted
Any request	120 per 15 seconds	per IP
Writes (POST requests)	30 per 1 minutes	per IP
Creating posts	6 per 5 minutes	per account
Creating comments	25 per 5 minutes	per account
Chat messages	25 per 1 minutes	per account
Chat burst	5 per 10 seconds	per account
Duplicate chat message	An identical repeat of your last chat message is dropped within 30 seconds.

Limits marked "per IP" count every request from an address; limits marked "per account" count actions by your token. Values may change as the forum is tuned.

Endpoints

GET/api/v1/me

Returns the account the token belongs to: id, username, coin balance and admin flag.

GET/api/v1/posts?sort=hot|new|top&page=1

Lists a page of posts (20 per page) in the chosen order, each with its score and comment count.

GET/api/v1/posts/{id}

Returns a single post together with its comments. Drafts and removed posts are not returned.

POST/api/v1/posts

Creates a post. Only the title is required. Responds 201 with the new post id.

{
  "title": "Hello from my bot",
  "url": "https://example.com",
  "body": "Optional markdown body :smile:",
  "nsfw": false
}

POST/api/v1/posts/{id}/comments

Adds a comment to a post. Set parent_comment_id to reply to another comment, or leave it null for a top-level comment.

{
  "body": "A reply :smile:",
  "parent_comment_id": null
}

GET/api/v1/chat

Returns the most recent chat messages.

POST/api/v1/chat

Posts a chat message. Set reply_to to the id of a message you are replying to, or leave it null.

{
  "body": "hello everyone",
  "reply_to": null
}

Example

Creating a post with curl:

curl -X POST https://this-forum/api/v1/posts \
  -H "Authorization: Bearer rnd_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Posted by a bot", "body": "Hi!"}'

Agreement

Bots may read and post, but not vote. There is deliberately no voting endpoint for obvious reasons. Do not use the API to flood the forum, to circumvent rate limits with several accounts, or to post spam. Tokens that are abused WILL be revoked and the account may be banned.