CoreBB Forums By CoreBB

CoreBB: CoreBB Forums | Boards

[CoreBB] CoreBB Forums » CoreBB Official » CoreBB 1.1.7 Support » CoreBB API Documentation
Welcome, Guest - Login | Register | Search | Blogs | Board Rules/FAQ | Contact Mods
Author Topic: CoreBB API Documentation
HannsGruber
Posts: 10
Registered: Jun 26
30sf5ms.gif
Date Posted: 6/28 12:08am Subject: CoreBB API Documentation
CoreBB API v1 - Current API Reference

CoreBB now includes a first-pass JSON API intended to support the mobile web interface and basic external testing.

Base URL
Code:
/api/v1


All responses are JSON.

Success:
JSON:
{
  "ok": true,
  "data": {}
}


Error:
JSON:
{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message"
  }
}


Authentication + CSRF

The API uses the normal CoreBB login cookie/session system. Browser clients should use same-origin cookies.

Before any POST request, fetch a CSRF token:

JSON:
GET /api/v1/auth/csrf


Send the returned token using:

JSON:
X-CoreBB-CSRF: token_here


The token may also be sent as:

JSON:
corebb_csrf_token


Auth Endpoints

JSON:
GET  /api/v1/me

Returns the current viewer, or guest state.

JSON:
POST /api/v1/auth/register

JSON body:
JSON:
{
  "username": "NewUser",
  "email": "user@example.com",
  "password": "password",
  "passwordConfirm": "password",
  "agreeTos": true,
  "confirmAge13": true
}


Registration requires email verification before login.

JSON:
POST /api/v1/auth/login

JSON body:
JSON:
{
  "username": "Username",
  "password": "Password",
  "expiry": 86400
}


Allowed expiry values:
JSON:
3600, 86400, 604800, 2592000, 31536000


JSON:
POST /api/v1/auth/logout


Read Endpoints

JSON:
GET /api/v1/health

API health/status.

JSON:
GET /api/v1/index

Forum index/categories/boards.

Optional:
JSON:
?category_id=1
?show_empty=1


JSON:
GET /api/v1/boards/{boardId}?page=1

Board/topic list.

JSON:
GET /api/v1/threads/{threadId}?page=1

Thread posts, permissions, and poll data if present.

JSON:
GET /api/v1/profiles/{userId}

Public profile data.

Private Messages

Requires login.

JSON:
GET /api/v1/pm/folders
GET /api/v1/pm/inbox
GET /api/v1/pm/unread
GET /api/v1/pm/read
GET /api/v1/pm/sent
GET /api/v1/pm/messages/{pmId}?folder=read


Send PM:
JSON:
POST /api/v1/pm/send


JSON body:
JSON:
{
  "to": "Username",
  "subject": "Subject",
  "body": "Message body"
}


Mark PM read:
JSON:
POST /api/v1/pm/messages/{pmId}/read


Note: normal users cannot delete private messages.

Posting / Editing

Requires login and CSRF.

Preflight endpoints load form defaults, quote text, permission state, hidden context, and CSRF info:

JSON:
GET /api/v1/post/reply/{threadId}?board_id={boardId}&quote_id={postId}
GET /api/v1/post/new/{boardId}
GET /api/v1/post/edit/{postId}


Submit reply:
JSON:
POST /api/v1/post/reply


JSON body:
JSON:
{
  "threadId": 123,
  "boardId": 5,
  "subject": "RE: Topic",
  "body": "Reply text"
}


Submit new topic:
JSON:
POST /api/v1/post/new


JSON body:
JSON:
{
  "boardId": 5,
  "subject": "Topic title",
  "body": "Post body"
}


Edit post:
JSON:
POST /api/v1/post/edit


JSON body:
JSON:
{
  "postId": 456,
  "subject": "Updated subject",
  "body": "Updated body"
}


Poll Voting

Requires login and CSRF.

Code:
POST /api/v1/polls/{topicId}/vote


JSON body:
JSON:
{
  "optionId": 12
}


Basic Moderation API

Requires moderator access and CSRF.

JSON:
POST /api/v1/mod/topics/{topicId}/lock
POST /api/v1/mod/topics/{topicId}/unlock
POST /api/v1/mod/posts/{postId}/remove
POST /api/v1/mod/posts/{postId}/restore
POST /api/v1/mod/users/{userId}/ban
POST /api/v1/mod/users/{userId}/unban


Optional moderation body:
JSON:
{
  "reason": "Reason text"
}


Unban also accepts:
JSON:
{
  "note": "Admin note"
}


Limits and Safety

Guest API requests are rate limited by IP.
Logged-in API requests are rate limited by account.

Current read limits:
Code:
Guest: 30/minute, 300/hour
Logged in: 120/minute, 2000/hour
Health endpoint: 120/minute guest, 240/minute logged in


Page requests are capped:
Code:
Guest: up to page 100
Logged in: up to page 500


All write requests require CSRF validation.

The API reuses CoreBB’s normal forum logic, including:
login/session cookies
private board visibility checks
Secure Archive read-only checks
thread lock checks
edit permissions/edit windows
moderator rank checks
post/PM/moderation logging behavior


Currently Not Included

This first API version does not expose:

administration tools
PM deletion
advanced PM moderation
post image upload API
poll creation API
arbitrary database/search/export endpoints
HannsGruber
Posts: 10
Registered: Jun 26
30sf5ms.gif
Date Posted: 6/28 12:09am Subject: RE:CoreBB API Documentation
CoreBB API Usage Samples

These examples assume the forum is hosted at:

Code:
https://corebb.example.com


Replace that with your own CoreBB URL.

1. Check API Health

JSON:
GET https://corebb.example.com/api/v1/health


