Dialog Sessions¶

Build translation and content creation briefings through an interactive conversation. The dialog agent guides users through setting up all parameters (languages, tone, glossary, instructions) before creating a job.

Overview¶

A dialog session is a multi-turn conversation that produces a fully configured translation or content creation briefing. Instead of filling out a form, users describe what they need in natural language.

Session lifecycle:

Create a session with initial context (mode, text, language)
Send messages — the agent asks clarifying questions and builds the briefing
Preview the briefing (optional) to check completeness
Confirm to create a job from the finalized briefing
Cancel if no longer needed

Sessions expire after 24 hours of inactivity.

POST /v1/dialog-sessions¶

Start a new dialog session.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK

Request Body¶

Field	Type	Required	Default	Description
`mode`	`string`	yes	--	`"translation"` or `"creation"`.
`language`	`string`	no	`null`	UI language hint for the agent.
`text`	`string`	no	`null`	Initial text to translate (translation mode).
`input_material`	`object`	no	`null`	Initial product data (creation mode).
`context.source_lang`	`string`	no	`null`	Pre-set source language.
`context.target_lang`	`string`	no	`null`	Pre-set target language.
`context.glossary_id`	`string`	no	`null`	Pre-select a glossary.
`context.glossary_ids`	`string[]`	no	`null`	Pre-select multiple glossaries.
`context.style_ref_id`	`string`	no	`null`	Pre-select a style reference.
`context.preset_id`	`string`	no	`null`	Pre-select a user preset.
`file_name`	`string`	no	`null`	Attached file name.
`file_type`	`string`	no	`null`	Attached file MIME type.
`file_preview`	`string`	no	`null`	File content preview (max 1,000 chars).

Request Example¶

{
  "mode": "translation",
  "text": "Unsere Produkte stehen für höchste Qualität und Innovation.",
  "context": {
    "source_lang": "de",
    "target_lang": "en"
  }
}

Response (200)¶

{
  "session_id": "dialog_a1b2c3d4",
  "status": "active",
  "phase": 1,
  "message": {
    "role": "assistant",
    "content": "I see you want to translate a German text to English. What domain is this for? (e.g., marketing, legal, technical)",
    "timestamp": "2026-04-02T10:30:00Z",
    "actions": [
      { "action": "set_domain", "label": "Marketing", "payload": { "domain": "marketing" } },
      { "action": "set_domain", "label": "Legal", "payload": { "domain": "legal" } }
    ]
  }
}

Errors¶

Status	Description
`401`	Invalid or missing API key.
`429`	Monthly session limit or max parallel sessions reached.

POST /v1/dialog-sessions/{session_id}/messages¶

Send a user message and receive the agent's response as a Server-Sent Events (SSE) stream.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK Content-Type: text/event-stream

Request Body¶

Field	Type	Required	Description
`message`	`string`	yes	User message (max 10,000 characters).

SSE Event Types¶

Event type	Data	Description
`token`	`{"text": "..."}`	Incremental text token from agent.
`briefing_update`	`{"field": "...", "value": "..."}`	A briefing field was updated.
`phase`	`{"phase": 2}`	Dialog advanced to a new phase.
`actions`	`{"actions": [...]}`	Suggested quick-action buttons.
`warning`	`{"message": "..."}`	Domain-specific warning (e.g., missing glossary).
`done`	`{"message": {...}}`	Final assembled message with full content.
`error`	`{"message": "..."}`	Error during processing.

Examples¶

JavaScriptPython

const response = await fetch(
  `https://app.falara.io/api/v1/dialog-sessions/${sessionId}/messages`,
  {
    method: "POST",
    headers: {
      "X-API-Key": FALARA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "This is a marketing text, formal tone" }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // Parse SSE events
  for (const line of text.split("\n")) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      console.log(event);
    }
  }
}

import requests
import json

