PDF Report API
With this API, users can download a PDF report of the analysis results for any sample on the Spectra Analyze appliance. The contents of the PDF file downloaded with this API are identical to the PDF report downloaded from the Sample Details page by clicking the Create PDF button.
The API provides 3 endpoints:
- Create PDF Report
- Check PDF Report Status
- Download PDF Report
To download the PDF report for a sample, users first have to initiate report creation by sending a request to Endpoint 1. The next step is to check report creation status by sending a request to Endpoint 2. When the response indicates that the report is ready, users should send a request to Endpoint 3 to download the PDF file.
All three endpoints accept GET requests with a single sample hash per request. Supported hash types are SHA1, SHA256, MD5. The sample hash is a required parameter that must be provided in every request.
For each sample, the same hash type used to send the initial request to Endpoint 1 should be used in requests to other endpoints. In other words, if a user requests the PDF by sending a MD5 hash to Endpoint 1, they must also use MD5 when downloading the PDF file from Endpoint 3.
When a PDF is initially requested from Endpoint 1, it is created and remains available for download on the appliance for 30 minutes. During this time, users can download it as many times as they want from Endpoint 3. When the report expires, it will no longer be available for download, and should be requested again.
Create PDF Report
GET /api/pdf/{hash}/create
Endpoint 1 accepts a GET request with the required hash parameter. The hash provided in the request should correspond to the hash of an existing sample on the appliance for which the user wants to generate a PDF report. Supported hash types are MD5, SHA1, SHA256. For each sample, the same hash type used to send the initial request to Endpoint 1 should be used in requests to other endpoints.
Sending a request to Endpoint 1 initiates the creation of a PDF analysis report for the requested sample. The response includes links to the Endpoint 2 and Endpoint 3 for the requested sample. Users can then send requests to those endpoints directly, or open them as links in their browser by appending them to the Spectra Analyze appliance host name (for example: https://a1000-example.com/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/status).
Request Format
Request Parameters
| NAME | REQUIRED | DESCRIPTION | TYPE |
|---|---|---|---|
| hash | Required | Hash of the sample for which the user wants to generate a PDF report. The sample must exist on the appliance prior to requesting a PDF report. Supported hash types: SHA1, SHA256, MD5. The same hash type that is used in the initial request to Endpoint 1 must be used in requests to other endpoints. | path, string |
Request Examples
cURL
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/pdf/07dbef34d2996447ffa8e8230f17d538e88f6ad6/create' \
--header 'Authorization: Token exampletoken'
Python
import requests
# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the hostname in the URL
url = f"https://appliance.example.com/api/pdf/{hash_value}/create"
headers = {
"Authorization": f"Token {token}"
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
print(response.text)
Response Format
Response Examples
200 OK
{
"status_endpoint": "/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/status",
"download_endpoint": "/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/download"
}
Response Status Codes
| CODE | DESCRIPTION |
|---|---|
| 200 | Returned on successful requests. |
| 403 | Authentication credentials were not provided. / Invalid API token. |
| 404 | Malformed hash. / Sample does not exist on the appliance. |
Check PDF Report Creation Status
GET /api/pdf/{hash}/status
Endpoint 2 accepts a GET request with the required hash parameter. The hash provided in the request should correspond to the hash used in the request to Endpoint 1, using the same hash type. Supported hash types are MD5, SHA1, SHA256.
Do not send requests to Endpoint 2 before sending the initial PDF creation request to Endpoint 1.
The response includes an informative message about the status of the PDF report previously requested via Endpoint 1. One of the following status messages may be returned in the response:
PDF is ready for download.
PDF does not exist and must be created.
PDF is being created. Please wait.
There was an error creating the PDF.
Request Format
Request Parameters
| NAME | REQUIRED | DESCRIPTION | TYPE |
|---|---|---|---|
| hash | Required | Hash of the sample for which the user wants to generate a PDF report. The sample must exist on the appliance prior to requesting a PDF report. Supported hash types: SHA1, SHA256, MD5. The same hash type that is used in the initial request to Endpoint 1 must be used in requests to other endpoints. | path, string |
Request Examples
cURL
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/pdf/07dbef34d2996447ffa8e8230f17d538e88f6ad6/status' \
--header 'Authorization: Token exampletoken'
Python
import requests
# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the hostname in the URL
url = f"https://appliance.example.com/api/pdf/{hash_value}/status"
headers = {
"Authorization": f"Token {token}"
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
print(response.text)
Response Format
Response Examples
200 OK
{
"status": 2,
"status_message": "PDF is ready for download."
}
The following response is returned if Endpoint 2 is called before Endpoint 1.
200 OK
{
"status": 1,
"status_message": "PDF does not exist and must be created."
}
Response Status Codes
| CODE | DESCRIPTION |
|---|---|
| 200 OK | PDF is ready for download. |
| PDF does not exist and must be created. Returned if the sample exists on the appliance, but the user has not sent the initial PDF creation request to Endpoint 1. | |
| 403 Forbidden | Authentication credentials were not provided. |
| Invalid token. | |
| 404 Not Found | Malformed hash. |
| Sample does not exist on the appliance. |
Download PDF Report
GET /api/pdf/{hash}/download
Endpoint 3 accepts a GET request with the required hash parameter. The hash provided in the request should correspond to the hash used in the request to Endpoint 1 and Endpoint 2, using the same hash type. Supported hash types are MD5, SHA1, SHA256.
Do not send requests to Endpoint 3 before Endpoint 2 indicates that the PDF is ready.
Sending a request to Endpoint 3 starts the download of the PDF analysis report for the requested sample. Users who are sending their requests to Endpoint 3 directly should include an option to save the response as a PDF file (see Request Examples).
Alternatively, users can open the link to Endpoint 3 in their browser (for example: https://a1000-example.com/api/pdf/862adc63da7c3737aad42458e22f99666f47ce0d/download) where they have previously logged into their Spectra Analyze appliance. Depending on the browser settings, the dialog for saving the PDF file will automatically open when they access the link.
Request Format
Request Parameters
| NAME | REQUIRED | DESCRIPTION | TYPE |
|---|---|---|---|
| hash | Required | Hash of the sample for which the user wants to generate a PDF report. The sample must exist on the appliance prior to requesting a PDF report. Supported hash types: SHA1, SHA256, MD5. The same hash type that is used in the initial request to Endpoint 1 must be used in requests to other endpoints. | path, string |
Request Examples
cURL
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/pdf/07dbef34d2996447ffa8e8230f17d538e88f6ad6/download' \
--header 'Authorization: Token exampletoken' \
--output report.pdf
Python
import requests
# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the hostname in the URL
url = f"https://appliance.example.com/api/pdf/{hash_value}/download"
headers = {
"Authorization": f"Token {token}"
}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
with open("report.pdf", "wb") as f:
f.write(response.content)
Response Format
Response Status Codes
| CODE | DESCRIPTION |
|---|---|
| 200 | Returned on successful requests. |
| 403 | Authentication credentials were not provided. / Invalid token. |
| 404 | Malformed hash. |
| 404 | Sample does not exist on the appliance. |
| 404 | PDF does not exist. Returned if the sample exists on the appliance, but the user has not sent the initial PDF creation request to Endpoint 1. |