Diskus
API Reference
Diskus exposes a robust, RESTful API. While the official Widget and Dashboard handle API interactions automatically, you can use these endpoints to build custom, headless comment integrations for your own frontend applications.
All endpoints are prefixed with /api/v1.
Authentication Flow
Authentication is required for most administrative and authenticated commenter actions.
| Method | Endpoint | Auth | Rate Limit | Description |
|---|---|---|---|---|
GET | /auth/setup-status | None | None | Returns {setupRequired: boolean} indicating if an admin account needs to be created. |
POST | /auth/register | None | 5 / hr | Register the first dashboard admin. (Subsequent registrations blocked unless ALLOW_REGISTRATION=true). |
POST | /auth/login | None | 10 / 15m | Login to the dashboard. Returns a JWT token. |
Public Widget Endpoints
These endpoints power the public-facing comment widget.
Initialization & Embed Tokens
To prevent unauthorized domains from spamming your API, Diskus requires an Embed Token for widget operations.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET | /widget/embed-token?api_key={appId} | None | Issues a short-lived Embed Token. The backend strictly verifies the Origin and Referer headers against the registered domain for the provided api_key. |
Note: All subsequent /widget/* requests must include this token via the X-Diskus-Embed-Token header or embed_token query parameter.
Comments
| Method | Endpoint | Auth | Rate Limit | Description |
|---|---|---|---|---|
GET | /widget/comments?threadKey={key} | Embed Token | None | Fetch paginated comments for a thread. Automatically creates the thread if it does not exist. |
POST | /widget/comments | Embed Token | 30 / min | Post a new comment. Automatically catches bot spam via the _diskus_trap honeypot field. |
POST | /widget/auth/register | Embed Token | 5 / hr | Register a new authenticated commenter. |
POST | /widget/auth/login | Embed Token | 10 / 15m | Login for authenticated commenters. |
POST | /widget/comments/:id/like | JWT | 30 / min | Like a comment. Requires user authentication. |
POST | /widget/comments/:id/unlike | JWT | 30 / min | Remove a like from a comment. |
DELETE | /widget/comments/:id | JWT | None | Soft-delete a user’s own comment. |
Admin Dashboard Endpoints
These endpoints are strictly for site administrators and require a valid Bearer JWT token in the Authorization header.
Sites & Domains
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/sites | Get all websites registered to the authenticated admin. |
POST | /admin/sites | Register a new website (generates a publicApiKey). |
PATCH | /admin/sites/:id | Update site configuration (requireLogin, enableEmail, etc.). |
DELETE | /admin/sites/:id | Delete a website and all associated comments. |
Moderation
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/analytics/summary | Get counts for all queues (Pending, Approved, Spam, Trash). |
GET | /admin/comments | Fetch all comments across all threads for moderation. |
PATCH | /admin/comments/bulk | Bulk update comment statuses (e.g., approve multiple comments). |
DELETE | /admin/comments/bulk | Bulk hard-delete comments from the database. |
PATCH | /admin/comments/:id/pin | Toggle the pinned status of a specific comment. |
Data Management
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/export/:siteId | Export all threads and comments as a highly portable JSON file. |
POST | /admin/import/:siteId | Import threads and comments from a JSON file. Includes automatic deduplication and HTML re-sanitization. |
Users
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/users | List all commenter accounts registered via the widget. |
DELETE | /admin/users/:id | Delete a commenter account. |
GET | /admin/account | Get current admin account details. |
PUT | /admin/account | Update admin account details (including Resend API key). |