#Summarise

One endpoint, many prompts. Send content + the operation key naming which prompt to use; get back a summary plus structured intent signals (action needed, due date, urgency, sensitivity) you can route on.

For worked requests and example responses across each operation variant, see Examples.

#Operation-as-first-class

Every flavour of summarisation — free-form text, support tickets, approval requests, knowledge-article answers, your tenant's custom prompts — uses the same endpoint. The operation field on the request body selects which prompt template runs.

Platform defaults shipped with every tenant:

Operators can author tenant-specific operations in the admin console. Use GET /api/v1/prompts to list everything available to your key.

#Request

#Body

¹ Required if the prompt declares any required: true variables.

#Discovering what variables a prompt expects

curl https://aiengine.velgent.com/api/v1/prompts/summarise_ticket/schema \
  -H "Authorization: Bearer $VELGENT_API_KEY"

Returns the declared variables, the auto-injected system_variables, and the version's output_format. Build your request from this.

#Response

#intent

The five built-in intent fields — present on every summarise response regardless of operation.

#Custom intent fields

Operators can declare additional structured fields on a prompt version in the admin console. Each declared field gets extracted alongside the five built-ins and lands in the response's intent_extra object.

Five field types are supported:

Each field also carries a description that the LLM sees in the system prompt — write it as you'd explain the field to a new operator.

Use cases:

• ITSM incident summariser → is_outage_related, affected_service, severity_class
• Sales-ops summariser → churn_risk_score, competitor_mention, expansion_signal
• Compliance summariser → regulated_data_present, jurisdiction

The schema is authored on the prompt version in the admin composer (/prompts/[id]/versions/new); the public schema-introspection endpoint GET /api/v1/prompts/{operation}/schema returns the declared schema alongside the existing variables block so callers can discover what custom fields they'll receive.

Cap of 20 custom fields per version. Missing or malformed fields in the LLM response are dropped from intent_extra and logged as schema_drift in your tenant audit log.

#Sentiment

Set include_sentiment: true on the request to have the same LLM call also gauge the emotional tone of the human who raised the ticket — their frustration, anger, or satisfaction — for customer-experience triage. The result lands in the response's sentiment object. It's off by default so calls that don't need it don't pay the extra output tokens, and it works on any operation (the engine injects the sentiment instruction — your prompt template needn't mention it).

Two things it deliberately does not do:

• It does not infer tone from the technical severity of the incident. A customer calmly reporting a critical outage is neutral, not negative.
• It does not invent a tone for machine-raised tickets. When the requester is an automated system, monitoring alert, or bot — no human author to read — the label is not_applicable, so an urgent alert isn't misread as an angry customer.

{
  "label":     "negative",
  "score":     0.82,
  "rationale": "Third time the requester has reported this; tone is clearly frustrated."
}

sentiment is null when the flag is off, or when the model's sentiment output drifted from the contract (logged as schema_drift; the summary itself is unaffected).

#Timeline

Set include_timeline: true to have the same call also emit a chronological timeline of significant events on the ticket plus a derived phases list with durations. Useful for handoffs ("what's been tried so far?"), audit replay, and reporting on mean-time-to-each-phase. Off by default so calls that don't need it don't pay the extra output tokens.

The timeline is citation-grounded: every returned entry references one or more event_ids from the request's events array. Uncited or unknown-id entries are dropped during validation and logged in your audit log — the timeline can't fabricate events that didn't exist in the input.

#Two input modes

Structured events[] (recommended). Pass the ticket's activity records — comments, work notes, state changes, assignments, links — and the engine produces citation-grounded entries. This is the path production integrations should use.

Free-text fallback. When events is omitted, the engine synthesises placeholder synth:N event_ids from the prose so citations still resolve. A timeline.synthesised audit event marks the response so operators can distinguish real-event timelines from extracted ones.

#TicketEvent

One entry in the request's events array.

#TimelineEntry

One entry in the response's timeline array.

#PhaseSpan

One entry in the response's phases array. Phases form a list, not a strict sequence — a ticket may skip phases (duplicate → resolved) or revisit them (validated → investigated when a fix doesn't hold).

#Phases

V1 ITSM phase taxonomy — 8 phases:

Phase boundaries are anchored deterministically by event kind — the LLM doesn't get to invent a "diagnosed" phase that didn't happen. Within each span the LLM picks which event was the narrative moment (e.g. which work note marked the diagnosis).

#Timeline options

Optional timeline_options object on the request.

#Audit events

Visible in the admin console's Activity logs under your tenant.

For a worked request and example response, see Examples → Timeline.

#Errors

Operation-specific errors layered on top of the standard Errors shape:

Missing-variable error body:

{
  "error":             "Required prompt variables not supplied: description",
  "missing_variables": ["description"],
  "operation":         "summarise_ticket",
  "path":              "/api/v1/summarise"
}

Next: Examples →