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 #
POST /v2/organizations/:orgId/provisioning/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY{
"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.
| Field | Contract |
|---|---|
engine | Required engine-create object. name must be nonempty; description is optional. It can also carry model configurations, coverage, and pipeline settings. |
kinds | Required object selecting at least one of glossary, ruleset, or brandVoice. Each selected value is {} or { "name": "Nonempty name" }. |
sources | Required 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 #
POST /v2/engines/:engineId/provisioning/jobs
Content-Type: application/jsonTo fill only the kinds for which the engine has no attached set:
{
"kinds": { "_tag": "Empty" },
"sources": [{ "_tag": "Content", "text": "Keep Acme unchanged. Use concise, friendly language." }]
}To request specific new sets:
{
"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.