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:

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 / Websites dashboard). You can see your keys on the ‘access keys’ section.

Manage Profile page

You can hit the “refresh” next to the key to create new API keys for your account.

Why are there two API-Keys?

Copyleaks allows you to generate two keys in case you need to generate a new key while keeping your active services running.
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:

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.

Token Expiration Time

For safety reasons, a token is valid for 48 hours. After the token has expired, you cannot use it anymore and you will have to login again to get a new security token. This is to make sure it is not being used by unauthorized parties.

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>

Create a new process

There are four ways to create a process on the Copyleaks system:

Receive back a unique process ID which will be the identification to this specific process.

Get the process status

Check the current scan status by calling the method /v1/businesses/{ProcessId}/status (for Businesses API), /v1/academic/{ProcessId}/status (for Academic API) or /v1/websites/{ProcessId}/status (for Websites 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'.

Usage Example

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, /v1/academic/daa6e2fb-6e84-4c75-be94-dd088159dd4c/status or /v1/websites/daa6e2fb-6e84-4c75-be94-dd088159dd4c/status.
There are two possible results:

  1. When the processing isn't complete yet:
    {
      Status: "processing"
    }
    
  2. When the processing is complete:
    {
      Status: "completed"
    }
    

The average process finishes in about 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.

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), /v1/academic/{ProcessId}/result (Academic API) or /v1/websites/{ProcessId}/result (Websites 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 24 hours. 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.

Usage Example

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, /v1/academic/daa6e2fb-6e84-4c75-be94-dd088159dd4c/result or /v1/websites/daa6e2fb-6e84-4c75-be94-dd088159dd4c/result (in this exmple the process id is 'daa6e2fb-6e84-4c75-be94-dd088159dd4c').
There are two possible results:

  1. 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/d69167b7-670b-491f-827f-46ba5ffd43a0/1493025"
       }
    ]
    
  2. Scan Failure: When Copyleaks servers return a status that is different than HTTP success status (200)

comparison report

You will get, as part of your results, a visual comparison report showing the exact copied parts, together with the relevant statistics.

This comparison report that will look like this:

Video Tutorials

Read More