API Reference

Authentication

All API requests require an API key passed via the X-API-Key header. You can generate and manage API keys from your dashboard.

// Include in every request
Headers: {
  "X-API-Key": "your-api-key",
  "Content-Type": "application/json"
}

warningNever expose your API key in client-side code. Always call from your server.

Messages Analyze

Analyze a player chat message for sentiment, toxicity, and automatically reward positive behavior.

Request Body

{
  "gameId": "string",       // Your registered game ID
  "playerId": "string",     // Unique player identifier
  "message": "string",      // The chat message to analyze
  "username": "string?"     // Optional display name
}

Response

{
  "sentimentScore": 0.88,
  "toxicityScore": 0.02,
  "flagged": false,
  "action": null,
  "reward": {
    "granted": true,
    "amount": 50,
    "type": "CURRENCY"
  }
}

Node.js Example

const response = await fetch("https://api.bloomai.gg/api/v1/messages/analyze", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BLOOM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    gameId: "game_abc123",
    playerId: "player_456",
    message: "Great teamwork everyone! GG!",
    username: "FriendlyGamer",
  }),
});

const data = await response.json();
console.log(data.sentimentScore); // 0.88
console.log(data.reward.granted); // true

Players

Retrieve detailed statistics and moderation history for a specific player.

Response

{
  "id": "player_456",
  "username": "FriendlyGamer",
  "sentimentAvg": 0.82,
  "totalMessages": 1420,
  "flaggedMessages": 3,
  "rewardsEarned": 2350,
  "status": "GOOD_STANDING",
  "joinedAt": "2025-09-14T08:00:00Z"
}

Node.js Example

const response = await fetch("https://api.bloomai.gg/api/v1/players/player_456", {
  headers: {
    "X-API-Key": process.env.BLOOM_API_KEY,
  },
});

const player = await response.json();
console.log(player.sentimentAvg); // 0.82

Leaderboard

Fetch the top players ranked by sentiment score and rewards earned.

Response

{
  "leaderboard": [
    {
      "rank": 1,
      "playerId": "player_456",
      "username": "FriendlyGamer",
      "sentimentAvg": 0.95,
      "rewardsEarned": 4800
    },
    {
      "rank": 2,
      "playerId": "player_789",
      "username": "HelpfulHero",
      "sentimentAvg": 0.91,
      "rewardsEarned": 4200
    }
  ],
  "total": 50,
  "page": 1,
  "perPage": 25
}

Node.js Example

const response = await fetch("https://api.bloomai.gg/api/v1/leaderboard?page=1&perPage=25", {
  headers: {
    "X-API-Key": process.env.BLOOM_API_KEY,
  },
});

const data = await response.json();
data.leaderboard.forEach((entry) => {
  console.log(`#${entry.rank} ${entry.username}: ${entry.sentimentAvg}`);
});

Moderation Actions

Approve, reject, or ban players based on flagged content. Use this to take manual action after reviewing flagged messages.

Request Body

{
  "playerId": "string",
  "action": "APPROVE" | "REJECT" | "WARN" | "MUTE" | "BAN",
  "reason": "string?",
  "duration": "number?"   // Duration in minutes (for MUTE)
}

Response

{
  "success": true,
  "action": "WARN",
  "playerId": "player_789",
  "appliedAt": "2026-03-23T12:00:00Z"
}

Node.js Example

const response = await fetch("https://api.bloomai.gg/api/v1/moderation/actions", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BLOOM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    playerId: "player_789",
    action: "WARN",
    reason: "Mild toxicity detected in recent messages",
  }),
});

const result = await response.json();
console.log(result.success); // true

Webhooks

Register a webhook URL to receive real-time notifications when messages are flagged or moderation actions are taken.

Request Body

{
  "url": "https://your-server.com/bloom-webhook",
  "events": ["message.flagged", "moderation.action", "reward.granted"],
  "secret": "string?"   // Optional signing secret
}

Response

{
  "id": "wh_abc123",
  "url": "https://your-server.com/bloom-webhook",
  "events": ["message.flagged", "moderation.action", "reward.granted"],
  "active": true,
  "createdAt": "2026-03-23T12:00:00Z"
}

Node.js Example

const response = await fetch("https://api.bloomai.gg/api/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BLOOM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/bloom-webhook",
    events: ["message.flagged", "moderation.action"],
    secret: "whsec_your_signing_secret",
  }),
});

const webhook = await response.json();
console.log(webhook.id); // wh_abc123

SDKs

Drop-in libraries for popular game engines and platforms. Install and start analyzing messages in minutes.