API de sugerencias del motor

Los comentarios sobre tus traducciones casi nunca llegan como un clic en un panel. Llegan como una línea en tu propia herramienta de soporte, una nota de un revisor o una fila en tu propia cola de QA: "dejen de traducir el nombre del producto", "usen el registro formal en alemán". La API de sugerencias del motor convierte ese texto libre en cambios del motor desde código: envías el comentario como texto, la plataforma razona sobre él y te devuelve ediciones concretas y estructuradas para el glosario, las instrucciones o la voz de marca de tu motor, listas para aplicar.

Esta es la contraparte programática de la función del panel. Allí, las sugerencias se generan automáticamente cuando tus AI Reviewers le dan una puntuación baja a una traducción; aquí, tú aportas la señal en texto. En ambos casos, el resultado es el mismo: sugerencias pendientes para que las revises y apliques.

El flujo tiene dos partes. La generación es asíncrona: entregas el comentario y la plataforma razona sobre él en segundo plano, dejando sugerencias pendientes en el motor. La revisión es síncrona: consultas las sugerencias pendientes, lees qué propone cada una y la aplicas o la descartas. Esta página cubre ambas. Para la experiencia en el panel —generación automática a partir de puntuaciones bajas de revisión, la pestaña Suggestions y las notificaciones— consulta Engine Suggestions.

Generar a partir de comentarios#

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

Envía una descripción en texto plano de lo que el motor está haciendo mal. La plataforma razona sobre ese texto junto con la configuración actual del motor y propone ediciones atómicas; no volverá a proponer algo que el motor ya tenga. La generación se ejecuta de forma asíncrona, así que la llamada devuelve respuesta en cuanto se acepta el trabajo, no cuando las sugerencias ya están listas.

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 la plataforma aceptó el trabajo, no que ya existan sugerencias. La generación es un paso en segundo plano: lee tu texto, razona sobre la configuración, elimina duplicados con lo que ya existe y guarda lo que proponga. Es totalmente válido que una ejecución no proponga nada (porque el comentario era vago o porque el motor ya cubre ese caso). Consulta los resultados listando las sugerencias del motor unos momentos después.

Listar sugerencias pendientes#

GET /engines/:id/suggestions

Devuelve las sugerencias del motor: el resultado de cualquier ejecución de generación, ya sea activada desde texto, desde el botón manual o automáticamente a partir de puntuaciones bajas de revisión. Cada entrada es una edición propuesta con su razonamiento asociado.

[
  {
    "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"
  }
]

El payload es el detalle que hace que aplicar sea barato: el cambio propuesto queda completamente estructurado en el momento de la generación, así que aplicarlo es una simple escritura, no otra ronda de IA. Tú decides; la plataforma no vuelve a razonar.

Aplicar una sugerencia#

POST /engine-suggestions/:id/apply

Escribe el cambio propuesto en el motor y marca la sugerencia como applied. Esta es una escritura determinística del payload que ya viste en la lista; no hay una segunda llamada de IA, así que lo que revisaste es exactamente lo que se escribe. Una sugerencia add_* crea un nuevo elemento de glosario, una nueva instrucción o una nueva voz de marca; una sugerencia update_* cambia la 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

La respuesta es la sugerencia en su estado applied, con appliedTargetId apuntando ahora a la entrada real del motor que creó o actualizó. A partir de ese momento, esa entrada es un elemento de glosario, una instrucción o una voz de marca normal: puedes abrirla, editarla o eliminarla como cualquier otra.

Descartar una sugerencia#

POST /engine-suggestions/:id/dismiss

Descarta una sugerencia que no quieres, marcándola como dismissed y dejando el motor intacto. Úsalo cuando una propuesta no sea adecuada para tu producto: el motor no cambia y la sugerencia deja de aparecer como pendiente.

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.

El ciclo completo#

Los cuatro endpoints forman un ciclo completo que puedes manejar enteramente desde código: envías comentarios, lees lo que se propuso y confirmas las ediciones con las que estás de acuerdo.

Siguientes pasos#