Skip to main content
The Co-writer module provides AI assistance for writing. It can rewrite, shorten, or expand text using knowledge base or web sources; auto-annotate important terms; export content as Markdown; and convert notes into narrated audio scripts.

​
Endpoints

MethodPathDescription
POST/api/v1/co_writer/editEdit text with an AI instruction
POST/api/v1/co_writer/automarkAuto-annotate text
GET/api/v1/co_writer/historyList all edit operations
GET/api/v1/co_writer/history/{operation_id}Get a single operation
GET/api/v1/co_writer/tool_calls/{operation_id}Get tool call details for an operation
POST/api/v1/co_writer/export/markdownExport content as a Markdown file
POST/api/v1/co_writer/narrateGenerate a narration script with optional TTS audio
POST/api/v1/co_writer/narrate/scriptGenerate a narration script only
GET/api/v1/co_writer/tts/statusCheck TTS service availability
GET/api/v1/co_writer/tts/voicesList available TTS voices

​
POST /api/v1/co_writer/edit

Edit a piece of text according to an instruction. The agent can optionally query a knowledge base or the web to ground its edits.

​
Request body

​
text
string
required
The text to edit.
​
instruction
string
required
Natural-language instruction describing the desired edit, e.g. "Make this more concise".
​
action
string
default:"\"rewrite\""
Edit action. One of "rewrite", "shorten", or "expand".
​
source
string
Optional grounding source. One of "rag" (knowledge base) or "web". Omit to edit without external context.
​
kb_name
string
Knowledge base to use when source is "rag".

​
Response

​
edited_text
string
The edited version of the input text.
​
operation_id
string
Unique identifier for this edit operation. Use with the history endpoints.
curl -X POST http://localhost:8001/api/v1/co_writer/edit \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Gradient descent is a method used to minimize a function by iteratively moving in the direction of steepest descent.",
    "instruction": "Simplify this for a high school student.",
    "action": "rewrite"
  }'

{
  "edited_text": "Gradient descent is a way to find the lowest point of a mathematical function by taking small steps downhill each time.",
  "operation_id": "op_abc123"
}

​
POST /api/v1/co_writer/automark

Automatically detect and annotate important terms, concepts, or entities in the text.

​
Request body

​
text
string
required
The text to annotate.

​
Response

​
marked_text
string
The annotated text with highlights or markup applied.
​
operation_id
string
Unique identifier for this operation.
curl -X POST http://localhost:8001/api/v1/co_writer/automark \
  -H "Content-Type: application/json" \
  -d '{ "text": "The transformer architecture uses self-attention and positional encodings." }'

{
  "marked_text": "The **transformer architecture** uses **self-attention** and **positional encodings**.",
  "operation_id": "op_def456"
}

​
GET /api/v1/co_writer/history

List all past edit and annotation operations. 
curl http://localhost:8001/api/v1/co_writer/history
​
history
object[]
Array of operation records.
​
total
number
Total number of operations.

​
GET /api/v1/co_writer/history/{operation_id}

Get detailed information about a single operation.
​
operation_id
string
required
Operation identifier.
Returns 404 if the operation is not found.

​
GET /api/v1/co_writer/tool_calls/{operation_id}

Get the raw tool call log for an operation, including all LLM tool invocations made during editing.
​
operation_id
string
required
Operation identifier.
Returns 404 if no tool calls are recorded for this operation.

​
POST /api/v1/co_writer/export/markdown

Download the current document content as a .md file.

​
Request body

​
content
string
Markdown content to export.
​
filename
string
default:"\"document.md\""
Filename for the downloaded file.
The response is a file download with Content-Type: text/markdown. 
curl -X POST http://localhost:8001/api/v1/co_writer/export/markdown \
  -H "Content-Type: application/json" \
  -d '{ "content": "# My Notes\n\nContent here.", "filename": "notes.md" }' \
  --output notes.md

​
POST /api/v1/co_writer/narrate

Generate a narration script from note content and optionally synthesize it into audio using TTS.

​
Request body

​
content
string
required
The note or document content to narrate.
​
style
string
default:"\"friendly\""
Narration style. One of:
  • "friendly" — Warm, approachable tutor style.
  • "academic" — Rigorous academic lecture style.
  • "concise" — Efficient, minimal knowledge delivery.
​
voice
string
TTS voice to use. One of "alloy", "echo", "fable", "onyx", "nova", "shimmer". Defaults to the configured TTS default.
​
skip_audio
boolean
default:"false"
Set to true to return only the script without generating audio.

​
Response

​
script
string
The generated narration script.
​
key_points
string[]
Key points extracted from the content.
​
style
string
The narration style used.
​
original_length
number
Character count of the input content.
​
script_length
number
Character count of the generated script.
​
has_audio
boolean
Whether an audio file was generated.
​
audio_url
string
URL to the generated audio file. null if skip_audio was true or TTS failed.
​
audio_id
string
Identifier for the audio file. null if not generated.
​
voice
string
Voice used for TTS. null if not generated.
​
audio_error
string
Error message if audio generation failed but the script was still returned.
curl -X POST http://localhost:8001/api/v1/co_writer/narrate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Backpropagation computes gradients by applying the chain rule from output to input layers.",
    "style": "friendly",
    "voice": "nova",
    "skip_audio": false
  }'

{
  "script": "Hey there! Today let's talk about backpropagation...",
  "key_points": ["chain rule", "gradient computation", "layer-by-layer"],
  "style": "friendly",
  "original_length": 84,
  "script_length": 312,
  "has_audio": true,
  "audio_url": "/api/outputs/co_writer/audio/narration_abc123.mp3",
  "audio_id": "narration_abc123",
  "voice": "nova",
  "audio_error": null
}

​
POST /api/v1/co_writer/narrate/script

Generate a narration script without audio. Faster than the full /narrate endpoint.

​
Request body

​
content
string
required
The note or document content to narrate.
​
style
string
default:"\"friendly\""
Narration style: "friendly", "academic", or "concise".

​
GET /api/v1/co_writer/tts/status

Check whether TTS is configured and available. 
curl http://localhost:8001/api/v1/co_writer/tts/status

{
  "available": true,
  "model": "tts-1",
  "default_voice": "alloy"
}
If TTS is not configured: 
{
  "available": false,
  "error": "TTS configuration not found",
  "hint": "Please configure TTS_MODEL, TTS_API_KEY, TTS_URL in .env file"
}

​
GET /api/v1/co_writer/tts/voices

List the available TTS voice options. 
curl http://localhost:8001/api/v1/co_writer/tts/voices

{
  "voices": [
    { "id": "alloy",   "name": "Alloy",   "description": "Neutral and balanced voice" },
    { "id": "echo",    "name": "Echo",    "description": "Warm and conversational voice" },
    { "id": "fable",   "name": "Fable",   "description": "Expressive and dramatic voice" },
    { "id": "onyx",    "name": "Onyx",    "description": "Deep and authoritative voice" },
    { "id": "nova",    "name": "Nova",    "description": "Friendly and upbeat voice" },
    { "id": "shimmer", "name": "Shimmer", "description": "Clear and pleasant voice" }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us