API Documentation

Flatboard Team • 13/12/2025 • 6 min de lecture

API Documentation

Flatboard 5 provides a REST API for integrating with external applications, mobile apps, and third-party services.

API Overview

Base URL

https://yourdomain.com/api

No API versioning

There is no /v1/ prefix. All endpoints are directly under /api/ (e.g. /api/discussions, /api/categories).

Response Format

All responses are in JSON format:

{
  "success": true,
  "data": { }
}

Error Responses

{
  "success": false,
  "error": "Error description"
}

Authentication

Session

The API authenticates via the active PHP session — the same session used by the browser interface.

To make authenticated API requests, your HTTP client must carry the session cookie obtained after logging in through the normal login form.

Bearer Token

The API supports Authorization: Bearer <token> authentication. A hashed token is stored per user (api_token field).

To generate or revoke your token, go to Profile → Settings → Security → API Token. The plain token is shown once upon generation — copy it immediately.

Rate Limiting

API requests are rate-limited per user (authenticated) or per IP (anonymous).

When the limit is exceeded, the server responds with HTTP 429 Too Many Requests and a Retry-After header indicating how many seconds to wait before retrying.

Endpoints

Discussions

List discussions

GET /api/discussions

Parameters:

category_id — Filter by category ID or slug
sort — Sort order: latest (default), oldest, newest, most_replied, most_viewed
limit — Results per page (default: config value)
offset — Offset for pagination (default: 0)

Response:

{
  "success": true,
  "discussions": [ { "id": "...", "title": "...", "category_id": "...", ... } ],
  "html": "<article>...</article>",
  "count": 20,
  "hasMore": true
}

Only discussions from categories accessible to the requesting user are returned. Discussions from restricted categories are filtered out.

Get discussion

GET /api/discussions/{id}

Response:

{
  "success": true,
  "discussion": { "id": "...", "title": "...", "content": "...", ... },
  "posts": [ { ... } ],
  "category": { ... }
}

Create discussion

Requires authentication.

POST /api/discussions

Request body (JSON or form-encoded):

{
  "title": "New Discussion",
  "content": "Discussion content...",
  "category_id": "category-id-here"
}

Response:

{
  "success": true,
  "discussion_id": "...",
  "post_id": "..."
}

Posts

List posts in a discussion

GET /api/discussions/{id}/posts

Parameters:

posts_order — ASC (default) or DESC

Get post

GET /api/posts/{id}

Create post (reply)

Requires authentication.

POST /api/posts

Request body:

{
  "discussion_id": "...",
  "content": "Reply content..."
}

Update post

Requires authentication (own post or moderator).

PUT /api/posts/{id}

Request body:

{
  "content": "Updated content..."
}

Delete post

Requires authentication (own post or moderator).

DELETE /api/posts/{id}

Users

Get user

GET /api/users/{id}

Search users

GET /api/users/search?q=username

Get user's discussions

Requires authentication (own profile or admin).

GET /api/users/discussions

Get user's posts

Requires authentication (own profile or admin).

GET /api/users/posts

Get user's reactions

GET /api/users/reactions

Get user's subscriptions

GET /api/users/subscriptions

Search

GET /api/search?q=keyword&type=discussions

Parameters:

q — Search query
type — discussions (default), posts, users

Reactions

Toggle reaction on a post

Requires authentication.

POST /api/reactions/toggle

Request body:

{
  "post_id": "...",
  "reaction": "like"
}

Get reactions for a post

GET /api/reactions/post/{post_id}

Notifications

List notifications

Requires authentication.

GET /api/notifications

Count unread notifications

Requires authentication.

GET /api/notifications/count

Mark notifications as read

Requires authentication.

POST /api/notifications/mark-read

Presence

Update presence (heartbeat)

POST /api/presence/update

Request body:

{
  "page": "/d/123/discussion-title"
}

This endpoint is excluded from visitor tracking — it never creates anonymous visitor records.

Get presence stats

GET /api/presence/stats

Response:

{
  "total": 12,
  "anonymous": 8,
  "authenticated": 3,
  "bots": 1
}

Get visitor list

GET /api/presence/visitors

Get bot list

GET /api/presence/bots

Markdown

Parse a Markdown string to HTML server-side.

POST /api/markdown/parse

Request body:

{
  "content": "## Hello\n\nThis is **bold**."
}

Typing Indicator

Send typing event

Requires authentication.

POST /api/typing-indicator/typing

Stop typing event

Requires authentication.

POST /api/typing-indicator/stop

Get typing status

GET /api/typing-indicator/status

Version

GET /api/version

Returns the current Flatboard version.

Webhooks

Receive inbound webhook

POST /api/webhooks

Fires the webhook.received hook with the payload. See Webhooks below.

Code Examples

JavaScript (Fetch)

// List discussions
fetch('https://yourdomain.com/api/discussions', {
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data.discussions);
});

PHP (cURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://yourdomain.com/api/discussions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your-token-here'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Python (Requests)

import requests

headers = {
    'Authorization': 'Bearer your-token-here'
}

response = requests.get(
    'https://yourdomain.com/api/discussions',
    headers=headers
)

data = response.json()

Error Codes

Code	Meaning
`400`	Bad Request — invalid or missing parameters
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — authenticated but insufficient permissions
`404`	Not Found
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Webhooks

Flatboard 5 includes a built-in webhook system for real-time notifications to external services. Configure webhooks at Admin Panel → Webhooks.

Webhook Endpoints

Method	Endpoint	Description
`POST`	`/api/webhooks`	Receive inbound webhook payloads
`GET`	`/admin/webhooks`	List configured webhooks
`GET`	`/admin/webhooks/history`	View delivery history
`POST`	`/admin/webhooks/save`	Create or update a webhook
`POST`	`/admin/webhooks/test`	Send a test payload to a webhook
`GET`	`/admin/webhooks/stats`	Webhook delivery statistics

Supported Events

discussion.created — New discussion published
post.created — New reply published
user.registered — New user registered
report.created — Content report submitted

Delivery

Each event sends a POST request to the configured URL with a JSON body and an X-Flatboard-Event header identifying the event type. Delivery history and retry status are available in the admin panel.

Best Practices

Security

Use HTTPS — Always use HTTPS for API requests
Protect tokens — Never expose tokens in client-side code or version control
Rate Limiting — Respect rate limits and implement backoff on 429 responses

Performance

Use pagination — Always paginate large result sets via limit and offset
Use filters — Pass category_id, sort, etc. to reduce data transfer
Cache responses — Cache API responses client-side when appropriate

Error Handling

Check status codes — Always check HTTP status codes before parsing the body
Handle 429 gracefully — Read the Retry-After header and wait before retrying

Resources

Developer Guide — Advanced development
Troubleshooting — API issues

Last updated: March 28, 2026