jjbrunton/RedditBot
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4404ae75ffe110d41ae2a37045f840df5847fffc
RedditBot/docs/api.md
T
Jamie BruntonandClaude Opus 5 725b5fc4e6 feat: application-level read state and inbox triage for conversations 
Conversations were hard to manage because "unread" came straight from
Matrix's notification_count, and nothing in the app ever sends a read
receipt — so opening a conversation in the dashboard could never clear it
and the unread set only ever grew. The list also collapsed three
orthogonal facts into one word, labelling "they spoke last and we have
not replied" as "Up to date".

Read state is now ours:

- conversation_read_state table (migration 19) plus
  ConversationReadStateRepository, kept separate from conversation_states
  so a read write can never be lost to mergeConversationState. The
  watermark is monotonic, so a stale poll cannot resurrect an unread
  badge.
- hasUnreadInbound and needsReply are derived server-side and returned on
  every conversation. Matrix's `unread` stays on the contract but the
  dashboard no longer reads it.
- POST /conversations/{id}/read|unread|status and
  POST /conversations/bulk-read, with optimistic cache updates.

Inbox rework:

- List rows are a real grid (checkbox, open button, chip strip) instead of
  a full-bleed absolute overlay button, which previously forced a
  pointer-events escape hatch for anything interactive in a row. Rows use
  aria-current rather than aria-pressed. Not a listbox: options must not
  contain interactive descendants.
- Counted filter pills replace the select, independent state chips replace
  the collapsed status word, plus a sort control (including oldest
  unanswered), a per-account filter, age-coloured timestamps, and an
  explicit count of rows hidden by the seller filter.
- Keyboard: j/k/arrows, Enter, u, e, / and Escape. Shortcuts yield to any
  open dialog so Escape dismisses the modal, not the conversation behind
  it. Multi-select with bulk mark-read and mark-done.
- Detail panel: auto-mark-read on open, a "New messages" divider pinned at
  mount (deriving it from the live watermark made it vanish a second after
  opening), triage actions in the header, the automation banner moved out
  of the composer, day dividers with time-only stamps, and a flex column
  so history scrolls in its own region instead of painting over the
  composer.
- Row order freezes while a conversation is open, with a "N new — refresh"
  pill, so a background poll cannot reorder rows mid-triage.

Two database tests rewound user_version by an offset from the latest
version, which silently re-targets a different migration whenever one is
appended. They now pin absolute versions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 10:06:03 +01:00

7.4 KiB
Raw Blame History

RedditBot API

This file is generated from src/web/api-catalog.ts. Run npm run docs:api after changing the HTTP surface. The live OpenAPI 3.1 document is available at GET /api/openapi.json, and compact agent discovery is available at GET /api/v1/capabilities.

Authentication

The dashboard token is an administrator credential. Browser users can exchange it for an HttpOnly, SameSite=Strict session; API clients can send it as a bearer token.

Optional least-privilege bearer credentials are configured with:

  • REDDIT_BOT_AGENT_READ_TOKEN: GET, HEAD, SSE, and private-media reads except debug routes.
  • REDDIT_BOT_AGENT_CONTROL_TOKEN: read access plus mutations under /api/v1.

Control credentials cannot send messages, import sessions, activate accounts, or update legacy configuration endpoints. Those operations require the administrator dashboard token.

Agent entry points

  • GET /healthz: unauthenticated process liveness with no private state.
  • GET /api/v1/readyz: component readiness and authentication degradation.
  • GET /api/v1/overview: bot, account, sync, rate-limit, and recent-error snapshot.
  • GET /api/v1/control: current running state.
  • POST /api/v1/control/start, /stop, or POST /api/v1/control: explicit bot control.
  • POST /api/v1/jobs: tracked chat/media sync; poll GET /api/v1/jobs/:id.
  • GET /api/events/stream: replayable typed SSE events.

MCP server

