Referencia da API Neotask

Referencia completa da API para a plataforma Neotask. Este documento cobre todos os endpoints disponiveis, metodos de autenticacao, tratamento de erros e limites de taxa.

Autenticacao

Todas as requisicoes de API requerem autenticacao via um dos seguintes metodos:

Muitos endpoints combinam multiplos requisitos de autenticacao. Por exemplo, "Tenant + Admin" significa que a requisicao deve incluir tanto um JWT valido (pertencente a um usuario com a funcao Admin) quanto o cabecalho x-tenant-id.

Endpoints de Autenticacao

Endpoints para autenticacao de usuarios em plataformas web, iOS e desktop.

Metodo Endpoint Descricao Autenticacao
POST /api/auth/login Autenticar com email e senha. Retorna um JWT em caso de sucesso. Nenhuma
POST /api/auth/google Autenticar via Google OAuth na web. Espera um codigo de autorizacao Google. Nenhuma
POST /api/auth/google-ios Autenticar via Google OAuth no iOS. Espera um payload de autorizacao especifico do iOS. Nenhuma
POST /api/auth/google-token Verificar um token de acesso Google e retornar um JWT do Neotask. Nenhuma
POST /api/auth/apple Autenticar via Apple Sign-In. Espera um token de identidade Apple. Nenhuma
GET /api/auth/me Retornar o perfil do usuario autenticado (nome, email, avatar, funcoes). JWT
DELETE /api/auth/account Excluir permanentemente a conta do usuario autenticado e todos os dados associados. JWT

Endpoints de Autenticacao do Painel

Endpoints de autenticacao especificos para o painel do Neotask, incluindo login por chave de licenca e autenticacao de dois fatores (TOTP).

Metodo Endpoint Descricao Autenticacao
POST /api/dashboard/auth/login Autenticar com uma chave de licenca. Retorna um JWT em caso de sucesso, ou sinaliza que TOTP e necessario. Nenhuma
POST /api/dashboard/auth/totp-login Completar login fornecendo um codigo TOTP ou codigo de backup quando a autenticacao de dois fatores esta ativada. Nenhuma
GET /api/dashboard/auth/me Retornar as informacoes de licenca atuais e direitos de recursos para o usuario do painel autenticado. JWT
POST /api/dashboard/totp/setup Gerar um segredo TOTP e codigo QR para configurar a autenticacao de dois fatores. JWT
POST /api/dashboard/totp/verify Verificar um codigo TOTP para confirmar e ativar a autenticacao de dois fatores na conta. JWT

Endpoints de Cobranca

Gerenciar assinaturas, sessoes de checkout e compras in-app pelo Stripe e RevenueCat.

Metodo Endpoint Descricao Autenticacao
POST /api/billing/checkout Criar uma sessao Stripe Checkout para o plano Pro. Retorna uma URL de checkout. Tenant + Admin
POST /api/billing/checkout/enterprise Criar uma sessao Stripe Checkout para o plano Enterprise. Retorna uma URL de checkout. Tenant + Admin
GET /api/billing/status Retornar o plano atual, contagem de mensagens e limites de uso para o tenant. Tenant + Viewer
POST /api/billing/portal Criar uma sessao do Portal do Cliente Stripe para gerenciar metodos de pagamento e faturas. Tenant + Admin
POST /api/billing/agent-addon Comprar um slot adicional de agente add-on para o tenant. Tenant + Admin
POST /api/billing/webhook Handler de webhook Stripe. Valida a assinatura Stripe e processa eventos do ciclo de vida da assinatura. Stripe Signature
POST /api/billing/revenuecat-sync Verificar uma compra in-app do iOS via RevenueCat e sincronizar direitos ao tenant. Tenant + Admin
POST /api/billing/revenuecat-webhook Handler de webhook RevenueCat. Processa eventos de assinatura originados da App Store. Bearer

Endpoints de Chat

Enviar e receber mensagens, gerenciar sessoes e consultar resultados de trabalhos assincronos.

