Início Rápido

Integre o ContentShield em sua aplicação em menos de 5 minutos.

1. Obtenha sua API Key

Após criar sua conta, você encontrará sua API Key no dashboard em Configurações → API Keys.

2. Faça sua primeira chamada

bash

curl -X POST https://api.contentshield.io/v1/analyze/text \
  -H "X-API-Key: cs_live_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Olá, esta é uma mensagem de teste",
    "userId": "user_123"
  }'

3. Trate a resposta

json

{
  "id": "analysis_abc123",
  "action": "ALLOW",
  "riskScore": 5,
  "categories": [],
  "confidence": 0.98,
  "forensicHash": "sha256:...",
  "processingTimeMs": 145
}

Ações possíveis

ALLOW - Conteúdo seguro, pode ser publicado
FLAG - Conteúdo suspeito, enviar para revisão humana
BLOCK - Conteúdo perigoso, bloquear imediatamente

Autenticação

Todas as chamadas à API devem incluir sua API Key no header.

Header de Autenticação

http

X-API-Key: cs_live_sua_api_key_aqui

Tipos de API Key

cs_live_* - Chaves de produção, cobradas normalmente
cs_test_* - Chaves de teste, não cobradas (sandbox)

Importante

Nunca exponha sua API Key no frontend. Use-a apenas em seu backend server-side.

Análise de Texto

Análise mensagens de texto para detectar grooming, assédio, hate speech e outros riscos.

POST/v1/analyze/textAnalisa texto

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
text	string	Sim	Texto a ser analisado (máx. 50.000 caracteres)
userId	string	Não	ID externo do usuário autor
context.platform	string	Não	Plataforma (chat, forum, comment, etc.)
context.recipientAge	number	Não	Idade do destinatário (para detecção de grooming)
context.conversationId	string	Não	ID da conversa para análise contextual
context.messageIndex	number	Não	Posição da mensagem na conversa

Exemplo de Request

javascript

const response = await fetch('https://api.contentshield.io/v1/analyze/text', {
  method: 'POST',
  headers: {
    'X-API-Key': 'cs_live_sua_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: "Mensagem do usuário",
    userId: "user_123",
    context: {
      platform: "chat",
      recipientAge: 14
    }
  })
})

const result = await response.json()

Resposta

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	ID único da análise
action	string	Sim	ALLOW, FLAG ou BLOCK
riskScore	number	Sim	Score de risco de 0-100
categories	string[]	Sim	Categorias detectadas
confidence	number	Sim	Nível de confiança (0-1)
forensicHash	string	Sim	Hash SHA-256 para auditoria
processingTimeMs	number	Sim	Tempo de processamento em ms

Categorias Detectadas

harassment - Assédio

grooming_risk - Risco de grooming

sexual - Conteúdo sexual

hate - Discurso de ódio

violence - Violência

self_harm - Auto-mutilação

bullying - Bullying

threat - Ameaça

Análise de Imagem

Análise imagens para detectar conteúdo impróprio, nudez, violência e CSAM.

POST/v1/analyze/imageAnalisa imagem

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
imageUrl	string	Não	URL da imagem (HTTPS)
imageBase64	string	Não	Imagem em base64
userId	string	Não	ID externo do usuário
context.platform	string	Não	Plataforma de origem
context.uploadedBy	string	Não	Quem fez o upload

Nota: Você deve fornecer imageUrl OU imageBase64, não ambos. Formatos suportados: JPEG, PNG, GIF, WebP. Tamanho máximo: 10MB.

Exemplo com URL

bash

curl -X POST https://api.contentshield.io/v1/analyze/image \
  -H "X-API-Key: cs_live_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://exemplo.com/imagem.jpg",
    "userId": "user_123"
  }'

Exemplo com Base64

bash

curl -X POST https://api.contentshield.io/v1/analyze/image \
  -H "X-API-Key: cs_live_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "data:image/jpeg;base64,/9j/4AAQ...",
    "userId": "user_123"
  }'

Usuários Suspeitos

Monitore usuários com comportamento de risco recorrente.

GET/v1/usersLista usuários suspeitos

GET/v1/users/:idDetalhes de um usuário

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
limit	number	Não	Máximo de resultados (padrão: 50, máx: 100)
offset	number	Não	Offset para páginação
minRiskScore	number	Não	Filtrar por score mínimo

Resposta

json

{
  "data": [
    {
      "id": "user_abc123",
      "externalUserId": "player_456",
      "riskScore": 85,
      "analysisCount": 47,
      "flagCount": 12,
      "blockCount": 8,
      "topCategories": ["grooming_risk", "harassment"],
      "firstSeenAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z"
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0
}

Webhooks

Receba notificações em tempo real quando conteúdo for flagged ou blocked.

Configuração

Configure webhooks no dashboard em Configurações → Webhooks.

Eventos Disponíveis

analysis.flagged - Análise retornou FLAG
analysis.blocked - Análise retornou BLOCK
user.risk_elevated - Score de usuário subiu para crítico

Payload do Webhook

json

{
  "event": "analysis.blocked",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "analysisId": "analysis_abc123",
    "type": "TEXT",
    "action": "BLOCK",
    "riskScore": 92,
    "categories": ["grooming_risk", "harassment"],
    "userId": "user_456",
    "forensicHash": "sha256:..."
  },
  "signature": "sha256=abc123..."
}

Verificando a Assinatura

javascript

const crypto = require('crypto')

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

Tratamento de Erros

A API retorna erros em formato JSON consistente e padronizado.

Formato de Erro

json

{
  "error": "ConflictError",
  "code": "EMAIL_ALREADY_REGISTERED",
  "message": "Email already registered",
  "details": { "field": "email" }
}

Códigos de Status HTTP

200Sucesso

400Erro de validação (parâmetros inválidos)

401Não autenticado (API Key inválida, credenciais erradas)

402Saldo insuficiente

404Recurso não encontrado

409Conflito (recurso já existe)

429Rate limit excedido

500Erro interno do servidor

Códigos de Erro

Código	Status	Descrição
VALIDATION_ERROR	400	Dados de entrada inválidos
INVALID_CREDENTIALS	401	Email ou senha incorretos
ACCOUNT_LOCKED	401	Conta bloqueada por tentativas de login
ACCOUNT_NOT_ACTIVE	401	Conta não está ativa (verificar email)
API_KEY_NOT_FOUND	404	API Key não encontrada
WEBHOOK_NOT_FOUND	404	Webhook não encontrado
EMAIL_ALREADY_REGISTERED	409	Email já cadastrado
ORGANIZATION_EMAIL_EXISTS	409	Organização com este email já existe
INSUFFICIENT_BALANCE	402	Saldo insuficiente para operação

Rate Limits

Limites de requisições por segundo para garantir estabilidade.

Plano	Requisições/segundo	Burst
Free Trial	10/s	20
Growth	100/s	200
Enterprise	Ilimitado*	Customizado

Headers de Rate Limit

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320000

Quando você excede o rate limit, a API retorna status 429 Too Many Requests. Espere até o timestamp em X-RateLimit-Reset para tentar novamente.

Pronto para começar?

Crie sua conta e comece a proteger sua plataforma agora.

Começar Grátis