JavaScript / TypeScript SDK

Installation (Coming Soon)

npm install @sieve/sdk

Quick Example (Coming Soon)

import { Sieve } from '@sieve/sdk';

const sieve = new Sieve({ apiKey: process.env.SIEVE_API_KEY });

const result = await sieve.moderate.text({
  content: 'Message to moderate',
  context: 'chat',
  user_id: 'player123',
});

if (result.action === 'block') {
  // Find the highest-scoring category
  const topCategory = Object.entries(result.categories)
    .sort(([,a], [,b]) => b.score - a.score)[0][0];
  console.log(`Blocked for: ${topCategory}`);
}

Using the API Directly

Until the SDK is available, use fetch to call the Sieve API:

const response = await fetch('https://api.getsieve.dev/v1/moderate/text', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SIEVE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: 'Message to moderate',
    context: 'chat',
    user_id: 'player123',
  }),
});

const result = await response.json();

// Find the highest-scoring category
const topCategory = Object.entries(result.categories)
  .sort(([,a], [,b]) => b.score - a.score)[0][0];

switch (result.action) {
  case 'block':
    console.log(`Blocked for: ${topCategory}`);
    break;
  case 'flag':
    console.log(`Flagged for review: ${topCategory}`);
    break;
  case 'allow':
    console.log('Content is clean');
    break;
}

interface ModerationResult {
  action: 'allow' | 'flag' | 'block';
  categories: Record<string, { score: number; threshold: number; flagged: boolean }>;
  pipeline_tier: string;
  latency_ms: number;
}

async function moderate(content: string, context: string, user_id?: string): Promise<ModerationResult> {
  const response = await fetch('https://api.getsieve.dev/v1/moderate/text', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SIEVE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ content, context, user_id }),
  });

  if (!response.ok) {
    throw new Error(`Sieve API error: ${response.status}`);
  }

  return response.json();
}

const result = await moderate('Hello world', 'chat', 'player123');
console.log(result.action); // 'allow' | 'flag' | 'block'

const axios = require('axios');

const { data } = await axios.post(
  'https://api.getsieve.dev/v1/moderate/text',
  {
    content: 'Message to moderate',
    context: 'chat',
    user_id: 'player123',
  },
  {
    headers: {
      'Authorization': `Bearer ${process.env.SIEVE_API_KEY}`,
    },
  }
);

console.log(data.action); // 'allow' | 'flag' | 'block'

Error Handling

try {
  const response = await fetch('https://api.getsieve.dev/v1/moderate/text', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SIEVE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ content: text, context: 'chat' }),
  });

  if (response.status === 401) {
    throw new Error('Invalid API key');
  }
  if (response.status === 429) {
    // Rate limited -- back off and retry
    const retryAfter = response.headers.get('Retry-After');
    throw new Error(`Rate limited. Retry after ${retryAfter}s`);
  }
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const result = await response.json();
} catch (err) {
  // Fail open: if moderation is unavailable, allow the content
  console.error('Moderation error:', err);
}