Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

Referência do waafir-redact

O servidor waafir-redact disponibiliza o tarjamento do Waafir para um cliente de IA conectado, em dois formatos:

  • redact_text — um bloco de texto, tarjado em linha e retornado imediatamente.
  • redact_file / redact_file_status — um documento inteiro em uma sala de dados, analisado em busca de PII e preparado para revisão humana.

Aplicar um tarjamento a um documento propositalmente não está disponível via MCP. A aplicação altera o que todas as outras partes veem ao abrir o arquivo, por isso uma pessoa precisa aprová-la na tela de revisão do Tarjamento por IA. Nenhuma ferramenta deste servidor altera o que qualquer leitor vê.

Conexão: https://app.waafir.io/api/mcp/waafir ou o servidor da área https://app.waafir.io/api/mcp/waafir-redact; os nomes das ferramentas são os mesmos em ambos — consulte Configuração. redact_text exige apenas um PAT com escopo read (ou superior) — ele não acessa nenhuma sala de dados, portanto não há verificação por arquivo ou por sala a cumprir (ainda assim, exige um plano pago e a IA ativada, como toda ferramenta que executa um modelo).

As duas ferramentas de documentos são exclusivas da equipe da transação. redact_file exige escopo write e participação na equipe da transação da sala de dados — e o mesmo vale para redact_file_status, embora ela apenas leia: um PAT com escopo read é necessário, mas não suficiente, porque a existência de um job de tarjamento é em si um fato sobre o documento. Quem chama de fora da equipe da transação recebe FORBIDDEN, qualquer que seja o escopo do token. O escopo do token é o teto do token; a participação na equipe da transação é o da pessoa — os dois precisam ser atendidos.

redact_text

Tarja PII de um bloco de texto. O texto é processado pelo agente de tarjamento da sua organização, e a ferramenta retorna o texto tarjado junto com a lista de entidades identificadas. Opcionalmente, restrinja o resultado a tipos específicos de entidade.

Entradas

CampoTipoObrigatórioDescrição
textstringsimO texto a tarjar (não pode ser vazio).
typesstring[]nãoRestringe o tarjamento a estes tipos de PII. Omita para tarjar tudo o que for detectado.

Saída

{ redacted_text, entities, truncated, processed_chars, total_chars, max_chars,
  filtered_out_count, unclassified_redacted_count, unclassified_types,
  filter_exact }
  • redacted_text — o texto analisado, com os trechos sensíveis tarjados.
  • entities — as PII removidas. type é o rótulo que o modelo de tarjamento usou; canonical_type é o tipo padrão ao qual ele corresponde, ou null se não foi possível classificá-lo.
  • truncated / processed_chars / total_chars / max_chars — consulte Limite de tamanho.
  • filtered_out_count / unclassified_redacted_count / unclassified_types / filter_exact — consulte Filtragem por tipo.

O tarjamento é executado com a configuração de tarjamento da sua própria organização, portanto os resultados refletem o mesmo agente que o produto usa. Como tudo nesta superfície, a chamada age como o proprietário do token e fica restrita a essa organização.

Limite de tamanho

Apenas os primeiros 80.000 caracteres são analisados. Isso sempre foi assim; agora o resultado informa isso a você. Quando truncated é true, o texto além de processed_chars nunca foi examinado — não trate a resposta como um tarjamento da entrada inteira. Envie o restante em uma chamada seguinte.

Filtragem por tipo

types aceita somente estes valores:

name, email, phone, ssn, account, address, financial, confidential, url, username

⚠️ Alteração incompatível (agosto de 2026). Antes, types aceitava qualquer string. Agora aceita somente os valores acima, e qualquer outro — "emails", "PII", "credit-card" ou uma capitalização diferente como "EMAIL" — retorna um erro de validação.

Isso substitui uma falha silenciosa por uma falha explícita. Um valor não reconhecido costumava não corresponder a nada, de modo que a ferramenta não tarjava nada e retornava o seu texto original como redacted_text dentro de uma resposta bem-sucedida. Se você passa types, mapeie seus valores para a lista acima. Chamadas que omitem types não são afetadas.

Um tipo de entidade é tarjado mesmo quando você não o solicitou. Se o modelo de tarjamento rotular algo com um tipo que não conseguimos reconhecer, essa entidade é tarjada mesmo assim, em vez de descartada — não conseguimos provar que ela está fora do que você solicitou, e deixar PII no texto é o erro mais grave. Quando isso acontece:

  • filter_exact é false (é true sempre que o filtro foi aplicado exatamente),
  • unclassified_redacted_count informa quantas entidades foram afetadas, e
  • unclassified_types lista os rótulos envolvidos.

As entidades que você filtrou deliberadamente são contadas separadamente, em filtered_out_count.

Requisitos: um plano pago e os recursos de IA da sua organização ativados (ativados por padrão; um administrador da organização pode desativá-los em Configurações → IA e Integrações). As chamadas também são recusadas quando sua organização atinge o limite diário de uso de IA ou enquanto o Waafir mantém o recurso pausado; a mensagem de erro indica qual é o caso.

redact_file

Analisa um documento inteiro em uma sala de dados em busca de PII. Esta ferramenta apenas analisa — o documento não é alterado, e a visualização dele não muda para ninguém. A análise é assíncrona; consulte redact_file_status.

Entradas

