Engine Suggestions API

Feedback about your translations rarely arrives as a dashboard click. It is a line in your own support tool, a note from a reviewer, a row in your own QA queue – "stop translating the product name", "use the formal register in German". The Engine Suggestions API turns that free text into engine changes from code: send the feedback as text, the platform reasons over it, and concrete, structured edits to your engine's glossary, instructions, or brand voice come back for you to apply.

This is the programmatic counterpart to the dashboard feature. There, suggestions are generated automatically when your AI Reviewers score a translation low; here, you supply the signal as text. Either way the output is the same – pending suggestions you review and apply.

The flow is two halves. Generation is asynchronous – you hand over feedback and the platform reasons over it in the background, landing pending suggestions on the engine. Review is synchronous – you list the pending suggestions, read what each proposes, and apply or dismiss each one. This page covers both. For the dashboard experience – automatic generation from low review scores, the Suggestions tab, notifications – see Engine Suggestions.

Generate from feedback#

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

Send a plain-text description of what the engine is getting wrong. The platform reasons over that text plus the engine's current configuration, and proposes atomic edits – it will not re-propose something the engine already has. Generation runs asynchronously, so the call returns the moment the work is accepted, not when the suggestions are ready.

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 means the platform accepted the work, not that suggestions exist yet. Generation is one background step – it reads your text, reasons over the config, de-duplicates against what is already there, and persists whatever it proposes. A run can legitimately propose nothing (the feedback was vague, or the engine already covers it). Read the results by listing the engine's suggestions a few moments later.

List pending suggestions#

GET /engines/:id/suggestions

Returns the engine's suggestions – the result of any generation run, whether triggered from text, from the manual button, or automatically from low review scores. Each entry is a proposed edit with its reasoning attached.

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

The payload is the detail that makes applying cheap: the proposed change is fully structured at generation time, so applying it is a plain write, not another round of AI. You decide; the platform does not re-reason.

Apply a suggestion#

POST /engine-suggestions/:id/apply

Writes the proposed change into the engine and marks the suggestion applied. This is a deterministic write of the payload you already saw in the list – there is no second AI call, so what you reviewed is exactly what gets written. An add_* suggestion creates a new glossary item, instruction, or brand voice; an update_* suggestion changes the existing entry named by 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

The response is the suggestion in its applied state, with appliedTargetId now pointing at the real engine entry it created or updated. That entry is an ordinary glossary item, instruction, or brand voice from this point on – open it, edit it, or delete it like any other.

Dismiss a suggestion#

POST /engine-suggestions/:id/dismiss

Drops a suggestion you do not want, marking it dismissed and leaving the engine untouched. Use it when a proposal is wrong for your product – the engine is not changed, and the suggestion stops showing up as pending.

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.

The loop, end to end#

The four endpoints form one cycle you can drive entirely from code: feed in feedback, read what was proposed, and commit the edits you agree with.

Next steps#