API de Sugestões do engine

O feedback sobre suas traduções raramente chega como um clique no dashboard. Ele aparece em uma linha da sua ferramenta de suporte, em uma observação de um revisor, em um item da sua própria fila de QA — "pare de traduzir o nome do produto", "use o registro formal em alemão". A API de Sugestões do engine transforma esse texto livre em mudanças no engine via código: envie o feedback como texto, a plataforma interpreta o contexto e devolve edições concretas e estruturadas para o glossário, as instruções ou a voz da marca do seu engine, prontas para você aplicar.

Esta é a contraparte programática do recurso no dashboard. Lá, as sugestões são geradas automaticamente quando seus avaliadores de IA atribuem uma pontuação baixa a uma tradução; aqui, você fornece o sinal em texto. Em ambos os casos, a saída é a mesma — sugestões pendentes para você revisar e aplicar.

O fluxo se divide em duas partes. A geração é assíncrona — você envia o feedback e a plataforma o processa em segundo plano, deixando sugestões pendentes no engine. A revisão é síncrona — você lista as sugestões pendentes, lê o que cada uma propõe e aplica ou descarta cada uma. Esta página cobre as duas etapas. Para a experiência no dashboard — geração automática a partir de baixas pontuações de revisão, a aba de Sugestões e notificações — veja Sugestões do engine.

Gerar a partir de feedback#

POST /engines/:id/suggestions/from-text

Envie uma descrição em texto simples do que o engine está errando. A plataforma analisa esse texto junto com a configuração atual do engine e propõe edições atômicas — sem repetir algo que o engine já tenha. A geração acontece de forma assíncrona, então a chamada retorna assim que o trabalho é aceito, e não quando as sugestões ficam prontas.

const response = await fetch(
  `https://api.lingo.dev/engines/${engineId}/suggestions/from-text`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Our German (de-DE) translations keep using the informal 'du'. For our B2B audience they must always use the formal 'Sie'.",
    }),
  },
);

const { enqueued } = await response.json();
console.log(enqueued); // true – generation accepted, running in the background

{ "enqueued": true }

enqueued: true significa que a plataforma aceitou o trabalho, não que já existam sugestões. A geração é uma etapa em segundo plano: ela lê seu texto, analisa a configuração, remove duplicatas em relação ao que já existe e persiste o que propuser. Uma execução pode, legitimamente, não propor nada (porque o feedback era vago ou o engine já cobre aquilo). Para ver os resultados, liste as sugestões do engine alguns instantes depois.

Listar sugestões pendentes#

GET /engines/:id/suggestions

Retorna as sugestões do engine — resultado de qualquer execução de geração, seja disparada por texto, pelo botão manual ou automaticamente a partir de baixas pontuações de revisão. Cada item é uma edição proposta com a respectiva justificativa.

[
  {
    "id": "egs_A1b2C3d4E5f6G7h8",
    "ownerOrganizationId": "org_X1y2Z3a4B5c6D7e8",
    "ownerEngineId": "eng_X1y2Z3a4B5c6D7e8",
    "actionType": "add_instruction",
    "targetKind": "instruction",
    "targetId": null,
    "targetLocale": "de-DE",
    "payload": { "instruction": "Use the formal 'Sie' form in all German translations; never use the informal 'du'." },
    "reasoning": "Feedback states the B2B audience requires formal address, but the engine has no instruction enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

O payload é o detalhe que torna a aplicação barata: a mudança proposta já sai totalmente estruturada na geração, então aplicar é uma simples gravação, não mais uma rodada de IA. A decisão é sua; a plataforma não reavalia nada.

Aplicar uma sugestão#

POST /engine-suggestions/:id/apply

Grava a mudança proposta no engine e marca a sugestão como applied. Trata-se de uma gravação determinística do payload que você já viu na lista — não há uma segunda chamada de IA, então o que você revisou é exatamente o que será gravado. Uma sugestão add_* cria um novo item de glossário, instrução ou voz da marca; uma sugestão update_* altera a entrada existente indicada por targetId.

const response = await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/apply`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);

const applied = await response.json();
console.log(applied.status);          // "applied"
console.log(applied.appliedTargetId); // "ins_…" – the instruction it just created

A resposta traz a sugestão no estado applied, com appliedTargetId agora apontando para a entrada real do engine que foi criada ou atualizada. A partir daí, essa entrada passa a ser um item comum de glossário, instrução ou voz da marca — você pode abrir, editar ou excluir como qualquer outro.

Descartar uma sugestão#

POST /engine-suggestions/:id/dismiss

Descarta uma sugestão que você não quer, marcando-a como dismissed e deixando o engine inalterado. Use isso quando uma proposta não fizer sentido para o seu produto — o engine não muda, e a sugestão deixa de aparecer como pendente.

await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/dismiss`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);
// The suggestion is now "dismissed"; nothing was written to the engine.

O ciclo completo#

Os quatro endpoints formam um ciclo que você pode controlar inteiramente por código: envie o feedback, veja o que foi proposto e confirme as edições com as quais concordar.

Próximos passos#