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
string
required
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.string
required
A base64 data string of a file. If you would like to scan plain text, encode it as base64 and submit it.Example:
aGVsbG8gd29ybGQ=string
required
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.pdfobject
required
Configuration options for the scan.
Show properties
Show properties
integer
default:"0"
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.
boolean
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.
string
default:"null"
Add custom developer payload that will then be provided on the webhooks.
<= 512 charactersboolean
default:"false"
You 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.
integer
default:"2880"
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 <= 2880integer
default:"0"
Choose 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.
array
default:"[]"
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" }
]
string
default:"en"
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 |
string
default:"User's country timezone"
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.
integer
default:"3"
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).
boolean
default:"false"
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.
object
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
string
required
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}string
A URL that will be called when a new result is found during the scan.
array
Custom headers to add to the
newResult webhook. Example: [["key", "value"]]array
Custom headers to add to the
status webhook. Example: [["key", "value"]]object
Fine-tune what kind of results are included in the scan report.
Show filters properties
Show filters properties
boolean
default:"true"
Enable matching of exact words.
boolean
default:"true"
Enable matching of nearly identical words (e.g., slow/slowly).
boolean
default:"true"
Enable matching of paraphrased content.
integer
Only show results with at least this many copied words.
boolean
default:"false"
Block explicit adult content from scan results.
array
default:"[]"
A list of domains to include or exclude from the scan.
integer
default:"1"
0 to include domains, 1 to exclude them.boolean
default:"false"
Allow results from the same domain as the submitted URL.
object
Define the sources to compare your document against.
Show scanning properties
Show scanning properties
boolean
default:"true"
Compare your content with online sources.
object
Show exclude properties
Show exclude properties
string
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”
array[string]
Exclude results that contain backlinks to these specific domains. Maximum 10 domains. Each domain: 1-256 characters.
array[string]
Exclude any results that contain text matching these phrases. Maximum 5 text phrases. Each phrase: 1-30 characters.
object
Show include properties
Show include properties
string
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.
array[object]
default:"[]"
Specify which repositories to scan the document against.
object
Configure scanning against the Copyleaks Shared Data Hub.
Show copyleaksDb properties
Show copyleaksDb properties
boolean
default:"true"
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.
boolean
default:"true"
When true: Copyleaks will also compare against content which was uploaded by OTHERS to the Copyleaks internal database.
object
Configure cross-language plagiarism detection.
Show crossLanguages properties
Show crossLanguages properties
array[object]
default:"[]"
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
string
Language code for cross language plagiarism detection.
object
object
Configure what content to exclude from the scan.
Show exclude properties
Show exclude properties
boolean
default:"false"
Exclude quoted text from the scan.
boolean
default:"false"
Exclude citations from the scan.
boolean
default:"false"
Exclude referenced text from the scan.
boolean
default:"false"
Exclude table of contents from the scan.
boolean
default:"false"
When the scanned document is an HTML document, exclude titles from the scan.
boolean
default:"false"
When the scanned document is an HTML document, exclude irrelevant text that appears across the site like the website footer or header.
array
default:"[]"
Exclude template text found in other documents. Provide an array of scan IDs (max 3).
object
Configure and request a PDF report of the scan results.
Show pdf properties
Show pdf properties
boolean
default:"false"
Set to true to generate a PDF report for this scan.
string
Customize the title for the PDF report (max 256 chars).
string
A base64 encoded PNG image (max 100kb) to use as a logo in the report.
boolean
default:"false"
When set to true the text in the report will be aligned from right to left.
integer
default:"1"
Deprecated - use
reportVersion. PDF version to generate (1, 2, or 3).string
default:"latest"
Specifies which version of the PDF report to generate (
v1, v2, v3, latest). Overrides version.object
Customize the highlight colors used in the PDF report.
Show colors properties
Show colors properties
string
default:"#040F21"
Change the color of titles in the PDF. Format: Color in HEX format.
string
default:"#FE5758"
Change the color of identical match highlights in the PDF.
string
default:"#FE8888"
Change the color of minor changes highlights in the PDF.
string
default:"#FDD0A3"
Change the color of related meaning (paraphrased) highlights in the PDF.
string
default:"#FE5758"
Change the color of AI content detection highlights in the PDF.
string
default:"#FF9A02"
Change the color of writing feedback highlights in the PDF.
object
object
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
boolean
default:"false"
Mask driver’s license numbers (supports Australia, Canada, UK, USA, Japan, Spain, Germany).
boolean
default:"false"
Mask credentials such as authentication tokens, AWS/Azure/GCP keys, JWTs, passwords, etc.
boolean
default:"false"
Mask passport numbers across many countries.
boolean
default:"false"
Mask network identifiers (IP address, MAC address, local MAC address).
boolean
default:"false"
Mask URLs from the scanned document.
boolean
default:"false"
Mask email addresses from the scanned document.
boolean
default:"false"
Mask credit card numbers and credit card track numbers.
boolean
default:"false"
Mask phone numbers from the scanned document.
object
Configure the automated Grammar Checker.
Show writingFeedback properties
Show writingFeedback properties
boolean
default:"false"
Enable automated Grammar Checker for grammar, spelling, etc.
object
Configure the weighting of different categories in the overall writing score.
Show score properties
Show score properties
number
default:"1.0"
Grammar correction category weight. Range:
0.0 to 1.0.number
default:"1.0"
Mechanics correction category weight. Range:
0.0 to 1.0.number
default:"1.0"
Sentence structure correction category weight. Range:
0.0 to 1.0.number
default:"1.0"
Word choice correction category weight. Range:
0.0 to 1.0.object
Enable Gen-AI Overview feature to extract key insights from the scan data.
Show overview properties
Show overview properties
boolean
default:"false"
Enable Gen-AI Overview feature to extract key insights from the scan data.
boolean
default:"false"
Ignore AI detection when generating the scan’s overview.
boolean
default:"false"
Ignore plagiarism detection when generating the scan’s overview.
boolean
default:"false"
Ignore Grammar Checker when generating the scan’s overview.
boolean
default:"false"
Ignore the author’s historical data when generating the scan’s overview.
object
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
boolean
default:"false"
Activates the AI Source Match functionality.
object
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
boolean
default:"false"
Activates the Internal AI Source Match functionality.
object
Check the references and citations found in the submitted text with the Citation Checker feature.
Show references properties
Show references properties
boolean
default:"false"
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