CampoTipoObrigatórioDescrição
file_idstringsimO UUID do arquivo.
override_redactedbooleannãoAnalisa novamente um documento que já foi tarjado. Sem ele, um arquivo já tarjado é recusado.

Saída

{ file_id, job_id, status: "analysis_started", applied: false,
  review_required: true, review_with, apply_via }

Não há opção auto_apply, por design — veja a observação no início desta página. Arquivos de imagem não são suportados.

Requisitos: um PAT com escopo write, participação na equipe da transação da sala de dados, um plano pago e os recursos de IA da sua organização ativados (ativados por padrão; um administrador da organização pode desativá-los em Configurações → IA e Integrações).

Um arquivo que ainda está sendo verificado. Se o arquivo for um novo envio ou uma nova versão que o Waafir ainda não terminou de verificar, redact_file e redact_apply respondem UNAVAILABLE com error.reason: "ACTIVATION_PENDING" e a mensagem This file is still being checked. Try again shortly. Nada é analisado nem aplicado; chame de novo após uma breve espera.

redact_file_status

Verifica uma análise de tarjamento de documento.

Entradas

CampoTipoObrigatórioDescrição
file_idstringsimO UUID do arquivo.

Saída

{ file_id, status, entity_count?, applied: false, apply_via }
  • status — um de idle, analyzing, applying, review_ready, completed, failed, error. applying e completed descrevem um tarjamento sendo aplicado na interface do Waafir por uma pessoa — você não pode chegar a esses estados pelo MCP, mas os verá se alguém aprovar a revisão enquanto você estiver consultando.
  • entity_count — quantas entidades de PII a análise propôs, depois que a revisão estiver pronta.
  • applied é sempre false: a aprovação e a aplicação do tarjamento acontecem na interface do Waafir.

Trate um status não reconhecido como "continue consultando", e não como um erro. Os estados terminais são mantidos apenas por pouco tempo antes de o marcador do job ser removido, então quem consulta tarde vê idle (ou um review_ready reconstruído) em vez do estado que estava aguardando — e idle significa "nenhum job em andamento", não "nada jamais aconteceu". Consulte até obter o estado desejado, com um prazo limite, em vez de afirmar que o valor pertence a uma lista fixa.

redact_history

A análise de tarjamento mais recente de um arquivo, como contagens por tipo de entidade. O texto tarjado em si nunca é retornado.

  • Escopo: read. Membros da equipe da transação, em um arquivo cujo conteúdo possam ler.
  • Entradas: file_id (obrigatório).
  • Saída: { file_id, analysis }. analysis é { history_id, analysed_at, entities: { total, by_type } }, ou null quando o arquivo nunca foi analisado.

redact_list_terms

Os termos de tarjamento de uma sala de dados: expressões sempre tarjadas (always) e expressões nunca tarjadas (never).

  • Escopo: read. Membros da equipe da transação.
  • Entradas: dataroom_id (obrigatório).
  • Saída: { terms }, cada um { id, term, kind, created_at }.

redact_add_term

Adiciona um termo a uma sala de dados. Ele se aplica ao próximo tarjamento de um arquivo da sala e não altera nenhum arquivo agora.

  • Escopo: write. Membros da equipe da transação, em um plano pago.
  • Entradas: dataroom_id, term (ambos obrigatórios); kind (always ou never, padrão always).
  • Saída: { term }.

redact_remove_term

Remove um termo de uma sala de dados. Não altera nenhum arquivo agora; adicionar o termo novamente desfaz a remoção.

  • Escopo: write. Membros da equipe da transação.
  • Entradas: dataroom_id, term_id (ambos obrigatórios).
  • Saída: { removed, term_id }.

redact_revert

Desfaz o tarjamento de um arquivo. Todos os leitores, incluindo os investidores, voltam a receber o documento original imediatamente. A versão tarjada é mantida, para que possa ser aplicada novamente.

  • Escopo: write. Membros da equipe da transação, em um arquivo que possam editar.
  • Entradas: file_id (obrigatório); confirm_token.
  • Duas etapas. Sem confirm_token, nada muda e você recebe uma prévia e um token. Chame novamente com os mesmos argumentos e o token para reverter.
  • Um arquivo que não está tarjado é recusado (409). O mesmo vale para um arquivo com uma análise ou aplicação definitiva em execução (409): você é avisado já na prévia, de modo que nenhum token é emitido para uma reversão que não pode ser executada, e a verificação é feita novamente quando você confirma.

redact_apply

Aplica a análise mais recente de um arquivo feita por redact_file, menos os tipos de entidade que você excluir, mais os termos de tarjamento obrigatório da sala de dados. Todos os leitores, incluindo os investidores, passam então a receber o documento tarjado. redact_revert desfaz a aplicação.

  • Escopo: write. Membros da equipe da transação, em um plano pago, em um arquivo cujo conteúdo possam ler.
  • Entradas: file_id (obrigatório); exclude_types; confirm_token.
  • Duas etapas. Sem confirm_token, nada muda e você recebe uma prévia (os alvos contados por tipo, nunca o texto) e um token. Chame novamente com os mesmos argumentos e o token para iniciar a aplicação definitiva. Se a análise, o arquivo, os termos da sala ou os alvos tiverem mudado nesse intervalo, a chamada é recusada e você gera a prévia novamente.
  • Com a IA desativada para a sua organização, somente os termos de tarjamento obrigatório salvos na sala podem ser aplicados, como no Waafir.