IMPORTANT: This experimental API is a work-in-progress that is not officially supported by Accusoft. Its behavior may change at any time in a future release of the product.
Available URLs
| URL | Description |
|---|---|
| POST /v3/viewingSessions | Creates a new Viewing Session. |
| GET /v3/viewingSessions/{viewingSessionId}/content/root/metadata | Gets metadata for the Viewing Session content. |
| GET /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index} | Gets PDF for a page group of the Viewing Session source. |
| HEAD /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index} | Gets the HTTP headers that would be returned if the HEAD request's URL was instead requested with the GET method. |
| POST /v3/viewingSessions/{viewingSessionId}/heartbeat | Let the server know that the client is still using this Viewing Session. |
POST /v3/viewingSessions
Creates a new Viewing Session.
Request
Request Headers
| Name | Description |
|---|---|
Content-Type |
Should be application/json |
Request Body
JSON object conforming to the following:
input(Object) Required. Specifies the input used for the Viewing Session creation.source(Object) Required. Identifies the source for the Viewing Session.type(String) Required. The type of the source. The only valid value is:"viewingPackage"An existing Viewing Package will be used as the source. Use the "v3" Viewing Package Creators API to create a Viewing Package. The Viewing Package lifetime will be extended when a Viewing Session is created.
packageId(String) Required. ID of the Viewing Package to use as the source.
Successful Response
Response Body
JSON object with the following properties:
viewingSessionId(String) Unique ID for this Viewing Session.
Error Responses
| Status Code | JSON errorCode |
Description |
|---|---|---|
480 |
"ResourceNotFound" |
The Viewing Package with the provided packageId could not be acquired. See errorDetails in the response body. |
480 |
"ViewingPackageIsNotComplete" |
The Viewing Package with the provided packageId is not complete. |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use). |
Example
Request
POST /v3/viewingSessions
Content-Type: application/json
{
"input": {
"source": {
"type": "viewingPackage",
"packageId": "my-viewing-package-id"
}
}
}
Response
HTTP 200 OK
Content-Type: application/json
{
"viewingSessionId": "4jOOgAh-9rktzXLzst-TIXYKdbDfy-I_3vQgnzzhcpkX"
}
GET /v3/viewingSessions/{viewingSessionId}/content/root/metadata
Gets metadata for the Viewing Session content.
Request
URL Parameters
| Parameter | Description |
|---|---|
{viewingSessionId} |
The viewingSessionId which identifies the Viewing Session. |
Successful Response
Response Headers
| Name | Description |
|---|---|
Content-Type |
application/json |
Content-Length |
The JSON size in bytes. |
Cache-Control |
Content caching directives. |
Response Body
JSON object with the following properties:
pageGroups(Array of Objects) Array of objects containing metadata on each of the page groups created for the viewing session content.startPage(Integer) Start page of the page group.
Error Responses
| Status Code | JSON errorCode |
Description |
|---|---|---|
404 |
"ResourceNotFound" |
No Viewing Session with the provided viewingSessionId could be found. |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use). |
Example
Request
GET /v3/viewingSessions/4jOOgAh-9rktzXLzst-TIXYKdbDfy-I_3vQgnzzhcpkX/content/root/metadata
Response
HTTP 200 OK
Content-Type: application/json
{
pageGroups: [
{
startPage: 1
}
]
}
GET /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}
Gets PDF for a page group of the Viewing Session source.
NOTE: This request extends source Viewing Package lifetime.
Request
URL Parameters
| Parameter | Description |
|---|---|
{viewingSessionId} |
The viewingSessionId which identifies the Viewing Session. |
{index} |
The zero-based index of the requested page group. |
Request Headers
| Name | Description |
|---|---|
Range |
Optional. Defines a single range of the file content, e.g. "bytes=0-1023" value can be used to request the first 1024 bytes. Full page group content will be requested when the header is not specified. |
Successful Response
Returns HTTP 200 when full content is requested. Returns HTTP 206 when content range is requested.
Response Headers
| Name | Description |
|---|---|
Content-Type |
application/pdf |
Content-Length |
The page group PDF file size in bytes. |
Cache-Control |
Content caching directives. |
Content-Range |
Returned when Range has been requested. The value indicates where in the full content the returned partial content belongs. |
Response Body
PDF file bytes.
Error Responses
| Status Code | JSON errorCode |
Description |
|---|---|---|
404 |
"ResourceNotFound" |
No Viewing Session with the provided viewingSessionId or no page group with provided index could be found. |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use). |
416 |
The requested Range could not be satisfied. This error can be thrown when page group content doesn't contain such ranges, or when the syntactically correct Range header value doesn't make sense. |
HEAD /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}
Gets the HTTP headers that would be returned if the HEAD request's URL was instead requested with the GET method.
NOTE: Unlike the GET /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}, this route does not support a Range header.
Request
URL Parameters
| Parameter | Description |
|---|---|
{viewingSessionId} |
The viewingSessionId which identifies the Viewing Session. |
{index} |
The zero-based index of the requested page group. |
Successful Response
Response Headers
| Name | Description |
|---|---|
Content-Type |
application/pdf |
Content-Length |
The page group PDF file size in bytes. |
Cache-Control |
Content caching directives. |
Response Body
No body.
Error Responses
| Status Code | Status Message | Description |
|---|---|---|
404 |
"ResourceNotFound" |
No Viewing Session with the provided viewingSessionId or no page group with provided index could be found. |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use). |
POST /v3/viewingSessions/{viewingSessionId}/heartbeat
Let the server know that the client is still using this Viewing Session. Use the Heartbeat API to keep the Viewing Session alive, otherwise it will self expire. Viewing Session lifetime after the last heartbeat is 5 minutes.
NOTE: Viewing Session lifetime after session creation is limited to 6 hours.
Request
Request Body
Empty.
Successful Response
Response Headers
| Name | Description |
|---|---|
Content-Type |
application/json |
Response Body
Empty JSON object.
Error Responses
| Status Code | Status Message | Description |
|---|---|---|
404 |
"ResourceNotFound" |
No Viewing Session with the provided viewingSessionId or no page group with provided index could be found. |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use). |
Example
Request
POST /v3/viewingSessions/4jOOgAh-9rktzXLzst-TIXYKdbDfy-I_3vQgnzzhcpkX/heartbeat
Response
HTTP 200 OK
Content-Type: application/json
{}