A API pública do n8n permite que sistemas autorizados consultem e operem recursos da instância por endpoints HTTP. As chamadas exigem API key e a disponibilidade depende do ambiente: a documentação atual lista planos Starter, Pro e Enterprise no n8n Cloud e todas as edições self-hosted, mas exclui o período de teste gratuito. Use a API para inventário ou operação administrativa com escopo controlado; não confunda essa chave com OAuth de uma integração externa.

Nota editorial: análise baseada nas fontes oficiais vinculadas e no Planejador Google; não houve teste próprio. Preços, acesso, limites e funcionalidades podem mudar e devem ser confirmados no serviço antes da implantação.

Confirme se sua instalação oferece a API

A referência oficial informa a disponibilidade em n8n Cloud Starter, Pro e Enterprise e em todas as edições self-hosted; a API não está disponível no free trial. Antes de construir o cliente, confirme a versão instalada, o plano e a URL base. Cloud usa o subdomínio da instância mais `/api/v1`; self-hosted usa seu domínio seguido do mesmo caminho. Proxies reversos e prefixos customizados podem alterar a URL pública.

Se a API não estiver disponível no seu ambiente, não tente contornar o plano por chamadas internas do banco ou endpoints não documentados. Escolha um plano compatível ou use os recursos da interface aprovados pela equipe. Para automação de negócio, muitas vezes basta chamar a API do sistema final a partir do n8n; não é obrigatório que o fluxo controle a própria instância n8n.

Referência: n8n API endpoint reference.

Crie uma chave dedicada e trate como credencial

A documentação orienta gerar a API key nas configurações do usuário, na área de API. Configure expiração quando disponível, guarde a chave em credencial segura e envie no cabeçalho `X-N8N-API-KEY`. Não passe em query string, URL, prompt, print de tela ou log. A referência menciona scopes de chave para Enterprise; fora dessa condição, a chave pode ter acesso amplo, então limite quem a cria e onde ela é usada.

Use uma chave diferente por integração e ambiente. Nomeie para identificar propósito, responsável e data de revisão, sem incluir segredo. Se houver vazamento ou mudança de responsável, revogue e emita outra. Não coloque uma chave admin em workflow compartilhado com usuários que não deveriam controlar credenciais. Teste se o n8n mascara o campo de credencial na exportação; uma exportação pode omitir o valor ou incluir configuração que precisa ser revisada.

Referência: n8n API authentication.

Faça uma primeira chamada de leitura

Comece com uma consulta simples documentada, como listar workflows, em uma instância de teste. Use HTTPS, o endpoint correto e o cabeçalho da chave. Confira status HTTP, estrutura da resposta e campos necessários. Não leia credenciais ou altere o estado de workflows no primeiro teste. A referência de endpoints é gerada a partir da OpenAPI e organiza operações por recurso; use a página específica do endpoint para parâmetros e esquema atuais.

Trate códigos de resposta de forma distinta: 401 indica problema de autenticação, 403 falta de autorização, 404 endpoint ou recurso inexistente, 429 limite de chamadas e 5xx erro do serviço. Evite repetir automaticamente uma operação que altera estado sem verificar se a primeira chamada foi concluída. Adicione timeout, logging sanitizado e limite de tentativas. Se usar HTTP Request no n8n, mantenha API key em credencial e não no campo de texto comum.

Referência: n8n API pagination.

Leia antes de escrever ou ativar

A API pode incluir endpoints de workflows, execuções e outros recursos administrativos, mas isso não significa que todos devem ser usados por uma integração. Para atualização ou ativação, confira o schema e a política do endpoint, armazene a versão anterior e faça backup. Se o objetivo é publicar alterações, prefira o processo oficial de revisão e controle de versão da organização. Uma chamada que salva um workflow não prova que ele está funcionando com os dados de produção.

Mantenha separação entre listar e alterar. Dê ao serviço a menor permissão possível, use uma instância de staging e inclua uma aprovação manual antes de ativar um workflow que envia mensagens, processa pagamentos ou modifica registros. Depois de uma alteração, rode teste manual com entradas conhecidas, verifique a execução e confirme que o workflow correto recebeu a mudança. Não use um endpoint de execução para disparar milhares de workflows em lote sem controle de fila.

Referência: n8n API endpoint reference.

Paginação e inventário completo

Listagens podem ser paginadas. A API do n8n documenta cursor `nextCursor`; a primeira chamada não é necessariamente a lista completa. Siga o cursor retornado até que não haja próximo valor e mantenha um limite de segurança. Se o script parar após a primeira página, o inventário ficará incompleto e uma auditoria pode afirmar incorretamente que não existem outros workflows.

Armazene apenas campos necessários no inventário e trate cursor como dado de navegação, não como segredo. Para uma exportação, registre instante da coleta, total de páginas, erros e filtro usado. Se a coleção muda durante a paginação, pode haver diferença entre páginas; para auditoria rigorosa, reduza alterações durante a coleta ou faça uma segunda reconciliação. Evite iniciar com atualização em massa: primeiro gere relatório somente de leitura e valide a contagem.

Referência: n8n API authentication.

Riscos de uma API administrativa

Uma API que administra workflows pode afetar atendimento, faturamento e dados de clientes. Proteja acesso em rede, rotação de chave e monitoramento de chamadas. Restrinja IP quando a infraestrutura permitir, limite acesso ao cofre e use ambiente separado. Evite registrar cabeçalhos HTTP, corpos com dados pessoais e tokens em observabilidade. Faça revisão periódica de chaves e remova credenciais de contas antigas.

A API key não substitui autenticação de usuários do sistema nem política de aprovação. Um script com acesso amplo pode listar ou alterar recursos de toda a instância. Defina casos de uso estreitos, revise dependências do cliente e fixe versões. Nunca exponha a API de administração no browser público. Se uma aplicação front-end precisar controlar operações, use um backend autorizado com validação e autenticação, não injete a chave n8n no JavaScript do navegador.

Referência: n8n API pagination.

Plano de automação com evidência

Para monitorar workflows, uma rotina pode listar recursos, filtrar por estado ou tags e produzir alerta sem alterar dados. Defina o que conta como anomalia e valide os campos retornados. Para sincronização, estabeleça chave de idempotência e estratégia de reconciliação. Mantenha um log técnico mínimo com horário, endpoint, status, identificador do recurso e resultado, sem payload sensível.

Antes de ativar, faça ensaio em staging e compare o relatório com a interface administrativa. Teste chave expirada, permissão insuficiente, paginação e indisponibilidade. Documente a URL base, plano, versão, responsável e data de expiração. A API economiza trabalho repetitivo quando o caso exige administração programática, mas amplia a consequência de um segredo comprometido. Comece com leitura, prove a necessidade de escrita e retire permissões que não forem usadas.

Referência: n8n API endpoint reference.

Perguntas frequentes

A API do n8n usa OAuth?

A documentação da API pública pede uma API key no cabeçalho `X-N8N-API-KEY`; isso é diferente de OAuth2 para uma API externa.

A API está disponível no trial?

A referência atual diz que não está disponível no free trial; confira o plano da instância.

Onde crio a chave?

Nas configurações do usuário, na seção de API, conforme a documentação oficial da sua versão.

Posso colocar a chave no workflow?

Armazene em credencial protegida; não em texto, URL, navegador, prompt ou log.

Uma listagem retorna todos os workflows?

Pode exigir paginação. Siga `nextCursor` até terminar e valide total e erros.

Fontes principais: n8n API endpoint reference; n8n API authentication; n8n API pagination.