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:

http
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEY

This request has no body. To provide feedback directly:

http
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY
json
{
  "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:

json
{ "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 #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
Query parameterMeaning
engineIdsRestrict to selected engines.
targetLocalesLocale scopes, including * for guidance that applies across locales.
statusesPending, Applied, or Dismissed; defaults to Pending.
idsRetrieve selected proposal IDs.
limitInteger from 1 to 100; defaults to 25.
cursorOpaque 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:

FieldMeaning
id, organizationId, engineIdProposal identity and ownership.
targetLocaleLocale scope of the proposed change.
changeTyped change, described below.
reasoningExplanation for the proposal.
sourcesEvidence references such as a scorer review, human edit, or work item.
statusObject whose type is Pending, Applied, or Dismissed.
destinationGuidance set receiving the change, or null when unavailable.
createdAt, updatedAtISO 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.typeContent
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, nullable description, and nonTranslatable.
UpdateGlossaryTermtermId, nullable glossaryId, and the supplied replacement fields.
AddRulename, text, and targetLocale.
UpdateRuleruleId and the supplied name, text, or targetLocale.
AddBrandVoiceVariationtargetLocale and text.
UpdateBrandVoiceVariationvariationId 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 #

http
POST /v2/engine-suggestions/:id/apply
http
POST /v2/engine-suggestions/:id/dismiss

Both 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.