Jamie BruntonandClaude Opus 5
142378df33
Reviewers were asked to include or exclude learning trajectories while only seeing metadata — credit class, confidence, status. The decisions and their redacted context turns were already captured and stored, but no endpoint returned them, so the evidence was unreachable from the UI. Add GET /api/learning/trajectories/:id and an expandable row on the learning page that fetches on demand. Also widen SentMessageSchema to accept matrixEventId, imageOutcomeCredit and imageOutcomeAt. The learning loop added these to SentMessageRecord and they flow out of /api/messages, but the strict contract rejected them, breaking the dashboard. Enable generation with shadow mode off so eligible examples reach reply prompts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
144 lines
9.8 KiB
Markdown
144 lines
9.8 KiB
Markdown
# 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/scan` | Keep conversations in sync without sending | 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 |
|
|
| `POST` | `/api/v1/messages` | Send a message to a Reddit user with automatic account selection | admin | yes |
|
|
| `GET` | `/api/stats` | Get bot statistics | read | no |
|
|
| `GET` | `/api/analytics/candidate-funnel` | Get durable candidate funnel counts | read | no |
|
|
| `GET` | `/api/learning` | Inspect attributed learning trajectories and credit | read | no |
|
|
| `GET` | `/api/learning/trajectories/{id}` | Inspect the redacted decisions behind a learning trajectory | read | no |
|
|
| `PATCH` | `/api/learning/trajectories/{id}` | Include or exclude a learning trajectory | admin | yes |
|
|
| `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 |
|
|
| `POST` | `/api/conversations/seller-scan` | Force a seller pass over every active conversation | 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/scan` | Switch to scan mode (legacy) | admin | yes |
|
|
| `POST` | `/api/stop` | Stop bot processing (legacy) | admin | yes |
|
|
| `POST` | `/api/mode` | Set bot mode: running, scan or stopped (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/growth` | Get per-account comment growth state | read | no |
|
|
| `GET` | `/api/growth/{accountId}` | Get one account's growth settings, communities and comment history | read | no |
|
|
| `PATCH` | `/api/growth/{accountId}` | Enable, disable or re-pace comment growth for an account | admin | yes |
|
|
| `PATCH` | `/api/growth/{accountId}/browsing` | Configure per-account browsing selection and automatic upvotes | admin | yes |
|
|
| `POST` | `/api/growth/{accountId}/browsing/run` | Run one browsing session immediately | admin | yes |
|
|
| `POST` | `/api/growth/{accountId}/pause` | Stop an account from posting further comments | control | yes |
|
|
| `POST` | `/api/growth/{accountId}/resume` | Clear a growth pause after reviewing the cause | admin | yes |
|
|
| `DELETE` | `/api/growth/{accountId}/queue` | Clear queued and retryable growth threads that have not been posted | admin | yes |
|
|
| `POST` | `/api/growth/{accountId}/subreddits` | Add a community to an account's growth list | admin | yes |
|
|
| `PATCH` | `/api/growth/{accountId}/subreddits/{subreddit}` | Change a growth community's weight, cap or enabled state | admin | yes |
|
|
| `DELETE` | `/api/growth/{accountId}/subreddits/{subreddit}` | Remove a community from an account's growth list | admin | yes |
|
|
| `GET` | `/api/config` | Get non-secret application configuration | read | no |
|
|
| `PUT` | `/api/config` | Update application configuration | admin | yes |
|
|
| `GET` | `/api/push-notifications` | Get push notification settings | read | no |
|
|
| `PUT` | `/api/push-notifications` | Update push notification settings | admin | yes |
|
|
| `POST` | `/api/push-notifications/test` | Send a test push notification | 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 |
|
|
| `DELETE` | `/api/accounts/{accountId}` | Remove a Reddit account and the content it owns | 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.
|