API Pública v2

A API v2 do ChatNorris permite integrar e automatizar sua plataforma de agentes de IA a partir de qualquer aplicação externa. Você pode gerenciar agentes, enviar mensagens, ler conversas, leads e muito mais. Base URL:

https://app.chatnorris.ai/api/v2

O acesso à API está disponível nos planos Standard e Premium. Para habilitá-lo, você precisa de uma API key ativa. No plano Free, a seção de chaves de API aparece bloqueada — ao tentar criar uma key, você é redirecionado para a página de planos.

Gerar uma API key

Entre na sua conta e acesse Configurações → Chaves de API.
Digite um nome descritivo para a chave (ex.: “Produção” ou “Zapier”).
Clique em Nova chave.
Copie a key gerada — ela é exibida uma única vez. Guarde-a em um lugar seguro.

Se você perder a key, precisa excluí-la e criar uma nova. Cada organização pode ter até 10 API keys.

Cada chave tem acesso completo à API em nome da sua organização. Trate-a como uma senha e não a compartilhe nem a exponha no código de um site.

A API v2 também é a base das integrações de automação listadas na página de Integrações: Zapier (app pública, sem credenciais próprias) e o community node do n8n (n8n-nodes-chatnorris, código aberto). Ambas se conectam com a sua API key e os endpoints desta referência — veja Zapier e n8n.

Autenticação

Todas as requests devem incluir a API key no header Authorization como Bearer token:

Authorization: Bearer <sua_api_key>

As requests sem key ou com key inválida recebem 401 Unauthorized. O header X-API-Key não é aceito.

Permissões (scopes)

Cada endpoint exige uma permissão (scope). As API keys que você cria em Configurações → Chaves de API sempre têm acesso completo (*), então podem usar todos os endpoints desta referência: não é preciso escolher permissões ao criar a chave. Como referência, esta é a permissão que cada grupo de endpoints exige:

Scope	Acesso
`chatbots:read`	Listar e obter agentes e fontes de knowledge
`chatbots:write`	Criar, atualizar e excluir agentes e fontes
`chat:write`	Enviar mensagens por meio de um agente e enviar anexos
`conversations:read`	Listar e obter conversas e mensagens
`leads:read`	Listar e obter leads
`channels:read`	Listar canais conectados
`*`	Acesso completo a todos os scopes

Os endpoints de projeto, membros e uso não exigem um scope específico — apenas autenticação válida.

Formato de resposta

Todas as respostas são JSON com a seguinte estrutura:

Sucesso

{
  "status": "success",
  "data": { ... }
}

Sucesso com paginação

{
  "status": "success",
  "data": { ... },
  "pages": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 98
  }
}

Erro

{
  "status": "error",
  "message": "Descrição do erro",
  "code": "CODIGO_ERROR"
}

Paginação

Os endpoints de listagem suportam paginação por meio de query params:

Parâmetro	Tipo	Default	Descrição
`page`	integer	`1`	Número da página (começa em 1)
`per_page`	integer	`25`	Resultados por página (máximo `100`)

Códigos de erro

Código HTTP	Code	Descrição
400	`INVALID_INPUT`	O corpo da request não passa na validação
401	`AUTH_REQUIRED`	Falta o header `Authorization`
401	`INVALID_API_KEY`	A API key não existe, foi excluída ou o formato é inválido
401	`API_KEY_EXPIRED`	A API key expirou
403	`ORG_SUSPENDED`	A organização dona da key não está ativa
403	`FEATURE_NOT_ALLOWED`	O plano da sua organização não inclui acesso à API (por exemplo, o plano Free)
403	`INSUFFICIENT_SCOPE`	A key não tem o scope necessário para este endpoint
403	`PLAN_LIMIT_REACHED`	O limite do plano foi atingido (agentes, créditos etc.)
404	`NOT_FOUND`	O recurso solicitado não existe ou não pertence à sua organização
429	`RATE_LIMIT_EXCEEDED`	O limite de requests por minuto foi ultrapassado
429	`PLAN_LIMIT_REACHED`	O limite de créditos de IA do plano foi atingido
500	`INTERNAL_ERROR`	Erro interno do servidor

Limite de taxa (Rate limiting)

A API permite 300 requests por minuto por API key. Quando o limite é ultrapassado, a resposta inclui o header Retry-After com os segundos que é preciso esperar antes de tentar novamente.

HTTP/1.1 429 Too Many Requests
Retry-After: 15

{
  "status": "error",
  "message": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED"
}

Primeiros passos

Agentes de IA

Widget web

Canais

Conversas e chat ao vivo

Campanhas

Leads e análises

Equipe

Conta e configurações

Faturamento

Solução de problemas

Perguntas frequentes

Glossário

API pública v2

Introdução à API

API Pública v2

Gerar uma API key

Autenticação

Permissões (scopes)

Formato de resposta

Sucesso

Sucesso com paginação

Erro

Paginação

Códigos de erro

Limite de taxa (Rate limiting)

​API Pública v2

​Gerar uma API key

​Autenticação

​Permissões (scopes)

​Formato de resposta

​Sucesso

​Sucesso com paginação

​Erro

​Paginação

​Códigos de erro

​Limite de taxa (Rate limiting)

API Pública v2

Gerar uma API key

Autenticação

Permissões (scopes)

Formato de resposta

Sucesso

Sucesso com paginação

Erro

Paginação

Códigos de erro

Limite de taxa (Rate limiting)