curl --request PUT \
--url https://api.copyleaks.com/v3/scans/submit/file/my-scan-123 \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"base64": "SGVsbG8gd29ybGQh",
"filename": "file.txt",
"properties": {
"webhooks": {
"status": "https://my-server.com/webhook/{STATUS}"
},
"sandbox": true
}
}'
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.document import FileDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
from copyleaks.models.submit.properties.submit_webhooks import SubmitWebhooks
auth_token = Copyleaks.login("[email protected]", "YOUR_API_KEY")
with open("file.txt", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
submission = FileDocument(b64, "file.txt")
submission.set_properties(ScanProperties(
webhooks=SubmitWebhooks(status="https://my-server.com/webhook/{STATUS}"),
sandbox=True,
))
Copyleaks.submit_file(auth_token, "my-scan-123", submission)
const { Copyleaks, CopyleaksFileSubmissionModel } = require('plagiarism-checker');
const fs = require('fs');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const base64Content = fs.readFileSync('file.txt').toString('base64');
const submission = new CopyleaksFileSubmissionModel(base64Content, 'file.txt', {
sandbox: true,
webhooks: { status: 'https://my-server.com/webhook/{STATUS}' },
});
await copyleaks.submitFileAsync(auth, 'my-scan-123', submission);
import classes.Copyleaks;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.file.*;
String authToken = Copyleaks.login("your@email", "API_KEY");
String b64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("file.txt")));
SubmissionWebhooks hooks = new SubmissionWebhooks("https://my-server.com/webhook/{STATUS}");
SubmissionProperties props = new SubmissionProperties(hooks);
props.setSandbox(true);
Copyleaks.submitFile(authToken, "my-scan-123",
new CopyleaksFileSubmissionModel(b64, "file.txt", props));
{
"scannedDocument": {
"scanId": "scan-id32",
"totalWords": 2,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T07:19:08.181236Z",
"metadata": { "filename": "file.txt" },
"detectedLanguage": "en"
},
"results": {
"score": { "aggregatedScore": 50.0, "identicalWords": 1 },
"internet": [
{ "url": "http://example.com/", "id": "2a1b402420", "title": "Example Domain" }
]
},
"status": 0,
"developerPayload": ""
}
Authenticity
Submit File
Scan files to find where the content has been used elsewhere and check its originality.
PUT
/
v3
/
scans
/
submit
/
file
/
{scanId}
curl --request PUT \
--url https://api.copyleaks.com/v3/scans/submit/file/my-scan-123 \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"base64": "SGVsbG8gd29ybGQh",
"filename": "file.txt",
"properties": {
"webhooks": {
"status": "https://my-server.com/webhook/{STATUS}"
},
"sandbox": true
}
}'
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.document import FileDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
from copyleaks.models.submit.properties.submit_webhooks import SubmitWebhooks
auth_token = Copyleaks.login("[email protected]", "YOUR_API_KEY")
with open("file.txt", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
submission = FileDocument(b64, "file.txt")
submission.set_properties(ScanProperties(
webhooks=SubmitWebhooks(status="https://my-server.com/webhook/{STATUS}"),
sandbox=True,
))
Copyleaks.submit_file(auth_token, "my-scan-123", submission)
const { Copyleaks, CopyleaksFileSubmissionModel } = require('plagiarism-checker');
const fs = require('fs');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const base64Content = fs.readFileSync('file.txt').toString('base64');
const submission = new CopyleaksFileSubmissionModel(base64Content, 'file.txt', {
sandbox: true,
webhooks: { status: 'https://my-server.com/webhook/{STATUS}' },
});
await copyleaks.submitFileAsync(auth, 'my-scan-123', submission);
import classes.Copyleaks;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.file.*;
String authToken = Copyleaks.login("your@email", "API_KEY");
String b64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("file.txt")));
SubmissionWebhooks hooks = new SubmissionWebhooks("https://my-server.com/webhook/{STATUS}");
SubmissionProperties props = new SubmissionProperties(hooks);
props.setSandbox(true);
Copyleaks.submitFile(authToken, "my-scan-123",
new CopyleaksFileSubmissionModel(b64, "file.txt", props));
{
"scannedDocument": {
"scanId": "scan-id32",
"totalWords": 2,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T07:19:08.181236Z",
"metadata": { "filename": "file.txt" },
"detectedLanguage": "en"
},
"results": {
"score": { "aggregatedScore": 50.0, "identicalWords": 1 },
"internet": [
{ "url": "http://example.com/", "id": "2a1b402420", "title": "Example Domain" }
]
},
"status": 0,
"developerPayload": ""
}
curl --request PUT \
--url https://api.copyleaks.com/v3/scans/submit/file/my-scan-123 \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"base64": "SGVsbG8gd29ybGQh",
"filename": "file.txt",
"properties": {
"webhooks": {
"status": "https://my-server.com/webhook/{STATUS}"
},
"sandbox": true
}
}'
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.document import FileDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
from copyleaks.models.submit.properties.submit_webhooks import SubmitWebhooks
auth_token = Copyleaks.login("[email protected]", "YOUR_API_KEY")
with open("file.txt", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
submission = FileDocument(b64, "file.txt")
submission.set_properties(ScanProperties(
webhooks=SubmitWebhooks(status="https://my-server.com/webhook/{STATUS}"),
sandbox=True,
))
Copyleaks.submit_file(auth_token, "my-scan-123", submission)
const { Copyleaks, CopyleaksFileSubmissionModel } = require('plagiarism-checker');
const fs = require('fs');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const base64Content = fs.readFileSync('file.txt').toString('base64');
const submission = new CopyleaksFileSubmissionModel(base64Content, 'file.txt', {
sandbox: true,
webhooks: { status: 'https://my-server.com/webhook/{STATUS}' },
});
await copyleaks.submitFileAsync(auth, 'my-scan-123', submission);
import classes.Copyleaks;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.file.*;
String authToken = Copyleaks.login("your@email", "API_KEY");
String b64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("file.txt")));
SubmissionWebhooks hooks = new SubmissionWebhooks("https://my-server.com/webhook/{STATUS}");
SubmissionProperties props = new SubmissionProperties(hooks);
props.setSandbox(true);
Copyleaks.submitFile(authToken, "my-scan-123",
new CopyleaksFileSubmissionModel(b64, "file.txt", props));
{
"scannedDocument": {
"scanId": "scan-id32",
"totalWords": 2,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T07:19:08.181236Z",
"metadata": { "filename": "file.txt" },
"detectedLanguage": "en"
},
"results": {
"score": { "aggregatedScore": 50.0, "identicalWords": 1 },
"internet": [
{ "url": "http://example.com/", "id": "2a1b402420", "title": "Example Domain" }
]
},
"status": 0,
"developerPayload": ""
}
Authentication Required. You need to login with a user and API key in order to access this method. Add this HTTP header to your request:Authorization: Bearer <Your-Login-Token>
Request
Path Parameters
A unique scan id provided by you. We recommend you use the same id in your database to represent the scan in the Copyleaks database. This will help you to debug incidents. Using the same ID for the same file will help you to avoid network problems that may lead to multiple scans for the same file. Learn more about the criteria for creating a Scan ID.
>= 3 characters <= 36 charactersMatch pattern: [a-z0-9] !@$^&-+%=_(){}<>';:/.",~`|Headers
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
Request Body
The request body is a JSON object containing the file to scan.A base64 data string of a file. If you would like to scan plain text, encode it as base64 and submit it.Example:
aGVsbG8gd29ybGQ=The name of the file as it will appear in the Copyleaks scan report Make sure to include the right extension for your filetype.
<= 255 characters
Example: Myfile.pdfConfiguration options for the scan.
Show properties
Show properties
The type of submission action.
0: Scan - Start scan immediately.1: Check-Credits - Check how many credits will be used for this scan.2: Index Only - Only index the file in the Copyleaks internal database or Copyleaks Repository (depends on your submit request). No credits will be used.
By default, Copyleaks will present the report in text format. If set to
true, Copyleaks will also include html format.true: results will be generated as HTML format, if possible. Otherwise, it will be generated as text format.false: results will be generated as text format.
Add custom developer payload that will then be provided on the webhooks.
<= 512 charactersYou can test the integration with the Copyleaks API for free using the sandbox mode.You will be able to submit content for a scan and get back mock results, simulating the way Copyleaks will work to make sure that you successfully integrated with the API.Turn off this feature on production environment.Rate Limiting: This method has a maximum call rate limit of 100 sandbox scans within 1 hour.
Specify the maximum life span of a scan in hours on the Copyleaks servers. When expired, the scan will be deleted and will no longer be accessible.
>= 1 <= 2880Choose the algorithm goal. You can set this value depending on your use-case.
- 0 - MaximumCoverage: prioritize higher similarity score.
- 1 - MaximumResults: prioritize finding more sources.
Add custom properties that will be attached to your document in a Copyleaks repository.If this document is found as a repository result, your custom properties will be added to the result.Example:
[
{ "key": "Test1", "value": "Test1" }
]
When specified, the PDF report will be generated in the selected language. Future updates may also apply this setting to the overview and other components.Currently supported languages:
| Code | Language |
|---|---|
en | English |
es | Spanish |
de | German |
fr | French |
it | Italian |
pt | Portuguese |
Specify the timezone for the scan time displayed on the final PDF report. The value must be a valid, case-sensitive IANA Time Zone name (e.g., America/New_York). If unspecified, the timezone defaults to the user’s country, or UTC if their country is unknown.Available Options: see the full list of IANA Time Zones.
You can control the level of plagiarism sensitivity that will be identified according to the speed of the scan. If you prefer a faster scan with the results that contains the highest amount of plagiarism choose 1, and if a slower, more comprehensive scan, that will also detect the smallest instances choose 5.Range between 1 (faster) to 5 (slower but more comprehensive).
When set to true the submitted document will be checked for cheating. If a cheating will be detected, a scan alert will be added to the completed webhook.
Show assignment properties
Show assignment properties
A unique assignment identifier for tracking analytics.
Show institution properties
Show institution properties
A unique institution identifier for tracking analytics.
The
webhooks object is where you define the callback URLs for Copyleaks to send notifications to. This object is required.Show webhooks properties
Show webhooks properties
A URL that will be called when the scan status changes. Use the
{STATUS} placeholder, which will be replaced with completed, error, creditsChecked, or indexed. Example: https://yoursite.com/webhook/{STATUS}A URL that will be called when a new result is found during the scan.
Custom headers to add to the
newResult webhook. Example: [["key", "value"]]Custom headers to add to the
status webhook. Example: [["key", "value"]]Fine-tune what kind of results are included in the scan report.
Show filters properties
Show filters properties
Enable matching of exact words.
Enable matching of nearly identical words (e.g., slow/slowly).
Enable matching of paraphrased content.
Only show results with at least this many copied words.
Block explicit adult content from scan results.
A list of domains to include or exclude from the scan.
0 to include domains, 1 to exclude them.Allow results from the same domain as the submitted URL.
Define the sources to compare your document against.
Show scanning properties
Show scanning properties
Compare your content with online sources.
Show exclude properties
Show exclude properties
Exclude submissions from results if their ID matches the supplied pattern. Matched submissions will be excluded from both internal database and repository results.Supported pattern wildcards:
*- Matches any number of characters (including zero).- Matches exactly one non-whitespace character
abc*- Excludes submissions with IDs starting with “abc”ab..- Excludes submissions with exactly 4-character IDs starting with “ab”
Exclude results that contain backlinks to these specific domains. Maximum 10 domains. Each domain: 1-256 characters.
Exclude any results that contain text matching these phrases. Maximum 5 text phrases. Each phrase: 1-30 characters.
Show include properties
Show include properties
Includes results only if their scan id matches the supplied pattern. Matched submissions will be the only submissions Included from internal database and repositories results.
Specify which repositories to scan the document against.
Show repository properties
Show repository properties
Id of a repository to scan the submitted document against.
Compare the scanned document against MY submissions in the repository.
Compare the scanned document against OTHER users submissions in the repository.
Configure scanning against the Copyleaks Shared Data Hub.
Show copyleaksDb properties
Show copyleaksDb properties
When true: Copyleaks will also compare against content which was uploaded by YOU to the Copyleaks internal database. If true, it will also index the scan in the Copyleaks internal database.
When true: Copyleaks will also compare against content which was uploaded by OTHERS to the Copyleaks internal database.
Configure cross-language plagiarism detection.
Show crossLanguages properties
Show crossLanguages properties
Cross language plagiarism detection. Choose which languages to scan your content against. For each additional language chosen, your pages will be deducted per page submitted. The language of the original document submitted is always scanned, therefore should not be included in the additional languages chosen. Supported languages list.
Show language properties
Show language properties
Language code for cross language plagiarism detection.
Configure what content to exclude from the scan.
Show exclude properties
Show exclude properties
Exclude quoted text from the scan.
Exclude citations from the scan.
Exclude referenced text from the scan.
Exclude table of contents from the scan.
When the scanned document is an HTML document, exclude titles from the scan.
When the scanned document is an HTML document, exclude irrelevant text that appears across the site like the website footer or header.
Exclude template text found in other documents. Provide an array of scan IDs (max 3).
Configure and request a PDF report of the scan results.
Show pdf properties
Show pdf properties
Set to true to generate a PDF report for this scan.
Customize the title for the PDF report (max 256 chars).
A base64 encoded PNG image (max 100kb) to use as a logo in the report.
When set to true the text in the report will be aligned from right to left.
Deprecated - use
reportVersion. PDF version to generate (1, 2, or 3).Specifies which version of the PDF report to generate (
v1, v2, v3, latest). Overrides version.Customize the highlight colors used in the PDF report.
Show colors properties
Show colors properties
Change the color of titles in the PDF. Format: Color in HEX format.
Change the color of identical match highlights in the PDF.
Change the color of minor changes highlights in the PDF.
Change the color of related meaning (paraphrased) highlights in the PDF.
Change the color of AI content detection highlights in the PDF.
Change the color of writing feedback highlights in the PDF.
Configure AI-generated text detection.
Mask sensitive data from the scanned document with
# characters. Available for users on a plan for 2500 pages or more.Show sensitiveDataProtection properties
Show sensitiveDataProtection properties
Mask driver’s license numbers (supports Australia, Canada, UK, USA, Japan, Spain, Germany).
Mask credentials such as authentication tokens, AWS/Azure/GCP keys, JWTs, passwords, etc.
Mask passport numbers across many countries.
Mask network identifiers (IP address, MAC address, local MAC address).
Mask URLs from the scanned document.
Mask email addresses from the scanned document.
Mask credit card numbers and credit card track numbers.
Mask phone numbers from the scanned document.
Configure the automated Grammar Checker.
Show writingFeedback properties
Show writingFeedback properties
Enable automated Grammar Checker for grammar, spelling, etc.
Configure the weighting of different categories in the overall writing score.
Show score properties
Show score properties
Grammar correction category weight. Range:
0.0 to 1.0.Mechanics correction category weight. Range:
0.0 to 1.0.Sentence structure correction category weight. Range:
0.0 to 1.0.Word choice correction category weight. Range:
0.0 to 1.0.Enable Gen-AI Overview feature to extract key insights from the scan data.
Show overview properties
Show overview properties
Enable Gen-AI Overview feature to extract key insights from the scan data.
Ignore AI detection when generating the scan’s overview.
Ignore plagiarism detection when generating the scan’s overview.
Ignore Grammar Checker when generating the scan’s overview.
Ignore the author’s historical data when generating the scan’s overview.
The AI Source Match feature enhances plagiarism detection by identifying online sources that are suspected of containing AI-generated text.
Show aiSourceMatch properties
Show aiSourceMatch properties
Activates the AI Source Match functionality.
The Internal AI Source Match feature enhances plagiarism detection by identifying sources in the Copyleaks internal AI database that contain AI-generated text.
Show internalAiSourceMatch properties
Show internalAiSourceMatch properties
Activates the Internal AI Source Match functionality.
Validate the references and citations found in the submitted text with the References Validation feature.
Show references properties
Show references properties
Detect, parse, and validate every reference in the submitted text.
For testing purposes, use sandbox mode, which does not consume credits.
Responses
- 201
- 400
- 401
- 409
- 429
201 Created - The scan was successfully created and is now processing.
{
"scannedDocument": {
"scanId": "scan-id32",
"totalWords": 2,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T07:19:08.181236Z",
"metadata": {
"filename": "file.txt"
},
"enabled": {
"plagiarismDetection": true,
"aiDetection": false,
"explainableAi": false,
"writingFeedback": false,
"pdfReport": true,
"cheatDetection": false,
"referencesValidation": false,
"aiSourceMatch": false,
"internalAiSourceMatch": false
},
"detectedLanguage": "en"
},
"results": {
"score": {
"identicalWords": 1,
"minorChangedWords": 0,
"relatedMeaningWords": 0,
"aggregatedScore": 50.0
},
"internet": [
{
"url": "http://example.com/",
"id": "2a1b402420",
"title": "Example Domain",
"introduction": "Example Domain This domain is for use in illustrative examples in documents. You may use this domain in literature without...",
"matchedWords": 1,
"identicalWords": 1,
"similarWords": 0,
"paraphrasedWords": 0,
"totalWords": 28,
"metadata": {
"authors": []
},
"tags": []
}
],
"database": [],
"batch": [],
"repositories": [],
"internalAIData": []
},
"notifications": {
"alerts": [
{
"code": "suspected-ai-text",
"title": "Potential AI-Generated Text Detected",
"message": "We are unable to verify that the text was written by a human.",
"severity": 4,
"additionalData": "{\"results\": [{\"classification\": 2, \"probability\": 0.7307997032499992, \"matches\": [ {\"text\": {\"chars\": {\"starts\": [0], \"lengths\": [1453]}, \"words\": {\"starts\": [0], \"lengths\": [230]}}}]}], \"summary\": {\"human\": 0.0, \"ai\": 1.0}, \"modelVersion\": \"v8.0\"}",
"category": 2
}
]
},
"writingFeedback": {
"textStatistics": {
"sentenceCount": 5,
"averageWordLength": 4.7,
"averageSentenceLength": 12.8,
"readingTimeSeconds": 21.0,
"speakingTimeSeconds": 29.5
},
"score": {
"grammarCorrectionsCount": 1,
"grammarCorrectionsScore": 93,
"grammarScoreWeight": 1.0,
"mechanicsCorrectionsCount": 1,
"mechanicsCorrectionsScore": 93,
"mechanicsScoreWeight": 1.0,
"sentenceStructureCorrectionsCount": 1,
"sentenceStructureCorrectionsScore": 93,
"sentenceStructureScoreWeight": 1.0,
"wordChoiceCorrectionsCount": 0,
"wordChoiceCorrectionsScore": 100,
"wordChoiceScoreWeight": 1.0,
"overallScore": 94
},
"readability": {
"score": 95,
"readabilityLevel": 1,
"readabilityLevelText": "5th Grader",
"readabilityLevelDescription": "Very easy to read"
}
},
"status": 0,
"developerPayload": ""
}
400 Bad Request - The filename field is required.
401 Unauthorized - Authentication failed or API key is invalid.
409 Conflict - A scan with the same Id already exists in the system.
429 Too Many Requests - Rate limit exceeded. Please retry after the specified time.
⌘I