Introduction

The Queriers REST API (which is part of the "Document Q&A" feature) is used by our Viewer to query 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}/queriers

Creates a new querier for the provided document text, starting the process of querying.

After a successful POST to create the querier, we immediately begin a background process to start a query for you to GET. Once a response exists for the query, the querier state will change from "processing" to "complete".

Request

Request Headers

Request Body

• input
  • query (String) Required. A question for querying the provided document text.
  • text (String) Required. The document text to query.
• minSecondsAvailable (Integer) The minimum number of seconds this querier 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 querier.

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

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

{
  "input": {
    "query": "What does the acronym EMT refer to?",
    "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."
  },
  "minSecondsAvailable": 600
}

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

Response

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

{
  "input": {
    "query": "What does the acronym EMT refer to?"
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "processing",
  "expirationDateTime": "2024-12-17T20:38:39.796Z"
}

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

Gets a response from a query.

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

Request

URL Parameters

Successful Response

Response Body

JSON with the available query response.

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

Error Responses

Example

Here is an example request and response illustrating how you would acquire the query response from the querier.

You would GET like so:

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

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

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

{
  "input": {
    "query": "What does the acronym EMT refer to?"
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "complete",
  "expirationDateTime": "2024-12-17T20:38:39.796Z",
  "output": {
    "response": "EMT stands for Emergency Medical Technician. An Emergency Medical Technician is a trained medical professional."
  }
}