Create a provisioning job

Generate guidance for a new or existing engine and retain its job ID for progress and recovery.

Provisioning runs in the background and starts when the API accepts the request. All routes use https://api.lingo.dev and API authentication.

Create and fill an engine #

http
POST /v2/organizations/:orgId/provisioning/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
json
{
  "engine": { "name": "Acme support", "description": "Customer support content" },
  "kinds": {
    "glossary": { "name": "Product terminology" },
    "ruleset": { "name": "Support writing rules" },
    "brandVoice": { "name": "Support voice" }
  },
  "sources": [
    { "_tag": "Link", "url": "https://example.com/style-guide" },
    { "_tag": "Content", "text": "Use clear, direct sentences. Keep the product name Acme unchanged." }
  ]
}

Replace the example URL with a reachable page containing your guidance, or supply text instead.

FieldContract
engineRequired engine-create object. name must be nonempty; description is optional. It can also carry model configurations, coverage, and pipeline settings.
kindsRequired object selecting at least one of glossary, ruleset, or brandVoice. Each selected value is {} or { "name": "Nonempty name" }.
sourcesRequired nonempty array, at most ten links or text sources.

Engine settings follow the engine-create contract. sourceCoverage and targetCoverage are locale arrays, with [] covering all locales. Omitting modelConfigs seeds the platform's model defaults; [] leaves no pinned model configurations. Configure the engine's models before using it for translation.

The caller needs engine-create permission and permission to create the requested guidance. Engine count, plan features, account credit, and provisioning rate limits can reject the request.

Fill an existing engine #

http
POST /v2/engines/:engineId/provisioning/jobs
Content-Type: application/json

To fill only the kinds for which the engine has no attached set:

json
{
  "kinds": { "_tag": "Empty" },
  "sources": [{ "_tag": "Content", "text": "Keep Acme unchanged. Use concise, friendly language." }]
}

To request specific new sets:

json
{
  "kinds": {
    "_tag": "Requested",
    "glossary": { "name": "Support terminology" },
    "ruleset": {}
  },
  "sources": [{ "_tag": "Link", "url": "https://example.com/support" }]
}

Requested can add a glossary or ruleset alongside existing ones. Provisioning never replaces an attached brand voice. Empty skips kinds already attached, including sets attached while the job is running. Review the per-kind outcomes rather than assuming every request creates all three kinds.

Only one provisioning job can run on an engine at a time. ProvisioningJobRunning (409) includes the existing jobId; follow it before submitting more work. NothingToProvision (409) means none of the requested work can fill the engine in its current state.

Save the response #

Both create routes return HTTP 200 with a provisioning job. Save id and engineId before polling. The initial state is normally status: { "_tag": "Running" }.

Creation does not declare an idempotency header. If a response is lost, inspect running jobs and the engine list before repeating a new-engine request, which can create another engine. Recovery explains those checks and failed-kind retries.