API Documentation

Version 1.9
Last updated: July 2026

Changelog

Date	Changelog Content
30.07.2026	Added the ability to disable crosschecks between files.
20.07.2026	Added externalId as optional parameter to scans.
30.06.2026	Added private repository file upload endpoints.
25.02.2026	Added excludeIdenticalPaper as optional parameter to the scan endpoint. Default behaviour is unchanged.
21.12.2025	Added highestScore to the scan result.
03.07.2025	Provide a callback URL to get notified when a scan finishes. You can now retrieve an overview of scans for a specific time span.
08.04.2025	AI-Generated images are now detected. We added a new field aiImageCount to the JSON result. You can now also select a minimum confidence score.
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.

Learn how Imagetwin can be used programmatically via a REST API.
Are you already using Imagetwin and want to access the API? Contact us at [email protected] to activate the API.

Authentication

Access to the API requires authentication through a distinctive API key. At 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

Limit:

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, .webp) 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.
IT-crosscheck	file header	Whether to crosscheck this file with other files in this scan. Use this to filter out expected duplicates. Defaults to true.
name	text	(Optional) Custom name of the scan.
title	text	(Optional) Title of the scanned publication. If extractMetadata is enabled, this value overrides the auto-extracted title.
authors	text	(Optional) Author(s) of the scanned publication. If extractMetadata is enabled, this value overrides the auto-extracted authors.
minScore	float	(Optional) A minimum confidence score from 0.0 to 0.9. Detected integrity issues below this score will be ignored in the PDF report and the JSON result, and will be hidden by default in the web application. The default value is 0.33, which includes fair- and high-confidence integrity issues.
callbackUrl	text	(Optional) A URL to which we will send a POST request once the scan is finished.
excludeIdenticalPaper	text	(Optional) If the scanned paper is in our database, the software might detect irrelevant duplicates. If set to true, we exclude duplicates from identical papers in the PDF report and the API response. Allowed values: true, false; Default: false
extractMetadata	text	(Optional) If true, automatically extracts the title and author from uploaded PDF or Word documents for display in the web interface's scan overview. Defaults to false.
externalId	text	(Optional) An arbitrary ID (up to 64 characters) that will be returned by the /result endpoint. Use this to match the scan with data in your own system.
source	text	(Optional) If the scan is performed by a third-party platform or integration, you can set this field to identify the origin (e.g., 'ScholarOne').

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 response is indicated by a 200 OK HTTP status code.

{
   'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',
   'message': 'Scan started successfully.'
}

Callback

If you provided the optional callback URL, we will send a POST request to this URL to inform you that your scan has finished. You can use the callback as an alternative to constantly polling the result endpoint.
The request you receive will be in JSON format. The status will be either finished or failed. Here is an example:

{
   'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',
   'status': 'finished'
}

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 scans. Results are available for 90 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.
aiImageCount	number	Number of potential AI-generated images detected in the provided images.
pdfReport	text	URL to a PDF Report containing the detected duplicates. Accessible for 90 days and contains up to 1000 findings.
resultUrl	text	URL to a web interface displaying all detections, active for 90 days.
minScore	float	The minimum confidence score supplied when submitting the scan. Will be 0.33 if no minScore was defined.
highestScore	float	The highest confidence value of all findings. 0 if nothing was found.
externalId	text (optional)	The value of externalId that was provided to the scan endpoint. Missing if none was provided.

Examples

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

Example response

If the scan is still in progress, a 202 Accepted HTTP status code is returned.
A successful response is indicated by a 200 OK HTTP status code.

{
    'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',
    'alterationCount': 0,
    'localDuplicateCount': 2,
    'externDuplicateCount': 0,
    'aiImageCount': 0,
    'pdfReport': 'https://app.imagetwin.ai/pdfreport/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60.pdf',
    'resultUrl': 'https://app.imagetwin.ai/result/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60',
    'minScore': 0.33,
    'highestScore': 0.99
}

To test different results, use one of the following predefined scanId values:

Scan type	HTTP status code	scanId
Successful scan	200	d904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579
Scan still in progress	202	bbe5489089af902791419a29f3fac98606c43359afc623f852c5e00e10afd0d9
Scan failed	500	21e16e8c71c015715dae4a64b6c12fc5f267b776ebafa27f175e27b48da788fd

Scan Overview

Use this endpoint to retrieve a summary list of scans performed within a specified time span. Scan dates are stored in Coordinated Universal Time (UTC, ±00:00).

Method:

GET

Endpoint:

https://api.imagetwin.ai/v1/scan-overview

Request body payload

Property Name	Type	Description
Authorization Bearer	header	API key used as a bearer token for authentication
startDate	text	Start date in YYYY-MM-DD format. Scans performed on this date are included.
endDate	text	End date in YYYY-MM-DD format. Scans performed on this date are included.
exportFormat	text	(Optional) Format of the response; can be either json (default) or csv.

Examples

curl -X GET https://api.imagetwin.ai/v1/scan-overview?startDate=2023-01-01&endDate=2023-06-30&exportFormat=json -H 'Authorization: Bearer API_Key'

Example response

A successful response is indicated by a 200 OK HTTP status code.

