API de sugerencias del motor

Los comentarios sobre tus traducciones rara vez llegan con un clic en un panel. Suelen aparecer como una línea en tu herramienta de soporte, una nota de una persona revisora o una fila en tu cola de control de calidad: "deja de traducir el nombre del producto", "usa el registro formal en alemán". La API de sugerencias del motor convierte ese texto libre en cambios en el 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 funcionalidad del panel. Allí, las sugerencias se generan automáticamente cuando tus evaluadores de IA dan una puntuación baja a una traducción; aquí, la señal la aportas tú en forma de texto. En ambos casos, el resultado es el mismo: sugerencias pendientes para que las revises y las apliques.

El flujo se divide en dos partes. La generación es asíncrona: envías feedback y la plataforma razona sobre ello en segundo plano, dejando sugerencias pendientes en el motor. La revisión es síncrona: consultas las sugerencias pendientes, lees lo que propone cada una y aplicas o descartas una por una. 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 feedback#

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 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 ha aceptado 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 respecto a lo que ya existe y guarda todo lo que proponga. Es perfectamente posible que una ejecución no proponga nada (porque el feedback era impreciso o porque el motor ya lo cubre). Consulta los resultados enumerando las sugerencias del motor unos instantes después.

Enumerar las sugerencias pendientes#

GET /engines/:id/suggestions

Devuelve las sugerencias del motor: el resultado de cualquier ejecución de generación, ya se haya activado 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 tan sencillo: el cambio propuesto queda totalmente 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. Se trata de una escritura determinista de payload que ya viste en la lista: no hay una segunda llamada a la IA, así que lo que revisaste es exactamente lo que se escribe. Una sugerencia add_* crea un nuevo elemento de glosario, una instrucción o una voz de marca; una sugerencia update_* modifica 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 normal del glosario, una instrucción o una voz de marca: puedes abrirla, editarla o eliminarla como cualquier otra.

Descartar una sugerencia#

POST /engine-suggestions/:id/dismiss

Descarta una sugerencia que no quieres, la marca como dismissed y deja el motor intacto. Úsalo cuando una propuesta no encaje con tu producto: el motor no cambia y la sugerencia deja de mostrarse 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, de principio a fin#

Los cuatro endpoints forman un ciclo que puedes controlar íntegramente desde código: envía feedback, revisa lo que se ha propuesto y confirma las ediciones con las que estés de acuerdo.

Siguientes pasos#