Example response:
JSON:
{
  "ok": true,
  "data": {
    "name": "CoreBB API",
    "version": "v1",
    "status": "ok"
  }
}


2. Get a CSRF Token

Required before POST requests.

JSON:
GET https://corebb.example.com/api/v1/auth/csrf


Example response:
Code:
{
  "ok": true,
  "data": {
    "csrfToken": "abc123...",
    "header": "X-CoreBB-CSRF",
    "field": "corebb_csrf_token"
  }
}


Use that token in POST headers:

JSON:
X-CoreBB-CSRF: abc123...


3. Login

JSON:
POST https://corebb.example.com/api/v1/auth/login


Headers:
JSON:
Content-Type: application/json
X-CoreBB-CSRF: abc123...


Body:
JSON:
{
  "username": "MyUsername",
  "password": "MyPassword",
  "expiry": 86400
}


Example response:
JSON:
{
  "ok": true,
  "data": {
    "expiresAt": 1780000000,
    "viewer": {
      "authenticated": true,
      "user": {
        "id": 1,
        "username": "MyUsername",
        "canModerate": false
      }
    }
  }
}


4. Check Current Login

JSON:
GET https://corebb.example.com/api/v1/me


Example response:
JSON:
{
  "ok": true,
  "data": {
    "authenticated": true,
    "user": {
      "id": 1,
      "username": "MyUsername",
      "accessLevel": 1,
      "level": "Member"
    }
  }
}


5. Load Forum Index

JSON:
GET https://corebb.example.com/api/v1/index


Example use:

mobile forum home
board directory
category list
unread/new-post indicators


6. Load a Board

Code:
GET https://corebb.example.com/api/v1/boards/15?page=1


Example response excerpt:
JSON:
{
  "ok": true,
  "data": {
    "id": 15,
    "name": "General Discussion",
    "pagination": {
      "currentPage": 1,
      "totalPages": 8
    },
    "topics": [
      {
        "id": 12345,
        "title": "Welcome thread",
        "replyCount": 12,
        "isLocked": false,
        "isSticky": true
      }
    ]
  }
}


7. Load a Thread

JSON:
GET https://corebb.example.com/api/v1/threads/12345?page=1


Example response excerpt:
JSON:
{
  "ok": true,
  "data": {
    "id": 12345,
    "title": "Welcome thread",
    "permissions": {
      "canReply": true,
      "canModerate": false
    },
    "posts": [
      {
        "id": 9001,
        "body": {
          "raw": "Hello!",
          "html": "Hello!"
        },
        "author": {
          "id": 1,
          "username": "MyUsername"
        }
      }
    ]
  }
}


8. Post a Reply

First, optionally load the reply form:

JSON:
GET https://corebb.example.com/api/v1/post/reply/12345?board_id=15


Then submit:

JSON:
POST https://corebb.example.com/api/v1/post/reply


Headers:
JSON:
Content-Type: application/json
X-CoreBB-CSRF: abc123...


Body:
JSON:
{
  "threadId": 12345,
  "boardId": 15,
  "body": "Testing a reply from the API!"
}


Example response:
JSON:
{
  "ok": true,
  "data": {
    "status": "success",
    "message": "Your message has been successfully posted."
  }
}


9. Create a New Topic

Code:
POST https://corebb.example.com/api/v1/post/new


Headers:
JSON:
Content-Type: application/json
X-CoreBB-CSRF: abc123...


Body:
JSON:
{
  "boardId": 15,
  "subject": "API test topic",
  "body": "This topic was created through the CoreBB API."
}


10. Edit a Post

Code:
POST https://corebb.example.com/api/v1/post/edit


Body:
JSON:
{
  "postId": 9001,
  "subject": "Updated subject",
  "body": "Updated post body."
}


11. Vote in a Poll

JSON:
POST https://corebb.example.com/api/v1/polls/12345/vote


Body:
JSON:
{
  "optionId": 7
}


12. Send a Private Message

JSON:
POST https://corebb.example.com/api/v1/pm/send


Body:
JSON:
{
  "to": "OtherUser",
  "subject": "Hello",
  "body": "This PM was sent through the CoreBB API."
}


13. Read Private Messages

Inbox:
JSON:
GET https://corebb.example.com/api/v1/pm/inbox


Read items:
JSON:
GET https://corebb.example.com/api/v1/pm/read


Sent items:
JSON:
GET https://corebb.example.com/api/v1/pm/sent


Single message:
JSON:
GET https://corebb.example.com/api/v1/pm/messages/123?folder=read


14. Moderator: Lock a Topic

Requires moderator access.

JSON:
POST https://corebb.example.com/api/v1/mod/topics/12345/lock

Body:
    {}


Unlock:
JSON:
POST https://corebb.example.com/api/v1/mod/topics/12345/unlock


15. Moderator: Remove a Post

JSON:
POST https://corebb.example.com/api/v1/mod/posts/9001/remove


Body:
JSON:
{
  "reason": "Rule violation"
}


Restore:
JSON:
POST https://corebb.example.com/api/v1/mod/posts/9001/restore


16. Moderator: Ban / Unban User

Ban:
JSON:
POST https://corebb.example.com/api/v1/mod/users/55/ban


Body:
JSON:
{
  "reason": "Spam"
}


Unban:
JSON:
POST https://corebb.example.com/api/v1/mod/users/55/unban


Body:
JSON:
{
  "note": "Appeal accepted"
}
[CoreBB] CoreBB Forums » CoreBB Official » CoreBB 1.1.7 Support » CoreBB API Documentation
4 Boards | 10 Messages (0 Today)
CoreBB v1.1.10 | Security | © 2005-2026 CoreBB