> For the complete documentation index, see [llms.txt](https://user-manual.imagetwin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://user-manual.imagetwin.ai/api-documentation-1/api-documentation.md).

# API Documentation

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">How can we help?</button><a href="https://imagetwin.ai/contact/" class="button primary" data-icon="paper-plane">Contact support</a>

***

### <mark style="color:$primary;">How to Create an API key</mark>

The API Access section allows developers to integrate Imagetwin's screening service programmatically into external workflows using a REST API.

**Follow these steps to enable and generate your API key:**

1. Request Activation: Contact your Account Manager to enable API access for your organization.
2. Navigate to Settings: Once activated, log into your account and navigate to the Account tab.

<div align="left"><img src="/files/p9uyLJ7EciL9Ou741psZ" alt="" height="181" width="215"></div>

3. Locate API Access: Scroll to the bottom of the page to find the API Access section.
4. Generate the Key: Click the Generate API Key button to create your unique authentication token.

⚠️ **Important:** Keep your API key secure and do not share it. For technical details on implementation, click the API documentation link provided directly in this section

<div align="left"><img src="/files/Q0quSV56Z5oA1qwO8xSM" alt="" height="72" width="602"></div>

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 <contact@imagetwin.ai> to activate the API.

### <mark style="color:$primary;">Authentication</mark>

Access to the API requires authentication through a distinctive API key. At [app.imagetwin.ai/account](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.

### <mark style="color:$primary;">Scan</mark>

**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.                                                                                                                                                                                                                                                                          |
| minScore              | float  | (Optional) A minimum [confidence score](https://imagetwin.ai/posts/introducing-confidence-scores) 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                                                                                                             |

**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.

{

&#x20;  'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',

&#x20;  '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:

{

&#x20;  'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',

&#x20;  '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'

### <mark style="color:$primary;">Obtain the Result From a Scan</mark>

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.                                            |

**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.

{

&#x20;   'scanId': 'd904c90756d6653f27ce9fc27847a5bf61e35b4cb288d0a301e879cbef3e4579',

&#x20;   'alterationCount': 0,

&#x20;   'localDuplicateCount': 2,

&#x20;   'externDuplicateCount': 0,

&#x20;   'aiImageCount': 0,

&#x20;   'pdfReport': '<https://app.imagetwin.ai/pdfreport/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60.pdf>',

&#x20;   'resultUrl': '<https://app.imagetwin.ai/result/e590ff7414eef232b52c990ab15773e58c5ad9965340b8f3461531d047184a60>',

&#x20;   'minScore': 0.33,

&#x20;   '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 |

### <mark style="color:$primary;">Scan Overview</mark>

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.

{

&#x20;   "startDate": "2025-04-10",

&#x20;   "endDate": "2025-04-12",

&#x20;   "scans": \[

&#x20;       {

&#x20;           "scanId": "1625b21d-0492-44b5-83bb-76161ab116eb",

&#x20;           "scanDate": "2025-04-10T13:54:05",

&#x20;           "user": "<user@example.com>",

&#x20;           "freeOfCharge": false,

&#x20;           "apiScan": false

&#x20;       },

&#x20;       {

&#x20;           "scanId": "b8218b13-ad59-4f59-8067-d5406732440f",

&#x20;           "scanDate": "2025-04-10T15:07:23",

&#x20;           "user": "<user@example.com>",

&#x20;           "freeOfCharge": true,

&#x20;           "apiScan": false

&#x20;       }

&#x20;   ]

}

### <mark style="color:$primary;">**Response Status Codes**</mark>

| 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.                                          |

Deprecated Endpoints&#x20;

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

#### <mark style="color:$primary;">Deprecated: Scan a PDF file</mark>

**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>

#### <mark style="color:$primary;">Request body payload</mark>

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

#### <mark style="color:$primary;">Response payload</mark>

| 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 |

#### <mark style="color:$primary;">Deprecated: Scan a list of images</mark>

**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>

#### <mark style="color:$primary;">Request body payload</mark>

| 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. |

#### <mark style="color:$primary;">Response payload</mark>

| 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 |

<br>