Announcing the Foru.ms API v2

We’re excited to announce the release of API v2, a redesigned Foru.ms API built with developer experience as our top priority.

After listening to feedback from our community and analyzing real-world usage patterns, we’ve created an API that’s more consistent, more powerful, and easier to use than ever before.

What’s New in v2

Consistent Resource Naming

No more guessing between singular and plural endpoints. In v2, all resources use plural names consistently:

- GET /api/v1/thread/:id
+ GET /api/v2/threads/:id
 
- POST /api/v1/post
+ POST /api/v2/posts
 
- GET /api/v1/user/:id
+ GET /api/v2/users/:id

Standardized Response Format

Every list endpoint now returns data in a consistent, predictable format:

{
  "data": {
    "items": [...],
    "nextCursor": "eyJpZCI6...",
    "count": 42
  }
}

No more remembering whether the key is threads, posts, or results — it’s always items.

Unified Reactions System

We’ve consolidated likes, dislikes, upvotes, and downvotes into a single, flexible reactions system:

# React to a thread
POST /api/v2/threads/:id/reactions
Content-Type: application/json
{
  "type": "like"
}
 
# React to a post
POST /api/v2/posts/:id/reactions
Content-Type: application/json
{
  "type": "upvote"
}

This opens the door for custom reaction types in the future — think emojis, awards, and more!

Powerful Query Filters

Instead of dedicated endpoints for every relationship, v2 uses intuitive query parameters:

# Get threads by tag
GET /api/v2/threads?tagId=abc123
 
# Get posts by user
GET /api/v2/posts?userId=xyz789
 
# Search with type filter
GET /api/v2/search?query=hello&type=threads

Enhanced Error Handling

Errors are now consistent and actionable:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'title' field is required",
    "details": {
      "field": "title",
      "constraint": "required"
    }
  }
}

New Features

• Poll Voting API: Create polls and cast votes via /threads/:id/poll/votes
• Webhook Deliveries: Track delivery history at /webhooks/:id/deliveries
• Private Message Replies: Clearer intent with /private-messages/:id/replies
• Subscriber Management: Subscribe/unsubscribe via /threads/:id/subscribers and /tags/:id/subscribers

Migration Guide

Step 1: Update Your Base URL

- const baseUrl = 'https://foru.ms/api/v1';
+ const baseUrl = 'https://api.foru.ms/v2';

Step 2: Update Resource Paths

Replace all singular resource paths with their plural equivalents:

Step 3: Update Response Parsing

If you were accessing response data directly:

- const threads = response.threads;
+ const threads = response.data.items;

Step 4: Migrate Reaction Endpoints

- await client.post(`/thread/${id}/like`);
+ await client.post(`/threads/${id}/reactions`, { type: 'like' });

SDK Support

Our official JavaScript/TypeScript SDK has been updated with full v2 support:

npm install @foru-ms/sdk@latest

import { ForumClient } from '@foru-ms/sdk';
 
const client = new ForumClient({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.foru.ms/v2'
});
 
// All methods now use v2 endpoints
const { data } = await client.threads.list({ limit: 10 });
console.log(data.items); // Always 'items'!

For v1 users

The v1 API will remain available for 12 months from today. We recommend migrating to v2 as soon as possible to take advantage of the new features and improvements.

During the deprecation period:

• v1 will receive security updates only
• No new features will be added to v1
• Full documentation for v1 will remain available

Try It Now

Explore the new API with our interactive documentation:

• API Reference
• OpenAPI Spec 
• SDK Documentation

We’d Love Your Feedback

This redesign was driven by your feedback, and we want to keep improving. If you have questions, suggestions, or run into any issues during migration, please reach out:

• Discord Community 
• GitHub Issues 
• Email Support

Thank you for being part of the Foru.ms community. We can’t wait to see what you build with API v2! 🚀