Summarise knowledge article

Condense a long-form knowledge article — runbook, FAQ, internal wiki page, doc — into a TL;DR plus key points. Designed for previews, search snippets, and "explain this article in 30 seconds" use cases.

This operation is read-only — it summarises the article as written and does not infer urgency or actions, since knowledge articles are reference material, not requests.

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

Headers

Same as Summarise text.

Request body

Field	Type	Required	Default	Description
title	string	Yes	—	Article title. 1–500 characters.
body	string	Yes	—	Article body. Plain text or Markdown. 1–64,000 characters.
audience	"end_user" \| "support_agent" \| "engineer" \| "general"	No	"general"	Who the summary is for. Tunes the tone and detail level.
max_words	integer	No	150	Soft upper bound for the TL;DR. Allowed range 50–400.
metadata	object	No	—	Free-form key/value pairs echoed on the response.

Response

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier.
tldr	string	Yes	—	A short paragraph capturing the article in one read.
key_points	array of string	Yes	—	3–7 bullet points covering the main takeaways.
topics	array of string	Yes	—	Up to 8 short topic tags useful for search and faceting.
usage	object	Yes	—	Token counts.
created_at	string (ISO 8601)	Yes	—	UTC timestamp.

Examples

Example response

{
  "id":   "sumk_01HZQ7K8YV9X3R2M5N6P7QABCD",
  "tldr": "Primary DB credentials are rotated every 90 days. The on-call engineer generates a new password in the secret manager, deploys it to the API and worker services, then revokes the old credential after 24 hours of overlap.",
  "key_points": [
    "Rotation cadence is every 90 days.",
    "On-call engineer is responsible.",
    "New credential is created in the secret manager first.",
    "Both API and worker services must pick up the new credential before the old one is revoked.",
    "A 24-hour overlap window is enforced before revocation."
  ],
  "topics":     ["database", "credentials", "rotation", "on-call", "secrets"],
  "usage":      { "input_tokens": 612, "output_tokens": 134, "total_tokens": 746 },
  "created_at": "2026-05-10T17:42:11Z"
}

Errors

See Errors. The most common knowledge-specific failures:

| Status | Code | When | | --- | --- | --- | | 400 | invalid_request | title or body missing/empty. | | 400 | invalid_request | audience not one of the allowed values. | | 413 | payload_too_large | body exceeds 64,000 characters. |