Summaries

Generate summaries from a Desktop Services session or from text entered directly by the user. Session summaries are asynchronous and remain attached to the session. Text summaries complete in the request and are not attached to a session.

Use List Assigned Templates to discover a prompt template UUID. Use List Context Plugins before sending optional context fields.

List Context Plugins

GET /api/v1/desktop-services/summary-context-plugins

Requires Authentication - Scopes: desktop:app:use

Return the supported context fields. Build additionalContext from the inputFields descriptors. The outputFields descriptors identify information that may appear in a summary's context audit.

curl https://koldan.dixilang.com/api/v1/desktop-services/summary-context-plugins \
  -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    "https://koldan.dixilang.com/api/v1/desktop-services/summary-context-plugins",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
)
response.raise_for_status()
print(response.json())

DesktopSummaryContextPluginListResponse

{
  "items": [
    {
      "pluginId": "clinical-context",
      "displayName": "Clinical context",
      "description": "Adds clinical context to a summary",
      "inputFields": [
        {
          "key": "patient_id",
          "displayName": "Patient ID",
          "description": "Patient identifier used for enrichment",
          "required": true,
          "defaultValue": null,
          "type": "STRING",
          "displayPolicy": "VISIBLE"
        }
      ],
      "outputFields": []
    }
  ]
}

Supplying Additional Context

Session-summary and text-summary requests accept an additionalContext JSON object whose property names match inputFields[].key. All values are JSON strings, including values described as integers or booleans.

{
  "patient_id": "123456",
  "visit_number": "3",
  "include_history": "true"
}

• Supply no more than 32 fields.
• Each value may contain at most 8,192 bytes when encoded as UTF-8.
• Keys are case-sensitive, must be non-blank, and must be declared as input fields. transcript and transcription are reserved.
• Values must not be null.
• Output-field keys cannot be supplied.
• INTEGER values must be valid signed whole numbers without surrounding whitespace.
• BOOLEAN values accept true or false without case sensitivity.
• For an active context source, omitted fields use defaultValue when defined; otherwise its fields marked required must be supplied.
• If items is empty, omit additionalContext; supplied values have no effect.

Invalid context returns 400 Bad Request from the summary operation.

Create a Session Summary

POST /api/v1/desktop-services/sessions/{sessionId}/summaries

Requires Authentication - Scopes: desktop:app:use

Start summary generation for one owned session. The session must satisfy the installation's minimum transcript length. Only one REQUESTED summary can run for the same session and prompt template at a time.

Path Parameters

DesktopSummaryCreateRequest

{
  "promptTemplateId": "ea97bc12-b521-4b22-8f86-7b60b36ac529",
  "additionalContext": {
    "patient_id": "123456"
  }
}

curl -X POST https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/summaries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptTemplateId": "ea97bc12-b521-4b22-8f86-7b60b36ac529",
    "additionalContext": {"patient_id": "123456"}
  }'

import requests

session_id = "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2"
response = requests.post(
    f"https://koldan.dixilang.com/api/v1/desktop-services/sessions/{session_id}/summaries",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
    json={
        "promptTemplateId": "ea97bc12-b521-4b22-8f86-7b60b36ac529",
        "additionalContext": {"patient_id": "123456"},
    },
)
response.raise_for_status()
print(response.headers["Location"])
print(response.json())

DesktopSummary

The response includes a Location header containing the new summary URL. Poll that URL or use Query Summary Statuses until the status is COMPLETED or FAILED.

List Session Summaries

GET /api/v1/desktop-services/sessions/{sessionId}/summaries

Requires Authentication - Scopes: desktop:app:use

Return summaries for one owned session, ordered newest first.

Path and Query Parameters

curl "https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/summaries?latestPerPromptTemplate=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DesktopSummaryListResponse

{
  "items": [
    { "...": "..." }
  ]
}

Get the Latest Summary

GET /api/v1/desktop-services/sessions/{sessionId}/summaries/latest

Requires Authentication - Scopes: desktop:app:use

Return the most recently created summary request for the session, regardless of prompt template or status.

Path Parameters

curl https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/summaries/latest \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DesktopSummary

Get a Summary

GET /api/v1/desktop-services/sessions/{sessionId}/summaries/{summaryId}

Requires Authentication - Scopes: desktop:app:use

Return one summary request and its result when complete.

Path Parameters

curl https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/summaries/8ac77882-61bf-445c-b464-27dfb06f7808 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DesktopSummary

Query Summary Statuses

POST /api/v1/desktop-services/summary-status-queries

Requires Authentication - Scopes: desktop:app:use

Query compact summary status information for as many as 100 sessions in one request. The response contains one entry for every requested session. An unknown or inaccessible session produces an empty summaries array.

DesktopSummaryStatusQueryRequest

DesktopSessionSummaryStatusQuery

{
  "sessions": [
    {
      "sessionId": "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2",
      "summaryIds": ["8ac77882-61bf-445c-b464-27dfb06f7808"]
    }
  ]
}

curl -X POST https://koldan.dixilang.com/api/v1/desktop-services/summary-status-queries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [{
      "sessionId": "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2",
      "summaryIds": ["8ac77882-61bf-445c-b464-27dfb06f7808"]
    }]
  }'

DesktopSummaryStatusQueryResponse

DesktopSessionSummaryStatuses

DesktopSummaryStatus

{
  "sessions": [
    {
      "sessionId": "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2",
      "summaries": [
        {
          "id": "8ac77882-61bf-445c-b464-27dfb06f7808",
          "status": "COMPLETED",
          "error": null
        }
      ]
    }
  ]
}

Summarize Entered Text

POST /api/v1/desktop-services/text-summaries

Requires Authentication - Scopes: desktop:app:use

Run a prompt template against manually entered text. The request waits for completion and returns the generated result. Set autoRemove to request immediate removal after processing; otherwise the installation's retention policy applies.

DesktopTextSummaryRequest

{
  "promptTemplateId": "ea97bc12-b521-4b22-8f86-7b60b36ac529",
  "inputText": "The patient reports improved mobility and no new pain.",
  "title": "Follow-up note",
  "additionalContext": {
    "patient_id": "123456"
  },
  "autoRemove": false
}

curl -X POST https://koldan.dixilang.com/api/v1/desktop-services/text-summaries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptTemplateId": "ea97bc12-b521-4b22-8f86-7b60b36ac529",
    "inputText": "The patient reports improved mobility and no new pain.",
    "title": "Follow-up note",
    "additionalContext": {"patient_id": "123456"},
    "autoRemove": false
  }'

DesktopTextSummaryResponse

{
  "id": "5c6cdcc3-373f-4ef2-a828-0e731de63f7a",
  "result": "Mobility has improved, with no new pain reported.",
  "contextAudit": { "...": "..." }
}

Data Models

DesktopSummary

{
  "sessionId": "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2",
  "id": "8ac77882-61bf-445c-b464-27dfb06f7808",
  "promptTemplate": { "...": "..." },
  "status": "COMPLETED",
  "createdAt": "2026-09-26T08:14:00Z",
  "updatedAt": "2026-09-26T08:14:08Z",
  "result": "The consultation covered current symptoms and next steps.",
  "error": null,
  "contextAudit": { "...": "..." }
}

DesktopSummaryPromptTemplateSnapshotResponse

SummaryContextPlugin

SummaryContextField

displayPolicy controls the audit representation:

SummaryContextAudit

SummaryContextPluginUsage

SummaryContextFieldValue