API Documentation

Version 1.1 Beta (last update: November 2023)

  • 11.11.2023: A PDF report containing the findings of a conducted scan can now be downloaded.
  • 3.10.2023: Launched the API.

This document explains how Imagetwin’s screening service is used programmatically via a REST API. The API is currently in beta state and only enabled for a few selected users. Please contact us if you are interested in participating.

Authentication

Access to the API requires authentication through a distinctive API key. At https://app.imagetwin.ai/account, you can generate a new API key or delete a previously generated key. Per user, one API key can be active. Generating a new key invalidates the previous one.

Scan a PDF file

Limits: One PDF file under 30 MB with fewer than 50 pages.

Method: POST

Content-Type: multipart/form-data

Endpoint:

https://api.imagetwin.ai/v1/scanPdf

Request body payload

Property Name Type Description
Authorization Bearer header API key used as a bearer token for authentication
pdfFile file PDF file to scan

Response payload

Property Name Type Description
scanId text A unique ID associated with the performed scan
message text A message indicating that the scan was started successfully

Example

curl -X POST https://api.imagetwin.ai/v1/scanPdf -H 'Authorization: Bearer API_Key' -F pdfFile=@'path/to/file.pdf'

Example response

A successful request is indicated by a 200 OK HTTP status code. 
{
   'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',
   'message': 'Scan started successfully.'
}

Sandbox

Use the sandbox as a safe environment to test your API calls. Calls to the sandbox are free of charge and return predefined responses.

curl -X POST https://api.imagetwin.ai/v1/sandbox/scanPdf -H 'Authorization: Bearer API_Key' -F pdfFile=@'path/to/file.pdf'

Scan a list of images

Limits: Up to 25 image files (.jpg, .jpeg, .png, .gif, .jfif, .bmp, .tif, .tiff, .svg.) under 20 MB each.

Method: POST

Content-Type: multipart/form-data

Endpoint:

https://api.imagetwin.ai/v1/scanImages

Request body payload

Property Name Type Description
Authorization Bearer header API key used as a bearer token for authentication
imageFile file Image file to scan. Multiple images can be added to a single request.

Response payload

Property Name Type Description
scanId text A unique ID associated with the performed scan
message text A message indicating that the scan was started successfully

Example

curl -X POST https://api.imagetwin.ai/v1/scanImages -H 'Authorization: Bearer API_Key' -F imageFile=@'path/to/file1.png' -F imageFile=@'path/to/file2.jpg'

Example response

A successful request is indicated by a 200 OK HTTP status code. 
{
   'scanId': '6ec90027ee710cd153924e84fee89bbcbf5142a6f38edf017d70c5c6bcb0cbc8',
   'message': 'Scan started successfully.'
}

Sandbox

Use the sandbox as a safe environment to test your API calls. Calls to the sandbox are free of charge and return predefined responses.

curl -X POST https://api.imagetwin.ai/v1/sandbox/scanImages -H 'Authorization: Bearer API_Key' -F imageFile=@'path/to/file1.png' -F imageFile=@'path/to/file2.jpg'

Obtain the result from a scan

Use this endpoint to obtain results from previous scanPdf and scanImages calls. Results are available for 30 days after performing the scan.

Method: GET

Content-Type: multipart/form-data

Endpoint:

https://api.imagetwin.ai/v1/result/scanId

Request body payload

Property Name Type Description
Authorization Bearer header API key used as a bearer token for authentication

Response payload

Property Name Type Description
scanId text A unique ID associated with the performed scan.
localDuplicateCount number Number of duplicates detected within and between the provided images.
externDuplicateCount number Number of duplicates detected between the provided images and our reference database.
pdfReport text URL to a PDF Report containing the detected duplicates. Accessible for 30 days and contains up to 500 duplicates.
resultUrl text URL to a web interface displaying all detections, active for 30 days.

Example

curl -X GET https://api.imagetwin.ai/v1/result/scanId -H 'Authorization: Bearer API_Key'

Example response

A successful request is indicated by a 200 OK HTTP status code.
If the scan is still in progress, a 202 Accepted HTTP status code is returned. 
{
    'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',
    'localDuplicateCount': 2,
    'externDuplicateCount': 0,
    'pdfReport': 'https://app.imagetwin.ai/pdfreport/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60.pdf',
    'resultUrl': 'https://app.imagetwin.ai/result/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60',
}
To test different results, use one of the following predefined scanId
Scan type HTTP status code scanId
Successful scanPdf 200 d904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579
Successful scanImages 200 6ec90027ee710cd153924e84fee89bbcbf5142a6f38edf017d70c5c6bcb0cbc8
Scan still in progress 202 bbe5489089af902791419a29f3fac98606c43359afc623f852c5e00e10afd0d9
Scan failed 500 21e16e8c71c015715dae4a64b6c12fc5f267b776ebafa27f175e27b48da788fd

Response status codes

HTTP status code Type Description
200 OK Response for successful HTTP requests.
202 Accepted The request has been accepted for processing, but has not been completed.
400 Bad Request The request body payload might be invalid, or the request limitations are exceeded.
401 Unauthorized Unauthorized to use the requested endpoint. Make sure that you are using a valid API key.
404 Not Found No result found for the provided scanId.
429 Too Many Requests The scanPdf and scanImages endpoints allow 20 requests per minute. The result endpoint allows 60 requests per minute.
500 Internal Server Error A server error occurred during processing the provided data.
503 Internal Server Error The service is currently unavailable or under maintenance.