Skip to main content

​
Overview

The session summarize endpoint produces and stores session summaries using an upsert model where ONE document exists per session. If the daemon already created an incremental summary, subsequent calls UPDATE it rather than creating duplicates.

​
Endpoint

​
method
string
POST
​
path
string
/api/session/summarize
​
authentication
string
API Key required

​
Request Body

​
content
string
required
Session transcript text to summarize. Content is capped at 50,000 characters to prevent OOM. If exceeded, the middle portion is truncated.
​
session_id
string
required
Session identifier used to create the session tag (e.g., session:{id[:12]})
​
source_ref
string
Project reference for tagging (e.g., project:org/repo)
​
project_context
string
Human-readable project context for LLM prompt (e.g., org/repo (main))
​
mode
string
default:"incremental"
Summary mode:
  • incremental: Daemon-generated incremental summary (appends to existing)
  • finalize: Stop hook comprehensive final version (replaces existing)
​
epoch
integer
default:"0"
Session epoch number. For epoch > 0, the session tag becomes session:{id[:12]}:e{N}
​
session_tag
string
Custom session tag. If not provided, automatically generated from session_id and epoch

​
Response

​
success
boolean
Indicates if the operation was successful
​
document_id
string
ID of the created or updated document. Null if skipped.
​
title
string
Generated title in format: Session: {date} - {project} - {title} (epoch {N})
​
action
string
Action taken: created, updated, or null if skipped
​
skipped_reason
string
Reason for skipping (if applicable):
  • extraction_produced_no_summary: LLM returned no summary
  • chunking_produced_no_output: Chunking failed

​
Behavior

​
Incremental Mode

In incremental mode, existing summaries are appended to with a separator (\n\n---\n\n). The stored summary is capped at 10,000 characters to prevent unbounded growth. When exceeded, the tail (most recent summaries) is kept.

​
Finalize Mode

The stop hook sends mode="finalize" to replace the incremental summary with a comprehensive final version.

​
Tagging

Documents are tagged with:
  • session-summary (category)
  • Priority tag from LLM extraction (default: medium)
  • Session tag (session:{id[:12]} or session:{id[:12]}:e{N})
  • Additional tags from LLM extraction
curl -X POST https://api.cems.dev/api/session/summarize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User asked about implementing authentication. Assistant helped configure OAuth2 with JWT tokens...",
    "session_id": "abc123def456",
    "source_ref": "project:acme/webapp",
    "project_context": "acme/webapp (main)",
    "mode": "incremental",
    "epoch": 0
  }'

{
  "success": true,
  "document_id": "doc_abc123",
  "title": "Session: 2026-02-28 - acme/webapp - OAuth2 Implementation",
  "action": "created"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us