Ad-hoc Summary SSE

Connection Info

Note: This endpoint only accepts POST (JSON body), so the browser-native EventSource API cannot be used. Call it with the fetch API plus ReadableStream, or any HTTP client that can read streamed responses.

Endpoint Overview

Difference from Regenerate Summary: regeneration always uses the transcript stored on the server as input, while this endpoint uses the content supplied in the request — for content the server does not have, such as the full transcript of several merged recordings, or a transcript edited by the user. The result is never stored; it is only streamed back to the client.

Added in v1.9.1. An earlier endpoint once existed at the same path (removed in V1.8.0); this endpoint is a brand-new contract — authentication, billing, and duplicate-request rules all differ, so do not reuse old integration code.

Request Parameters (JSON body)

Mutual-exclusion rules (same as Regenerate Summary):

• With mode=builtin, prompt and promptSlug must not be sent
• With mode=custom, template must not be sent, while prompt and promptSlug are required

Error Response Model (differs from other SSE endpoints — please note)

This endpoint is intended for backend integrations. Errors before the stream starts always return a real HTTP status code with a JSON body, instead of the "HTTP 200 + error event" convention used by other SSE endpoints:

Authentication only accepts the X-API-Key header; API keys in the query string are not accepted.

The 422 JSON body carries per-field error messages under data.details.errors, so your program can act on them:

{
  "type": "error",
  "data": {
    "error_code": "validation_failed",
    "message": "Validation failed",
    "details": { "errors": { "content": ["The content parameter is required"] } }
  }
}

Billing

• Billed by the character count of content: 0.1 credits per 1,000 characters (rounded up below 1,000; same rate as Meeting Summary and Regenerate Summary).
• Billed only on successful generation; failed generation (including filtered content, or a stream that stalls or does not end normally) is not billed. A summary that is incomplete, with truncated in done, still counts as successful and is billed as usual.
• Example: a 35,000-character content = 3.5 credits; 1 character = 0.1 credits (minimum billing unit).

Duplicate Requests and Billing Guarantees

idempotency_key is supplied by the client (we recommend a stable identifier from your system, such as a merge-batch ID or revision ID). The system compares the entire request — content plus every summary parameter (mode / template / prompt / promptSlug / language / plainText) — to decide whether two calls are retries of the same piece of work:

Retries must carry exactly the same fields as the original request; when summarizing new content or switching prompts, always send a new idempotency_key.

idempotency_key is only valid within a single API key: the same identifier on different API keys is unrelated and billed separately. Re-sending the same piece of work through a backup key counts as two requests.

Edge case: if the same identifier is used concurrently for two different requests (a client error), the first to complete claims it; the other is still billed and delivered normally, but any later retry with that identifier (regardless of content) returns 409 — switch to a new identifier.

Request Examples

builtin mode

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/sse/summary" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "(full transcript merged from multiple recordings…)",
    "idempotency_key": "merge-batch-20260813-001",
    "mode": "builtin",
    "template": "meeting",
    "language": "en-US",
    "plainText": true
  }'

custom mode

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/sse/summary" \
  -H "X-API-Key: vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "(full transcript after user edits…)",
    "idempotency_key": "revision-8f31c2",
    "mode": "custom",
    "prompt": "Extract the decisions and action items from the transcript…",
    "promptSlug": "acme-meeting-v2",
    "language": "en-US"
  }'

Event Sequence

1. connected              → connection confirmed
2. summary_regeneration   → summary fragments (repeated N times, cumulative)
3. done                   → generation complete
   or
3. error                  → generation failed (sse_summary_regeneration_failed); no done is sent and nothing is billed

connected

{ "message": "Ad-hoc summary stream connected (mode: builtin)" }

summary_regeneration

{ "text": "The meeting covered the following topics:\n1. Product development progress", "is_final": false }

done

{
  "tokens_used": 123,
  "final_content": "The meeting... (full summary content)",
  "mode": "custom",
  "template": "acme-meeting-v2",
  "plain_text": true,
  "characters_billed": 35000,
  "charged": "3.5",
  "idempotency_key": "revision-8f31c2",
  "billed": true,
  "summary_language": "zh-TW",
  "prompt_snapshot": "Extract the decisions and action items from the transcript…"
}

Differences from the Regenerate Summary done event: this endpoint has no task_id (not tied to a recording) and no persisted (never stored), and adds the idempotency_key field.

The characters_billed and charged fields carry the same meaning as in Regenerate Summary. The difference is that this endpoint always includes them (they can always be determined), while billed is false for free retries and empty generation results. Reconcile against billed.

Endpoint-Specific Error Codes

Before the stream starts (real HTTP status code + JSON):

After the stream starts (HTTP 200 + SSE error event):

Version: V1.24.1 Last Updated: 2026-09-28