Summarise text

Condense free-form text — meeting notes, an email thread, a long Slack message, a comment chain — into a short summary, plus structured intent signals (action needed, due date, urgency, sensitivity) you can route on.

This is the right operation when you have a generic block of text and want a clean summary. For ticket-shaped or approval-shaped inputs, use Summarise ticket or Summarise approval — they preserve the domain-specific fields better.

POSThttps://aiengine.velgent.com/api/v1/summarise

Headers

| Header | Required | Description | | --- | --- | --- | | Authorization | Yes | Bearer velgent_live_… — see Authentication. | | Content-Type | Yes | application/json. | | Idempotency-Key | No | Any opaque string ≤ 128 chars. Repeated calls within 24h return the original response. Recommended for retries. |

Request body

Field	Type	Required	Default	Description
text	string	Yes	—	The text to summarise. UTF-8, 1–32,000 characters.
format	"paragraph" \| "bullets"	No	"paragraph"	Shape of the summary. "paragraph" returns one tight paragraph; "bullets" returns 3–6 bullet points joined by newlines.
max_words	integer	No	120	Soft upper bound on summary length. Allowed range 30–400.
language	string	No	auto	BCP-47 code (e.g. "en", "es", "fr") for the summary language. Defaults to the detected input language.
metadata	object	No	—	Free-form key/value pairs (string → string, ≤ 16 keys) echoed back on the response. Useful for correlating with your own records.

Response

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier for this summarisation. Use it when reporting issues.
summary	string	Yes	—	The summary, in the requested format.
intent	object	Yes	—	Structured signals derived from the text. See Intent object below.
language	string	Yes	—	BCP-47 code of the summary language.
usage	object	Yes	—	Token counts: { input_tokens, output_tokens, total_tokens }.
metadata	object	No	—	Echo of the metadata you supplied on the request.
created_at	string (ISO 8601)	Yes	—	UTC timestamp the response was produced.

Intent object

Field	Type	Required	Default	Description
action_needed	boolean	Yes	—	True if the text implies the reader needs to do something — answer a question, approve, follow up, decide.
due_date	string (ISO 8601 date) \| null	Yes	—	A due date if the text mentions or strongly implies one; null otherwise. Only the date part — no time or timezone.
urgency_score	integer (0–100)	Yes	—	0 = no urgency, 100 = drop everything. Calibrated against tone, deadlines, and escalation language.
sensitivity	"low" \| "medium" \| "high"	Yes	—	How sensitive the content is — legal, HR, financial, or customer-impacting topics push this up.

Examples

Example response

{
  "id":        "sum_01HZQ7K8YV9X3R2M5N6P7QABCD",
  "summary":   "- Acme renewal call is Thursday at 2pm.\n- Legal flagged a data-residency clause that must be resolved beforehand.\n- Platform team needs to confirm EU customer data is stored in EU regions only.\n- This is blocking the renewal.",
  "intent": {
    "action_needed":  true,
    "due_date":       "2026-05-14",
    "urgency_score":  78,
    "sensitivity":    "high"
  },
  "language":   "en",
  "usage":      { "input_tokens": 86, "output_tokens": 64, "total_tokens": 150 },
  "created_at": "2026-05-10T17:42:11Z"
}

Errors

This operation can return any of the common error codes. The ones you're most likely to hit:

| Status | Code | When | | --- | --- | --- | | 400 | invalid_request | text is missing, empty, or longer than 32,000 characters. | | 400 | invalid_request | format is not "paragraph" or "bullets". | | 400 | invalid_request | max_words is outside 30–400. | | 401 | unauthorized | API key missing or invalid. | | 429 | rate_limited | Per-key rate limit exceeded — see Rate limits. | | 503 | upstream_unavailable | The underlying model provider is temporarily unreachable. Retry with backoff. |

Idempotency

If you send Idempotency-Key and the request fails before a response is produced, retrying with the same key is safe — you'll either get the original successful response (if it eventually completed) or a fresh attempt (if it didn't).