Notiamo

Notiamo para agentes de IA

Tudo de que um agente de IA precisa para abrir uma conta gratuita para o seu proprietário, colocar o widget em um site e cuidar dos comentários e do trabalho, sem navegador.

O fluxo

  1. Peça uma conta para o seu proprietário: envie POST https://my.notiamo.com/api/agent/signup com email, name, agent, locale e, se tiver, company, projectUrl (o endereço do site) e referral. A resposta traz requestId, pollSecret e pollAfterSeconds.
  2. Diga ao proprietário para abrir o e-mail de confirmação que o Notiamo envia e confirmar. Nada acontece até ele confirmar.
  3. Consulte GET https://my.notiamo.com/api/agent/signup/{requestId} com Authorization: Bearer <pollSecret> a cada pollAfterSeconds segundos. O status é pending, confirmed, expired ou reported.
  4. Quando o status for confirmed, a resposta traz, uma única vez, a sua chave (token, começando com ntm_) e mcpUrl. Guarde a chave na hora: as consultas seguintes não a devolvem. Resgate-a em até 7 dias após a confirmação.
  5. Conecte-se ao servidor MCP em https://my.notiamo.com/api/mcp com o cabeçalho Authorization: Bearer ntm_…. Se o seu app aceita login MCP, ele pode usar Entrar com o Notiamo em vez de uma chave (veja abaixo).
  6. Chame list_projects (ou find_project) para encontrar o projeto feito para você: ele já usa o seu projectUrl como endereço. Se o endereço estiver ausente ou errado, chame update_project_address. Depois get_install, instale o trecho e check_install. Use create_workspace e create_project só quando o plano tiver espaço (planos pagos ou o teste do Studio); create_project precisa de um workspaceId de list_workspaces. Um espaço de trabalho agrupa projetos, por exemplo um por cliente. Um projeto pode não ter endereço web (omita origin): então ele tem tarefas, trabalhos e novidades, mas não tem widget. Depois da instalação, get_badge dá o selo do rodapé: um pequeno logótipo Notiamo para o rodapé do site, que abre as ferramentas de revisão aos revisores e é uma simples ligação para o Notiamo para os restantes, no idioma do site (update_project_language, ou language em create_project).
  7. Depois trabalhe nos comentários: list_comments, get_comment, reply e set_status. Para ver o que há de novo, passe since a list_comments: um horário UTC terminado em Z (como 2026-10-17T08:00:00Z), ou o cursor da última resposta. Você recebe só o que mudou, em um projeto ou, sem projectId, em todos os seus projetos. Guarde o novo cursor para a próxima verificação, siga more: true na hora e remova duplicados por id: um item pode vir duas vezes.
  8. Para outra organização, chame create_organization com um name: o proprietário passa a ser o administrador e recebe um e-mail, e a resposta traz um novo token só para essa organização. Ela é gratuita se o proprietário não tiver uma organização gratuita; caso contrário, precisa de um plano: chame get_payment_link com o novo token, ou start_trial para o teste do Studio de 14 dias (uma vez por pessoa; o proprietário abre o link e informa um cartão). Há um limite diário; a recusa diz quando você pode tentar de novo.
  9. Para mover um projeto para outro espaço de trabalho (kind project, projectId, toWorkspaceId), ou um espaço de trabalho com seus projetos para outra organização onde o proprietário também é administrador (kind workspace, workspaceId, toOrganizationId), chame request_move. Nada é movido ainda: o proprietário recebe um e-mail e deve confirmar na página indicada, em até 24 horas. Chame get_move_request para ver o status: pending, done, cancelled, expired ou failed.
  10. Para adicionar trabalho que não está ligado a uma página, chame create_task com um projectId e um title, e opcionalmente text e pageUrl. Para mudar o texto, chame update_task com o taskId e um novo title, text ou os dois. Ambos contam para um limite diário de novos espaços de trabalho, projetos e tarefas; a recusa diz quando você o atinge. list_comments mostra as tarefas marcadas com [Task] e aceita type: task ou comment.
  11. Os relatórios de trabalho (Studio, Agency e o teste) são tarefas que um cliente preenche sobre um serviço feito: local, data, cliente final e arquivos por fase (before, during, after, other) com legendas. Chame list_job_reports (state ready lista os que esperam por você), leia um com get_comment e responda com role article no idioma dele. Só uma pessoa aprova: dê a ela o link de aprovação ou chame request_approval. Depois de aprovado, responda com role posts e files (os ids dos arquivos a usar). update_file define a phase ou a caption de um arquivo; create_task e update_task aceitam jobReport.
  12. Notas de voz e IA (Studio, Agency e o teste): get_comment lista cada gravação com um link para o áudio e sua transcrição por IA (e qualquer transcrição posterior, não publicada), cada vídeo com mais de cerca de 20 segundos com notas de tempo (m:ss–m:ss o que acontece) e legendas por IA marcadas com (AI, not checked) até uma pessoa conferir. Quando a IA não conseguiu processar um arquivo, ela diz isso com as mesmas palavras simples que as pessoas veem, com um código de referência (AI-…) para o suporte. list_plans e get_billing informam os minutos de voz e IA por mês.

Não consulte mais rápido que pollAfterSeconds. Se receber rate_limited, aguarde retryAfter segundos. Um id ou segredo errado ou desconhecido devolve 404 com {"code":"not_found"}.

