Summary

Overview

Generate a meeting summary from any transcript text, with the response streamed segment by segment over SSE. This endpoint is independent of the recording flow and can be used to integrate transcripts from external sources (meeting notes from other systems, pre-upload previews, and so on).

If you want to regenerate a summary for a recording that has already been uploaded to VAS, use GET / POST /api/v1/sse/regenerate/summary/{taskId} instead.

Connection Information

Note: This endpoint uses Authorization: Bearer authentication, which differs from the X-API-Key used by other REST endpoints.

Request

Request Body (JSON)

Mutual-exclusivity rules:

• Under mode=builtin, you must not include prompt or prompt_slug
• Under mode=custom, you must not include template, but prompt and prompt_slug are required

Violation → 400 summary_mode_field_mismatch

Request Examples

builtin mode (apply a built-in template)

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/summary" \
  -H "Authorization: Bearer vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...transcript...",
    "mode": "builtin",
    "template": "medical_consultation",
    "language": "zh-TW",
    "plain_text": true
  }'

custom mode (fully customized prompt)

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/summary" \
  -H "Authorization: Bearer vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...transcript...",
    "mode": "custom",
    "prompt": "You are a dermatology specialist assistant. From the transcript, extract: 1) chief complaint 2) Fitzpatrick type 3) allergy history. Output JSON.",
    "prompt_slug": "skin-clinic-acme-v2",
    "language": "zh-TW",
    "plain_text": true
  }'

Effect:

• The backend does not query any built-in template
• The customer's prompt replaces the built-in template rules; only minimal default processing is applied (language, plain text, safety guard)
• The prompt content is forcibly snapshotted into the done event and stored in the backend record (the sole basis for reconstruction)

SSE Events

Event Sequence

1. start    → Generation begins
2. chunk    → Summary segment (repeated N times, includes markdown)
3. done     → Generation complete (includes the final cleaned content; in custom mode, includes prompt_snapshot)
4. error    → An error occurred (replaces done)

start event

{
  "summary_id": "sum_abc123",
  "mode": "custom",
  "template": "skin-clinic-acme-v2",
  "format": "bullet_points",
  "language": "zh-TW",
  "plain_text": true
}

chunk event

{ "content": "This meeting discussed..." }

A streamed segment (includes markdown; the frontend can render it in real time).

done event

{
  "summary_id": "sum_abc123",
  "tokens_used": { "input": 1234, "output": 567 },
  "created_at": "2026-05-13T08:30:00Z",
  "mode": "custom",
  "template": "skin-clinic-acme-v2",
  "plain_text": true,
  "final_content": "This meeting... (cleaned plain text when plain_text=true)",
  "prompt_snapshot": "You are a dermatology specialist assistant..."
}

error event

{
  "errorCode": "summary_mode_field_mismatch",
  "message": "Field mismatch with mode",
  "details": { "provider": "llm_service" }
}

Security discipline: details does not include the LLM's internal raw error (to avoid exposing prompt fragments, API key hashes, and other sensitive information); it only indicates the provider. The full error message goes into the server log.

Specific Error Codes

Integration Best Practices

1. For the builtin path, first call GET /api/v1/summary-templates/{slug} to understand the built-in template content (see summary-templates.md)
2. Under the custom path, your prompt must include the output language, structure description, and field requirements (the backend no longer applies built-in template rules)
3. Avoid using markdown symbols in the prompt (-, *, #) — if plain_text=true, the backend post-processing strips them out
4. Do not splice untrusted end-user input directly into prompt (you assume the prompt-injection risk; the backend includes prompt-injection protection but it is not foolproof)
5. Do not write passwords or API keys in prompt (the content is sent to the LLM service for processing, and in custom mode the prompt content is stored in the backend record for auditing)
6. It is recommended that prompt_slug include a version (e.g. acme-v1 → acme-v2) so integrators can trace it
7. When plain_text=true, expect fully plain-text output (even - list markers are stripped); if you need to preserve list structure, use CJK symbols (・, ①②③, 【】)

Related Resources

• GET /api/v1/summary-templates - Summary template list (supports ?category=)
• GET /api/v1/summary-templates/{slug} - Detailed prompt for a single template
• GET / POST /api/v1/sse/regenerate/summary/{taskId} - Regenerate the summary for an existing recording

Version: V1.5.7 Last Updated: 2026-05-20