SpeakSafely Desenvolvedores

Endpoints de descoberta

• Catálogo de API: https://speaksafely.com/index.php/.well-known/api-catalog
• OpenAPI: https://speaksafely.com/index.php/openapi.json
• Cartão do servidor MCP: https://speaksafely.com/index.php/.well-known/mcp/server-card.json
• Descoberta de agente: https://speaksafely.com/index.php/.well-known/agent.json
• Artigo de uso: https://speaksafely.com/index.php/blog/whistleblowing-platform-anonymity-compliance

API pública somente leitura

Os endpoints públicos atuais são somente leitura e focados em descoberta de serviço e metadados. Eles são indicados para planejamento de agentes, catalogação de produto e inicialização de integrações.

• GET /api/public/status
• GET /api/public/plans
• GET /api/public/capabilities

Quickstart para agentes

1. Descubra a superfície técnica em /.well-known/api-catalog e /openapi.json.
2. Inicie com leitura de status para validar disponibilidade da API pública.
3. Consuma capacidades e faixas de preço para catalogação e comparação de fornecedor.

curl -s https://speaksafely.com/index.php/api/public/status | jq

curl -s https://speaksafely.com/index.php/api/public/capabilities | jq

curl -s https://speaksafely.com/index.php/api/public/plans | jq

Autenticação

A superfície /api/public/* é pública e somente leitura no momento. Para reduzir fricção de onboarding, agentes podem começar sem credenciais. A evolução para APIs protegidas será publicada via endpoints well-known com escopos.

1. Leia metadados de autenticação em /.well-known/oauth-protected-resource.
2. Leia o servidor OAuth em /.well-known/oauth-authorization-server.
3. Para validação de readiness, o endpoint POST /api/public/token retorna erro estruturado enquanto a emissão real estiver desativada.

curl -s -X POST https://speaksafely.com/index.php/api/public/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=public.read" | jq

Escopos e rate limits

A superfície pública da SpeakSafely é limitada por IP e documenta os cabeçalhos usados para auto-throttling de agentes. Escopos planejados para recursos protegidos: public.read, reports.read, reports.write e webhooks.write.

• X-RateLimit-Limit: 120 requisições por minuto
• X-RateLimit-Remaining: saldo restante na janela atual
• Retry-After: orientação para re-tentativa após bloqueio
• X-API-Key: role planejada para integrações por chave

Erros e recuperação

Todas as respostas de erro da API pública seguem o mesmo schema JSON para facilitar recuperação automática por agentes. Sempre leia error.code e error.hint, e respeite Retry-After em cenários de limite.

{
  "error": {
    "code": "not_found",
    "message": "O endpoint público solicitado não foi encontrado.",
    "hint": "Consulte /openapi.json para ver as operações disponíveis."
  }
}

MCP Apps

O cartão MCP publica recursos ui:// para três experiências interativas: status público, faixas de preço e capacidades públicas. Os tools correspondentes expõem _meta.ui.resourceUri para clientes compatíveis renderizarem essas UIs em conversa.

• ui://speaksafely/public-status
• ui://speaksafely/public-plans
• ui://speaksafely/public-capabilities

Fale com nossa equipe