Introduction

The Classifiers REST API (which is part of the "Auto Tagging and Classification" feature) is used by our Viewer to determine a classification for 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}/classifiers

Creates a new classifier for the provided document text, starting the process of document classification.

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

Request

Request Headers

Request Body

• input
  • classifications (Array of strings) Required. A list of classifications from which to select a classification for the document.
  • text (String) Required. The document text to classify.
• minSecondsAvailable (Integer) The minimum number of seconds this classifier 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 classifier.

• input (Object) Input we accepted to create the classifier.
• processId (String) Unique id for this classifier.
• state (String) State of classification.
  • "processing" - The classification is still being executed.
  • "complete" - The classification is complete.
  • "error" - There was a problem performing the classification.
• expirationDateTime (String) Currently planned date and time when the classifier 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 classification:

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

{
  "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.",
    "classifications": ["geography", "health", "history", "mathematics", "nature", "philosophy", "technology"]
  },
  "minSecondsAvailable": 600
}

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

Response

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

{
  "input": {
    "classifications": ["geography", "health", "history", "mathematics", "nature", "philosophy", "technology"]
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "processing",
  "expirationDateTime": "2024-12-17T20:38:39.796Z"
}

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

Gets a classification of the provided document text.

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

Request

URL Parameters

Successful Response

Response Body

JSON with the available classification.

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

Error Responses

Example

Here is an example request and response illustrating how you would acquire the classification from the classifier.

You would GET like so:

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

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

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

{
  "input": {
    "classifications": ["geography", "health", "history", "mathematics", "nature", "philosophy", "technology"]
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "complete",
  "expirationDateTime": "2024-12-17T20:38:39.796Z",
  "output": {
    "classification": "health"
  }
}