response = requests.post(
    f"https://app.falara.io/api/v1/dialog-sessions/{session_id}/messages",
    headers={"X-API-Key": FALARA_API_KEY},
    json={"message": "This is a marketing text, formal tone"},
    stream=True,
)

for line in response.iter_lines():
    if line and line.startswith(b"data: "):
        event = json.loads(line[6:])
        if event.get("type") == "token":
            print(event["data"]["text"], end="", flush=True)
        elif event.get("type") == "done":
            print("\n--- Done ---")

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Not the session owner.
`404`	Session not found.
`409`	Session is not active (already confirmed or cancelled).
`422`	Potential prompt injection detected.
`429`	Message limit reached — please confirm or cancel.

GET /v1/dialog-sessions/{session_id}¶

Get full session details including conversation history.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK

Response (200)¶

{
  "session_id": "dialog_a1b2c3d4",
  "status": "active",
  "mode": "translation",
  "phase": 2,
  "messages": [
    {
      "role": "assistant",
      "content": "What domain is this text for?",
      "timestamp": "2026-04-02T10:30:00Z"
    },
    {
      "role": "user",
      "content": "Marketing, formal tone please",
      "timestamp": "2026-04-02T10:30:15Z"
    }
  ],
  "message_count": 4,
  "cost_eur": 0.02,
  "created_at": "2026-04-02T10:30:00Z",
  "expires_at": "2026-04-03T10:30:00Z"
}

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Not the session owner.
`404`	Session not found.

GET /v1/dialog-sessions/{session_id}/briefing-preview¶

Preview the current briefing state without confirming. Useful for showing a summary before the user commits.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK

Response (200)¶

{
  "briefing_json": {
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Unsere Produkte stehen für höchste Qualität.",
    "domain": "marketing",
    "tone": "formal"
  },
  "completeness": 0.8,
  "missing_fields": ["glossary_id"],
  "warnings": []
}

Field	Type	Description
`briefing_json`	`object`	Current partial briefing state.
`completeness`	`float`	Score from 0 to 1 (1 = ready to confirm).
`missing_fields`	`string[]`	Required fields that are still empty.
`warnings`	`string[]`	Domain-specific warnings (e.g., "Legal domain: consider adding a glossary").

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Not the session owner.
`404`	Session not found.

POST /v1/dialog-sessions/{session_id}/confirm¶

Finalize the briefing and create a translation or content creation job.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK

Request Body¶

Field	Type	Required	Default	Description
`save_as_template`	`boolean`	no	`false`	Save this briefing as a reusable template.
`template_name`	`string`	no	`null`	Name for the saved template.

Response (200)¶

{
  "session_id": "dialog_a1b2c3d4",
  "status": "confirmed",
  "job_id": "job_550e8400-...",
  "job_status": "queued",
  "template_id": null
}

Idempotent

Confirming an already-confirmed session returns the existing job ID without creating a duplicate.

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Not the session owner.
`404`	Session not found.
`409`	Session is not active (already confirmed or cancelled).
`422`	Briefing is incomplete — required fields are missing.

POST /v1/dialog-sessions/{session_id}/cancel¶

Cancel an active session. No job is created.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK

Response (200)¶

{
  "session_id": "dialog_a1b2c3d4",
  "status": "cancelled"
}

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Not the session owner.
`404`	Session not found.
`409`	Session is not active (already confirmed or cancelled).

PATCH /v1/dialog-sessions/{session_id}/metadata¶

Update file metadata on an active session.

Authentication

Header: X-API-Key: your_api_key or Authorization: Bearer <JWT>

Status: 200 OK

Request Body¶

Field	Type	Required	Description
`file_name`	`string`	no	File name to attach.
`file_type`	`string`	no	MIME type of the file.
`file_preview`	`string`	no	Content preview (max 1,000 chars).

Response (200)¶

{ "status": "ok" }

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Not the session owner.
`404`	Session not found.
`409`	Session is not active.