Skip to content

Summaries

Manage AI-generated summaries for speech service transcriptions. Generate concise summaries, meeting minutes, or action items from completed transcriptions using customizable prompt templates.

Base path: /api/v1/speech-services/summaries

Method Endpoint Description
GET /api/v1/speech-services/summaries List Summaries
POST /api/v1/speech-services/summaries Create Summary
GET /api/v1/speech-services/summaries/{id} Get Summary
GET /api/v1/speech-services/summaries/{id}/result Get Summary Result
PUT /api/v1/speech-services/summaries/{id}/webhook Update Webhook
DELETE /api/v1/speech-services/summaries/{id}/webhook Delete Webhook
POST /api/v1/speech-services/summaries/{id}/cancel Cancel Summary
DELETE /api/v1/speech-services/summaries/{id} Delete Summary
POST /api/v1/speech-services/summaries/{id}/purge Permanently Delete Summary

List Summaries

GET /api/v1/speech-services/summaries

Requires Authentication - Scopes: speech:summaries:read

Retrieve a paginated list of summaries. By default returns only the current user's summaries. When fileId or transcriptionId is specified, returns all summaries for that resource (requires READ access to the parent file, enabling discovery of summaries on shared files).

Query Parameters
Parameter Type Required Default Description
page integer No 0 Page number (zero-based).
size integer No 20 Page size (max 100).
transcriptionId string (UUID) No - Filter by parent transcription ID.
fileId string (UUID) No - Filter by source file ID.
status string[] No - Filter by status (comma-separated). Values: PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED.
promptTemplateId string (UUID) No - Filter by prompt template ID.
isDeleted boolean No false Filter by deleted state.
isPurged boolean No - Filter by permanently deleted state.
createdAfter string (ISO 8601) No - Return summaries created on or after this timestamp.
createdBefore string (ISO 8601) No - Return summaries created on or before this timestamp.
completedAfter string (ISO 8601) No - Return summaries completed on or after this timestamp.
completedBefore string (ISO 8601) No - Return summaries completed on or before this timestamp.
sort string No creationDate,desc Sort field and direction. Allowed: creationDate, completionDate, status. 
curl -X GET "https://koldan.dixilang.com/api/v1/speech-services/summaries?page=0&size=20&status=COMPLETED" \
  -H "Authorization: Bearer $JWT"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speech-services/summaries",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"page": 0, "size": 20, "status": "COMPLETED"}
)
print(resp.json())
SpeechServiceSummaryListResponse
Field Type Nullable Description
summaries SpeechServiceSummaryResponse[] No Array of summary objects (without full result).
size integer No Number of items returned in this page.
total long No Total number of matching items across all pages.
filters object No Echo of applied filters.
sort object No Applied sort order (field and direction).
SpeechServiceSummaryListResponse
{
  "summaries": [
    { "id": "e5f6g7h8-...", "status": "COMPLETED", ... }
  ],
  "size": 1,
  "total": 1
}
Status Description
200 OK Summaries retrieved successfully.
400 Bad Request Invalid sort field or query parameters.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Create Summary

POST /api/v1/speech-services/summaries

Requires Authentication - Scopes: speech:summaries:write

<small>:material-speedometer:{ style="color: #e53935" } **Rate Limited** - This endpoint enforces stricter rate limits</small> Generate an AI summary for a completed transcription job. You must provide a transcriptionId for a job that has reached the COMPLETED status and a promptTemplateId defining the summarization logic.

SpeechServiceSummaryRequest
Field Type Required Description
transcriptionId string (UUID) Yes The ID of the completed transcription to summarize.
promptTemplateId string (UUID) Yes The ID of the prompt template to use.
webhook SpeechServiceWebhook No Optional webhook configuration for completion notifications.
SpeechServiceSummaryRequest
{
  "transcriptionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
  "promptTemplateId": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p",
  "webhook": {
    "url": "https://example.com/webhook/summaries"
  }
}

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/summaries \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "transcriptionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
    "promptTemplateId": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p"
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/speech-services/summaries",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type": "application/json"
    },
    json={
        "transcriptionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "promptTemplateId": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p"
    }
)
print(resp.json())
SpeechServiceSummaryResponse

See Get Summary for the full response DTO definition.

Status Description
201 Created Summary job created and queued.
400 Bad Request Invalid parameters or transcription not completed.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Transcription or prompt template not found.
429 Too Many Requests Rate limit exceeded.

Get Summary

GET /api/v1/speech-services/summaries/{id}

Requires Authentication - Scopes: speech:summaries:read

Retrieve the details and current status of a specific summary job.