Se a sua plataforma assina os pedidos com Web Bot Auth (assinaturas de mensagens HTTP, um Signature-Agent com um diretório de chaves) e o Notiamo confia nela, o cadastro e o servidor MCP contam você pela plataforma e não pelo endereço, com limites maiores. Pedidos sem assinatura funcionam como antes.

Exemplo: pedir uma conta

curl -X POST https://my.notiamo.com/api/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@example.com","name":"Ada Owner","agent":"my-agent","locale":"en","projectUrl":"https://example.com"}'

O plano gratuito

O plano gratuito permite 1 espaço de trabalho, 1 projeto, 3 pessoas (membros da equipe, membros clientes e convites pendentes, cada e-mail uma vez) e 1 endereço público por projeto. Depois do primeiro comentário público do projeto, o endereço pode ser alterado uma vez. Ele guarda 100 MB de arquivos, 5 MB por arquivo; acima de 100 MB os administradores da organização recebem dois e-mails, depois os arquivos mais antigos são removidos, e comentários, tarefas e respostas ficam. Os envios podem ser recusados para impedir abusos. Vídeo não está incluído: precisa do Studio, do Agency ou do teste. Um espaço de trabalho e um projeto já existem quando a conta é aberta.

O widget mostra um selo do Notiamo no plano gratuito.

Mantenha a linha de comentário acima da tag script. Os termos do plano gratuito exigem isso:

<!-- Notiamo (notiamo.com): website feedback. Free plan: keep this line. -->

Uma recusa plan_limit diz qual limite você atingiu e o que fazer em seguida.

Recusas

O cadastro e as ferramentas respondem com um código. Os códigos do cadastro vêm com um status HTTP:

CódigoStatus HTTPO que significa
signup_blocked403A rede não pode fazer cadastro. O proprietário se cadastra por conta própria.
country_blocked403O Notiamo não está disponível no país de onde vem o pedido. O proprietário também não pode se cadastrar a partir de lá.
rate_limited429Requisições demais. Aguarde retryAfter segundos.
agent_signup_paused503O cadastro por agentes está pausado por enquanto. O proprietário se cadastra por conta própria.
agent_signup_closed503O cadastro por agentes está encerrado. O proprietário se cadastra por conta própria.
account_exists409Este e-mail já tem uma conta. O proprietário faz login e cria uma chave em Configurações > Agentes de IA > Tokens de agente.
email_not_accepted422Este endereço de e-mail não pode ser usado. O proprietário se cadastra por conta própria.
invalid_input422Um campo não é válido. field o indica.
plan_limit402Um limite do plano foi atingido. Devolvido pelas ferramentas MCP, com o próximo passo (start_trial ou get_payment_link).
read_only403Esta chave ou app é somente leitura: pode olhar, mas não alterar. Devolvido pelas ferramentas MCP.
permission_missing403Esta chave ou app não pode fazer isto. permission nomeia o grupo que falta (ou full). Devolvido pelas ferramentas MCP.

Mostre as recusas ao seu proprietário. Nunca as contorne.

Entrar com o Notiamo (OAuth)

Em vez de uma chave, um cliente MCP que aceita login pode se conectar com OAuth. Os metadados do servidor de autorização estão em https://my.notiamo.com/.well-known/oauth-authorization-server, e o servidor MCP responde 401 com um cabeçalho WWW-Authenticate que aponta para os metadados do seu recurso protegido (https://my.notiamo.com/.well-known/oauth-protected-resource/api/mcp, RFC 9728), que nomeiam este servidor, e sugere o escopo notes replies status tasks. Os clientes se registram sozinhos e usam PKCE (S256), sem segredo de cliente.

Seu proprietário faz login, escolhe a organização, o que você pode alterar (Trabalhar no feedback vem marcado) e os projetos, e clica em Permitir. Os escopos são os grupos de permissão abaixo. Seu proprietário vê o app em Configurações > Agentes de IA > Aplicativos conectados e pode desconectá-lo a qualquer momento.

Permissões

Ler não exige permissão. Para alterar algo, uma chave ou um app conectado precisa do grupo correspondente:

notes replies status tasks setup invites billing moves

Somente leitura não tem grupo. Trabalhar no feedback tem notes, replies, status e tasks. Total tem todos; convidar membros da equipe exige Total. Sem o grupo, a ferramenta recusa com permission_missing e nomeia o grupo em permission; uma chave somente leitura recebe read_only. Mostre isso ao seu proprietário: só ele pode dar mais acesso.

Pagamento

list_plans mostra os planos (veja a página de preços para os valores). start_trial inicia o teste, uma vez por pessoa. Preços

get_payment_link cria um link de pagamento que o proprietário abre e paga. Você nunca lida com dados de cartão.

Indicação

Se um selo ou link do Notiamo trouxe você até aqui, passe o código dele no campo referral do corpo JSON do cadastro. A forma ?via=<code> serve só para o link de cadastro que as pessoas abrem.

As ferramentas MCP

Depois de conectar, você pode chamar:

whoami list_projects find_project list_comments list_activity get_comment reply set_status assign list_team list_people get_account list_plans get_billing start_trial list_workspaces create_workspace create_project update_project_address update_project_language get_install get_badge check_install invite get_payment_link create_organization request_move get_move_request create_task update_task list_job_reports update_file request_approval

Mais