Run the stdio MCP adapter with npm run mcp. It connects to REDDIT_BOT_API_URL (default http://127.0.0.1:3000) and reads its bearer credential from REDDIT_BOT_AGENT_TOKEN, then the scoped agent variables, and finally WEB_DASHBOARD_TOKEN.

Read tools cover overview, readiness, accounts, activity, conversations, errors, sync state, and performance. Control tools include start_bot, stop_bot, set_bot_running, trigger_sync, and get_job. External message tools are separately annotated as destructive/non-idempotent and need an administrator credential.

Operations

Method Path Summary Access Mutates
GET /healthz Process liveness read no
GET /api/v1/overview Consolidated operational snapshot read no
GET /api/v1/readyz Component readiness read no
GET /api/v1/capabilities Discover API operations and safety attributes read no
GET /api/openapi.json OpenAPI 3.1 description read no
GET /api/v1/control Get bot running state read no
POST /api/v1/control Set bot running state control yes
POST /api/v1/control/start Start bot processing control yes
POST /api/v1/control/stop Stop bot processing control yes
GET /api/v1/jobs List recent asynchronous jobs read no
GET /api/v1/jobs/{id} Get asynchronous job state read no
POST /api/v1/jobs Start chat or media synchronisation control yes
GET /api/stats Get bot statistics read no
GET /api/analytics/candidate-funnel Get durable candidate funnel counts read no
GET /api/activity Get recent activity read no
GET /api/posts/by-author/{username} Get processed posts by author read no
GET /api/messages Get recent sent messages read no
GET /api/successful Get successful message examples read no
GET /api/chats Get active chats read no
GET /api/chats/sync Get chat sync state read no
POST /api/chats/sync/delta Trigger incremental chat sync admin yes
POST /api/chats/sync/full Trigger full chat sync admin yes
POST /api/chats/fetch-all Fetch all chats synchronously admin yes
GET /api/conversations List conversations read no
GET /api/conversations/{id} Get conversation detail read no
POST /api/conversations/{id}/suggest-reply Generate a reply suggestion admin yes
POST /api/conversations/{id}/suggest-media-ask Generate a media request suggestion admin yes
POST /api/conversations/{id}/send-reply Send a conversation reply admin yes
GET /api/conversations/{id}/shareable-media List every enabled exchange-library image not yet shared in this conversation read no
POST /api/conversations/{id}/share-media Send a selected exchange-library image admin yes
POST /api/conversations/start Start a new conversation admin yes
POST /api/conversations/{id}/read Advance the operator read watermark admin yes
POST /api/conversations/{id}/unread Return a conversation to the unread queue admin yes
POST /api/conversations/{id}/status Snooze, resolve or reopen a conversation admin yes
POST /api/conversations/bulk-read Mark many conversations read in one request admin yes
GET /api/media List received private media read no
GET /api/media/sync Get media sync state read no
POST /api/media/sync Trigger media sync admin yes
POST /api/media/sync/full Trigger full media sync admin yes
GET /api/media-library List operator-owned exchange images read no
POST /api/media-library Upload and classify an operator-owned exchange image admin yes
PATCH /api/media-library/{id} Correct tags or enable an exchange image admin yes
DELETE /api/media-library/{id} Delete an exchange image admin yes
POST /api/start Start bot processing (legacy) admin yes
POST /api/stop Stop bot processing (legacy) admin yes
GET /api/timers Get rate-limit timers read no
GET /api/analytics/by-subreddit Get performance by subreddit read no
GET /api/analytics/by-strategy Get performance by strategy read no
GET /api/analytics/funnel Get mature message outcome funnel read no
GET /api/analytics/trend Get daily performance trend read no
GET /api/analytics/ai-usage Get OpenRouter cost and model reliability read no
GET /api/attention Get operator attention items read no
GET /api/outreach Get active outreach candidates and funnel stages read no
GET /api/config Get non-secret application configuration read no
PUT /api/config Update application configuration admin yes
GET /api/login/status Get Reddit session state read no
POST /api/login/session-import Import Reddit and Matrix credentials admin yes
GET /api/accounts List Reddit accounts read no
POST /api/accounts/{accountId}/activate Activate a Reddit account admin yes
GET /api/logs/stream Stream legacy log events read no
GET /api/events/stream Stream typed application events read no
GET /api/logs Get recent structured logs read no
GET /api/debug/cookies Get redacted cookie diagnostics when enabled admin no
POST /api/debug/check-responses Run response check when enabled admin yes

Error model

Errors use JSON with an error string and optional detail. Authentication failures are 401; recognized but insufficient agent credentials receive 403; invalid inputs receive 400; unavailable services receive 503. Long-running agent jobs expose failure text in the job resource.

Reference in new issue View Git Blame Copy Permalink