SpeechServiceSummaryResponse
Field Type Nullable Description
id string (UUID) No Unique identifier of the summary.
transcriptionId string (UUID) No The ID of the parent transcription job.
status SummaryJobStatus No Current status of the summary.
isDeleted boolean No Whether the summary has been deleted.
isPurged boolean No Whether result/error data has been permanently removed.
promptTemplateId string (UUID) No The ID of the prompt template used.
creationDate string (ISO 8601) No Timestamp when created.
completionDate string (ISO 8601) Yes Timestamp when completed.
deletedAt string (ISO 8601) Yes Timestamp when deleted.
purgedAt string (ISO 8601) Yes Timestamp when permanently deleted.
purgeAt string (ISO 8601) Yes Scheduled automatic permanent deletion timestamp.
result SpeechServiceSummaryResult Yes Summary output. Present only when COMPLETED and not permanently deleted.
errors SpeechServiceSummaryError[] Yes List of errors encountered. Cleared when permanently deleted.
webhook SpeechServiceWebhook Yes Configured webhook for this summary.
SpeechServiceSummaryResult
Field Type Nullable Description
text string No The generated summary text.
promptTemplateId string (UUID) No The ID of the template used.
usage SpeechServiceSummaryTokenUsage No LLM token usage statistics.
SpeechServiceSummaryTokenUsage
Field Type Nullable Description
inputTokens integer No Tokens in the request.
outputTokens integer No Tokens in the response.
totalTokens integer No Total tokens consumed.
SpeechServiceSummaryError
Field Type Nullable Description
code SpeechServiceSummaryErrorCode No Machine-readable error code.
message string No Human-readable error message.
timestamp string (ISO 8601) No When the error occurred.
SpeechServiceWebhook
Field Type Required Description
url string Yes HTTPS URL for notifications.
secret string No Secret for HMAC-SHA256 signing.
headers object No Custom HTTP headers.
SpeechServiceSummaryResponse
{
  "id": "e5f6g7h8-i9j0-4k1l-2m3n-4o5p6q7r8s9t",
  "transcriptionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
  "status": "COMPLETED",
  "result": {
    "text": "The meeting discussed the Q3 marketing strategy...",
    "promptTemplateId": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p",
    "usage": {
      "inputTokens": 1250,
      "outputTokens": 380,
      "totalTokens": 1630
    }
  }
}
Status Description
200 OK Summary details retrieved.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Summary not found.

Get Summary Result

GET /api/v1/speech-services/summaries/{id}/result

Requires Authentication - Scopes: speech:summaries:read

Specifically retrieve the generated summary text and token usage for a completed summary.

SpeechServiceSummaryResult

Refer to SpeechServiceSummaryResult in the Get Summary section for the field table and structure.

Status Description
200 OK Summary result retrieved successfully.
401 Unauthorized Missing or invalid authentication.
404 Not Found Summary result not yet available (job not completed).
410 Gone Summary result has been permanently deleted.

Update Webhook

PUT /api/v1/speech-services/summaries/{id}/webhook

Requires Authentication - Scopes: speech:summaries:write

Set or update the webhook configuration for a pending or in-progress summary. This will overwrite any existing webhook.

SpeechServiceWebhook

Refer to SpeechServiceWebhook in the Get Summary section for the field table and structure.

Status Description
200 OK Webhook updated successfully.
409 Conflict Cannot update webhook for a summary in a terminal state.

Delete Webhook

DELETE /api/v1/speech-services/summaries/{id}/webhook

Requires Authentication - Scopes: speech:summaries:write

Remove the webhook configuration from an existing summary.

Status Description
204 No Content Webhook removed successfully.
409 Conflict Cannot remove webhook from a summary in a terminal state.

Cancel Summary

POST /api/v1/speech-services/summaries/{id}/cancel

Requires Authentication - Scopes: speech:summaries:write

Cancel a pending or in-progress summary generation.

Status Description
204 No Content Summary cancelled successfully.
409 Conflict Summary is already in a terminal state and cannot be cancelled.

Delete Summary

DELETE /api/v1/speech-services/summaries/{id}

Requires Authentication - Scopes: speech:summaries:delete

Delete a summary. The record remains in the system until the retention period expires. Use ?purge=true to immediately and permanently remove the summary result and error data.

Query Parameters
Parameter Type Required Default Description
purge boolean No false If true, immediately and permanently deletes result/error data.
Status Description
204 No Content Summary deleted.
409 Conflict Summary is not in a terminal state or is already deleted.

Permanently Delete Summary

POST /api/v1/speech-services/summaries/{id}/purge

Requires Authentication - Scopes: speech:summaries:delete

Permanently delete result and error data of a previously deleted summary. This operation is irreversible and is intended for immediate compliance with data privacy requests.

Status Description
204 No Content Summary data permanently deleted.
409 Conflict Summary is not deleted or has already been permanently deleted.

Enumerations

SummaryJobStatus

Value Description
PENDING Summary job has been accepted but processing has not started.
IN_PROGRESS Transcription text is being processed by the AI model.
COMPLETED Summary finished successfully. Result is available.
FAILED Summarization failed. Check errors for details.
CANCELLED Job was cancelled before completion.

SpeechServiceSummaryErrorCode

Value Description
SUMMARIZATION_FAILED The AI engine encountered an error while generating the summary.
PROMPT_TEMPLATE_NOT_FOUND The specified prompt template does not exist or has been deleted.
TRANSCRIPTION_NOT_COMPLETED The parent transcription has not yet reached a COMPLETED status.
INTERNAL_ERROR An unexpected internal error occurred during processing.