Copyleaks API Tutorial
Copyleaks API gives you access to a variety of plagiarism detection technologies to protect your online content. Get the most comprehensive plagiarism report for your content that is easy to use and integrate with your services.
In this document:
- Sign up for Copyleaks
- Get your API-Key
- Login to the API
- Create a new process
- Get the process status
- Get the scan results of your process
Get Prepared
Sign up for Copyleaks
Sign up , and click the link on the confirmation email.
Get your API key
Once you are registred, login to the API site and get your API key by going to your Dashboard ( Businesses dashboard / Academic dashboard ). You can see your keys on the ‘access keys’ section.
You can hit the “refresh” next to the key to create new API keys for your account.
Once you have updated all of your services with your new key you can cancel the second key.
You now have all the necessary information (email and API key) in order to identify yourself to the Copyleaks Authorization System.
Start Using The API
Copyleaks API follows REST architectural style and according to the following rules:
- All requests and responses are UTF8 encoded.
- Requests content-type could be JSON (application/json) or XML (application/xml).
- Base API Address:
https://api.copyleaks.com.
The basic user flow when using Copyleaks API:
Login to the API
The interaction with the Copyleaks API is through processes the users send to the Copyleaks cloud. Each scan request will create a new independent process.
In order to create new processes you need to first login to the API and then get back your API token. Do so by using the /v1/account/login-api method with your email and API-Key you created in the previous steps. Receive back the API token which will be your identification when creating new processes.
Technical information - POST /v1/account/login .
You can generate more than one security token (multiple calls to Login method). There is no way to de-activate an existing security token, it will stay active until its expiration date.
After calling the /v1/account/login-api method and getting back the security token, you can access members only API methods.
This can be done by adding the "Authorization" HTTP-Header to the HTTP-Request:
Authorization: Bearer <Your-Token-Here>
Read more about "Authorization" header .
Create a new process
There are four ways to create a process on the Copyleaks system:
- Scan URL - by calling the method
/v1/businesses/create-by-url(for Businesses API) or/v1/education/create-by-url(for Education API) with a valid URL to scan.Usage ExampleSubmitting the URL http://example.com/ for a plagiarism check.
HTTP POST Request to
/v1/businesses/create-by-urlor/v1/education/create-by-urlwith the body:{ "Url": "http://example.com/" }The HTTP-Response:
{ "ProcessId:" "daa6e2fb-6e84-4c75-be94-dd088159dd4c" "CreationTimeUTC": "01/01/2016 18:36:10" }Technical information - Businesses API: POST /v1/businesses/create-by-url , Education API: POST /v1/education/create-by-url .
Scan File - by calling the method
/v1/businesses/create-by-fileor/v1/education/create-by-filewith a valid file containing the content you wish to scan for plagiarism.Technical information - Businesses API: POST /v1/businesses/create-by-file , Education API: POST /v1/education/create-by-file .
Scan picture with text - by calling the method
/v1/businesses/create-by-file-ocror/v1/education/create-by-file-ocrwith a valid file containing picture with textual content you wish to scan for plagiarism.Technical information - Businesses API: POST /v1/businesses/create-by-file-ocr , Education API: POST /v1/education/create-by-file-ocr .
Scan text - by calling the method
/v1/businesses/create-by-textor/v1/education/create-by-textwith raw text you wish to scan for plagiarism.Technical information - Businesses API: POST /v1/businesses/create-by-text or Education API: POST /v1/education/create-by-text .
Receive back a unique process ID which will be the identification to this specific process.
Managing HTTP Callbacks .
Get the process status
Check the current scan status by calling the method /v1/businesses/{ProcessId}/status (for Businesses API) or /v1/education/{ProcessId}/status (for Education API) with the specific Process ID. The status continuously updates until the scan results are ready to view.
There are two possible statuses - 'processing' and 'completed'.
To check the status of your specific process on the servers (in this exmple the process id is 'daa6e2fb-6e84-4c75-be94-dd088159dd4c'), send GET request to the address /v1/businesses/daa6e2fb-6e84-4c75-be94-dd088159dd4c/status or /v1/education/daa6e2fb-6e84-4c75-be94-dd088159dd4c/status .
There are two possible results:
- When the processing isn't complete yet:
{ Status: "processing" } - When the processing is complete:
{ Status: "completed" }
The average process finishes in less than 60 seconds. So, calling the ‘Status’ method once every few seconds is enough. Also, You can always use call-backs and get notified automatically once the results are ready.
Technical information - Businesses API: GET v1/businesses/{ProcessId}/status , Education API: GET v1/education/{ProcessId}/status .
Get the scan results of your process
Once the status is "completed", which means the results are ready to view, call the method /v1/businesses/{ProcessId}/result (Businesses API) or /v1/education/{ProcessId}/result (Education API) with your Process ID to get a full plagiarism report for your submited request. We will keep the results on the Copyleaks servers for until they expire. See expire policy on the Technical Specification page. They will be deleted after so you should save the results locally before.
In case of an error, you will receive information about why it occurred.
To get the scan results of your specific process send a HTTP-GET request to the address /v1/businesses/daa6e2fb-6e84-4c75-be94-dd088159dd4c/result or /v1/education/daa6e2fb-6e84-4c75-be94-dd088159dd4c/result (in this exmple the process id is 'daa6e2fb-6e84-4c75-be94-dd088159dd4c').
There are two possible results:
- Successful scan. For example, the servers found one suspected copy:
[ { "URL":"http://example.com/", "Percents":14, "NumberOfCopiedWords":15, "ComparisonReport":"https://api.copyleaks.com/v1/downloads/comparison?rid=1493025", "CachedVersion":"https://api.copyleaks.com/v1/downloads/result-text?rid=1493025", "Title":"Title of the file", "Introduction":"This is how the text starts.", "EmbededComparison":"https://copyleaks.com/compare-embed/d69167b7-670b-491f-827f-46ba5ffd43a0/1493025" } ] - Scan Failure: When Copyleaks servers return a status that is different than HTTP success status (200)
Technical information - For Businesses: GET v1/businesses/{ProcessId}/result , For Education: GET v1/education/{ProcessId}/result .
Comparison Report
You will get, as part of your results, a visual comparison report you can embed in your platform showing the similar parts, along with the relevant statistics.You can embed the comparison report in two ways:
- Ready-to-use reports that are designed by Copyleaks and can seamlessly integrate with your platform:
- Education report - this report is available only to the Education API users and includes an aggregated plagiarism score for the submitted content as well as all the results that were found. Read here how to access this report. The report looks like this:
- One to one comparison report - this report is available for all API users and is a comparison between a specific result and the submitted content. This report is available for each scan result and is accessible through the 'embedded comparison' link you get using the 'Results' method output. The report looks like this:
- Build the reports with your own design - If you would like to build the report yourself, instead of using the Copyleaks report, use the downloads methods that will give you access to the full raw information of the report.