Metodo Endpoint Descricao Autenticacao
POST /api/chat/init Auto-provisionar um tenant, agente e sessao para o usuario autenticado. Use isso para inicializar o ambiente de chat de um novo usuario em uma unica chamada. JWT
POST /api/chat/send Enviar uma mensagem ao agente. A mensagem e processada de forma assincrona; um ID de trabalho e retornado imediatamente. Tenant + Admin
GET /api/chat/jobs/:jobId Consultar o status e resultado de um trabalho de chat assincrono pelo seu ID. Tenant + Viewer
GET /api/chat/messages Buscar todas as mensagens de uma sessao. Passe o ID da sessao como parametro de consulta. Tenant + Viewer
GET /api/chat/sessions Listar todas as sessoes de chat do tenant. Tenant + Viewer
POST /api/chat/sessions Criar uma nova sessao de chat. Tenant + Admin

Endpoints de Agentes e Atividades

Navegar por agentes, sessoes, ferramentas, arquivos, skills, canais, trabalhos agendados e equipes associados ao tenant.

Metodo Endpoint Descricao Autenticacao
GET /api/activity/agents Listar todos os agentes pertencentes ao tenant. Tenant
GET /api/activity/sessions Listar sessoes. Suporta filtragem por agentId, status e parametros de intervalo de datas. Tenant
GET /api/activity/sessions/:id/entries Obter todas as entradas (mensagens e eventos) de uma sessao especifica. Tenant
GET /api/activity/tools Listar todas as ferramentas disponiveis para os agentes do tenant. Tenant
GET /api/activity/files Listar todos os arquivos associados aos agentes do tenant. Tenant
GET /api/activity/skills Listar todas as skills associadas aos agentes do tenant. Tenant
GET /api/activity/channels Listar todos os canais associados aos agentes do tenant. Tenant
GET /api/activity/cron-jobs Listar todos os trabalhos agendados (cron) do tenant. Tenant
GET /api/activity/teams Listar todas as equipes dentro do tenant. Tenant

Endpoints de Skills

Gerenciar o catalogo de skills, instalar e configurar skills, e publicar skills personalizadas.

Metodo Endpoint Descricao Autenticacao
GET /api/skills/catalog Navegar pelo catalogo completo de skills. Retorna todas as skills publicadas disponiveis para instalacao. Tenant
GET /api/skills/list Listar as skills atualmente instaladas pelo usuario. Tenant + Viewer
POST /api/skills/sync Sincronizar skills do sistema de arquivos. Use isso apos implantar novos arquivos de skill para atualizar o registro. Tenant + Admin
POST /api/skills/register Registrar (instalar) uma skill do catalogo. Tenant + Viewer
DELETE /api/skills/register/:skillId Desregistrar (desinstalar) uma skill pelo seu ID. Tenant + Viewer
POST /api/skills/:skillId/publish Publicar uma skill para torna-la disponivel no catalogo. Tenant + Admin
POST /api/skills/:skillId/unpublish Despublicar uma skill, removendo-a do catalogo. Tenant + Admin
GET /api/skills/all Listar todas as skills incluindo as nao publicadas. Endpoint somente para admin para gerenciamento de skills. Tenant + Admin
PUT /api/skills/:skillId/env-schema Definir ou atualizar o esquema de variaveis de ambiente de uma skill. Isso controla quais campos de configuracao sao apresentados aos usuarios. Tenant + Admin
POST /api/skills/:skillId/configure Salvar valores de configuracao para uma skill instalada. Tenant + Viewer
DELETE /api/skills/:skillId/configure Remover toda configuracao de uma skill, redefinindo para padroes. Tenant + Viewer

Endpoints de Canais

Vincular, configurar, ativar e desconectar canais de mensagens (ex.: Slack, Discord, WhatsApp).

Metodo Endpoint Descricao Autenticacao
GET /api/channels/ Listar todos os canais e seus status atuais. Tenant + Viewer
GET /api/channels/:channel/status Obter o status detalhado de um canal especifico. Tenant + Viewer
POST /api/channels/:channel/link Iniciar o processo de vinculacao de um canal. Retorna uma URL de link ou token de sessao dependendo do tipo de canal. Tenant + Admin
GET /api/channels/:channel/link/wait Long-poll para a conclusao de um fluxo de vinculacao de canal. Retorna quando o canal e vinculado com sucesso ou a operacao expira. Tenant + Admin
GET /api/channels/:channel/jobs/:jobId Obter o resultado de um trabalho assincrono especifico do canal. Tenant + Admin
POST /api/channels/:channel/enable Ativar um canal vinculado para que o agente comece a receber mensagens dele. Tenant + Admin
POST /api/channels/:channel/disable Desativar um canal sem desvincular-lo. O agente para de receber mensagens, mas a conexao do canal e preservada. Tenant + Admin
POST /api/channels/:channel/disconnect Desconectar e desvincular completamente um canal. Tenant + Admin
GET /api/channels/:channel/config Obter a configuracao atual de um canal. Tenant + Admin
POST /api/channels/:channel/config Atualizar a configuracao de um canal. Tenant + Admin

