API Documentation
Version 1.2 (last update: April 2024)
Changelog
27.04.2024 | Vertical image splicing in gel band images is now detected. We added a new field |
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 a PDF file
Limits: One PDF file under 30 MB with fewer than 50 pages.
Method: POST
Content-Type: multipart/form-data
Endpoint:
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
Example response
{ '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.
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:
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
Example response
{ '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.
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:
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
Example response
{ 'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579', 'alterationCount': 0, 'localDuplicateCount': 2, 'externDuplicateCount': 0, 'pdfReport': 'https://app.imagetwin.ai/pdfreport/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60.pdf', 'resultUrl': 'https://app.imagetwin.ai/result/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60', }
Scan type | HTTP status code | scanId |
---|---|---|
Successful |
200 | d904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579 |
Successful |
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 |
429 | Too Many Requests | The |
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. |