Async Provisioning API

Create a fully configured localization engine from your existing content. Submit links to your website, style guides, or raw text — an AI agent crawls the sources, extracts brand voice, glossary terms, and translation instructions, then applies them to a new engine. One POST returns a 202 in milliseconds. The configured engine is ready to use when the job completes.

On this page

• Authentication
• How it works
• Create a provisioning job
• Source types
• Output summary
• Webhooks
• WebSocket

Authentication#

All provisioning endpoints require API key authentication. Pass your API key in the X-API-Key header. API keys are scoped to an organization and have access to all localization engines within it. See API Keys for details.

How it works#

Create a provisioning job#

POST /jobs/provisioning

Request#

const response = await fetch("https://api.lingo.dev/jobs/provisioning", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LINGO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    engine: {
      name: "Acme Corp Engine",
      description: "Production localization engine for acme.com",
    },
    locales: ["de", "fr", "ja", "es"],
    sources: [
      { type: "link", payload: "https://acme.com/brand-guidelines" },
      { type: "link", payload: "https://acme.com/docs/style-guide" },
      {
        type: "content",
        payload:
          "Brand name 'Acme' is never translated. Use formal tone in German (Sie-form). Product names: AcmeFlow, AcmeSync, AcmeVault — always keep in English.",
      },
    ],
    callbackUrl: "https://your-app.com/webhooks/provisioning",
  }),
});

const { jobId, engineId, status } = await response.json();
// 202 back in milliseconds.
// status: "in_progress" — AI is analyzing your sources.
console.log(engineId); // "eng_X1y2Z3a4B5c6D7e8"

Response (202 Accepted)#

{
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "engineId": "eng_X1y2Z3a4B5c6D7e8",
  "status": "in_progress"
}

When no sources are provided, the engine is created with default model configurations and returned immediately with status: "completed".

Source types#

Each source in the sources array has a type and payload:

Link sources are crawled in parallel and converted to markdown before analysis. Content sources are passed directly to the AI agent.

What the AI extracts#

The AI agent analyzes all sources and creates three types of engine configuration:

Brand voices and instructions use * as the target locale when they apply across all languages. Glossary items are created per locale pair, with non-translatable terms using * to apply globally.

Output summary#

When a provisioning job completes, the output summary reports everything the AI created:

{
  "brandVoices": {
    "count": 3,
    "ids": ["bv_A1b2C3d4", "bv_B2c3D4e5", "bv_C3d4E5f6"]
  },
  "glossaryItems": {
    "count": 12,
    "ids": ["gi_A1b2C3d4", "gi_B2c3D4e5", "..."]
  },
  "instructions": {
    "count": 5,
    "ids": ["ins_A1b2C3d4", "ins_B2c3D4e5", "..."]
  },
  "errors": []
}

Individual item creation failures don't fail the overall job. Failed items appear in the errors array, while successfully created items are applied to the engine.

Webhooks#

When a provisioning job completes or fails, the platform POSTs the result to your callback URL.

Payload#

When the job completes:

{
  "type": "provisioning.completed",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "engineId": "eng_X1y2Z3a4B5c6D7e8",
  "summary": {
    "brandVoices": { "count": 3, "ids": ["bv_A1b2C3d4", "bv_B2c3D4e5", "bv_C3d4E5f6"] },
    "glossaryItems": { "count": 12, "ids": ["gi_A1b2C3d4", "..."] },
    "instructions": { "count": 5, "ids": ["ins_A1b2C3d4", "..."] },
    "errors": []
  }
}

When the job fails:

{
  "type": "provisioning.failed",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "engineId": "eng_X1y2Z3a4B5c6D7e8",
  "error": "All sources failed to crawl. No content available for analysis."
}

Signature verification#

Provisioning webhooks use the same Standard Webhooks signature scheme as localization job webhooks. The three headers (webhook-id, webhook-timestamp, webhook-signature) and HMAC-SHA256 verification process are identical.

Retry behavior#

If your endpoint returns a non-2xx status code or is unreachable, the platform retries with exponential backoff up to 4 attempts. After all retries are exhausted, the webhook is marked as failed. The engine and its configuration are still available — only the notification delivery failed.

WebSocket#

For real-time progress updates, connect a WebSocket to the provisioning job. The platform sends two types of messages: an initial snapshot of the current job state, then progress events as the workflow advances.

GET /jobs/provisioning/:jobId/ws

Message types#

Snapshot (on connect)#

The server immediately sends the current job state from the database:

{
  "type": "provisioning.snapshot",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "status": "in_progress",
  "errorMessage": null
}

If the job has already finished (completed or failed), the server sends the snapshot and closes the connection immediately. This means you can connect at any point — even after the job finishes — and get the final state.

Progress events#

As the workflow runs, the server broadcasts progress events:

{
  "type": "provisioning.progress",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "step": "crawling",
  "detail": "Crawling source URLs..."
}

Example#

import WebSocket from "ws";

const jobId = "pjb_A1b2C3d4E5f6G7h8";
const ws = new WebSocket(
  `wss://api.lingo.dev/jobs/provisioning/${jobId}/ws`,
  { headers: { "X-API-Key": process.env.LINGO_API_KEY } }
);

ws.on("message", (raw) => {
  const event = JSON.parse(raw);

  switch (event.type) {
    case "provisioning.snapshot":
      console.log(`Job status: ${event.status}`);
      break;

    case "provisioning.progress":
      console.log(`${event.step}: ${event.detail}`);
      if (event.step === "completed" || event.step === "failed") {
        ws.close();
      }
      break;
  }
});

Next Steps#