Endpoints Google OAuth

Iniciar e gerenciar fluxos Google OAuth para conectar servicos Google ao Neotask.

Metodo Endpoint Descricao Autenticacao
GET/POST /oauth/google/start Iniciar um fluxo Google OAuth. Aceita parametros opcionais para especificar quais servicos Google solicitar acesso. Opcional
GET /oauth/google/services Listar todas as definicoes de servicos Google suportadas pelo Neotask, agrupadas por categoria. Nenhuma
GET /oauth/google/callback Handler de callback OAuth. O Google redireciona aqui apos o usuario conceder ou negar acesso. Nenhuma
GET /oauth/google/status Consultar o status de um fluxo OAuth em andamento. Retorna se o fluxo esta pendente, concluido ou falhou. Nenhuma

Servicos Google Disponiveis

O Neotask suporta conexao com 25 servicos Google, organizados por categoria:

Categoria Servicos
Core Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Keep, Tasks
Comunicacao People/Contacts, Chat, Meet, YouTube, Photos
Localizacao Places API, Routes/Directions, Business Profile
Especializados Classroom, Play Developer, AdSense, Google Ads

Endpoints de Chaves de Provedor

Gerenciar chaves de API de terceiros (ex.: para provedores de LLM). As chaves sao criptografadas em repouso e podem ser resolvidas (descriptografadas) sob demanda.

Metodo Endpoint Descricao Autenticacao
PUT /api/provider-keys/:provider Salvar ou atualizar uma chave de API para o provedor especificado. A chave e criptografada antes do armazenamento. HMAC + Auth
GET /api/provider-keys/ Listar todas as chaves de provedor salvas. Valores das chaves sao mascarados (apenas os ultimos quatro caracteres sao mostrados). Auth
DELETE /api/provider-keys/:provider Remover uma chave de API salva para o provedor especificado. HMAC + Auth
GET /api/provider-keys/:provider/resolve Descriptografar e retornar a chave de API completa para o provedor especificado. Auth
GET /api/provider-keys/mode Obter o modo de chave atual (fornecido pelo usuario vs. creditos da plataforma) e o saldo de creditos restante. Auth

Provedores Permitidos

O parametro de caminho :provider deve ser um dos seguintes valores:

Endpoints de Uso

Rastrear uso, consultar analytics, monitorar gastos e gerenciar orcamentos.

Metodo Endpoint Descricao Autenticacao
POST /api/usage/ingest Ingerir um registro de dados de uso (ex.: contagens de tokens, modelo usado). Auth
GET /api/usage/query Consultar analytics de uso com filtros flexiveis (intervalo de datas, modelo, agente). Auth
GET /api/usage/summary Obter um resumo de uso para um periodo. Passe period como parametro de consulta (ex.: day, week, month). Auth
GET /api/usage/analytics Recuperar analytics detalhados de uso incluindo discriminacoes por modelo e agente. Auth
GET /api/usage/spending Obter dados de gastos para um periodo. Passe period como parametro de consulta. Auth
GET /api/usage/budget Obter informacoes de orcamento incluindo o limite total, valor usado e valor restante. Auth
POST /api/usage/cron-runs Registrar a execucao de um trabalho agendado (cron) para rastreamento de uso. Auth
POST /api/usage/budget-snapshot Capturar um snapshot pontual do estado atual do orcamento. Auth

Endpoints de Onboarding

Guiar novos usuarios pela configuracao inicial, incluindo selecao de provedor de modelo e configuracao de chave de API.

Metodo Endpoint Descricao Autenticacao
POST /api/onboarding/init Inicializar a configuracao de onboarding para o usuario autenticado. Cria configuracoes padrao e retorna o estado de onboarding. JWT
GET /api/onboarding/models Listar provedores de modelos disponiveis e seus modelos suportados. Este endpoint e publico e nao requer autenticacao. Nenhuma
POST /api/onboarding/setup Configurar uma chave de API de provedor durante o onboarding. Valida a chave antes de salvar. Tenant + Admin
POST /api/onboarding/complete Marcar o onboarding como completo para o usuario atual. Dashboard Auth

