API de Sugestões do motor

O feedback sobre as suas traduções raramente chega através de um clique num dashboard. Surge numa linha da sua ferramenta de suporte, numa nota de um revisor, numa entrada da sua fila de QA — "deixem de traduzir o nome do produto", "usem registo formal em alemão". A API de Sugestões do motor transforma esse texto livre em alterações ao motor a partir do código: envia o feedback em texto, a plataforma interpreta-o e devolve alterações concretas e estruturadas ao glossário, às instruções ou à voz da marca do seu motor, prontas para aplicar.

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

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

Gerar a partir de feedback#

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

Envie uma descrição em texto simples do que o motor está a fazer mal. A plataforma processa esse texto em conjunto com a configuração atual do motor e propõe alterações atómicas — não voltará a propor algo que o motor já tenha. A geração decorre de forma assíncrona, por isso a chamada devolve resposta assim que o trabalho é aceite, e não quando as sugestões estiverem 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 — lê o seu texto, processa a configuração, elimina duplicados face ao que já existe e persiste tudo o que propuser. Uma execução pode, legitimamente, não propor nada (porque o feedback era vago ou porque o motor já cobre esse caso). Pode ler os resultados listando as sugestões do motor alguns instantes depois.

Listar sugestões pendentes#

GET /engines/:id/suggestions

Devolve as sugestões do motor — o resultado de qualquer execução de geração, quer tenha sido acionada por texto, pelo botão manual ou automaticamente a partir de pontuações baixas de revisão. Cada entrada é uma alteração proposta com a respetiva justificação associada.

[
  {
    "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 simples: a alteração proposta fica totalmente estruturada no momento da geração, pelo que aplicá-la é apenas uma gravação, não outra ronda de IA. A decisão é sua; a plataforma não volta a processar.

Aplicar uma sugestão#

POST /engine-suggestions/:id/apply

Grava a alteração proposta no motor e marca a sugestão como applied. Trata-se de uma gravação determinística do payload que já viu na lista — não há uma segunda chamada à IA, por isso aquilo que reviu é 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 identificada 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 devolve a sugestão no estado applied, com appliedTargetId agora a apontar para a entrada real do motor que foi criada ou atualizada. A partir desse momento, essa entrada passa a ser um item de glossário, instrução ou voz da marca como qualquer outro — pode abri-la, editá-la ou eliminá-la normalmente.

Descartar uma sugestão#

POST /engine-suggestions/:id/dismiss

Elimina uma sugestão de que não precisa, marcando-a como dismissed e deixando o motor inalterado. Use esta opção quando uma proposta não fizer sentido para o seu produto — o motor não é alterado 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, do princípio ao fim#

Os quatro endpoints formam um ciclo único que pode controlar inteiramente a partir do código: fornece feedback, vê o que foi proposto e confirma as alterações com que concorda.

Próximos passos#