Engine suggestions API
Generate proposals from feedback, inspect their changes, and apply or dismiss them explicitly.
Engine suggestions propose changes to glossary terms, rules, and brand-voice variations. Review the proposed content and destination before applying it. Generation adds proposals to the queue; applying a proposal changes the engine's guidance.
Engine Suggestions is listed on the Enterprise plan. The caller also needs access to the engine and the relevant suggestion permissions. See Suggestions in Queue for the dashboard workflow.
All routes below use https://api.lingo.dev and API authentication.
Request generation #
Generate from the engine's collected feedback:
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEYThis request has no body. To provide feedback directly:
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY{
"text": "In German account settings, use Abonnement for subscription. Avoid Mitgliedschaft for this product feature."
}text must contain non-whitespace content and be at most 10,000 characters. This mode generates proposals from the supplied feedback itself, so include the intended correction and the language it applies to.
Both routes return HTTP 200 with:
{ "enqueued": true }This confirms queue submission, not completed generation. List the engine's pending suggestions after processing. Generation can produce no proposals when there is no useful change to make; an immediate empty list does not establish a failed request.
List proposals #
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25| Query parameter | Meaning |
|---|---|
engineIds | Restrict to selected engines. |
targetLocales | Locale scopes, including * for guidance that applies across locales. |
statuses | Pending, Applied, or Dismissed; defaults to Pending. |
ids | Retrieve selected proposal IDs. |
limit | Integer from 1 to 100; defaults to 25. |
cursor | Opaque pagination cursor. |
Repeat array parameters for multiple values. The response contains data and meta.nextCursor; continue with the same filters until nextCursor is null.
Each proposal includes:
| Field | Meaning |
|---|---|
id, organizationId, engineId | Proposal identity and ownership. |
targetLocale | Locale scope of the proposed change. |
change | Typed change, described below. |
reasoning | Explanation for the proposal. |
sources | Evidence references such as a scorer review, human edit, or work item. |
status | Object whose type is Pending, Applied, or Dismissed. |
destination | Guidance set receiving the change, or null when unavailable. |
createdAt, updatedAt | ISO timestamps. |
A destination includes kind (Glossary, Ruleset, or BrandVoice), nullable id, name, and willCreate. Check willCreate to understand whether applying it creates a guidance set. Applied status includes at, nullable by, and nullable target; system-dismissed proposals can include a reason.
Inspect the change #
change.type | Content |
|---|---|
AddGlossaryTerm | sourceLocale, sourceText, targetLocale, targetText, nullable description, and nonTranslatable. |
UpdateGlossaryTerm | termId, nullable glossaryId, and the supplied replacement fields. |
AddRule | name, text, and targetLocale. |
UpdateRule | ruleId and the supplied name, text, or targetLocale. |
AddBrandVoiceVariation | targetLocale and text. |
UpdateBrandVoiceVariation | variationId and the supplied targetLocale or text. |
Update proposals contain only the fields being changed. Check the target record and any shared use of its guidance set before applying a broad change.
Apply or dismiss #
POST /v2/engine-suggestions/:id/applyPOST /v2/engine-suggestions/:id/dismissBoth requests have no body and return the updated proposal. Only pending proposals can be decided. Applying writes the proposed guidance; dismissing leaves that guidance unchanged.
If the target changed or disappeared, applying can return EngineSuggestionConflicts or EngineSuggestionTargetGone. Refresh the proposal and its target before choosing a correction. Repeating a decision on an already decided proposal returns EngineSuggestionNotPending; inspect its state after an uncertain response instead of blindly repeating the write.
Decide several proposals #
Post { "ids": ["FIRST_ID", "SECOND_ID"] } to:
/v2/engine-suggestions/apply-many: 1–25 unique IDs./v2/engine-suggestions/dismiss-many: 1–1,000 unique IDs.
Apply returns applied and failed; dismiss returns dismissed and failed. Each failed entry contains id and a named error. An HTTP success can include individual failures. Successful items are retained when another item fails, so handle each result independently.
Use the revised guidance #
After applying, inspect the engine's glossary, rules, or voice and try representative content. Apply accepted guidance before starting the new job. To update existing translations, deliberately select the content and request a refresh; applying guidance alone is not a retranslation request.