Categories API

Manage fundraising categories and retrieve category statistics.

List Categories

GET /api/v1/categories

Retrieve all active fundraising categories with statistics.

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`https://api.fundlyhub.org/api/v1/categories`);
const categories = await response.json();

// Response format
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Medical",
    "slug": "medical",
    "emoji": "🏥",
    "description": "Healthcare and medical emergency campaigns",
    "fundraiser_count": 145,
    "total_raised": 2847500
  },
  {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "name": "Education",
    "slug": "education",
    "emoji": "📚",
    "description": "School supplies, tuition, and educational programs",
    "fundraiser_count": 87,
    "total_raised": 1234000
  }
]

Get Single Category

GET /api/v1/categories/:slug

Retrieve detailed information about a specific category including statistics.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const slug = 'medical';

const response = await fetch(`https://api.fundlyhub.org/api/v1/categories/${slug}`);
const category = await response.json();

console.log('Category:', category.name);
console.log('Active fundraisers:', category.fundraiser_count);
console.log('Total raised:', category.total_raised);

Get Category Statistics

GET /api/v1/categories/stats

Get aggregated statistics across all categories.

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`https://api.fundlyhub.org/api/v1/categories/stats`);
const stats = await response.json();

// Response format
{
  "total_categories": 12,
  "total_fundraisers": 1543,
  "total_raised": 15678900,
  "categories": [
    {
      "category_name": "Medical",
      "count": 145,
      "total_raised": 2847500
    },
    {
      "category_name": "Education",
      "count": 87,
      "total_raised": 1234000
    }
  ]
}

Get Fundraisers by Category

GET /api/v1/categories/:slug/fundraisers

Retrieve all fundraisers in a specific category.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const categorySlug = 'medical';

const response = await fetch(
  `https://api.fundlyhub.org/api/v1/categories/${categorySlug}/fundraisers?limit=20&offset=0`
);

const fundraisers = await response.json();
console.log(`Found ${fundraisers.length} medical fundraisers`);

Common Use Cases

Display Category Navigation

Build a category navigation menu with counts:

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`https://api.fundlyhub.org/api/v1/categories`);
const categories = await response.json();

// Render category menu
categories.forEach(cat => {
  console.log(`${cat.emoji} ${cat.name} (${cat.fundraiser_count})`);
});

Get Top Categories by Activity

Sort categories by most active fundraisers or total raised:

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`https://api.fundlyhub.org/api/v1/categories/stats`);
const { categories } = await response.json();

// Sort by amount raised
const topByAmount = [...categories]
  .sort((a, b) => b.total_raised - a.total_raised)
  .slice(0, 5);

console.log('Top 5 categories by amount raised:');
topByAmount.forEach((cat, i) => {
  console.log(`${i+1}. ${cat.category_name}: $${cat.total_raised.toLocaleString()}`);
});

Response Codes

• 200 - Success
• 404 - Category not found
• 429 - Rate limit exceeded
• 500 - Server error