API Documentation

API Documentation

API Overview

Base URL

https://yourdomain.com/api

API Version

Current API version: v1

All endpoints are prefixed with /api/v1/

Response Format

All responses are in JSON format:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful"
}

Error Responses

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Authentication

API Keys

Generate API keys:

1. Go to Admin Panel > Settings > API
2. Click "Generate API Key"
3. Copy and save the key securely
4. Use key in API requests

Using API Keys

Include API key in requests:

Header:

X-API-Key: your-api-key-here

Query Parameter:

?api_key=your-api-key-here

OAuth 2.0 (Coming Soon)

OAuth 2.0 support for more advanced authentication.

Rate Limiting

API requests are rate limited:

• Default Limit: 100 requests per hour per API key
• Headers:
  • X-RateLimit-Limit - Request limit
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Reset timestamp

Endpoints

Discussions

List Discussions

GET /api/v1/discussions

Parameters:

• category - Filter by category ID
• page - Page number (default: 1)
• limit - Results per page (default: 20)
• sort - Sort order (latest, oldest, popular)

Response:

{
  "success": true,
  "data": {
    "discussions": [
      {
        "id": "123",
        "title": "Discussion Title",
        "slug": "discussion-title",
        "category_id": "456",
        "author": {
          "id": "789",
          "username": "john_doe"
        },
        "created_at": "2025-12-25T10:00:00Z",
        "reply_count": 5,
        "view_count": 100
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "pages": 3
    }
  }
}

Get Discussion

GET /api/v1/discussions/{id}

Response:

{
  "success": true,
  "data": {
    "discussion": {
      "id": "123",
      "title": "Discussion Title",
      "content": "Discussion content...",
      "category_id": "456",
      "author": {
        "id": "789",
        "username": "john_doe",
        "avatar": "https://example.com/avatar.jpg"
      },
      "created_at": "2025-12-25T10:00:00Z",
      "updated_at": "2025-12-25T11:00:00Z",
      "reply_count": 5,
      "view_count": 100,
      "tags": ["tag1", "tag2"]
    }
  }
}

Create Discussion

POST /api/v1/discussions

Request Body:

{
  "title": "New Discussion",
  "content": "Discussion content...",
  "category_id": "456",
  "tags": ["tag1", "tag2"]
}

Response:

{
  "success": true,
  "data": {
    "discussion": {
      "id": "123",
      "title": "New Discussion",
      // ... full discussion object
    }
  }
}

Posts

List Posts

GET /api/v1/discussions/{discussion_id}/posts

Parameters:

• page - Page number
• limit - Results per page

Get Post

GET /api/v1/posts/{id}

Create Post

POST /api/v1/discussions/{discussion_id}/posts

Request Body:

{
  "content": "Post content..."
}

Users

Get User

GET /api/v1/users/{id}

List Users

GET /api/v1/users

Parameters:

• page - Page number
• limit - Results per page
• search - Search by username

Categories

List Categories

GET /api/v1/categories

Get Category

GET /api/v1/categories/{id}

Code Examples

JavaScript (Fetch)

// Get discussions
fetch('https://yourdomain.com/api/v1/discussions', {
  headers: {
    'X-API-Key': 'your-api-key'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data);
});

PHP (cURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://yourdomain.com/api/v1/discussions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: your-api-key'
]);

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

Python (Requests)

import requests

headers = {
    'X-API-Key': 'your-api-key'
}

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

data = response.json()

Error Codes

Common error codes:

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Too Many Requests
• 500 - Internal Server Error

Best Practices

Security

• Use HTTPS - Always use HTTPS for API requests
• Protect API Keys - Never expose API keys in client-side code
• Rate Limiting - Respect rate limits
• Validate Input - Validate all input data

Performance

• Use Pagination - Always paginate large result sets
• Cache Responses - Cache API responses when appropriate
• Minimize Requests - Batch requests when possible
• Use Filters - Use filters to reduce data transfer

Error Handling

• Check Status Codes - Always check HTTP status codes
• Handle Errors Gracefully - Implement proper error handling
• Retry Logic - Implement retry for transient errors
• Log Errors - Log API errors for debugging

Presence Endpoint

Flatboard 5 provides a presence update endpoint used by the frontend heartbeat to track the current visitor's page in real time.

POST /presence/update         (authenticated users — CSRF protected)
POST /api/presence/update     (API clients)

Request Body:

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

Response:

{ "success": true }

Webhooks

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

Webhook Endpoints

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.

Resources

• Developer Guide - Advanced development
• Troubleshooting - API issues

Last updated: February 23, 2026