PrizmDoc v12.4 - Updated
Search Contexts
API Reference > PrizmDoc Server RESTful API > Search Contexts

Search Contexts

The search context and search task APIs are designed for a viewer to perform server-side searching and text retrieval of a document.

A search context contains a collection of records of full-page text data, one record per page.

Available URLs

URL Description
POST /v2/searchContexts Creates a new search context.
GET /v2/searchContexts/{contextId} Gets information about a search context.
DELETE /v2/searchContexts/{contextId} Deletes a search context.
PUT /v2/searchContexts/{contextId}/records Uploads previously extracted text records to a context, when the context uses input.source of "upload".
POST /v2/searchContexts/{contextId}/completed Marks all previously extracted text records as uploaded, when the context uses input.source of "upload".
GET /v2/searchContexts/{contextId}/records Gets full-page text data (records) for a specified set of pages.

POST /v2/searchContexts

Creates a search context which will eventually hold a set of full-page text records for a source document.

After a successful POST to create the search context, we immediately begin a background process to extract the text records using a work file you specified in the POST (via input.fileId). As we extract pages of text, new records will become available for you to GET. The search context state will change from "processing" to "complete" when there are no more records to extract.

Request

Request Headers

Name Description
Content-Type Must be application/json
Accusoft-Affinity-Token The affinityToken of the work file specified by input.fileId. Required when server clustering is enabled and input.source is "workFile".

Request Body

Successful Response

Response Body

JSON with metadata about the created search context. You can check for changes to this metadata with additional GET requests.

Error Responses

Status Code JSON errorCode Description
400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
580 "InternalError" The server encountered an internal error when handling the request.

Examples

Creating a searchContext using a workfile:

Request

POST /v2/searchContexts
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  }
}

Response

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "state": "processing",
  "percentComplete": 0,
  "expirationDateTime": "2016-12-17T20:38:39.796Z",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Creating a searchContext using previously extracted text:

Note that it is recommended that you use the Accusoft-Affinity-Hint header here when working in multi-server mode, so that multiple contexts created for the same document can be routed to the same server when possible.

Request

POST /v2/searchContexts
Content-Type: application/json
Accusoft-Affinity-Hint: "your-own-unique-identifier-for-the-source-document"

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "upload"
  },
  "minSecondsAvailable": 1200
}

Response

200 OK
Content-Type: application/json

