API Documentation

Version 1.3 (last update: December 2024)

03.12.2024 Added the new endpoint scan for scanning documents and images. Deprecated scanPdf and scanImages
27.04.2024 Vertical image splicing in gel band images is now detected. We added a new field alterationCount to the JSON result indicating the number of detected image alterations, such as splicing.
11.11.2023 A PDF report containing the findings of a conducted scan can now be downloaded.
03.10.2023 API launched

This document explains how Imagetwin’s screening service is used programmatically via a REST API.

Are you already using Imagetwin and want to access the API? Contact us at [email protected].

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

Limits: Either one document (.pdf, .docx) under 30 MB with fewer than 50 pages or up to 25 images (.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/scan

Request body payload

Property Name Type Description
Authorization Bearer header API key used as a bearer token for authentication
file file PDF or image files to scan. In case of scanning images, multiple files can be provided.

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

Examples

Scanning a document

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

Scanning images

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

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/scan -H 'Authorization: Bearer API_Key' -F file=@'path/to/file.pdf'

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.
alterationCount number Number of alterations (e.g., image splicing) detected in the provided images.
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',
    'alterationCount': 0, 
    '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 scan 200 d904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579
Scan still in progress 202 bbe5489089af902791419a29f3fac98606c43359afc623f852c5e00e10afd0d9
Scan failed 500 21e16e8c71c015715dae4a64b6c12fc5f267b776ebafa27f175e27b48da788fd

Deprecated: Scan a PDF file

Deprecation Notice: this endpoint is deprecated and will not be updated. Please use the scan endpoint instead.

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

Deprecated: Scan a list of images

Deprecation Notice: this endpoint is deprecated and will not be updated. Please use the scan endpoint instead.

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

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 scan endpoint allows 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.
504 Internal Server Error The service is currently unavailable or under maintenance.