Introduction

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

Creates a new tagger for the provided document text, starting the process of tagging.

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

Request

Request Headers

Request Body

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

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

POST pas_base_url/v2/viewingSessions/XYZ.../taggers
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}/taggers/{processId}

Gets tags for the provided document text.

This URL is designed to give you the tags when they become available.

Request

URL Parameters

Successful Response

Response Body

JSON with the available tags.

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

Error Responses

Example

Here is an example request and response illustrating how you would acquire the tags from the tagger.

You would GET like so:

GET pas_base_url/v2/viewingSessions/XYZ.../taggers/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": {
    "tags": ["Emergency Medical Technicians", "medical career", "life-saving care", "skills", "EMS"]
  }
}