Skip to main content

Instruction Sets

Overview​

Instruction sets let you save and reuse translation instructions. Instead of passing the same instructions string with every request, create a named set once and reference it by ID.

This is useful for enforcing consistent style rules across your application: formality, brand name handling, tone of voice, or domain-specific terminology guidelines.

Quick example​

Create an instruction set:

curl -X POST https://api.langbly.com/v2/instruction-sets \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce formal Dutch",
    "instructions": "Use formal Dutch (u/uw). Keep product names and brand names in English. Use comma as decimal separator. Format prices as €X,XX."
  }'

Use it in translations:

{
  "q": "Add to cart",
  "target": "nl",
  "instructionSetId": "your-set-id-here"
}

API endpoints​

Create instruction set​

POST /v2/instruction-sets

Request body:

{
  "name": "E-commerce formal Dutch",
  "instructions": "Use formal Dutch (u/uw). Keep brand names in English."
}

Fields:

  • name (required): display name, max 100 characters
  • instructions (required): the translation instructions, max 2,000 characters

List instruction sets​

GET /v2/instruction-sets

Response:

{
  "instructionSets": [
    {
      "id": "abc-123",
      "name": "E-commerce formal Dutch",
      "instructions": "Use formal Dutch (u/uw)...",
      "createdAt": "2026-02-26T12:00:00Z",
      "updatedAt": "2026-02-26T12:00:00Z"
    }
  ]
}

Get single instruction set​

GET /v2/instruction-sets/:id

Update instruction set​

PATCH /v2/instruction-sets/:id

Request body (all fields optional):

{
  "name": "Updated name",
  "instructions": "Updated instructions"
}

Delete instruction set​

DELETE /v2/instruction-sets/:id

Using in translations​

Reference a saved instruction set by adding instructionSetId to your translate request:

{
  "q": "Your order has been shipped",
  "target": "nl",
  "instructionSetId": "abc-123"
}

Priority: if you provide both instructions (inline) and instructionSetId, the inline instructions take precedence. The instruction set is only used when no inline instructions are provided.

Limits​

  • Maximum 100 instruction sets per account
  • Instructions text: max 2,000 characters per set
  • Name: max 100 characters