{

  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "upload"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "state": "awaitingInput",
  "percentComplete": 0,
  "expirationDateTime": "2016-12-17T20:38:39.796Z",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

GET /v2/searchContexts/{contextId}

Gets information about a search context.

Request

URL Parameters

Parameter Description
{contextId} The contextId which identifies the resource.

Request Headers

Name Description
Accusoft-Affinity-Token The affinityToken of the search context. Required when server clustering is enabled.

Successful Response

Response Body

JSON with current metadata about the search context.

Error Responses

Status Code JSON errorCode Description
400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
580 "InternalError" The server encountered an internal error when handling the request.

Examples

Example request

GET /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Response when the state is still "processing"

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "processing",
  "percentComplete": 47,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the state is "complete"

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "complete",
  "percentComplete": 100,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the state is "error" because the work file could not be found

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "errorCode": "ResourceNotFound",
  "errorDetails": {
    "in": "searchContext",
    "at": "input.fileId"
  },
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the source document required a password but no password was provided

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "errorCode": "InvalidPassword",
  "errorDetails": {
    "in": "searchContext",
    "at": "input.password"
  },
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the source document required a password but the wrong password was provided

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
    "password": "wrong-password"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "errorCode": "InvalidPassword",
  "errorDetails": {
    "in": "searchContext",
    "at": "input.password"
  },
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

DELETE /v2/searchContexts/{contextId}

Deletes a search context. Further requests using this contextId will return errors.

Request

URL Parameters

Parameter Description
{contextId} The contextId which identifies the resource.

Request Headers

Name Description
Accusoft-Affinity-Token The affinityToken of the search context. Required when server clustering is enabled.

Successful Response

This request returns no body in the response when successful.

Error Responses

Status Code JSON errorCode Description
404 "Not Found" No search context with the provided contextId could be found.
400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
580 "InternalError" The server encountered an internal error when handling the request.

Examples

Example request

DELETE /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Response

HTTP/1.1 204 No Content

PUT /v2/searchContexts/{contextId}/records

This URL is used to upload one or more previously extracted text records to a search context.

Note that this is only necessary when creating a searchContext using input.source of "upload" and receive a state of "awaitingInput".

Request

URL Parameters

Parameter Description
{contextId} The contextId which identifies the resource.

Request Headers

Name Description
Content-Type Must be application/json
Accusoft-Affinity-Token The affinityToken of the search context. Required when server clustering is enabled.

Request Body

Note: since this is previously extracted text being uploaded, the body of the request corresponds to the body of the response on GET /v2/searchContexts/{contextId}/records.

Successful Response

This request returns no body in the response when successful.

Error Responses

Status Code JSON errorCode Description
400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "ResourceNotUsable" The search context is in a state of "error", or has otherwise become unusable.
480 "IncorrectUsage" The state of the search context is not correct. See errorDetails in the response body.
580 "InternalError" The server encountered an internal error when handling the request.

Examples

Example request

PUT /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/records
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=
Content-Type: application/json

{
  "pages": [{
    "number": 1,
    "text": "the text to be searched",
    "width": 147,
    "height": 349
    "rectangles": [
      [ 23.6, 767.75, 15.01, 23.08 ],
      ...
    ]
  }, ...]
}

Example responses

When the data was successfully accepted
HTTP/1.1 200 OK
When the search context is not awaiting input
HTTP/1.1 480 IncorrectUsage
Content-Type: application/json

{
  "errorCode": "IncorrectUsage",
  "errorDetails": {
    "in": "searchContext",
    "at": "state",
    "actual": "processing",
    "expected": {
      "value": "awaitingInput"
    }
  }
}

POST /v2/searchContexts/{contextId}/completed

This URL is used to let the server know that all previously extracted records have been uploaded.

Note that this is only necessary when creating a searchContext using input.source of "upload" and receive a state of "awaitingInput".

The provided records should make up a set of contiguous page records (e.g. [1,2,3,4,5] and not [1,2,3,5,27]), and if any pages are missing from the set, the context will not be allowed to complete successfully.

Request

URL Parameters

Parameter Description
{contextId} The contextId which identifies the resource.

Request Headers

Name Description
Accusoft-Affinity-Token The affinityToken of the search context. Required when server clustering is enabled.

Request Body

This request has no body.

Successful Response

This request returns no body in the response when successful.

Error Responses

Status Code JSON errorCode Description
400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
480 "ResourceNotUsable" The search context is in a state of "error", or has otherwise become unusable.
480 "IncorrectUsage" The state of the search context is not correct. See errorDetails in the response body.
580 "InternalError" The server encountered an internal error when handling the request.

Examples

Example request

POST /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/completed
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Example responses

When the context is successfully completed
HTTP/1.1 200 OK
When a non-contiguous range of pages is provided (e.g. [1, 2, 3, 5, 27])
HTTP/1.1 480 MissingRecords
Content-Type: application/json

{
  "errorCode": "MissingRecords"
}
When the state of the context is "error"
HTTP/1.1 480 ResourceNotUsable
Content-Type: application/json

{
  "errorCode": "ResourceNotUsable"
}
When the context is not awaiting input
HTTP/1.1 480 IncorrectUsage
Content-Type: application/json

{
  "errorCode": "IncorrectUsage",
  "errorDetails": {
    "in": "searchContext",
    "at": "state",
    "actual": "processing",
    "expected": {
      "enum": ["awaitingInput","complete"]
    }
  }
}

GET /v2/searchContexts/{contextId}/records?pages={pages}

Gets full-page text data (records) for a specified set of pages.

Request

URL Parameters

Parameter Description
{contextId} The contextId which identifies the resource.
{pages} Required. A set of comma-delimited page indices (zero-indexed page numbers) and/or hyphenated page index ranges for which you want the full-page text data (records). See more below.
pages

The pages parameter accepts one or more zero-indexed page numbers (page indices). Between commas, you can specify individual pages (like 0), closed page ranges (like 0-3), and open-ended page ranges (like 3-, which means page index 3 through the end of the document).

Here are some examples:

Example Description
pages=0 Get the text data for page index 0.
pages=5 Get the text data for page index 5.
pages=0-5 Get the text data for page indices 0-5.
pages=3- Get the text data for page indices 3 through the end of the document.
pages=0- Get the text data for all pages (page index 0 through the end of the document).
pages=1- Get the text data for all but the first page (page index 1 through the end of the document).
pages=0,2,5,9 Get the text data for page indices 0, 2, 5, and 9.
pages=2,4-5,7- Get the text data for page indices 2, 4 through 5, and 7 through the end of the document.

Request Headers

Name Description
Accusoft-Affinity-Token The affinityToken of the search context. Required when server clustering is enabled.

Successful Response

JSON containing full-page text records for the requested pages.

Error Responses

Status Code JSON errorCode Description
404 No search context exists for the {contextId} given in the URL. It may have expired, or it may have never existed.
400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
480 "MissingInput" A required input was missing. See the errorDetails for more information.
480 "InvalidSyntax" Can occur when the pages query string parameter is set to a value we cannot understand.
480 "ResourceNotUsable" Can occur when the search context is in a state of "error". You may be able to get more information from a GET /v2/searchContexts/{contextId}.
580 "InternalError" The server encountered an internal error when handling the request.

Examples

When all data is returned successfully

Request records for pages 0 through 9:

GET /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/records?pages=0-9
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Successful response (where ... indicates that data has been omitted for brevity):

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

{
  "pages": [
    {
      "number": 0,
      "text": "the page text",
      "width": 648.00,
      "height": 828.00,
      "rectangles": [
        [
          202.25,
          135.05,
          27.00,
          73.26
        ],
        [
          229.25,
          135.05,
          30.00,
          73.26
        ],
        ...
      ]
      "markup": [
        {
          "changeType": "Add",
          "markType": "DocumentHyperlink",
          "properties": {
            "rectangle": {
              "height": 14.71,
              "width": 86.20,
              "y": 73.50,
              "x": 71.31
            },
            "borderHorizontalRadius": 0.0,
            "borderVerticalRadius": 0.0,
            "borderThickness": 0.0,
            "href": "http://www.google.com/",
            "borderOpacity": 255
          }
        },
        ...
      ]
    },
    ...
  ]
}

When the data stream is interrupted

Because this URL may return large amounts of data, we progressively stream data to the HTTP response. As such, it is possible that we encounter a data streaming error after we have sent HTTP 200. When this happens, we will close the JSON with a top-level errorCode of "DataStreamInterruption", like so:

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

{
  "pages": [...],
  "errorCode": "DataStreamInterruption"
}

When out-of-range, non-existent pages are requested

If you request a set of pages that include non-existent pages beyond the length of the document, we will include whatever actual pages we can, but we will also add a top-level errorCode of "RequestedPagesOutOfRange" with the actual documentPageCount within an errorDetails object, like so:

GET /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/records?pages=0-9
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=


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

{
  "pages": [...],
  "errorCode": "RequestedPagesOutOfRange",
  "errorDetails": {
    "documentPageCount": 3
  }
}

When data cannot be extracted from some pages

The pages array will contain one item for each requested page that actually exists. If we are unable to obtain data for a particular page, we will include an item in the pages array that contains the page number and a page-specific errorCode of "CouldNotGetPageData", like so:

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

{
  "pages": [
    {
      "number": 0,
      "text": "Once upon a time...",
      "width": 612.00,
      "height": 792.00,
      "rectangles": [...]
    },
    {
      "number": 1,
      "errorCode": "CouldNotGetPageData"
    },
    {
      "number": 2,
      "errorCode": "CouldNotGetPageData"
    },
    {
      "number": 3,
      "text": "and then, she said to the dragon...",
      "width": 612.00,
      "height": 792.00,
      "rectangles": [...]
    }
  ]
}

 

 

©2017. Accusoft Corporation. All Rights Reserved.

Send Feedback