{
    "startDate": "2025-04-10",
    "endDate": "2025-04-12",
    "scans": [
        {
            "scanId": "1625b21d-0492-44b5-83bb-76161ab116eb",
            "scanDate": "2025-04-10T13:54:05",
            "user": "[email protected]",
            "freeOfCharge": false,
            "apiScan": false
        },
        {
            "scanId": "b8218b13-ad59-4f59-8067-d5406732440f",
            "scanDate": "2025-04-10T15:07:23",
            "user": "[email protected]",
            "freeOfCharge": true,
            "apiScan": false
        }
    ]
}

Upload files to private repository

Limits:

Upload either documents (.pdf, .docx, .doc) or images (.jpg, .jpeg, .png, .gif, .jfif, .bmp, .tif, .tiff, .svg., .webp). You can upload up to 50 files per request.

Method:

POST

Content-Type:

multipart/form-data

Endpoint:

https://api.imagetwin.ai/v1/repositories/repositoryId/upload

Request body payload

Property Name	Type	Description
Authorization Bearer	header	API key used as a bearer token for authentication
file	file	The image and document files to upload. Multiple files can be provided.
IT-title	file header	(Optional) Title of the publication. If extractMetadata is enabled, this value overrides the auto-extracted title.
IT-authors	file header	(Optional) Author(s) of the publication. If extractMetadata is enabled, this value overrides the auto-extracted authors.
parent	integer	(Optional) ID of the destination directory inside the repository. Omit to upload into the repository root.
newDirectory	text	(Optional) Name of a subdirectory to create under the parent for storing the uploaded files. If the directory already exists, it is reused.
extractMetadata	text	(Optional) If true, automatically extracts the title and author from uploaded PDF or Word documents for display in the web interface's scan overview. Defaults to false.
ifExists	text	(Optional) If set to 'error' and the filename or file content already exists, the upload will fail. If set to 'allow', the upload will pass regardless of the conflicts. Defaults to 'error'.

Response payload

Property Name	Type	Description
items	array of objects	Repository files created by the upload, including a unique file ID for each file.
indexingTask	text	UUID of the task. Used to track the asynchronous upload progress.
parentId	integer or null	Directory ID that contains the uploaded files.

Examples

Uploading a document.

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

Uploading multiple files with per-file metadata.

curl -X POST "https://api.imagetwin.ai/v1/repositories/repositoryId/upload" \
  -H 'Authorization: Bearer API_Key' \
  -F 'file=@path/to/file1.pdf;headers="IT-title: A study on duplicate detection";headers="IT-authors: Ada Lovelace; Grace Hopper"' \
  -F 'file=@path/to/file2.jpg'

Example response

A successful response is indicated by a 200 OK HTTP status code.

{
  "items": [
    {
      "id": 989,
      "name": "figure-2.png",
      "type": "file",
      "parent": null,
      "size": 143821,
      "title": "",
      "authors": "",
      "createdAt": "2026-01-01T10:32:50Z",
      "createdBy": "[email protected]"
    }
  ],
  "indexingTask": "00000000-0000-4000-8000-000000000002",
  "parentId": null
}

Check status of upload to private repository

Method:

GET

Endpoint:

https://api.imagetwin.ai/v1/repositories/task/indexingTaskId

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
task_id	text	UUID of an asynchronous file indexing task.
task_status	text	State of the task in the processing queue. Possible values are PENDING, PROGRESS, SUCCESS or FAILURE.
result	object or null	Returned result from the task. Contains the error message in case of FAILURE status.
metadata.items	object	Object where keys are the file identifiers and values are the upload state of each file. The states can be 'indexing', 'processing' or 'processed'.

Examples

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

Example response

Response while indexing is still running.

{
    "task_id": "00000000-0000-4000-8000-000000000002",
    "task_status": "PROGRESS",
    "result": null,
    "metadata": {
        "items": {
            "998": "processing",
            "999": "indexing"
        }
    }
}

Response after completion.

{
    "task_id": "00000000-0000-4000-8000-000000000002",
    "task_status": "SUCCESS",
    "result": null,
    "metadata": {}
}

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.
409	Conflict	File already exists in private repository.
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.

Deprecated Endpoints

The following endpoints are deprecated and will not be supported in the future.

Deprecated: Scan a PDF file

Limit:

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

Limit:

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

API Documentation

Authentication

Scan

Limit:

Method:

Content-Type:

Endpoint:

Request body payload

Response payload

Examples

Example response

Callback

Sandbox

Obtain the Result From a Scan

Method:

Content-Type:

Endpoint:

Request body payload

Response payload

Examples

Example response

Scan Overview

Method:

Endpoint:

Request body payload

Examples

Example response

Upload files to private repository​

Limits:

Method:

Content-Type:

Endpoint:

Request body payload

Response payload

Examples

Example response

Check status of upload to private repository

Method:

Endpoint:

Request body payload

Response payload

Examples

Example response

Response Status Codes

Deprecated: Scan a PDF file

Limit:

Method:

Content-Type:

Endpoint:

Request body payload

Response payload

Deprecated: Scan a list of images

Limit:

Method:

Content-Type:

Endpoint:

Request body payload

Response payload

Stay Updated with Imagetwin

Product

Solutions

Resources

Company

Upload files to private repository