Introduction

The 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 API will continue to evolve as we refine these features and extend our cloud service offerings.

Available URLs

POST /v2/viewingSessions/{viewingSessionId}/summarizers

Creates a new summarizer for the provided document text, starting the process of summarization.

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

Request

Request Headers

Request Body

• input
  • text (String) Required. The document text to summarize.
• minSecondsAvailable (Integer) The minimum number of seconds this 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 summarizer.

• processId (String) Unique id for this summarizer.
• state (String) State of summarization.
  • "processing" - The summarization is still being executed.
  • "complete" - The summarization is complete.
  • "error" - There was a problem performing the summarization.
• expirationDateTime (String) Currently planned date and time when the 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

Example

Request

This POST begins summarization:

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

{
  "minSecondsAvailable": 600
  "input": {
    "text": "Emergency Medical Technicians (EMTs) perform life-saving medical procedures on-site and in ambulances as patients are being transported to hospitals. Read on to learn more about this critical medical career and how to join the profession. Emergency medical technicians (EMTs) provide critical medical care to patients both on-site and in ambulances on their way to the hospital. Key members of the emergency medical services (EMS), EMTs are often the first to arrive on the scene of an emergency, where they provide basic life-saving care to those in need. If you're interested in a fast-paced medical profession, then you might consider a career as an EMT. In this article, you'll learn more about what an EMT does, the skills they need to perform their life-saving responsibilities, their salary and job outlook, and how to become one. At the end, you'll also find recommended courses to help you get started today."
  }
}

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",
  "expirationDateTime": "2024-12-17T20:38:39.796Z"
}

GET /v2/viewingSessions/{viewingSessionId}/summarizers/{processId}

Gets a summarization of the provided document text.

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

Request

URL Parameters

Successful Response

Response Body

JSON with the available summarization.

• processId (String) Unique id for this summarizer.
• state (String) State of summarization.
  • "processing" - The summarization is still being executed.
  • "complete" - The summarization is complete.
  • "error" - There was a problem performing the summarization.
• errorCode (String) An error code string if a problem occurred during the summarization process. Only present when state is "error".
• expirationDateTime (String) Currently planned date and time when the 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".
• output (Object) Describes the summarization results. Only present when state is "complete".
  • summarization (String) String containing the summarization. If no summarization is available, this string will be empty.

Error Responses

Example

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

You would GET like so:

GET pas_base_url/v2/viewingSessions/XYZ.../summarizers/pR5X6nPDgMwat6cxlmn0Q3

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

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

{
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "complete",
  "expirationDateTime": "2024-12-17T20:38:39.796Z",
  "output": {
    "summarization": "Emergency Medical Technicians (EMTs) are critical members of the Emergency Medical Services (EMS) who provide life-saving medical care to patients both on-site and in ambulances. They are often the first to arrive on the scene of an emergency and require specific skills to perform their responsibilities. If interested in this fast-paced medical profession, individuals can learn more about the job outlook, salary, and steps to become an EMT, including recommended courses to get started."
  }
}