From 48a21260cc28d3e8483530aa6575f924f5b689d6 Mon Sep 17 00:00:00 2001
From: Emanuele <106186915+OneStepAt4time@users.noreply.github.com>
Date: Sun, 10 May 2026 19:46:44 +0200
Subject: [PATCH] docs: add session export endpoint (GET
 /v1/sessions/:id/export)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents PR #3153 — download full transcript as JSONL or Markdown.
- api-reference.md: new section with params, response examples, errors
- api-quick-ref.md: add endpoint to session routes table
---
 docs/api-quick-ref.md |  1 +
 docs/api-reference.md | 70 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/docs/api-quick-ref.md b/docs/api-quick-ref.md
index a37055f83..b9b856ab5 100644
--- a/docs/api-quick-ref.md
+++ b/docs/api-quick-ref.md
@@ -92,6 +92,7 @@ A compact summary of all Aegis API endpoints. For detailed documentation, exampl
 | `GET` | `/v1/sessions/{id}/read` | Bearer | Read recent messages |
 | `GET` | `/v1/sessions/{id}/transcript` | Bearer | Paginated transcript |
 | `GET` | `/v1/sessions/{id}/transcript/cursor` | Bearer | Cursor-based transcript replay |
+| `GET` | `/v1/sessions/{id}/export` | Bearer | Download transcript as JSONL/Markdown |
 | `GET` | `/v1/sessions/{id}/summary` | Bearer | AI-generated session summary |
 | `GET` | `/v1/sessions/{id}/metrics` | Bearer | Per-session metrics (tokens, duration) |
 | `GET` | `/v1/sessions/{id}/latency` | Bearer | Latency percentiles (p50/p95/p99) |
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 263fa1ea1..7abff2f59 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1009,6 +1009,76 @@ curl "http://localhost:9100/v1/sessions/abc123/transcript/cursor?limit=50&role=u
 
 ---
 
+### Export Session Transcript
+
+```
+GET /v1/sessions/:id/export
+```
+
+Download the full session transcript as JSONL (NDJSON) or Markdown.
+
+```bash
+# JSONL format (default)
+curl "http://localhost:9100/v1/sessions/abc123/export?format=jsonl" \
+  -H "Authorization: Bearer $TOKEN" \
+  -o session.jsonl
+
+# Markdown format
+curl "http://localhost:9100/v1/sessions/abc123/export?format=markdown" \
+  -H "Authorization: Bearer $TOKEN" \
+  -o session.md
+```
+
+**Query parameters:**
+
+| Parameter | Type   | Default | Description                          |
+|-----------|--------|---------|--------------------------------------|
+| `format`  | string | `jsonl` | Export format: `jsonl` or `markdown` |
+
+**JSONL response:** Each line is a JSON object with the transcript entry:
+
+```json
+{"role":"user","contentType":"text","text":"Hello","timestamp":"2026-05-10T15:00:00Z"}
+{"role":"assistant","contentType":"text","text":"Hi there!","timestamp":"2026-05-10T15:00:01Z"}
+```
+
+JSONL fields per entry:
+
+| Field          | Description                       |
+|----------------|-----------------------------------|
+| `role`         | Message role (user/assistant)     |
+| `contentType`  | Content type (text/tool_use/etc.) |
+| `text`         | Message content                   |
+| `toolName`     | Tool name (tool_use entries only) |
+| `toolUseId`    | Tool use ID (if applicable)       |
+| `timestamp`    | ISO 8601 timestamp                |
+
+**Markdown response:** Readable export with section headers, tool calls in collapsible `<details>` blocks, thinking blocks (💭), and error callouts (⚠️).
+
+```markdown
+# Session Export: my-session
+
+> Exported: 2026-05-10T15:50:00Z
+> Session ID: abc-123
+
+---
+
+### 👤 User
+Hello, how are you?
+
+### 🤖 Assistant
+I am doing well, thanks!
+```
+
+**Errors:**
+
+| Status | Condition                              |
+|--------|----------------------------------------|
+| 400    | Unsupported format (not jsonl/markdown) |
+| 404    | Session not found or no transcript data |
+
+---
+
 ### Per-Session Metrics
 
 ```