Style References

Style references let you store tone, voice, and style guidelines as reference texts. When attached to a translation job, the Translator agent matches the style of the reference — producing translations that sound like your brand, not a generic output.

Common use cases:

• Brand voice guidelines
• Marketing tone samples
• Editorial style sheets
• Industry-specific writing conventions

---

Create a Style Reference

POST /v1/style-references

Store a new style reference from plain text.

Authentication: X-API-Key header Status: 201 Created

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/style-references \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Voice",
    "description": "Casual, confident brand voice for B2C content",
    "content": "Our products don'\''t just work — they delight. We speak to our customers like friends, not corporations. Short sentences. Active voice. Enthusiasm without exclamation marks."
  }'

import requests

resp = requests.post(
    "https://app.falara.io/v1/style-references",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Marketing Voice",
        "description": "Casual, confident brand voice for B2C content",
        "content": (
            "Our products don't just work — they delight. "
            "We speak to our customers like friends, not corporations. "
            "Short sentences. Active voice. Enthusiasm without exclamation marks."
        ),
    },
)
style_ref = resp.json()

const resp = await fetch("https://app.falara.io/v1/style-references", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Marketing Voice",
    description: "Casual, confident brand voice for B2C content",
    content:
      "Our products don't just work — they delight. " +
      "We speak to our customers like friends, not corporations. " +
      "Short sentences. Active voice. Enthusiasm without exclamation marks.",
  }),
});
const styleRef = await resp.json();

Request Body

Field	Type	Required	Description
name	string	yes	Human-readable reference name
description	string	no	Optional description of the style
content	string	yes	Reference text (max 50,000 characters)

Response 201 Created

{
  "id": "sref_mktg_7x9k2",
  "name": "Marketing Voice",
  "description": "Casual, confident brand voice for B2C content",
  "content_preview": "Our products don't just work — they delight. We speak to our customers like friends, not corporations. Short sentences. Active voice. Enthusiasm without exclamation marks.",
  "created_at": "2026-03-15T10:30:00Z"
}

Field	Type	Description
id	string	Unique style reference ID
name	string	Reference name
description	string	Description (or null)
content_preview	string	First 200 characters of the content
created_at	string	ISO 8601 creation timestamp

---

List Style References

GET /v1/style-references

Retrieve all style references associated with the current API key. Returns name, description, and a content preview -- not the full content.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/style-references \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/style-references",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
references = resp.json()

const resp = await fetch("https://app.falara.io/v1/style-references", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const references = await resp.json();

Response 200 OK

[
  {
    "id": "sref_mktg_7x9k2",
    "name": "Marketing Voice",
    "description": "Casual, confident brand voice for B2C content",
    "content_preview": "Our products don't just work — they delight...",
    "created_at": "2026-03-15T10:30:00Z"
  }
]

---

Get a Style Reference

GET /v1/style-references/{style_ref_id}

Retrieve a single style reference including the full content.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/style-references/sref_mktg_7x9k2 \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
full_ref = resp.json()
print(full_ref["content"])

const resp = await fetch(
  "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const fullRef = await resp.json();

Response 200 OK

{
  "id": "sref_mktg_7x9k2",
  "name": "Marketing Voice",
  "description": "Casual, confident brand voice for B2C content",
  "content": "Our products don't just work — they delight. We speak to our customers like friends, not corporations. Short sentences. Active voice. Enthusiasm without exclamation marks.",
  "created_at": "2026-03-15T10:30:00Z"
}

---

Update a Style Reference

PUT /v1/style-references/{style_ref_id}

Update the name or description of an existing style reference.

Authentication: X-API-Key header Status: 200 OK

Content Is Immutable

The content field cannot be changed after creation. To update the reference text, delete the existing reference and create a new one.

cURLPythonJavaScript

curl -X PUT https://app.falara.io/v1/style-references/sref_mktg_7x9k2 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Voice v2",
    "description": "Updated casual brand voice for all B2C channels"
  }'

resp = requests.put(
    "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Marketing Voice v2",
        "description": "Updated casual brand voice for all B2C channels",
    },
)

const resp = await fetch(
  "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Marketing Voice v2",
      description: "Updated casual brand voice for all B2C channels",
    }),
  }
);

Request Body

Field	Type	Required	Description
name	string	no	New reference name
description	string	no	New description

---

Delete a Style Reference

DELETE /v1/style-references/{style_ref_id}

Permanently delete a style reference.

Authentication: X-API-Key header Status: 204 No Content

cURLPythonJavaScript

curl -X DELETE https://app.falara.io/v1/style-references/sref_mktg_7x9k2 \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.delete(
    "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
assert resp.status_code == 204

await fetch(
  "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);

---

Using Style References in Jobs

To apply a style reference when creating a translation job, pass the reference text in the style_reference field of any job creation request.

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Unsere Produkte begeistern. Wir setzen auf Qualitat und Klarheit.",
    "style_reference": "Our products don'\''t just work — they delight. We speak to our customers like friends, not corporations. Short sentences. Active voice. Enthusiasm without exclamation marks."
  }'

# Fetch the stored reference content
ref = requests.get(
    "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
    headers={"X-API-Key": "YOUR_API_KEY"},
).json()

# Pass the content to a translation job
resp = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Unsere Produkte begeistern.",
        "style_reference": ref["content"],
    },
)

// Fetch the stored reference content
const refResp = await fetch(
  "https://app.falara.io/v1/style-references/sref_mktg_7x9k2",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const ref = await refResp.json();

// Pass the content to a translation job
const resp = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Unsere Produkte begeistern.",
    style_reference: ref.content,
  }),
});

Inline Text, Not Reference ID

The style_reference field accepts inline text, not a reference ID. Copy the content from your stored reference, or fetch it via GET /v1/style-references/{id} and pass the content field value directly.

---

Errors

Status	Reason
401 Unauthorized	Missing or invalid API key
404 Not Found	Style reference ID does not exist
422 Unprocessable Entity	Validation error (e.g. content exceeds 50,000 characters, missing required field)