Introduction

The search context and Document Summarizers REST API (also referred to as "Auto Summarization") is used by our Viewer to summarize text in a document which is currently being viewed.

IMPORTANT: This REST API is designed primarily for our Viewer. If your application needs to perform document summarization without a viewer involved, we recommend you use PrizmDoc Server’s search context and document summarizers REST APIs directly.

IMPORTANT: This API will continue to evolve as we refine these features and extend our cloud service offerings.

Available URLs

URL	Description
POST /v2/viewingSessions/{viewingSessionId}/documentSummarizers	Creates a new document summarizer for a viewing session’s source document, starting the process of document summarization.
GET /v2/documentSummarizers/{processId}	Gets available document summarization.

POST /v2/viewingSessions/{viewingSessionId}/documentSummarizers

Creates a new document summarizer for a viewing session’s source document, starting the process of document summarization.

After a successful POST to create the document summarizer, we immediately begin a background process to start a document summarization for you to GET. Once the full text of the document has been searched and summarized, the document summarizer state will change from "processing" to "complete".

Request

Request Headers

Name	Description
`Content-Type`	Must be `application/json`

Request Body

minSecondsAvailable (Integer) The minimum number of seconds this document summarizer will remain available. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime central configuration parameter.

Successful Response

Response Body

JSON with metadata about the created document summarizer.

processId (String) Unique id for this document summarizer.
affinityToken (String) Affinity token for this document summarizer. Present when clustering is enabled.
state (String) State of document summarization.
- "processing" - The summarization is still being executed.
- "complete" - The summarization is complete.
- "error" - There was a problem performing the summarization.
percentComplete (Integer) Percentage of document summarization which has completed (from 0 to 100).
expirationDateTime (String) Currently planned date and time when the document summarizer resource will expire and no longer be available for use. Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2024-11-05T08:15:30.494Z".

Error Responses

Status Code	JSON `errorCode`	Description
`404`	-	No viewing session with the provided `{viewingSessionId}` could be found.
`480`	`"DocumentNotProvidedYet"`	The viewing session does not yet have a source document attached.
`480`	`"ServerContentDisabled"`	The source document satisfies the client-side viewing formats configured for the viewing session and the server content is disabled.
`480`	`"InvalidInput"`	An invalid input value was used. See `errorDetails` in the response body.
`480`	`"FeatureDisabled"`	The viewing session was created with `"serverSideSearch"` disabled.
`480`	`"FeatureNotLicensed"`	You are not licensed to use the document summarization feature.
`580`	`"InternalError"`	The server encountered an internal error when handling the request.

Example

Request

This POST begins document summarization:

POST pas_base_url/v2/viewingSessions/XYZ.../documentSummarizers
Content-Type: application/json

{
  "minSecondsAvailable": 600
}

NOTE: See the Base URL for PAS topic for more information.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "processing",
  "percentComplete": 0,
  "expirationDateTime": "2024-12-17T20:38:39.796Z"
}

GET /v2/documentSummarizers/{processId}

Gets a summarization of the document.

This URL is designed to give you the document summarization when it becomes available.

Request

URL Parameters

Parameter	Description
`{processId}`	The `processId` which identifies the document summarizer.

Successful Response

Response Body

JSON with the available document summarization.

summarization (String) Always present. String containing the document summarization. If no summarization is available, this string will be empty.

Error Responses

Status Code	JSON `errorCode`	Description
`404`	-	No document summarizer with the provided `{processId}` could be found.
`400`	`"MissingInput"`	Can occur when clustering is enabled and an `Accusoft-Affinity-Token` request header was not provided.
`480`	`"InvalidInput"`	An invalid input value was used. See `errorDetails` in the response body.
`480`	`"ResourceNotUsable"`	Can occur when the document summarizer is in a `state` of `"error"`.
`580`	`"InternalError"`	The server encountered an internal error when handling the request.

Example

Here is an example request and response illustrating how you would acquire the summarization from the document summarizer.

You would GET like so:

GET pas_base_url/v2/documentSummarizers/pR5X6nPDgMwat6cxlmn0Q3

NOTE: See the Base URL for PAS topic for more information.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "summarization": "This document discusses the yearly migration of giraffes from Norway to New Zealand."
}