Endpoints de Tenant

Criar e gerenciar tenants (workspaces), armazenar segredos criptografados e criar sessoes e trabalhos diretamente.

Metodo Endpoint Descricao Autenticacao
POST /api/tenants/ Criar um novo tenant (workspace). Retorna o ID do tenant e configuracoes padrao. JWT
GET /api/tenants/:tenantId Obter detalhes de um tenant especifico, incluindo configuracoes e contagem de membros. JWT
POST /api/tenants/secrets Armazenar um segredo criptografado associado ao tenant. Usado para integracoes de servicos. Tenant + Admin
POST /api/tenants/sessions Criar uma nova sessao dentro do tenant. Tenant + Admin
POST /api/tenants/jobs Criar um novo trabalho assincrono dentro do tenant. Tenant + Admin

Endpoints de Memoria

Gerenciar configuracao de memoria do agente, arquivos e conteudo. A memoria permite que agentes persistam informacoes entre sessoes.

Metodo Endpoint Descricao Autenticacao
GET /api/memory/config Buscar a configuracao de memoria atual (estado ativado, politica de retencao, limites). Auth
POST /api/memory/config Atualizar configuracoes de memoria como periodo de retencao e limites de armazenamento. Auth
GET /api/memory/files Listar todos os arquivos de memoria armazenados para o agente. Auth
GET /api/memory/files/:filename Recuperar o conteudo de um arquivo de memoria especifico pelo nome. Auth
DELETE /api/memory/files/:filename Excluir um arquivo de memoria especifico pelo nome. Auth
GET /api/memory/content Recuperar conteudo de memoria armazenado. Auth
POST /api/memory/content Armazenar novo conteudo de memoria para o agente. Auth

Endpoints de Contas Google

Gerenciar contas Google que foram conectadas ao Neotask via OAuth.

Metodo Endpoint Descricao Autenticacao
GET /api/google-accounts/ Listar todas as contas Google conectadas com seus escopos de servico e status. Auth
POST /api/google-accounts/:accountId/activate Ativar uma conta Google conectada, permitindo que o agente use seus servicos autorizados. Auth
DELETE /api/google-accounts/:accountId Remover uma conta Google conectada e revogar seus tokens armazenados. Auth

Endpoints de Contato e Suporte

Enviar e gerenciar solicitacoes de contato de suporte.

Metodo Endpoint Descricao Autenticacao
POST /api/contact/ Enviar uma mensagem do formulario de contato. Limitado a 5 requisicoes por 15 minutos por endereco IP. Nenhuma
GET /api/contacts/ Listar todos os envios de contato com suporte a paginacao. Somente admin. Admin
PATCH /api/contacts/:id Atualizar o status de um envio de contato (ex.: marcar como resolvido). Admin
DELETE /api/contacts/:id Excluir um envio de contato. Admin

Limites de Taxa

O Neotask aplica limites de taxa em certos endpoints para proteger a estabilidade do servico. Quando um limite de taxa e excedido, a API retorna uma resposta 429 Too Many Requests.

Categoria de Endpoint Limite
Formulario de contato 5 requisicoes por 15 minutos por IP
Tentativas de login 10 requisicoes por 15 minutos por IP
Rastreamento/analytics 30 requisicoes por 60 segundos por IP

Respostas de Erro

Todas as respostas de erro seguem um formato JSON consistente:

{
  "error": "Descricao da mensagem de erro",
  "status": 400
}

Codigos de Status

Codigo Significado
400 Bad Request -- A requisicao estava malformada ou continha parametros invalidos.
401 Unauthorized -- Autenticacao esta faltando ou o token fornecido e invalido.
402 Payment Required -- Os creditos do tenant foram esgotados. Faca upgrade do seu plano ou adicione creditos para continuar.
403 Forbidden -- O usuario autenticado nao tem permissoes suficientes para esta acao.
404 Not Found -- O recurso solicitado nao existe.
429 Rate Limited -- Muitas requisicoes. Aguarde e tente novamente apos o periodo indicado nos cabecalhos da resposta.
500 Internal Server Error -- Um erro inesperado ocorreu no servidor. Se isso persistir, entre em contato com o suporte do Neotask.