pdfToolbox in the cloud- POST an operation and GET the result

These operations require your personal api-key which can be requested via 'Request the key'.

For a POST request, two things are needed:

  • Your personal api-key
  • The POST request body containing the json data to be submitted. A POST request body can look like this
{ 
    "finput": "https://s3.eu-central-1.amazonaws.com/ccapi-sample/sample.pdf",
    "imgformat": "PNG" 
}
Click to copy

Request

For brevity the POST request body has been stored in a file named saveasimg_data.json.

Your personal api-key needs to be specified in an HTTP x-api-key header field.

curl -X POST https://api.callassoftware.io/v1/pdfToolbox/saveasimg \
-H 'x-api-key: your-api-key-here'
-d '{ "finput": "https://s3.eu-central-1.amazonaws.com/ccapi-sample/sample.pdf" }'
Click to copy

This responds with an HTTP/202 message that contains a path component in the body. There are other components such as state and progress that can be used for progress information.

{
"path": "/v1/result/4qwrfluvo5_a809270b-6cad-4afa-b7bc-1c90f830618a",
"message": "operation pending",
"ms_retry_after": 400,
"progress": 0,
"state": "INITIAL"
}
Click to copy

Fields:

  • path is to be used in subsequent HTTP GET requests
  • ms_retry_after should be used to delay the next HTTP GET request by the specified amount of milliseconds (it is only present in newer API versions). Note: the API throttles on its own if you ommit the delay specified in ms_retry_after. It is however recommended that you make use of this field because otherwise an error HTTP/427 too many requests can occur
  • state be used to for progress indication (see below for progress)
  • progress can be used to indicate the percentual progress of the remote operation (informational only)

Subsequent HTTP GET request

The same personal api-key needs to be specified in an HTTP x-api-key header field.

curl https://api.callassoftware.io/v1/result/4qwrfluvo5_a809270b-6cad-4afa-b7bc-1c90f830618a \
-H 'x-api-key: your-api-key-here'
Click to copy

You should repeat this subsequent GET requests as long as the HTTP return code is a 202, and stop as soon a final response code is received (either HTTP/200 or HTTP/4xx or HTTP/5xx)

Response

On success

The API responds with an HTTP Status of 202 (Accepted). The json response body could look like this:

{
    "message": "operation enqueued for asynchronous processing (keep going using a GET on the belonging path ...)",
    "ms_retry_after": 200,
    "operation": "saveasimg",
    "path": "/v1/result/4qwrfluvo5_5a56290d-8422-4bfb-a95f-792656ddefc4",
    "progress": 0,
    "state": "INITIAL"
}
Click to copy

On Error 

{
    "message": "failed to download: https://s3.eu-central-1.amazonaws.com/ccapi-sample/sample.pdf"
}
Click to copy