Public API

The same API the widget uses. With it you build the comments in your own design, in an app or anywhere that can make HTTP requests.

The basics

• Base address: https://useqorum.com
• Format: JSON both ways. Dates in ISO 8601, in UTC.
• Key: every request carries the public key in the X-Qorum-Key header (or ?key= in the URL).
• Login: actions by logged-in people carry Authorization: Bearer TOKEN, with the token from your site's login or from a Qorum account. Without it, you can only read.
• Origin: requests made from a browser must come from a domain allowed for the site. Requests from your server (with no Origin header) go straight through.
• Errors: always {"error": "message"}, with a message that can be shown to the person. Send X-Qorum-Lang: en to get the messages in English. See the codes in Troubleshooting.

const QORUM = 'https://useqorum.com';
const KEY = 'pk_YOUR_PUBLIC_KEY';

async function qorum(method, path, body, token) {
  const r = await fetch(QORUM + path, {
    method,
    headers: {
      'X-Qorum-Key': KEY,
      'X-Qorum-Lang': 'en',
      ...(token ? { Authorization: 'Bearer ' + token } : {}),
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await r.json();
  if (!r.ok) throw new Error(data.error);
  return data;
}

The comment

Every route that returns comments uses this format:

{
  "id": 81,
  "content": "Great **post**!",
  "html": "Great <strong>post</strong>!",
  "images": [{ "url": "https://i.ibb.co/...", "thumb": "https://i.ibb.co/...", "width": 1200, "height": 800 }],
  "userId": 123,
  "user": { "id": 123, "username": "ana_lima", "displayName": "Ana Lima", "avatar": "https://..." },
  "likes": 12, "dislikes": 0, "hasLiked": true, "hasDisliked": false,
  "replyCount": 2, "isEdited": false,
  "createdAt": "2026-11-08T21:00:00Z",
  "replies": [ { "id": 82, "parentId": 81, "replyToUserId": 123, "replyToUsername": "Ana Lima", ... } ]
}

Read

The site's appearance and rules, for you to follow in your interface.

{ "site": "My Blog", "template": "classico", "tema": "auto", "cor1": "#6b2fe0", "cor2": "#2a8ad8", "raio": 8,
  "ordem": "recent", "mostrarNaoCurti": true, "loginSite": true, "loginQorum": true, "urlLogin": "",
  "preModeracao": false, "imagens": true, "imagemMaxMB": 32 }

The comments of a conversation, page by page. A conversation with no comments yet returns an empty list, not an error.

{
  "comments": [ ... ],
  "pinned": [ ... ],
  "pagination": { "page": 1, "limit": 20, "total": 37, "totalRootComments": 21, "totalPages": 2 },
  "thread": { "ref": "post-42", "title": "My post", "url": "https://...", "locked": false }
}

pinned only comes on page 1 and only when there's a pinned comment. Pinned comments also appear in comments, in their normal position: hide the duplicates if you show both. total counts replies; totalPages counts only main comments.

One comment, for direct links. It always returns the main comment with its replies, and in focusId the one requested (which may be one of the replies).

{ "comment": { "id": 81, ..., "replies": [ ... ] }, "focusId": 82, "thread": { "ref": "post-42", ... } }

More replies of a main comment, beyond the 50 that come in the list. limit goes up to 100.

{ "replies": [ ... ], "total": 73, "offset": 50 }

How many comments each conversation has, to show "12 comments" in a list of posts. 1 to 100 refs per request.

{ "counts": { "post-1": 12, "post-2": 0, "post-3": 5 } }

Who is logged in

Data about whoever is logged in on this site.

{ "userId": 123, "user": { ... }, "isMod": false, "qorumAccount": false,
  "ban": null,                                 // or { "reason", "isPermanent", "expiresAt" }
  "entitlements": [ { "item": "fixar_comentario", "quantity": 2, "expiresAt": null } ],
  "unread": 3 }                                // unread notifications

The replies the logged-in person received (default 30, up to 100, with ?unread=1 and paging). Everything about notifications, including how to bring them into your site, in Notifications.

{ "notifications": [ { "id": 9, "commentId": 82, "read": false, "createdAt": "...",
    "preview": "I agree, and...", "actor": { "username": "bia" },
    "thread": { "ref": "post-42", "title": "My post", "url": "https://..." } } ],
  "unread": 1 }

Marks as read. Body {"ids": [9, 10]}, or empty to mark all.

Write

All of them need login.

Comments or replies. The first time someone comments on a ref, the conversation is created.

await qorum('POST', '/v1/comments', { ref: 'post-42', content: 'Nice!', parentId: 81 }, token);
// 201: the created comment. With "status": "pending", it went to the approval queue.

Common errors: 400 text too short or too long; 403 locked conversation or banned person (with isBanned, reason, isPermanent, expiresAt); 404 the answered comment doesn't exist; 429 commented less than 5 seconds ago or hit a spam limit.

Uploads an image to attach to a comment. A multipart/form-data form with the file in the image field: JPG, PNG, GIF or WebP, up to 32 MB. Then send the returned url in images when commenting. The image is converted to WebP (animated GIFs stay animated) and scaled down to at most 2560 pixels on the longest side; width and height already come with the final size.

const fd = new FormData();
fd.append('image', file);                        // from an <input type="file">
const r = await fetch('https://useqorum.com/v1/images', {
  method: 'POST',
  headers: { 'X-Qorum-Key': KEY, Authorization: 'Bearer ' + token },   // no Content-Type
  body: fd,
});
const img = await r.json();   // { "url", "thumb", "medium", "width", "height" }

Errors: 400 format not accepted or resolution over 40 megapixels; 403 images turned off on the site; 413 larger than 32 MB; 429 more than 20 images in 10 minutes.

Edits your own comment: {"content": "..."}. Returns {"id", "content", "html", "isEdited": true}.

Deletes your own comment (moderators delete anyone's). Deleting a main comment deletes its replies.

Like and dislike. Sending it again undoes it. Liking removes the dislike and vice versa.

{ "liked": true, "likes": 13, "dislikes": 0 }       // /dislike returns "disliked"

Reports: {"reason": "Spam or advertising"}. You can't report your own (400) or report twice (409).

Pins and unpins. Moderators send {"hours": 48} (default 24). The author pins their own for 24 hours if they have the fixar_comentario perk. Main comments only.

Reactions, follow, block and friends

On comments: sort=best and sort=hot in the list; the embeds field carries the YouTube videos mentioned ({"type": "youtube", "id", "thumb"}); in html, [text](url) becomes a link and @username becomes <span class="mencao">.

Qorum account

To build your own login screen. It only works if Qorum accounts are turned on for the site.

// sign up: { "username": "ana_lima", "password": "a good password", "name": "Ana Lima" }   (name optional)
// log in:  { "username": "ana_lima", "password": "a good password" }
// answer:  { "token": "eyJ...", "userId": "q:12", "user": { "username": "ana_lima", "displayName": "Ana Lima" } }

The token lasts 30 days and goes in Authorization: Bearer. Errors: 400 username taken or breaking the rules; 401 wrong username or password; 403 Qorum accounts turned off on the site; 429 more than 10 attempts per minute.

Moderating from the widget

With a moderator login (mod: true in your site's token, or a Qorum account that moderates the site):

Testing the connection

Says whether the key exists, whether the origin is allowed and which logins are on. It isn't blocked by origin, precisely so you can diagnose. See the ready-made test in Troubleshooting.