Scriberr/docs/api/chat.md

Chat With Transcripts API

Chat routes live under /api/v1/chat and require the same bearer token or API key authentication as the rest of the v1 API.

Response Shapes

Collections use:

{ "items": [], "next_cursor": null }

Context source responses expose state and metadata only. They do not include raw transcript text, local paths, provider metadata, or compacted snapshot bodies.

Important context fields:

• status: active, disabled, compacting, compacted, or failed
• compaction_status: persisted compaction lifecycle state
• has_plain_text_snapshot: whether the backend has a stable plaintext snapshot
• has_compacted_snapshot: whether the source is currently using compacted context
• tokens_estimated: approximate context size for UI budgeting displays

Assistant message responses keep final content and reasoning separate:

{
  "id": "chatmsg_...",
  "role": "assistant",
  "content": "Final Markdown answer.",
  "reasoning_content": "Provider reasoning text.",
  "status": "completed",
  "prompt_tokens": 1200,
  "completion_tokens": 240,
  "reasoning_tokens": 80,
  "total_tokens": 1520
}

content is the final Markdown body suitable for read-only rendering. reasoning_content is never mixed into content.

Streaming Events

POST /api/v1/chat/sessions/{session_id}/messages:stream returns text/event-stream.

Every run-scoped event includes session_id, run_id, and message_id when applicable.

Event names:

• chat.run.started
• chat.message.created
• chat.delta.reasoning
• chat.delta.content
• chat.run.completed
• chat.run.failed

Delta payloads:

{
  "session_id": "chat_...",
  "run_id": "chatrun_...",
  "message_id": "chatmsg_...",
  "delta": "partial text"
}

Completion payload:

{
  "session_id": "chat_...",
  "run_id": "chatrun_...",
  "message_id": "chatmsg_...",
  "status": "completed",
  "assistant_message": {
    "id": "chatmsg_...",
    "role": "assistant",
    "content": "Final Markdown answer.",
    "reasoning_content": "Reasoning text.",
    "status": "completed"
  },
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 240,
    "reasoning_tokens": 80,
    "total_tokens": 1520
  }
}

Errors use the standard envelope before streaming starts. Provider failures after streaming starts are emitted as chat.run.failed with a sanitized error string.