`
#### Examples
- `tech-corp-employee456-q3-report`
- `acme-university-student123-final-thesis`
In plagiarism scans, this structure enables powerful filtering capabilities:
- **Exclude by author**: Use a pattern like `*-student123-*` to prevent a student's new submission from being checked against their previous work.
- **Include by organization**: Use `acme-university-*` to compare a document only against others from the same institution.
- **Focus on document types**: Use `*-final-thesis` to analyze all final theses submitted.
For more information, see the [Prevent Self-Plagiarism](/concepts/features/self-plagiarism/) guide.
## Handling ID Mismatches
If your internal system uses IDs that don't meet Copyleaks' requirements (e.g., they are too long or contain uppercase letters), the recommended solution is to generate a compliant Scan ID and maintain a mapping table on your end.
This table will link your internal entity ID to the corresponding Copyleaks Scan ID, ensuring seamless integration.
| Your Internal ID | Copyleaks Scan ID |
| :--- | :--- |
| `USER-9876-DOC-A` | `user9876-doca` |
| `Submission_ABC_123`| `submission-abc-123` |
## Next Steps
Learn more about how to exclude previous submissions from the same student to prevent self-plagiarism.
See how to implement your Scan ID strategy when submitting a file for scanning.
---
## Manage Your Credits
Source: https://docs.copyleaks.com/concepts/management/manage-your-credits
> Learn how to manage your Copyleaks credits effectively to optimize usage and prevent unnecessary costs.
Copyleaks provides a comprehensive suite of content integrity services through a flexible, credit-based API. To help you maximize the value of the platform and manage your usage effectively, it is essential to implement smart credit management strategies. Copyleaks offers robust tools to monitor and control your credit consumption, ensuring full transparency and predictability.
This guide outlines the available options to help you get started.
## Price Check Before Scan
Some applications may not have visibility into document sizes before submission, as end-users directly upload files. This can lead to **unintended credit consumption** when scanning large documents.
To mitigate this, Copyleaks recommends **pre-checking** the number of credits required for a scan before proceeding. This allows you to decide whether to continue with the scan or abort it, avoiding unnecessary charges.
### How to Enable Price Check
To activate the **Check-Credits** flow, set the `properties.action` parameter to `1` (Check-Credits) when submitting a document. In the webhook response, you will receive the expected cost of the scan without actually performing it.
After receiving the response, you can decide whether to proceed with the scan or not. To start the scan use the [**Start**](/reference/actions/authenticity/start) endpoint.
## Confirming Scan Cost After Completion
Once a scan is completed, Copyleaks sends a **[Completed Webhook](/reference/data-types/authenticity/webhooks/scan-completed)** to your application, including details about the **final cost** of the scan.
By tracking this information, you can develop insights into your **expected service costs** and optimize your usage accordingly.
You are only charged for **successfully completed** scans. If a scan fails due to an error, the credits will be **automatically refunded**.
## Programmatically Monitor Your Remaining Credits
Copyleaks API is designed to provide **full automation**, reducing the need for manual intervention. You can retrieve your **current credit balance** to implement various control mechanisms:
- **Set spending limits** - Define a threshold (e.g., limit usage to 50% of the budget by mid-month) and configure your system to react accordingly.
- **Trigger alerts** - Automatically send notifications when your remaining credits fall below a certain percentage (e.g., below 10%). This can be implemented as a **cron job** for regular monitoring.
### Retrieve Credit Balance
You can check your current credit balance using the **[Get Credits Balance](/reference/actions/admin/check-credits)** endpoint. This will return the number of credits available in your account.
## Set a Spend Limit on Automatic Refills
To prevent running out of credits during a billing cycle, **Copyleaks offers automatic refills**, ensuring that scans are never interrupted.
### Why Use Automatic Refills?
- Ensures that ongoing scans are not disrupted.
- Eliminates the need for manual intervention.
However, **uncontrolled automatic refills can lead to unexpected costs**, especially if a bug in your application results in excessive scans.
Set a **maximum budget** for automatic refills to prevent unforeseen expenses.
### How to Enable Automatic Refills
You can manage this feature via the **billing settings** in your Copyleaks account.
## Predict Your Usage
To forecast your credit consumption, **Copyleaks provides access to historical usage data**.
By retrieving your **usage history**, you can generate reports (in CSV format) to analyze past trends and predict future requirements.
### Retrieve Usage History
You can programmatically retrieve a detailed history of your credit consumption using the **[API Usage History](/reference/actions/admin/usage-history)** endpoint. This allows you to fetch data for specific date ranges, which can then be exported or integrated into your own internal dashboards. By analyzing this historical data, you can identify usage patterns, track costs associated with different projects, and build more accurate forecasts for future credit needs.
## Summary
The Copyleaks API offers extensive flexibility to help you manage credits efficiently. By leveraging these features strategically, you can prevent excessive usage, optimize costs, and maintain control over your plagiarism detection workflows.
Use these tools to ensure a cost-effective and seamless integration.
## Next Steps
Learn how to initiate a scan after checking the credit cost.
Understand the details provided in the completed webhook, including the final scan cost.
Retrieve your current credit balance programmatically.
Access your historical usage data to predict future credit consumption.
---
## Enterprise Organization Management
Source: https://docs.copyleaks.com/concepts/management/organization-management
> Manage your organization using admin.copyleaks.com - structure teams, set permissions, and control credit allocation.
Copyleaks provides enterprise organization management through [admin.copyleaks.com](https://admin.copyleaks.com). Structure your teams hierarchically, manage permissions, and control resource allocation across your organization.
## Managing Members
### Adding Team Members
Invited members receive an email with join instructions. Once accepted, they appear in your members list and can start using Copyleaks under your organization's account.
Added members will use your organization's credits. Plan accordingly when inviting team members.
### Managing Departments
Organize members into departments for better control and tracking:
The members table shows Email, Department, Status (Activated/Pending), Role, and Last activity for each user.
Use departments to match your organizational structure - by division, project, or client account for granular reporting.
## Roles and Permissions
| Role | Permissions | Typical Use |
|------|-------------|-------------|
| **Super Admin** | Full access to billing, organization settings, and all features | Executive leadership, IT administrators |
| **Admin** | Full feature access and user management, limited billing | Department managers, team leads |
| **Member/Contributor** | Use all features, cannot manage users | Regular team members |
## Organization Settings
Access organization-wide settings through the **Organization** menu in the sidebar.
### Organization Details
Configure your organization profile:
- Organization name and branding
- Billing address (Country, Address Lines, City, Zip/Postal Code)
- Open ID Authentication settings
### Available Policies
Navigate to **Policies** in the sidebar to configure:
- **Member Session Timeout** - Control how long sessions stay active
- **IP Whitelist** - Restrict access to specific IP addresses
- **Organization Scan Profiles** - Assign default scan settings by department
- **Multi-Factor Authentication (MFA) Policy** - Enforce 2FA across the organization
- **Shared Data Hub** - Control internal content scanning without saving data
- **Prevent email address autofill** - Security policy for email entry
Properly configured policies help maintain compliance with GDPR, CCPA, and industry-specific regulations.
## Credits and Billing
### Centralized Credit Management
View your credit status in the **Billing** section:
- **Current balance** displayed in the top navigation bar (e.g., "133k Credits left")
- **Credit usage** bar shows available credits and word capacity
- **Plan type** (Prepaid, Free, or Subscription)
- **Member seats** allocation and usage
All organization members consume credits from the central pool. No individual billing required.
### Monitoring Usage
The **Analytics** dashboard provides detailed tracking:
- Total Credits consumed
- Total Submitted Scans
- Matched Text Results
- AI Text Cases
- Character Manipulation Alerts
- Cross-Language scans
- **Credits Used** - Monthly breakdown of credit consumption
- **Submitted Scans** - Track scan volume over time
- Filter by date range and method (APP, API)
- Export data for custom analysis
Set usage thresholds and alerts to monitor when credits fall below specified amounts.
## Private Cloud Hubs
Create secure, internal repositories for content comparison. Access through **Private Cloud Hubs** in the sidebar.
### Creating a Repository
### Repository Management
The Billing page shows your Private Cloud Hub usage and allocation. Manage existing repositories through the dedicated hub interface.
Private Cloud Hubs keep document comparisons within organizational boundaries for compliance requirements.
## API Integration
### Generating API Keys
Never embed API keys in client-side code. Use environment variables and secure secret storage.
## Next Steps
Explore API endpoints for programmatic organization management
Deep dive into secure internal document repositories
Detailed credit management and optimization strategies
Get help with organization setup, administrator training, and API integration planning.
---
# Concepts → Performance
## Performance
Source: https://docs.copyleaks.com/concepts/performance/overview
> Optimize throughput, retry behavior, and compression when working with the Copyleaks APIs at scale.
Run scans efficiently. These pages cover the practical knobs, compression, batching, retries, and the per-content-type best practices.
Optimize text and document scanning, compression, feature scoping, submission patterns.
Optimize the AI Image Detection API, multipart uploads, compression, throughput.
Retry strategy and exponential backoff for transient errors and rate limits.
---
## Best Practices for Working with Texts & Documents
Source: https://docs.copyleaks.com/concepts/performance/best-practices
> Optimize Copyleaks scan performance with data compression, feature management, and submission strategies for the text and document APIs.
Copyleaks is designed for **scalability and high performance**, handling large workloads efficiently. To get the best results from your integration, follow these best practices to **optimize speed, reduce bottlenecks, and maximize efficiency**.
This guide covers best practices for **text and document scanning** using the Authenticity, Grammar Checker, Text Moderation and AI Text Detector APIs. For image-specific optimization, see the [Image Detection Best Practices](/concepts/performance/image-best-practices) guide.
## Use Network Data Compression
Transmitting large amounts of data over the internet **slows down** performance. **Compressing data** can reduce payload size by **up to 70%**, speeding up processing times.
### Enable Request Compression
Compress the data before sending it to Copyleaks and add this header:
```http
Content-Encoding: gzip
```
This is **especially useful** when submitting large files.
### Enable Response Compression
To receive compressed responses from Copyleaks, include this header in your request:
```http
Accept-Encoding: gzip
```
This ensures faster data transfer between your system and Copyleaks.
## Disable Unused Features
Copyleaks offers **many configurable features**, but enabling unnecessary ones can **slow down** scans. Only enable what you need.
Some features to **disable if not needed**:
| Feature | Description | Recommendation |
|---------|------------|---------------|
| `properties.includeHtml` | Includes results in **HTML format** | Disable if plain text is enough. |
| `properties.pdf.create` | Generates a **PDF report** | Turn off if you don’t need a PDF. |
| `properties.expiration` | Defines how long scan data is stored | Use **7 days or less** for optimal speed. |
| `properties.filters` | Narrows search results | Customize filters to **improve scan efficiency**. |
Check the [Authenticity API methods](/reference/actions/authenticity/overview) for the full list of features you can toggle.
## Submit Scans at an Optimal Rate
Copyleaks runs on cloud infrastructure, dynamically scaling resources based on demand. However, submitting too many requests at once can reduce efficiency.
### Avoid Overloading the System
- Instead of submitting all documents at once, send them gradually at a controlled rate (`N` calls per second).
- If handling large volumes (e.g., 1M+ files), adjust to the maximum allowed rate limit (see [Rate Limit Policy](/reference/data-types/authenticity/technical-specifications)).
### Prevent Slow Start Issues
- Don’t flood the system with a sudden burst of requests.
- Instead, start with a low rate and gradually increase to maintain stable performance.
Custom plans are available for large-scale users who need higher limits. Contact [support@copyleaks.com](mailto:support@copyleaks.com) to discuss options.
## Adjust Sensitivity for Speed vs. Accuracy
Copyleaks supports different **sensitivity levels**, balancing **speed** and **comprehensiveness** based on your needs.
Set the **`properties.sensitivityLevel`** value based on priority:
| Level | Focus | Best For |
|-------|-------|---------|
| `1` | **Speed** | Quicker scans, less comprehensive. |
| `3` *(default)* | **Balanced** | Recommended for most use cases. |
| `5` | **Comprehensive** | Deep analysis, high accuracy. |
We recommend level `3` for most users, but feel free to adjust as needed.
## Reuse Your Authentication Token
Each **JWT token** generated during login is **valid for 48 hours**.
Avoid unnecessary login calls, reuse your token for multiple requests within its validity period.
For more information on obtaining a new token, refer to the **[Login API](/reference/actions/account/login)**.
## Next Steps
Learn optimization strategies specific to AI Image Detection API.
Explore the full list of features and options available for configuring your scans.
Understand the rate limit policy and other technical specifications for optimal API usage.
Learn how to obtain and manage your authentication token for API access.
---
## Handling Failures
Source: https://docs.copyleaks.com/concepts/performance/handling-failures
> Learn how to implement an exponential backoff strategy for retrying requests to the Copyleaks API.
This document outlines how to handle failures when interacting with the Copyleaks API, specifically focusing on implementing an **exponential backoff strategy** for retrying requests.
## Understanding Failure Responses
When making requests to the Copyleaks API, you may encounter various HTTP status codes indicating different types of failures. Here are some common ones:
- **Error code 503:** Service Unavailable. Typically, this error will appear when Copyleaks is undergoing a maintenance period. You can be notified for these events using [**Copyleaks Status**](https://status.copyleaks.com) by subscribing to alerts. We broadcast a message days prior to the event time so users will be able to make preparations in advance.
- **Error code 5xx**: Internal errors. There is an issue pertaining to Copyleaks’ service and\or the network.
- **Error code 429**: Too many requests. Copyleaks, like other REST API services, has a rate limit policy that defines the maximum calls that can be made. Exceeding the maximum calls repeatedly will lead to temporary/permanent blocks.
## Suggested Retry Strategy
[**Exponential backoff**](https://en.wikipedia.org/wiki/Exponential_backoff) is a standard algorithm that helps applications define a retry strategy for consuming a network service.
For these status codes mentioned above, we recommend implementing a retry algorithm by doing the following:
1. Make a request to the Copyleaks API.
2. If the requests fail, wait 1 + `rand_seconds_number` seconds. Then, retry.
3. If the requests fail, wait 2 + `rand_seconds_number` seconds. Then, retry.
4. If the requests fail, wait 4 + `rand_seconds_number` seconds. Then, retry.
5. ...
6. And so on, up to `max_time` seconds.
7. Wait `max_time` and retry up to a limit of n times.
### Definitions:
`rand_seconds_number` - Is a random number to add to the wait time. This is to prevent multiple clients from retrying at the same time, which can lead to a thundering herd problem. Suggested values is between 1 and 10 seconds.
`max_time` - Is the maximum number of seconds to wait. Suggested value is 60 seconds.
## Next Steps
Learn how to use webhooks to receive real-time notifications about scan statuses, including failures.
Review the technical specifications, including rate limits, to optimize your API usage.
Explore the comprehensive Authenticity API for managing your plagiarism and AI detection processes.
---
## Best Practices for Working with Images
Source: https://docs.copyleaks.com/concepts/performance/image-best-practices
> Learn how to optimize performance when using the Copyleaks AI Image Detection API, including compression, multipart uploads and throughput optimization.
Follow these best practices to **maximize performance, reduce bandwidth usage and improve throughput** when working with the Copyleaks [AI Image Detection](https://copyleaks.com/ai-detector/ai-image-detector) API.
This guide covers best practices specifically for **AI Image Detection**. For text and document scanning optimization, see the [Text & Document Best Practices](/concepts/performance/best-practices) guide.
## Use Multipart/Form-Data Format
Always use **multipart/form-data** instead of JSON with base64 encoding:
- **Smaller payload size**: Avoids 33% base64 encoding overhead
- **Faster uploads**: Direct binary transfer is more efficient
- **Better memory usage**: Reduces processing overhead
## Enable Response Compression
Add this header to your requests to reduce response size:
```http
Accept-Encoding: gzip
```
Image detection results can include large RLE masks. Most HTTP clients automatically decompress gzip responses.
## Submit Scans at an Optimal Rate
The API has rate limits to ensure optimal performance:
- **900 requests per 15 minutes** per host
- **10 requests per second** per user (default)
Send images at a steady rate rather than in bursts, and implement retry logic with exponential backoff when rate limits are reached.
Need higher rate limits? Contact [support@copyleaks.com](mailto:support@copyleaks.com) to discuss custom plans.
## Scale Across Multiple Servers
For higher throughput, distribute uploads across multiple servers. Each server can independently send up to 900 requests per 15 minutes, allowing parallel processing of large image batches.
## Reuse Your Authentication Token
JWT tokens are **valid for 48 hours**:
- Cache and reuse tokens for multiple requests
- Refresh before the 48-hour window ends
- Avoid calling the login API for every image submission
## Preserve Original Image Data
Submit images in their original form for accurate [AI detection](https://copyleaks.com/ai-detector) results.
**Avoid:**
- Resizing or cropping
- Recompressing or converting formats
- Applying filters or adjustments
**Best practice:** Submit the exact image file as received or captured, preserving EXIF metadata and original format. AI-generated images have subtle patterns in pixel data that can be lost through manipulation.
## Summary
- Use **multipart/form-data** format
- Enable **response compression** with `Accept-Encoding: gzip`
- Submit at a **steady rate** (under 900/15min per host, 10/sec per user)
- **Distribute load across multiple servers** for higher throughput
- **Reuse authentication tokens** for up to 48 hours
- **Submit original images** without modifications
## Next Steps
Learn how to implement AI image detection in your application.
View the complete API specification and parameters.
---
# Concepts → Security
## Trust & Security
Source: https://docs.copyleaks.com/concepts/security/overview
> How Copyleaks protects your data: AES-256 encryption, SOC 2 and SOC 3 certification, GDPR compliance, and a restricted, TLS-secured network.
At Copyleaks, we are committed to the security of your data and privacy. We understand that our customers are entrusting us with their data, and we take that responsibility very seriously.
We have implemented a comprehensive security program that includes administrative, technical, and physical safeguards to protect your data from unauthorized access, use, or disclosure.
This page provides an overview of our security program, including our security architecture, data handling policies, and compliance certifications.
## Our Commitment to Security
Our approach to security is built on several key pillars:
### Security Architecture and Infrastructure
Our platform is built on a robust and secure foundation to protect your data at every level.
- **Secure Network Design:** All platform components communicate through a secure internal company network. Access to this network is highly restricted, even for Copyleaks employees, and requires identity verification via an SSL client certificate. All communication within the internal network is secured using TLS v1.2 or newer.
- **Cloud-Based Architecture:** We leverage a secure, cloud-based system architecture to provide scalable and reliable service.
- **On-Premises Option:** For organizations requiring complete control over their data infrastructure, we offer on-premises Cloud Private Hubs. This allows you to retain all sensitive data within your own secured digital environment while utilizing our advanced detection technology.
- **Continuous Monitoring:** Our systems are monitored 24/7, enabling us to respond instantly to any downtime or security incidents as they are detected.
### Data Encryption
Data safety is a cornerstone of our security mechanisms. We employ military-grade encryption to ensure your data is protected at all times.
- **Encryption in Transit:** All data transferred to and from our platform is sent exclusively over secure channels (100% HTTPS) using SSL connections.
- **Encryption at Rest:** All data saved on our platform is encrypted using the AES-256 standard. Encryption keys are managed by our Cloud providers and are rotated automatically to ensure maximum security.
- **Data Backup:** We perform daily data backups, which are stored securely in our backup data centers.
## Compliance and Certifications
Our products routinely undergo independent verification of privacy, security, and compliance controls to meet global standards and earn the trust of our users.
- [**SOC 2 & SOC 3:**](https://en.wikipedia.org/wiki/System_and_Organization_Controls) Copyleaks is SOC 2 & 3 certified, demonstrating our commitment to securely managing data to protect our customers' interests and privacy. Our SOC 3 report, audited by KPMG, is publicly available and outlines our high-powered system's adherence to security, privacy, and confidentiality standards.
- [**GDPR:**](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation) We are fully committed to adhering to the guidelines of the EU General Data Protection Regulation (GDPR). For our European customers, we offer the `copyleaks.eu` site with servers located in Germany, ensuring data processing remains within Europe.
- [**PCI DSS:**](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard) We adhere to the Payment Card Industry Data Security Standard (PCI DSS). All payments are processed through Stripe, and we do not access or store any personal credit card information within the Copyleaks system.
- [**NIST RMF:**](https://en.wikipedia.org/wiki/Risk_Management_Framework) We meet the guidelines of the NIST Risk Management Framework (RMF), a systematic process for managing information security risk developed by the U.S. National Institute of Standards and Technology.
- [**Accessibility:**](https://copyleaks.com/accessibility) We believe technology should be accessible to everyone. Our platform is designed to be user-friendly for all, and our Voluntary Product Accessibility Templates (VPATs) are available for review.
## Application and Operational Security
We maintain a rigorous application security program to protect our platform from threats.
- **Vulnerability Management:** We routinely run vulnerability scans of our system components and use static code analyzers to detect problematic code before it is deployed.
- **Regular Updates:** We regularly update the security of our products to protect against emerging threats.
- **Responsible Disclosure:** We take security and privacy very seriously and encourage our users to report any identified vulnerabilities. If you believe you have found a security vulnerability, please submit a report with details such as your account email and a screenshot of the issue so our team can investigate.
## Useful Links
Learn about our compliance with global security standards and certifications.
Explore our security practices and measures to protect your data.
---
## Webhooks Security
Source: https://docs.copyleaks.com/concepts/security/webhooks
> Learn how to secure your Copyleaks webhook endpoints against unauthorized access and ensure reliable communication.
Communication with the Copyleaks service is conducted via RESTful requests and responses. Some operations involve asynchronous processing, during which a webhook notification is sent upon completion.
Since your server must be accessible over the internet to receive webhook notifications, it is crucial to ensure that incoming requests originate from Copyleaks. To verify the authenticity of webhook requests, you can implement one or more of the following security measures.
## Authentication via HTTPS Client Certificate
Copyleaks webhook servers support **HTTPS connections** for secure communication with your endpoints, preventing unauthorized access to transmitted data. To enable this security feature, simply provide an **HTTPS endpoint** when submitting a file for scanning.
To further secure your endpoint, Copyleaks employs **SSL client certificates** to authenticate webhook requests and confirm they originate from Copyleaks. Self-signed certificates are also supported.
To retrieve the latest SSL client certificate thumbprints, use the following REST API request:
```http
GET https://api.copyleaks.com/v2/security/client-certificates
```
This authentication method requires an HTTPS-enabled endpoint with SSL support. Non-secure HTTP connections do not support this feature.
Since this list is **dynamic** and subject to change, we recommend setting up an automated process to update your environment daily.
## Authentication via Developer Payload
An alternative method to prevent unauthorized access is by utilizing the `properties.developerPayload` field. To implement this:
1. Set the `developerPayload` value to a unique, secret string known only to you.
2. When receiving a webhook request, verify that the `developerPayload` in the request matches the expected value.
3. For enhanced security, consider encrypting the secret string with a private key known only to your system.
By employing these authentication methods, you can safeguard your webhook endpoints and ensure secure communication with Copyleaks.
## Configuring Web Application Firewalls (WAF)
Many users have security measures such as AWS WAF, Cloudflare, or other Web Application Firewalls (WAF) in place, which may block webhook requests if they appear suspicious. If you are not receiving webhook notifications, it may be due to your WAF filtering the requests.
### Exclude Copyleaks Webhook Requests from WAF
To resolve this, allow Copyleaks' webhooks by adding a custom header to the requests and configuring your WAF to allow requests containing this header. This ensures that webhook notifications are received without interference from security mechanisms.
By employing these authentication methods and considering WAF exclusions, you can safeguard your webhook endpoints and ensure secure, uninterrupted communication with Copyleaks.
## Static IP Addresses for Webhook Delivery Enterprise
For an enhanced layer of security, we offer enterprise customers the option to receive all webhook notifications from a static, predefined list of IP addresses. Enabling this feature allows you to configure your firewall to accept incoming traffic exclusively from our trusted servers, a practice known as IP allowlisting. This significantly reduces the risk of spoofing and ensures that your systems only process legitimate, verified requests from our platform. To have this feature enabled and to receive the list of static IPs for allowlisting, please contact your account manager.
## Next Steps
Learn about the different types of webhooks and how to configure them.
Review the technical specifications, including security considerations for API interactions.
Understand how to export scan results, often delivered via webhooks.
---
# Resources
## Docs for LLMs
Source: https://docs.copyleaks.com/resources/llms
> Copyleaks Docs provide llms.txt standard to optimize AI interactions with our documentation.
When working with any AI or Large Language Model (LLM), providing relevant and accurate context is critical for achieving high-quality results. To help developers and their AI applications better understand our documentation, we have adopted the `llms.txt` standard.
This standard provides a structured, machine-readable format that guides AI models on how to interpret and utilize our documentation, ensuring the highest level of integrity and accuracy in AI-powered applications.
The `llms.txt` standard is an open initiative for GenAI Governance. You can learn more about its specification and goals at [llmstxt.org](https://llmstxt.org/).
## Available Documents
We provide several versions of our documentation in the `llms.txt` format, each tailored for different use cases:
This file provides a high-level, structured sitemap of our documentation, including page descriptions. It is ideal for use cases where a concise overview of the content is required.
[**llms.txt**](/llms.txt)
This file contains the entire, unabridged content of our documentation in a single markdown file, providing the most comprehensive context possible.
The full content version is extensive and may exceed the context window of some Large Language Models.
[**llms-full.txt**](/llms-full.txt)
---
## Run in Postman
Source: https://docs.copyleaks.com/resources/postman
> Access and utilize the Copyleaks API Postman collection for seamless integration and testing.
Postman is a popular tool that simplifies API testing and development. Copyleaks provides a Postman collection that covers all available API calls. This document will guide you through setting up the collection and making requests.
### Get Started
- Sign up or log in to your account on [**Postman**](https://www.postman.com)
- Click the button below to access the Copyleaks Postman collection:
- Select **Fork Collection**
- Name your fork and select a workspace
- To make API calls, you need to authenticate:
- Find your **API Key** in the **[API Dashboard](https://api.copyleaks.com/dashboard)**
- In Postman, select your fork of the Copyleaks collection
- Go to the **Variables** tab and enter the following values in the **CURRENT VALUE** column:
- **email**: `YOUR_EMAIL_ADDRESS`
- **key**: `YOUR_API_KEY`
- Save the changes
- After logging in, check the response for the `access_token`
- Take the value of the `access_token` and place it in the Authorization tab of your fork in Postman as the value of Token. All endpoints will inherit this token from the parent and will use it for authentication automatically
You can now start making API requests.
For example, to run an AI detection scan:
- In your Postman workspace, navigate to your fork of the Copyleaks collection
- Select **AI Detection** > **Submit Natural Language** > Update the request body and add the scan ID, then click **Send**
- Review the response
## Next Steps
Check out our Copyleaks API Postman Profile
Visit the complete Copyleaks API Postman Collection documentation
Learn how to authenticate and get started with Copyleaks APIs
Discover the full list of available Scans Methods Endpoints. Submit, start, and manage plagiarism scans
---
# Resources → SDKs
## Overview
Source: https://docs.copyleaks.com/resources/sdks/overview
> Accelerate your integration with our official SDKs. Connect to the Copyleaks API with just a few lines of code and start building with confidence.
Integrate the full power of the Copyleaks API with just a few lines of code. Our official Software Development Kits (SDKs) are designed to provide a seamless developer experience, allowing you to build robust applications quickly and confidently.
### The Developer Experience
The official Copyleaks SDKs are:
Save hours of development time with pre-built functions for every API endpoint.
Our SDKs are always in sync with the latest API features, so you can take advantage of new capabilities as soon as they are released.
Rely on officially maintained, production-ready code with comprehensive documentation and clear examples.
We handle the complexities of authentication, request signing, and error handling, so you can focus on building great features for your users.
### Get Started with Your Language
Select an official SDK for your preferred programming language and start building with Copyleaks today.
---
## Python SDK Quickstart
Source: https://docs.copyleaks.com/resources/sdks/python
> Install the Copyleaks Python SDK, authenticate, and submit your first scan in under 5 minutes with this step-by-step guide.
This guide will walk you through installing the official Python SDK and running your first scan. In just a few minutes, you'll be able to run your first scan directly from your Python application.
Before you start, ensure you have the following:
- An active Copyleaks account. If you don't have one, **[sign up for free](https://api.copyleaks.com/signup)**.
- You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
## Get Started
First, install the official `copyleaks` package from PyPI into your project using pip:
```bash
pip install copyleaks
```
Remember to replace the placeholder `YOUR_EMAIL_ADDRESS` and `YOUR_API_KEY` with your actual credentials.
```python title="scan_text.py"
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.exceptions.command_error import CommandError
from copyleaks.models.submit.document import FileDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
# --- Your Credentials ---
EMAIL_ADDRESS = 'YOUR_EMAIL_ADDRESS'
KEY = 'YOUR_API_KEY'
# --------------------
# Log in to the Copyleaks API
try:
auth_token = Copyleaks.login(EMAIL_ADDRESS, KEY)
print(" Logged in successfully!")
except CommandError as ce:
print(f" Login failed: {ce}")
exit()
# Prepare your content for scanning
# You can scan a URL, a local file, or raw text.
# This example scans a simple string of text.
print("Submitting text for scanning...")
text_to_scan = "Hello world, this is a test."
base64_content = base64.b64encode(text_to_scan.encode()).decode()
# Configure the scan
# A unique scan ID for this submission
scan_id = "my-first-scan"
scan_properties = ScanProperties("https://your-server.com/webhook/{STATUS}")
scan_properties.set_sandbox(True) # Turn on sandbox mode for testing
file_submission = FileDocument(base64_content, "test.txt")
file_submission.set_properties(scan_properties)
# Submit the scan to Copyleaks
Copyleaks.submit_file(auth_token, scan_id, file_submission)
print(f" Scan submitted successfully! Scan ID: {scan_id}")
print("You will be notified via your webhook when the scan is complete.")
```
The example code performs four main actions to submit a scan:
1. **Login:** It authenticates with your email and API key to get a secure login token from the Copyleaks server. This token is required for all subsequent requests.
2. **Prepare Content:** It takes a simple string of text and encodes it into Base64 format. The SDK requires content to be in this format for submission.
3. **Configure Scan:** It creates a `ScanProperties` object to define the scan's behavior. We enable `sandbox` mode for safe testing without using credits and provide a `webhook` URL.
4. **Submit for Scanning:** It sends the prepared content and its configuration to the Copyleaks API. The process is asynchronous, meaning you don't have to wait for the results. Instead, Copyleaks will notify your webhook URL once the scan is complete.
## Next Steps
Check the official Copyleaks Python SDK repository on GitHub for installation and usage details.
Install the official Copyleaks Python package from PyPI for easy integration.
Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.
Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.
Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.
Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.
---
## JavaScript SDK Quickstart
Source: https://docs.copyleaks.com/resources/sdks/javascript
> Install the Copyleaks JavaScript SDK, authenticate, and submit your first scan in minutes with this step-by-step guide.
This guide will walk you through installing the official JavaScript SDK and running your first scan. In just a few minutes, you'll be able to easily use Copyleaks products directly from your JavaScript or TypeScript application.
Before you start, ensure you have the following:
- An active Copyleaks account. If you don't have one, **[sign up for free](https://api.copyleaks.com/signup)**.
- You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
## Get Started
First, install the official `plagiarism-checker` package from npm into your project.
```bash
npm i plagiarism-checker
```
The following example shows how to authenticate and submit a simple string of text for a plagiarism scan using the SDK's data models.
Remember to replace the placeholder credentials and webhook URL with your actual values.
```javascript title="scan.js" icon="square-js"
const { Copyleaks, CopyleaksFileSubmissionModel } = require('plagiarism-checker');
// --- Your Credentials ---
const EMAIL_ADDRESS = 'YOUR_EMAIL_ADDRESS';
const KEY = 'YOUR_API_KEY';
const WEBHOOK_URL = 'https://your-server.com/webhook/{STATUS}';
// --------------------
async function main() {
console.log('Authenticating...');
const copyleaks = new Copyleaks();
const authToken = await copyleaks.loginAsync(EMAIL_ADDRESS, KEY);
console.log(' Login successful!');
console.log('Submitting text for scanning...');
const scanId = `${Date.now()}`; // Use a timestamp for a unique ID
const textToScan = 'Hello world, this is a test.';
const base64Content = Buffer.from(textToScan).toString('base64');
const submission = new CopyleaksFileSubmissionModel(
base64Content,
'test.txt',
{
sandbox: true, // Turn on sandbox mode for testing
webhooks: {
status: WEBHOOK_URL
}
}
);
await copyleaks.submitFileAsync(authToken, scanId, submission);
console.log(` Scan submitted successfully! Scan ID: ${scanId}`);
}
main().catch(err => console.error(err));
```
```typescript title="scan.ts" icon="code"
import {
Copyleaks,
CopyleaksFileSubmissionModel,
type CopyleaksAuthToken
} from 'plagiarism-checker';
// --- Your Credentials ---
const EMAIL_ADDRESS = 'YOUR_EMAIL_ADDRESS';
const KEY = 'YOUR_API_KEY';
const WEBHOOK_URL = 'https://your-server.com/webhook/{STATUS}';
// --------------------
async function main() {
console.log('Authenticating...');
const copyleaks = new Copyleaks();
const authToken: CopyleaksAuthToken = await copyleaks.loginAsync(EMAIL_ADDRESS, KEY);
console.log(' Login successful!');
console.log('Submitting text for scanning...');
const scanId = `${Date.now()}`; // Use a timestamp for a unique ID
const textToScan = 'Hello world, this is a test.';
const base64Content = Buffer.from(textToScan).toString('base64');
const submission = new CopyleaksFileSubmissionModel(
base64Content,
'test.txt',
{
sandbox: true, // Turn on sandbox mode for testing
webhooks: {
status: WEBHOOK_URL
}
}
);
await copyleaks.submitFileAsync(authToken, scanId, submission);
console.log(` Scan submitted successfully! Scan ID: ${scanId}`);
}
main().catch(err => console.error(err));
```
1. **Login**: We authenticate with your email and API key to get a secure login token.
2. **Prepare Submission**: We encode a string to Base64 and create a new `CopyleaksFileSubmissionModel`. This model is the recommended way to structure your submission data.
3. **Configure & Submit**: We pass the submission model to `submitFileAsync`. The model itself contains the sandbox settings and the webhook URL where Copyleaks will send a notification when the scan is complete.
## Next Steps
Check the official Copyleaks NodeJS SDK repository on GitHub for installation and usage details.
Install the official Copyleaks NodeJS package from NPM for easy integration.
Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.
Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.
Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.
Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.
---
## Java SDK Quickstart
Source: https://docs.copyleaks.com/resources/sdks/java
> Install the Copyleaks Java SDK, authenticate, and submit your first scan in under 5 minutes with this step-by-step guide.
This guide will walk you through installing the official Java SDK and running your first scan. In just a few minutes, you'll be able to check content for plagiarism, AI-generated text, moderation and more directly from your Java application.
Before you start, ensure you have the following:
- An active Copyleaks account. If you don't have one, **[sign up for free](https://api.copyleaks.com/signup)**.
- You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
## Get Started
The SDK requires **Java 11 or higher**. Add the official `copyleaks-java-sdk` dependency to your project's `pom.xml` file.
```xml title="pom.xml"
com.copyleaks.sdk
copyleaks-java-sdk
5.1.0
```
Remember to replace the placeholder credentials and webhook URL with your actual values.
```java title="ScanExample.java"
import classes.Copyleaks;
import models.response.CopyleaksAuthToken;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.SubmissionProperties;
import models.submissions.properties.SubmissionWebhooks;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.Random;
public class ScanExample {
// --- Your Credentials ---
private static final String EMAIL_ADDRESS = "YOUR_EMAIL_ADDRESS";
private static final String KEY = "YOUR_API_KEY";
private static final String WEBHOOK_URL = "https://your-server.com/webhook/{STATUS}";
// --------------------
public static void main(String[] args) {
CopyleaksAuthToken token;
try {
// Log in to the Copyleaks API
System.out.println("Authenticating...");
token = Copyleaks.login(EMAIL_ADDRESS, KEY);
System.out.println(" Logged in successfully!");
// Prepare your content for scanning
System.out.println("Submitting text for scanning...");
String textToScan = "Hello world, this is a test.";
String base64Content = Base64.getEncoder().encodeToString(textToScan.getBytes(StandardCharsets.UTF_8));
String filename = "test.txt";
String scanId = Integer.toString(new Random().nextInt(100000));
// Configure the scan
SubmissionWebhooks webhooks = new SubmissionWebhooks(WEBHOOK_URL);
SubmissionProperties submissionProperties = new SubmissionProperties(webhooks);
submissionProperties.setSandbox(true); // Turn on sandbox mode for testing
CopyleaksFileSubmissionModel submissionModel = new CopyleaksFileSubmissionModel(base64Content, filename, submissionProperties);
// Submit the scan to Copyleaks
Copyleaks.submitFile(token, scanId, submissionModel);
System.out.println(" Scan submitted successfully! Scan ID: " + scanId);
System.out.println("You will be notified via your webhook when the scan is complete.");
} catch (Exception e) {
System.out.println(" An error occurred:");
e.printStackTrace();
}
}
}
```
The example code performs four main actions to submit a scan:
1. **Login:** It authenticates with your email and API key to get a secure `CopyleaksAuthToken` object, which is required for all subsequent requests.
2. **Prepare Content:** It takes a simple string of text and encodes it into Base64 format.
3. **Configure Scan:** It creates a `SubmissionProperties` object containing `SubmissionWebhooks` to define the scan's behavior. We enable `sandbox` mode for safe testing and provide the webhook URL.
4. **Submit for Scanning:** It creates a `CopyleaksFileSubmissionModel` with the content and properties, then sends it to the Copyleaks API. The process is asynchronous; Copyleaks will notify your webhook URL once the scan is complete.
## Next Steps
Check the official SDK repository on GitHub for more examples and details.
View the official package on the Maven Central Repository to see all available versions.
Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.
Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.
Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.
Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.
---
## C# SDK Quickstart
Source: https://docs.copyleaks.com/resources/sdks/csharp
> Install the Copyleaks C# SDK, authenticate, and submit your first scan in under 5 minutes with this step-by-step guide.
This guide will walk you through installing the official C# SDK and running your first scan. In just a few minutes, you'll be able to check content for plagiarism, AI-generated text, and more directly from your .NET application.
Before you start, ensure you have the following:
- An active Copyleaks account. If you don't have one, **[sign up for free](https://api.copyleaks.com/signup)**.
- You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
## Get Started
First, install the official `Copyleaks` package from NuGet into your project using the Package Manager Console.
```powershell
Install-Package Copyleaks
```
Remember to replace the placeholder credentials and webhook URL with your actual values.
```csharp title="Program.cs"
using System;
using System.Text;
using System.Threading.Tasks;
using Copyleaks.SDK.V3.API;
using Copyleaks.SDK.V3.API.Models.Requests;
using Copyleaks.SDK.V3.API.Models.Requests.Properties;
public class Program
{
// --- Your Credentials ---
private const string USER_EMAIL = "YOUR_EMAIL_ADDRESS";
private const string USER_KEY = "YOUR_API_KEY";
private const string WEBHOOK_URL = "https://your-server.com/webhook/{STATUS}";
// --------------------
public static async Task Main(string[] args)
{
try
{
// Log in to the Copyleaks API
Console.WriteLine("Authenticating...");
var identityClient = new CopyleaksIdentityApi();
var loginResponse = await identityClient.LoginAsync(USER_EMAIL, USER_KEY);
Console.WriteLine(" Logged in successfully!");
// Prepare your content for scanning
Console.WriteLine("Submitting text for scanning...");
var apiClient = new CopyleaksScansApi();
var scanId = Guid.NewGuid().ToString();
var textToScan = "Hello world, this is a test.";
var base64Content = Convert.ToBase64String(Encoding.UTF8.GetBytes(textToScan));
// Configure the scan
var scanProperties = new ClientScanProperties();
scanProperties.Sandbox = true; // Turn on sandbox mode for testing
scanProperties.Webhooks = new Webhooks { Status = new Uri($"{WEBHOOK_URL}") };
var fileDocument = new FileDocument
{
Base64 = base64Content,
Filename = "test.txt",
PropertiesSection = scanProperties
};
// Submit the scan to Copyleaks
await apiClient.SubmitFileAsync(scanId, fileDocument, loginResponse.Token);
Console.WriteLine($" Scan submitted successfully! Scan ID: {scanId}");
Console.WriteLine("You will be notified via your webhook when the scan is complete.");
}
catch (Exception ex)
{
Console.WriteLine($" An error occurred: {ex.Message}");
}
}
}
```
The example code performs four main actions to submit a scan:
1. **Login:** It authenticates with your email and API key to get a secure login token. This token is required for all subsequent requests.
2. **Prepare Content:** It takes a simple string of text and converts it into a Base64 string.
3. **Configure Scan:** It creates a `ClientScanProperties` object to define the scan's behavior. We enable `sandbox` mode for safe testing and provide a `webhook` URL for completion notifications.
4. **Submit for Scanning:** It creates a `FileDocument` with the content and properties, then sends it to the Copyleaks API. The process is asynchronous; Copyleaks will notify your webhook URL once the scan is complete.
## Next Steps
Check the official SDK repository on GitHub for more examples and details.
View the official package on the NuGet Gallery to see all available versions.
Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.
Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.
Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.
Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.
---
## PHP SDK Quickstart
Source: https://docs.copyleaks.com/resources/sdks/php
> Install the Copyleaks PHP SDK, authenticate, and submit your first scan in under 5 minutes with this step-by-step guide.
This guide will walk you through installing the official PHP SDK and running your first scan. In just a few minutes, you'll be able to check content for plagiarism, AI-generated text, and more directly from your PHP application.
Before you start, ensure you have the following:
- An active Copyleaks account. If you don't have one, **[sign up for free](https://api.copyleaks.com/signup)**.
- You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
## Get Started
First, install the official `copyleaks/php-plagiarism-checker` package from Packagist into your project using Composer.
```bash
composer require copyleaks/php-plagiarism-checker
```
Remember to replace the placeholder credentials and webhook URL with your actual values.
```php title="scan.php"
login($EMAIL_ADDRESS, $KEY);
echo " Logged in successfully!\n";
// Prepare your content for scanning
echo "Submitting text for scanning...\n";
$textToScan = "Hello world, this is a test.";
$base64Content = base64_encode($textToScan);
$scanId = time();
// Configure the scan
$webhooks = new SubmissionWebhooks($WEBHOOK_URL);
$properties = new SubmissionProperties($webhooks);
$properties->setSandbox(true); // Turn on sandbox mode for testing
$submission = new CopyleaksFileSubmissionModel($base64Content, 'test.txt', $properties);
// Submit the scan to Copyleaks
$copyleaks->submitFile($loginToken, $scanId, $submission);
echo " Scan submitted successfully! Scan ID: " . $scanId . "\n";
echo "You will be notified via your webhook when the scan is complete.\n";
} catch (Exception $e) {
echo " An error occurred: " . $e->getMessage() . "\n";
}
```
The example code performs four main actions to submit a scan:
1. **Login:** It authenticates with your email and API key to get a secure login token, which is required for all subsequent requests.
2. **Prepare Content:** It takes a simple string of text and encodes it into Base64 format.
3. **Configure Scan:** It creates a `SubmissionProperties` object containing `SubmissionWebhooks` to define the scan's behavior. We enable `sandbox` mode for safe testing and provide the webhook URL.
4. **Submit for Scanning:** It creates a `CopyleaksFileSubmissionModel` with the content and properties, then sends it to the Copyleaks API. The process is asynchronous; Copyleaks will notify your webhook URL once the scan is complete.
## Next Steps
Check the official SDK repository on GitHub for more examples and details.
View the official package on Packagist to see all available versions.
Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.
Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.
Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.
Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.
---
## Ruby SDK Quickstart
Source: https://docs.copyleaks.com/resources/sdks/ruby
> Install the Copyleaks Ruby SDK, authenticate, and submit your first scan in under 5 minutes with this step-by-step guide.
This guide will walk you through installing the official Ruby SDK and running your first scan. In just a few minutes, you'll be able to check content for plagiarism, AI-generated text, and more directly from your Ruby application.
Before you start, ensure you have the following:
- An active Copyleaks account. If you don't have one, **[sign up for free](https://api.copyleaks.com/signup)**.
- You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
## Get Started
First, install the official `plagiarism-checker` gem from RubyGems into your project.
```bash
gem install plagiarism-checker
```
Remember to replace the placeholder credentials and webhook URL with your actual values.
```ruby title="scan.rb"
require 'copyleaks'
require 'base64'
# --- Your Credentials ---
USER_EMAIL = 'YOUR_EMAIL_ADDRESS'
USER_API_KEY = 'YOUR_API_KEY'
WEBHOOK_URL = 'https://your-server.com/webhook/{STATUS}'
# --------------------
begin
# Log in to the Copyleaks API
puts "Authenticating..."
copyleaks = Copyleaks::API.new
auth_token = copyleaks.login(USER_EMAIL, USER_API_KEY)
puts " Logged in successfully!"
# Prepare your content for scanning
puts "Submitting text for scanning..."
scan_id = Time.now.to_i.to_s
text_to_scan = 'Hello world, this is a test.'
base64_content = Base64.strict_encode64(text_to_scan)
# Configure the scan
webhooks = Copyleaks::SubmissionWebhooks.new(WEBHOOK_URL)
properties = Copyleaks::SubmissionProperties.new(webhooks)
properties.sandbox = true # Turn on sandbox mode for testing
submission = Copyleaks::CopyleaksFileSubmissionModel.new(
base64_content,
'test.txt',
properties
)
# Submit the scan to Copyleaks
copyleaks.submit_file(auth_token, scan_id, submission)
puts " Scan submitted successfully! Scan ID: #{scan_id}"
puts "You will be notified via your webhook when the scan is complete."
rescue StandardError => e
puts " An error occurred: #{e.message}"
end
```
The example code performs four main actions to submit a scan:
1. **Login:** It authenticates with your email and API key to get a secure login token, which is required for all subsequent requests.
2. **Prepare Content:** It takes a simple string of text and encodes it into Base64 format.
3. **Configure Scan:** It creates a `SubmissionProperties` object containing `SubmissionWebhooks` to define the scan's behavior. We enable `sandbox` mode for safe testing and provide the webhook URL.
4. **Submit for Scanning:** It creates a `CopyleaksFileSubmissionModel` with the content and properties, then sends it to the Copyleaks API. The process is asynchronous; Copyleaks will notify your webhook URL once the scan is complete.
## Next Steps
Check the official SDK repository on GitHub for more examples and details.
View the official package on RubyGems.org to see all available versions.
Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.
Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.
Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.
Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.
---
# Resources → Legal
## About CopyleaksBot
Source: https://docs.copyleaks.com/resources/legal/copyleaksbot
> Information for webmasters, SEOs, and developers about CopyleaksBot, the web crawler used by Copyleaks.
CopyleaksBot is the official web crawler for Copyleaks. Its purpose is to discover and crawl publicly available web pages for our search services. We are committed to respecting the rules set forth by webmasters in their robots.txt files.
## User Agent
CopyleaksBot identifies itself with the following User-Agent string in its HTTP requests:
```
CopyleaksBot/1.0
```
## How to Control CopyleaksBot
To limit which pages Copyleaks can index, use your website's robots.txt file. CopyleaksBot fully respects the robots.txt standard. You can use it to prevent our bot from indexing your entire site, specific directories, or individual pages. The User-agent token for our bot is `CopyleaksBot`.
Add the following to your robots.txt file:
```txt
User-agent: CopyleaksBot
Disallow: /
```
Add the following to your robots.txt file:
```txt
User-agent: CopyleaksBot
Disallow: /private-directory/
```
Add the following to your robots.txt file:
```txt
User-agent: CopyleaksBot
Disallow: /path/to/page.html
```
## Related Resources
Get help with CopyleaksBot or other questions from our support team.
---
# Resources → Updates
## What's New
Source: https://docs.copyleaks.com/resources/updates/release-notes
> Learn about the latest updates and features in Copyleaks API.
Please periodically check this page to get official updates on the product. In this document, you will find information about product updates, new releases, deprecated functionality, bug fixes, and known issues.
***
## September 23, 2026 New
**Heatmaps for AI Image Detection**
AI Image Detection now shows you not just where an image was touched by AI, but how confident we are about every region. Request a heatmap and you get a graded, pixel-level view of the image, with the hottest areas marking the parts most likely to be AI-generated. It makes results easier to explain at a glance and gives you a richer visual to build into your own reports and review tools.
Heatmaps are available on both the synchronous and asynchronous AI Image Detection endpoints through a single optional request setting. Only need the verdict? On the synchronous endpoint you can skip the mask entirely for a leaner response. Existing integrations keep working exactly as before.
See the [AI Image Detector](/reference/actions/ai-image-detector/check) reference to get started, or the [async endpoint](/reference/actions/ai-image-detector/submit) for webhook-based submissions.
---
## September 22, 2026 New
**AI Text Detection Model V11.0**
We've released version 11.0 of the AI Text Detection model. This release improves detection accuracy and extends coverage to recently released large language models, so the detector keeps pace with the latest generative AI.
The new model is live on the [AI Text Detector](/reference/actions/writer-detector/check) endpoint and on scans submitted with `properties.aiGeneratedText.detect` enabled. No request changes are needed - the `modelVersion` field in the response now returns `v11.0`.
See the [AI Text Detection guide](/guides/ai-detector/ai-text-detection) to get started, or the [response reference](/reference/data-types/ai-detector/ai-text-detector-response).
---
## August 17, 2026 New
**AI Video Detection Upgrade**
We've improved AI Video Detection with support for newly released AI video generation models and broadened our supported video formats. See the [AI Video Detection guide](/guides/ai-detector/ai-video-detection) for supported formats, or the [API reference](/reference/actions/ai-video-detector/submit).
---
## September 24, 2026 New
**Object Detection Now Part of AI Image Detection**
Object detection is now available directly on the [AI Image Detector](/reference/actions/ai-image-detector/check) endpoint. Add the optional `objectDetection` field to your request to tell us which objects to locate (for example `[{"object":"face"}]`) and receive the AI-detection result together with a `detectedObjects` array - one Run-Length Encoded (RLE) segmentation mask per object found - in a single synchronous response. The same field is supported on the [asynchronous flow](/reference/actions/ai-image-detector/submit).
Requests with or without `objectDetection` cost the same 1 credit.
See the [AI Image Detection guide](/guides/ai-detector/ai-image-detection) to get started.
---
{/* In comment until the BU decides to publish the standalone Object Detection endpoint again (the endpoint itself remains operational).
## July 15, 2026 New
**Object Detection API Launch**
The new Object Detection API is now available. Submit an image with a list of objects to locate and receive a per-object Run-Length Encoded (RLE) segmentation mask in a single synchronous call. Object detection is also available on the asynchronous AI Image Detection flow via the `objectDetection` request field, which adds a `detectedObjects` array to the webhook payload.
See the [Object Detection guide](/guides/object-detection/detect-objects) to get started, or jump to the [API reference](/reference/actions/object-detection/check).
---
*/}
## July 12, 2026 New
**Citation Checker**
A new scan capability that checks whether the references and citations in a document are real and accurately described. Copyleaks detects every reference in the submitted text, parses it into structured fields, and validates it against a trusted source, helping you catch fabricated, misattributed, or incorrectly dated citations.
**Highlights:**
- Enable per scan with the new top-level `references.validate` property on the existing Submit endpoints (defaults to `false`)
- **Academic references** (papers, journal articles) are verified against the Copyleaks academic citation index
- **Non-academic references** (web pages, docs, encyclopedias) are verified by fetching the cited URL and comparing the live page to the citation
- The completed webhook reports a `referencesValidation` summary; the full per-reference results, including parsed fields, corroborating sources, and per-field match signals, are available in the crawled version
See the [Citation Checker concept](/concepts/features/citation-checker), the [Citation Checker guide](/guides/authenticity/citation-checker), or the [response schema](/reference/data-types/authenticity/results/crawled-version#citation-checker).
---
## July 1, 2026 New
**AI Image Detection Upgrade**
This version improves overall accuracy, particularly for image-editing use cases where AI-generated features are blended into standard images. We've sharpened our detection algorithms to better localize intricate details and specific subjects across varying image qualities. As always, this release ensures excellent, continuous compatibility with state-of-the-art, recently-released models.
---
## July 1, 2026 New
**Image Plagiarism Detection API Launch**
The new Image Plagiarism Detection API is now available. Submit an image and receive a categorized list of web matches - full matches (exact copies) and partial matches (modified versions), each with the web pages where the image was found — in a single synchronous call.
See the [Image Plagiarism Detection guide](/guides/authenticity/image-plagiarism-detection) to get started, or jump to the [API reference](/reference/actions/image-plagiarism-detector/check).
---
## June 22, 2026 New
**Higher Character Limit for AI Detection**
The synchronous AI Detection endpoint now accepts up to **100,000 characters** per request, raised from the previous 25,000 character limit. Submit larger text passages in a single call without splitting them.
See the [AI Text Detector reference](/reference/actions/writer-detector/check).
---
## June 17, 2026 New
**AI Image Detection Async Endpoint**
A new asynchronous endpoint joins the AI Image Detection API. Submit an image URL and receive results via webhook when processing is complete useful when you want a fire-and-forget submission instead of holding the connection open for the synchronous response.
**Highlights:**
- `POST /v1/ai-image-detector-async/{scanId}/submit` accepts an image URL and a webhook config
- Optional `maskType: "heatmap"` returns a pixel-level overlay of AI-generated regions
- Same `ai-image-1-ultra` model and webhook payload shape as the synchronous endpoint
- Custom `headers` for both the inbound image fetch and the outbound webhook call
See the [Async Submit reference](/reference/actions/ai-image-detector/submit) for the full property list and code samples. The original synchronous [Detect](/reference/actions/ai-image-detector/check) endpoint remains unchanged.
---
## May 31, 2026 New
**AI Video Detection API Launch**
We're launching the AI Video Detection API, which detects whether a video was generated or partially generated by AI.
**Key features:**
- **Audio & visual track analysis** - independently analyzes both tracks, returning time-based detection data (start positions and durations in milliseconds) for each
- **Overall AI ratio** - a single `overallAIRatio` score representing the proportion of the video that is AI-generated, combining both audio and visual detections
- **Metadata extraction** - pulls embedded provenance metadata (C2PA standard) to identify the generating tool and creation timestamp when available
- **Broad format support** - `.mp4`, `.avi`, `.mov`, `.mkv`, `.webm`, `.flv`, `.wmv`, `.mpg`, `.m4v`, `.3gp`, `.mxf`, up to 0.5 GB and 1 hour
- **Async webhook delivery** - submit a video URL and receive results via webhook when processing completes
See the [AI Video Detection guide](/guides/ai-detector/ai-video-detection) to get started, or jump to the [API reference](/reference/actions/ai-video-detector/submit).
---
## February 22, 2026 New
**Multipart Support for AI Image Detection**
The [AI Image Detection API](/reference/actions/ai-image-detector/check) now supports `multipart/form-data` (recommended) for submitting images as binary files. JSON with base64 encoding remains available but is less recommended for production use. See [Best Practices for Working with Images](/concepts/performance/image-best-practices) for optimization tips.
---
## February 1, 2026 New
**AI Image Detection Upgrade**
Enhanced capability by improving accuracy, adding supported models, smartphone features (iPhone smart magic eraser and Samsung GenAI editing).
The new version offers accuracy level improvements on social media, small, low-quality, and professionally filtered images. It also provides excellent support for the top-of-the-class models.
## December 16, 2025 Removal
**AI Code Detection Deprecated in Submit Endpoints**
Following the deprecation of the standalone AI Code Detection endpoint in August, we are now deprecating AI code detection capabilities from the all endpoints. The `properties.aiGeneratedText` feature will no longer support source code files.
The following property is deprecated in:
- `PUT https://api.copyleaks.com/v3/scans/submit/file/{scanid}`
- `PUT https://api.copyleaks.com/v3/scans/submit/url/{scanid}`
- `PUT https://api.copyleaks.com/v3/scans/submit-ocr/url/{scanid}`
For further information about the submit methods, please see [Scans Actions](/reference/actions/authenticity/overview).
This change only affects AI detection for programming languages and source code. AI Content Detection for natural language text continues to be fully supported.
---
## December 3, 2025 New
**Enhanced Scan Exclusion Options**
Added new fields to the `properties.scanning.exclude` object in Submit Endpoints:
- `properties.scanning.exclude.backlinksDomains` - Exclude results that contain backlinks to these specific domains. Provide an array of domain names to filter out from internet plagiarism results.
- `properties.scanning.exclude.text` - Exclude any results that contain text matching these phrases. Provide an array of text strings to ignore during scanning.
Documentation available in the [API Reference](/reference/actions/overview).
---
## August 31, 2025 New
**AI Image Detection API Launch**
The new AI Image Detection API is now available, enabling you to detect whether an image is AI-generated or partially AI-generated.
**Key Features:**
- **Pixel-level analysis** - Get detailed masks showing which parts of an image are AI-generated vs. human-created
- **Metadata extraction** - Automatically extract AI generation metadata when available (issuer, creation time, tool used)
- **Comprehensive results** - Receive percentage breakdowns of AI vs. human content, plus detailed RLE-encoded mask data
- **Flexible image support** - Process PNG, JPG, JPEG, BMP, WebP, and HEIC/HEIF formats up to 27 megapixels
See the [AI Image Detection API documentation](/reference/actions/ai-image-detector/check) for details.
---
## August 28, 2025 Deprecated
**Standalone AI Code Detection Endpoint Deprecated**
The standalone AI Code Detection endpoint for source code has been deprecated and will be removed in a future release. This is a dedicated endpoint specifically for detecting AI-generated source code across multiple programming languages.
**Deprecated endpoint:**
`POST https://api.copyleaks.com/v2/writer-detector/source-code/{scanId}/check`
**Alternative:** For natural language text, use the standard [AI Content Detection API](/reference/actions/writer-detector/overview).
## August 18, 2025 New
**Timezone Customization for PDF Reports**
You can now control the timezone of the scan time displayed on PDF reports by using a new field in your scan submissions.
`properties.scanTimeZone` - Specifies the desired IANA Time Zone (e.g., 'America/New_York') for the report's scan time. If this property is not set, the timezone will default to the user's country. If the country is unknown, UTC will be used.
---
## July 08, 2025 New
**Text Moderation API Launch**
The new Text Moderation API is now available, designed to help you maintain safe and appropriate content across your platform.
**Key Features:**
- **Real-time content analysis** - Get instant results for submitted text
- **10+ moderation categories** - Detect hate speech, toxic language, adult content, violence, self-harm, cybersecurity threats, and more
- **Precise flagging** - Receive exact character positions for each flagged segment
- **Simple integration** - RESTful API that fits seamlessly into any content workflow
See the [Text Moderation API documentation](/guides/moderation/moderate-text/) for details.
---
## May 15, 2025 New
**PDF Report Version Management**
A new field has been added for scan submissions:
- `properties.pdf.reportVersion` - Specifies which version of the PDF report to generate. This string-based property overrides the legacy `version` (integer) property if both are provided. It also allows you to select the latest stable version of the PDF report by using `"latest"`.
**Default Behavior:**
If neither `reportVersion` nor `version` is set:
- New users (created after **2025-05-15**) receive **v3** by default
- Existing users receive **v1** by default
---
## May 14, 2025 New
**AI Source Match Feature Launch**
In an evolving digital landscape, understanding the origin and nature of content is more crucial than ever. AI Source Match revolutionizes our plagiarism and AI detection capabilities by identifying online sources that are suspected to be AI-generated.
**Key Benefits:**
- **Comprehensive Plagiarism Analysis** - Go beyond standard plagiarism checks by providing insights into whether the source of plagiarized content is likely AI-generated
- **Deeper Source Intelligence** - Gain a clearer understanding of the authenticity of external sources, helping you assess content originality more thoroughly
- **Enhanced Authenticity & Integrity** - Equip yourself with advanced tools to better uphold originality and academic/creative integrity by identifying both direct plagiarism and reliance on AI-generated source material
**Implementation:**
The `properties.aiSourceMatch` feature can be easily activated with the `enable` parameter within your Authenticity API calls.
---
## May 08, 2025 New
**Display Language Support**
A new field has been added for scan submissions:
- **Display Language** - 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.
---
## March 09, 2025 New
**Overview API Introduction**
Copyleaks introduces the Overview API to provide key insights from user scans and author's historical data.
**Features:**
- **Gen AI Overview** - Delivers a thorough analysis of each submitted scan, summarizing its content and identifying central themes or patterns
- **Key Insights Analysis** - Pinpoints notable findings and directs user attention to significant details within the scanned material
- **Historical Context** - When historical scan data is available, incorporates past insights and trends to provide a richer, context-driven perspective on current scan results
---
## March 05, 2025 New
**Course and Assignment Identification**
New fields have been added for scan submissions:
- **Course ID** - A unique identifier for the course associated with the submission
- **Assignment ID** - A unique identifier for the assignment associated with the submission
---
## April 18, 2024 New
**Enhanced Alert Categorization**
A new field has been added for alerts in the completed webhook response:
- `category` - Scan alert category
---
## April 16, 2024 New
**AI Content Detection Model Versioning**
Added a new field to the response of AI Content Detection:
- `modelVersion` - The version of the AI Content Detection model used
---
## April 16, 2024 New
**ID Pattern Filtering for Scan Results**
Added a new field in the different types of Submit Endpoints in the API:
- `properties.scanning.include.idPattern` - Includes results only if their scan ID matches the supplied pattern. Matched submissions will be the only submissions included from Shared Data Hub and Private Cloud Hubs results.
Documentation available in the [API Reference](/reference/actions/overview).
---
## April 4, 2024 New
**Alert Types Documentation**
Added comprehensive [Alert Types documentation](/reference/data-types/authenticity/scan-alerts).
When scanning with Copyleaks, various alerts may be received in your Completion Webhook for AI detection, writing suggestions, failed scans, cheating, and more. This page provides a complete list of possible alerts.
---
## February 26, 2024 New
**Grammar Checker API Enhancement**
New field added to the Grammar Checker API - [Get Correction Types](/reference/data-types/writing/correction-types):
- `correctionTypes[].category` - Category of the correction type
---
## February 26, 2024 New
**Language Code Support**
New field added to the request body for:
- [AI Content Detection - Submit Natural Language](/reference/actions/writer-detector/check)
- [Grammar Checker - Submit Text](/reference/actions/writing-assistant/check)
- `language` - The language code of your content. The selected language should be from the Supported Languages list. If not supplied, the system will automatically detect the content language.
---
## February 25, 2024 New
**Private Cloud Hubs API**
Introduction of the [Private Cloud Hubs API](/reference/actions/private-cloud-hub/overview).
Retrieve Private Cloud Hub information including credit consumption, metadata values, and current status. Requires "Super Admin" or "Admin" role.
---
## December 7, 2023 New
**Grammar Checker API Launch**
Introduction of the [Grammar Checker API](/reference/actions/writing-assistant/overview).
Grammar Checker offers real-time, AI-driven writing corrections, serving as a virtual assessment API capable of providing constructive critiques and instantaneous enhancements to textual content.
---
## September 28, 2023 New
**AI Content Detection for Source Code**
Launch of [AI Content Detection API for Source Code](/reference/actions/writer-detector/overview).
Use Copyleaks AI Content Detection to differentiate between human-written and AI-generated source code.
---
## May 3, 2023 New
**PDF Report Version 2 Public Release**
PDF version 2 is now publicly available for API users. The updated PDF report includes AI detection results, cheat alerts, and an updated interface. To enable the newest version, edit the `properties.pdf.version` flag of the [Submit endpoint](/reference/actions/authenticity/overview).
---
## January 29, 2023 New
**Document Template Exclusion**
You can now easily exclude document template text from plagiarism scanning. For more information, check the `properties.exclude.documentTemplateIds` flag on the [Submit endpoint](/reference/actions/authenticity/overview).
---
## January 12, 2023 New
**AI Content Detection API Launch**
Launch of the AI Content Detection API, which confirms whether provided text was created by a human or AI.
Read the [AI Content Detection API Documentation](/reference/actions/writer-detector/overview).
---
## January 1, 2023 New
**AI Content Detection Integration**
AI Content Detection is now available as an option within the plagiarism detection API. To enable this option, use the flag `properties.aiGeneratedText.detect`.
Documentation available for the [Submit endpoint](/reference/actions/authenticity/overview).
---
## November 13, 2022 New
**Cross-Language Plagiarism Detection**
Launch of Cross-Language Plagiarism Detection feature. Scans can be performed on uploaded documents across nearly 30 languages, with additional languages regularly added. For example, a document uploaded in English can find potential plagiarism matches in Chinese, Spanish, German, or any other selected language.
To activate this feature, use the flag: `properties.scanning.crossLanguages.languages[]`.
Documentation available for the [Submit endpoint](/reference/actions/authenticity/overview).
---
## November 1, 2022 New
**New-Result Webhook Enhancement**
Added two fields to the [New-Result webhook](/reference/data-types/authenticity/results/new-result):
- `developerPayload` - The developer payload provided in the submit method
- `score` - The current aggregate score of the scan up to this point
---
## May 25, 2022 New
**Product Unification**
Merged Education and Business products into one unified product that includes all features from both previous products.
**Key Changes:**
- Former Business users can now access Education-exclusive features, such as the Copyleaks Shared Data Hub
- [New endpoints](/reference/actions/authenticity/overview) available for the merged product (existing integrations remain unchanged)
- Pricing model aligned with Education pricing model (existing subscriptions unchanged)
---
## February 9, 2022 New
**Indexed Document Masking Policy**
Added support for indexed document masking policy for repository users. Define custom masking policies for each document in your repository.
For more information, see the `properties.indexing.repositories[].maskingPolicy` flag on the submit method.
---
## February 8, 2022 New
**Enhanced URL Submission Control**
Added options to control HTTP headers (`headers` field) and request method (`verb` field) when using Submit by URL for both Business and Education users.
---
## February 6, 2022 New
**Copyleaks Platform Release**
Released new version of Copyleaks with comprehensive management capabilities:
- [Copyleaks Identity](https://id.copyleaks.com) - Manage security settings, billing, and teams or Private Cloud Hubs
- [Copyleaks Authentication](https://id.copyleaks.com/security) - Multi-factor authentication options: email or authenticator app
- [Copyleaks Teams](https://admin.copyleaks.com/members) & [Private Cloud Hubs](https://admin.copyleaks.com/repositories) - Manage users, documents, analytics, and permissions
- [Copyleaks Billing](https://id.copyleaks.com/billing) - View current plan, past invoices, and billing information
---
## January 9, 2022 New
**Credits Management Documentation**
Added comprehensive article about effective Copyleaks credits management and monitoring: [How to manage your credits?](/concepts/management/manage-your-credits)
---
## September 1, 2021 New
**Teams Integration Documentation**
Added integration guide between Copyleaks API and Copyleaks Teams.
---
## February 28, 2021 New
**Java SDK Launch**
Launched official SDK for Java developers: [Java SDK](https://github.com/Copyleaks/Java-Plagiarism-Checker).
Package available via [Maven](https://search.maven.org/search?q=g:com.copyleaks.sdk).
---
## February 1, 2021 Change
**Server IP Address Update**
Server IP addresses changed starting March 1, 2021.
If your application is behind a firewall, update your HTTP endpoints to allow the new Copyleaks IP policy. If you are not filtering access by IP, no action is required.
Starting March 1, 2021, specific IP addresses for contacting your service are not guaranteed.
---
## January 24, 2021 New
**Whitelist IP Authentication**
Security enhancement: Whitelist IP Authentication allows approval of requests from specified IP addresses. Read more: [Whitelist IP Authentication](https://api.copyleaks.com/dashboard/ip-whitelist).
---
## January 21, 2021 Change
**Date Format Update**
Updated date format in result titles for better readability.
- Old format: "dd/MM/yyyy"
- New format: "MMMM dd, yyyy"
---
## January 19, 2021 New
**PHP SDK Launch**
Launched official SDK for PHP developers: [PHP SDK](https://github.com/Copyleaks/PHP-Plagiarism-Checker).
Package available via [Packagist](https://packagist.org/packages/copyleaks/php-plagiarism-checker).
---
## January 17, 2021 New
**Node.js SDK Launch**
Launched official SDK for Node.js developers: [Node.js SDK](https://github.com/Copyleaks/NodeJS-Plagiarism-Checker).
Package available via [npm](https://www.npmjs.com/package/plagiarism-checker).
---
## January 13, 2021 New
**Python SDK Launch**
Launched official SDK for Python developers: [Python SDK](https://github.com/Copyleaks/Python-Plagiarism-Checker).
Package available via [PyPI](https://pypi.org/project/copyleaks/).
---
## December 24, 2020 Change
**Webhook Retry Policy Enhancement**
Increased the number of retry attempts when sending system webhooks. Read more in the "Retry Policy" section on the [Webhooks page](/reference/data-types/authenticity/webhooks/overview).
- Previous: Up to 12 attempts (2, 4, 8, ..., 4096 seconds)
- Updated: Up to 17 attempts (2, 4, ..., 65535 seconds)
---
## December 23, 2020 New
**ID Pattern Exclusion**
Added new feature to Submit methods: `properties.scanning.exclude.idPattern`. This feature allows exclusion of submissions from results if their ID matches the supplied pattern.
Available for all Submit endpoints in both Business and Education APIs.
---
## December 10, 2020 Change
**Webhooks Documentation Update**
Updated [Webhooks documentation page](/reference/data-types/authenticity/webhooks/overview) with "At-Least-Once Delivery" section.
---
## November 24, 2020 Deprecated
**Batch Method Deprecation**
The following method is now obsolete:
- `PATCH https://api.copyleaks.com/v3/education/batch/start`
To compare multiple files, see instructions: [Cross Compare Multiple Files](/reference/actions/miscellaneous/supported-cross-languages).
---
## November 23, 2020 New
**Cross Compare Documentation**
New article: [Cross Compare Multiple Files](/reference/actions/miscellaneous/supported-cross-languages).
---
## November 2, 2020 New
**API Dashboard Launch**
Launched new version of the API dashboard. Easily administer scans and visualize API scan results to ensure comprehensive monitoring.
---
## October 25, 2020 Change
**Rate Limiting Implementation**
Copyleaks API now enforces rate limits for the following methods:
- `https://id.copyleaks.com/v3/account/login/api` - Maximum 12 calls per 15 minutes
- `https://api.copyleaks.com/v3/education|businesses/scans/{scanId}/webhooks/resend` - Maximum 300 calls per 60 minutes
- `https://api.copyleaks.com/v3/education|businesses/usages/history` - Maximum 10 calls per 60 minutes
- `https://api.copyleaks.com/v3/businesses/credits` - Maximum 10 calls per 15 minutes
Exceeding the maximum number of calls will result in an [HTTP 429](/using-the-apis/rate-limits/#handling-rate-limit-blocks) response code.
---
## October 15, 2020 New
**Open Source Plagiarism Report**
Launched the Open Source Plagiarism Report. Embed a ready-to-use plagiarism report within your own domain (whitelabel). Read more: [Open Source Plagiarism Report](https://github.com/Copyleaks/plagiarism-report).
---
## October 10, 2020 New
**Cheat Detection**
Added cheat detection capabilities. To enable this feature, turn on the `properties.cheatDetection` flag in the Submit methods. Available for both Education and Business users.
---
## September 18, 2020 New
**Teams Capabilities**
Copyleaks V3 API now supports Teams capabilities. Build your own team, invite members, and share credits across multiple users.
---
## September 1, 2020 Deprecated
**Download Methods Deprecation**
The following methods are now obsolete:
- `https://api.copyleaks.com/v3/downloads/{scanId}`
- `https://api.copyleaks.com/v3/downloads/{scanId}/results/{resultId}`
- `https://api.copyleaks.com/v3/downloads/{scanId}/report.pdf`
Use the [Export method](/reference/actions/downloads/overview) instead.
---
## August 7, 2020 New
**.NET Core SDK Launch**
Launched official SDK for .NET Core: [.NET Core SDK](https://github.com/Copyleaks/.net-core-plagiarism-checker).
Package available via [NuGet](https://www.nuget.org/packages/Copyleaks/).
---
## August 5, 2020 New
**Sensitive Data Masking**
Added Sensitive Data Masking feature to prevent leakage of sensitive data within submitted materials. This feature works on textual content and images; other media types are not covered. For more information, visit the Submit method documentation.
---
## June 25, 2020 New
**Reference Exclusion**
Copyleaks now supports excluding references from educational plagiarism scans. This text detection algorithm is based on advanced AI capabilities to ensure high success rates. To use this feature, turn on the `properties.exclude.references` flag.
---
## June 1, 2020 New
**Private Cloud Hubs**
Use Copyleaks to host all your internal documents and compare scans against them. This feature works similarly to the Copyleaks Shared Data Hub but provides private storage accessible only to you. To use this feature, purchase the product hosting plan and use the `properties.scanning.repositories` flag in the Submit method.
---
## May 15, 2020 Change
**PDF Reports for Business Users**
PDF reports are now available for Business users. To enable this feature, turn on the `properties.pdf.create` flag in the Submit method.
---
## February 28, 2019 New
**API Version 3 Launch**
API version 3 is now deployed and in production.
---
# Reference
## API Reference
Source: https://docs.copyleaks.com/reference/overview
> Explore the comprehensive Copyleaks API reference, with detailed information about endpoints, data types, and specifications.
Explore the comprehensive [Copyleaks API](https://copyleaks.com/api) reference, with detailed information about endpoints, data types, and specifications.
Endpoints for submitting scans, checking credits, downloading reports, and more.
Detailed information about various data types, supported languages, and other technical details.
---
# Actions
## Actions Overview
Source: https://docs.copyleaks.com/reference/actions/overview
> Explore the Copyleaks API actions for managing scans, detecting AI-generated content, moderating text, and more.
Explore the Copyleaks API actions to manage your content integrity and authenticity needs. Each action provides specific functionalities to help you integrate our services effectively.
Manage your account and login.
Submit scans, check status, and manage results.
Check credits and view usage history.
Detect AI-generated text.
Detect AI-generated images.
{/* In comment until the BU decides to publish the standalone Object Detection endpoint again
Locate and segment specific objects within an image.
*/}
Search the web for unauthorized copies of an image.
Check grammar and get writing feedback.
Moderate text for harmful content.
Export full scan results to your servers.
Get supported file types, languages, and more.
Get information about your Private Cloud Hubs.
---
# Actions → Account
## Account Actions
Source: https://docs.copyleaks.com/reference/actions/account/overview
> Learn how to authenticate and get started with Copyleaks APIs
import { EndpointRow } from '/snippets/endpoint-row.mdx';
Copyleaks APIs allow you to integrate your systems and services with Copyleaks products. You can start working with a Copyleaks API by sending HTTP requests to the Copyleaks servers. To do so, first register to Copyleaks and get your API key. Then, use your API key and email address to login.
## Authentication API
---
## Login
Source: https://docs.copyleaks.com/reference/actions/account/login
> Authenticate with the Copyleaks API using your email and API key
```bash title="cURL" icon="terminal"
export COPYLEAKS_EMAIL="your@email.address"
export COPYLEAKS_API_KEY="your-api-key-here"
curl --request POST \
--url https://id.copyleaks.com/v3/account/login/api \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data "{
\"email\": \"${COPYLEAKS_EMAIL}\",
\"key\": \"${COPYLEAKS_API_KEY}\"
}"
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
EMAIL_ADDRESS = "your@email.address"
API_KEY = "your-api-key-here"
auth_token = Copyleaks.login(EMAIL_ADDRESS, API_KEY)
print("Logged successfully!\nToken:", auth_token)
```
```javascript title="JavaScript" icon="square-js"
const { Copyleaks } = require("plagiarism-checker");
const EMAIL_ADDRESS = "your@email.address";
const API_KEY = "your-api-key-here";
const copyleaks = new Copyleaks();
copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY).then(
(loginResult) => console.log("Access Token:", loginResult.access_token),
(err) => { throw err; }
);
```
```java title="Java" icon="java"
import com.copyleaks.sdk.api.Copyleaks;
String EMAIL_ADDRESS = "your@email.address";
String API_KEY = "00000000-0000-0000-0000-000000000000";
String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
System.out.println("Logged successfully!\nToken: " + authToken);
```
```json 200 OK
{
"access_token": "ACLNSKNSDAACCAJANCOIUiausoo_saidjaskldjoa...",
".issued": "2018-11-24T16:15:38.2431255+02:00",
".expires": "2018-11-26T16:15:38.2431255+02:00"
}
```
Login to the Copyleaks API using your email and API key.
Once logged in, you will get back a login token that will be used to authenticate yourself when calling the other API methods.
After generating the login-token, you should attach the token for your next calls. Attaching the endpoint is done by adding this header to your calls:
```http
Authorization: Bearer TOKEN
```
A generated token is valid for **48 hours**. Within this period of time, you can use it multiple times. Before attaching the `Authorization` header for your next endpoint calls, make sure that the token has not expired. If it expired, generate a new one.
The Copyleaks API token should be treated as a password. Attackers, who can gain access to this token, can access your private information and modify it.
**12 requests per account/15 minutes**
If you exceed the API limit, authentication will be blocked for 5 minutes (Rate Limit Exceeded HTTP 429 - Too Many Requests).
## Request
### Headers
```http
Content-Type: application/json
Accept: application/json
```
### Body
Your Copyleaks account email address
Your Copyleaks account API key (UUID format)
## Responses
**200 OK** - The command was executed successfully.
```json
{
"access_token": "ACLNSKNSDAACCAJANCOIUiausoo_saidjaskldjoa...",
".issued": "2018-11-24T16:15:38.2431255+02:00",
".expires": "2018-11-26T16:15:38.2431255+02:00"
}
```
**400 Bad Request** - Invalid request format or missing required fields
**401 Unauthorized** - Invalid email or API key
**429 Too Many Requests** - Rate limit exceeded (blocked for 5 minutes)
---
# Actions → Admin
## Admin Actions
Source: https://docs.copyleaks.com/reference/actions/admin/overview
> Manage your Copyleaks account, check credits, and view usage history
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks Admin API endpoints allow you to manage account-related operations such as checking your credit balance and viewing your usage history. These endpoints help you monitor and administer your Copyleaks account effectively.
## Endpoints
---
## Get Credit Balance
Source: https://docs.copyleaks.com/reference/actions/admin/check-credits
> Get your current credit balance.
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v3/scans/credits \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
balance = Copyleaks.credits_balance(auth_token)
print(balance)
```
```json 200 OK
{
"Amount": 100
}
```
Get your current credit balance. Each credit allows the scan of up to 250 words.
**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
### Headers
```http
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Responses
**200 OK** - The command was executed.
```json
{
"Amount": 100
}
```
**401 Unauthorized** - Authorization has been denied for this request.
---
## Usage History
Source: https://docs.copyleaks.com/reference/actions/admin/usage-history
> Get your usage history between two dates.
```bash title="cURL" icon="terminal"
curl --request GET \
--url 'https://api.copyleaks.com/v3/scans/usages/history?start=01-01-2020&end=31-01-2020' \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
csv_history = Copyleaks.usages_history_csv(auth_token, "01-01-2020", "31-01-2020")
print(csv_history)
```
```text 200 OK
CSV file attached to the response.
```
This endpoint allows you to export your usage history between two dates.
The output results will be exported to a csv file and it will be attached to the response.
**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
### Query Parameters
The start date to collect usage history from.
Format: `dd-MM-yyyy`
Example: `01-01-2020`
The end date to collect usage history from.
Format: `dd-MM-yyyy`
Example: `31-01-2020`
### Headers
```http
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Responses
**200 OK** - The data was exported. Example: csv file will be attached to the response.
**400 Bad Request** - Bad request. Wrong input parameters were provided.
**401 Unauthorized** - Authorization has been denied for this request.
---
# Actions → Authenticity
## Authenticity Actions
Source: https://docs.copyleaks.com/reference/actions/authenticity/overview
> Reference for the Copyleaks Authenticity API endpoints to submit, start, and manage plagiarism and AI detection scans.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks Authenticity API allows you to integrate your institution's platform, learning management system or any other e-learning solution with Copyleaks products.
## Endpoints
---
## Submit File
Source: https://docs.copyleaks.com/reference/actions/authenticity/submit-file
> Scan files to find where the content has been used elsewhere and check its originality.
import ScanSubmitProperties from '/snippets/scan-submit-properties.mdx';
```bash title="cURL" icon="terminal"
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
}
}'
```
```python title="Python" icon="python"
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("your@email.address", "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)
```
```javascript title="JavaScript" icon="square-js"
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);
```
```java title="Java" icon="java"
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));
```
```json 201 Created
{
"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": ""
}
```
Scan files to find where the content has been used elsewhere and check its originality. Using submit-file you can scan various file types for plagiarism and identify copied content. See [supported formats](/reference/actions/miscellaneous/supported-plagiarism-file-types).
**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](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
Match pattern: ``[a-z0-9] !@$^&-+%=_(){}<>';:/.",~`|``
### Headers
```http
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.pdf`
Configuration options for the scan.
For testing purposes, use sandbox mode, which does not consume credits.
## Responses
**201 Created** - The scan was successfully created and is now processing.
```json
{
"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.
---
## Submit URL
Source: https://docs.copyleaks.com/reference/actions/authenticity/submit-url
> Scan a URL to check for plagiarism, AI-generated content, and writing quality.
import ScanSubmitProperties from '/snippets/scan-submit-properties.mdx';
```bash title="cURL" icon="terminal"
curl --request PUT \
--url https://api.copyleaks.com/v3/scans/submit/url/my-scan-123 \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://copyleaks.com/ai-detector",
"properties": {
"webhooks": {
"status": "https://my-server.com/webhook/{STATUS}"
},
"sandbox": true,
"aiGeneratedText": { "detect": true }
}
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.document import UrlDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
from copyleaks.models.submit.properties.submit_webhooks import SubmitWebhooks
from copyleaks.models.submit.properties.ai_generated_text import AIGeneratedText
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
submission = UrlDocument("https://copyleaks.com/ai-detector")
submission.set_properties(ScanProperties(
webhooks=SubmitWebhooks(status="https://my-server.com/webhook/{STATUS}"),
sandbox=True,
ai_generated_text=AIGeneratedText(detect=True),
))
Copyleaks.submit_url(auth_token, "my-scan-123", submission)
```
```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksURLSubmissionModel } = require('plagiarism-checker');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const submission = new CopyleaksURLSubmissionModel(
'https://copyleaks.com/ai-detector',
{
sandbox: true,
webhooks: { status: 'https://my-server.com/webhook/{STATUS}' },
aiGeneratedText: { detect: true },
}
);
await copyleaks.submitUrlAsync(auth, 'my-scan-123', submission);
```
```java title="Java" icon="java"
import com.copyleaks.sdk.api.Copyleaks;
import com.copyleaks.sdk.api.models.submissions.CopyleaksUrlSubmissionModel;
import com.copyleaks.sdk.api.models.submissions.properties.*;
String authToken = Copyleaks.login("your@email", "API_KEY");
SubmissionWebhooks hooks = new SubmissionWebhooks("https://my-server.com/webhook/{STATUS}");
SubmissionProperties props = new SubmissionProperties(hooks);
props.setSandbox(true);
SubmissionAIGeneratedText ai = new SubmissionAIGeneratedText();
ai.setDetect(true);
props.setAiGeneratedText(ai);
Copyleaks.submitUrl(authToken, "my-scan-123",
new CopyleaksUrlSubmissionModel("https://copyleaks.com/ai-detector", props));
```
```json 201 Created
{
"scannedDocument": {
"scanId": "scan-id23",
"totalWords": 42,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T06:46:31.501305Z",
"metadata": {},
"detectedLanguage": "en"
},
"results": {
"score": { "aggregatedScore": 2.4, "identicalWords": 1 }
},
"status": 0,
"developerPayload": ""
}
```
Submit a URL to be scanned for plagiarism, AI-generated content, and writing analysis. Copyleaks will crawl the URL, extract its content, and scan it against its vast database and the internet.
Once submitted, the scan will be processed, and you can monitor its progress using webhooks or by checking the scan status.
**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](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
The request body is a JSON object containing the URL to scan and a `properties` object to configure the scan.
The URL to be scanned. e.g., `https://copyleaks.com`
Describes the HTTP method that is going to be executed on the specified url. Supported Values: `GET`, `POST`, `PUT`
Custom headers for the request. If specified, no Copyleaks headers are attached (otherwise defaults are used). Use `Set-Cookie` for cookies. Multiple values supported. Example: `[["header-key", "header-value"], ...]`
Configuration options for the scan.
For testing purposes, use sandbox mode, which does not consume credits.
## Responses
**201 Created** - The scan was successfully created and is now processing.
```json
{
"scannedDocument": {
"scanId": "scan-id23",
"totalWords": 42,
"creationTime": "2025-08-05T06:46:31.501305Z",
"detectedLanguage": "en"
},
"results": {
"score": {
"identicalWords": 1,
"minorChangedWords": 0,
"relatedMeaningWords": 0,
"aggregatedScore": 2.4
}
},
"status": 0,
"developerPayload": ""
}
```
**400 Bad Request** - The url 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.
## Next Steps
Learn how to use Copyleaks to detect AI-generated text, including from the latest models.
Learn how to use Copyleaks to detect plagiarism by comparing your content against billions of online sources and internal documents.
Learn how to use Copyleaks to check for grammar mistakes and get suggestions for improving your writing.
---
## Submit OCR
Source: https://docs.copyleaks.com/reference/actions/authenticity/submit-ocr
> Scan images with textual content to find where the content has been used before and check its originality.
import ScanSubmitProperties from '/snippets/scan-submit-properties.mdx';
```bash title="cURL" icon="terminal"
curl --request PUT \
--url https://api.copyleaks.com/v3/scans/submit/ocr/my-scan-123 \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"base64": "YOUR_BASE64_HERE",
"filename": "image.jpg",
"langCode": "en",
"properties": {
"webhooks": {
"status": "https://my-server.com/webhook/{STATUS}"
},
"sandbox": true
}
}'
```
```python title="Python" icon="python"
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.document import OcrFileDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
from copyleaks.models.submit.properties.submit_webhooks import SubmitWebhooks
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
with open("image.jpg", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
submission = OcrFileDocument(b64, "image.jpg", "en")
submission.set_properties(ScanProperties(
webhooks=SubmitWebhooks(status="https://my-server.com/webhook/{STATUS}"),
sandbox=True,
))
Copyleaks.submit_file_ocr(auth_token, "my-scan-123", submission)
```
```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksFileOcrSubmissionModel } = 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('image.jpg').toString('base64');
const submission = new CopyleaksFileOcrSubmissionModel(
'en',
base64Content,
'image.jpg',
{
sandbox: true,
webhooks: { status: 'https://my-server.com/webhook/{STATUS}' },
}
);
await copyleaks.submitFileOcrAsync(auth, 'my-scan-123', submission);
```
```java title="Java" icon="java"
import classes.Copyleaks;
import models.submissions.CopyleaksOcrSubmissionModel;
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("image.jpg")));
SubmissionWebhooks hooks = new SubmissionWebhooks("https://my-server.com/webhook/{STATUS}");
SubmissionProperties props = new SubmissionProperties(hooks);
props.setSandbox(true);
Copyleaks.submitOCR(authToken, "my-scan-123",
new CopyleaksOcrSubmissionModel(b64, "image.jpg", "en", props));
```
```json 201 Created
{
"scannedDocument": {
"scanId": "scan-id32",
"totalWords": 2,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T07:19:08.181236Z",
"metadata": { "filename": "file.jpg" },
"detectedLanguage": "en"
},
"results": {
"score": { "aggregatedScore": 50.0, "identicalWords": 1 },
"internet": [
{ "url": "http://example.com/", "id": "2a1b402420", "title": "Example Domain" }
]
},
"status": 0,
"developerPayload": ""
}
```
Scan images with textual content to find where the content has been used before and check its originality. Using submit-ocr you can scan various image file types for plagiarism and identify infringed content. Only the textual content in the picture will be scanned and not the graphics. See [supported formats](/reference/actions/miscellaneous/supported-plagiarism-file-types).
**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](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
The request body is a JSON object containing the image file to scan and a `properties` object to configure the 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: `image.jpg`
The language of the text in the image. See [supported languages](/reference/actions/miscellaneous/ocr-supported-languages).
Example: `en`
Configuration options for the scan.
For testing purposes, use sandbox mode, which does not consume credits.
## Responses
**201 Created** - The scan was successfully created and is now processing.
```json
{
"scannedDocument": {
"scanId": "scan-id32",
"totalWords": 2,
"totalExcluded": 0,
"credits": 0,
"expectedCredits": 1,
"creationTime": "2025-08-05T07:19:08.181236Z",
"metadata": {
"filename": "file.jpg"
},
"detectedLanguage": "en"
},
"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.
---
## Start Scans
Source: https://docs.copyleaks.com/reference/actions/authenticity/start
> Start scanning a list of price-checked scans.
```bash title="cURL" icon="terminal"
curl --request PATCH \
--url https://api.copyleaks.com/v3/scans/start \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"trigger": ["Your-scan-id-1", "Your-scan-id-2"],
"errorHandling": 0
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.start import Start, StartErrorHandling
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
start = Start()
start.set_trigger(["Your-scan-id-1", "Your-scan-id-2"])
start.set_error_handling(StartErrorHandling.CANCEL)
Copyleaks.start(auth_token, start)
```
```json 200 OK
{
"success": ["Your-scan-id"],
"failed": []
}
```
Start scanning all the files you submitted for a price-check.
**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
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
The request body is a JSON object containing the scans to start.
A list of scans that you submitted for a check-credits scan and that you would like to submit for a full scan.
This array can scan up to 100 submissions.
Example: `[ "Your-scan-id-1", "Your-scan-id-2" ]`
When set to ignore (ignore = 1) the trigger scans will start running even if some of them are in error mode, when set to cancel (cancel = 0) the request will be cancelled if any error was found. Possible Values: 0 (Cancel), 1 (Ignore).
Possible Values:
- **0** : Cancel
- **1** : Ignore
## Responses
**200 OK** - The command was executed.
```json
{
"success": ["Your-scan-id"],
"failed": []
}
```
**400 Bad Request** - Bad request.
**401 Unauthorized** - Authorization has been denied for this request.
---
## Delete Scans
Source: https://docs.copyleaks.com/reference/actions/authenticity/delete
> Delete scans from Copyleaks API.
```bash title="cURL" icon="terminal"
curl --request PATCH \
--url https://api.copyleaks.com/v3.1/scans/delete \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"scans": [
{ "id": "Your-scan-id-1" },
{ "id": "Your-scan-id-2" }
],
"purge": false
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.delete import Delete, DeleteScan
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
delete = Delete()
delete.set_scans([DeleteScan("Your-scan-id-1"), DeleteScan("Your-scan-id-2")])
delete.set_purge(False)
Copyleaks.delete(auth_token, delete)
```
```json 202 Accepted
{}
```
Delete scans from Copyleaks API. Only completed scans can be deleted. All of the scan results, metadata and information will be removed.
The delete is performed in the background, the deletion process can take few minutes.
**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
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
The request body is a JSON object containing the scans to delete.
The list of scans to delete.
`<= 10000` items
Example: `[ {"id": "Your-scan-id-1"}, {"id": "Your-scan-id-2"} ]`
Deleting and purging a scan through the API will remove all traces of the scan from Copyleaks servers, including Shared Data Hubs and Private Cloud Hubs. Once purged, the scan will be permanently deleted and will not be available for future scans.
Allows you to register to a webhook that will be fired once the removal has been completed. Make sure that your endpoint is listening to a POST method (no body parameters were supplied).
Example: `https://yoursite.com/webhook/deleted`
Adds user specific headers to the request. This is needed in case the webhook endpoint requires any custom headers.
Example: `[ [ "header-key", "header-value" ], ... ]`
## Responses
**202 Accepted** - The request was placed for removal. Note that this process is asynchronous. This means that the actual removal will take place once one of our servers will be free. In order to get notified after the command execution, register to webhook notification (completionWebhook).
**400 Bad Request** - Bad Request.
**401 Unauthorized** - Authorization has been denied for this request.
---
## Resend Webhook
Source: https://docs.copyleaks.com/reference/actions/authenticity/resend-webhook
> Resend webhooks for existing scans.
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v3/scans/my-scan-123/webhooks/resend \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
Copyleaks.resend_webhook(auth_token, "my-scan-123")
```
```json 202 Accepted
{}
```
If for some reason you did not receive the webhook to a specific scan or you are interested in resending a webhook, you can do it using the resend webhook.
Simply add the Scan Id of the relevant scan and a webhook will be sent to your endpoint.
Use this endpoint to resend webhooks for scan with completed status. Valid statuses: success (completed), failed (error'ed), indexed and price-checked. You cannot send the resend webhook for scans that are still running and processed.
**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
The scan id of the scan you would like to resend the webhook for.
### Headers
```http
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Responses
**202 Accepted** - The request accepted. The webhook will be sent shortly.
**400 Bad Request** - The scan is not ready yet. Therefore, cannot resend webhook.
**401 Unauthorized** - Authorization has been denied for this request.
**404 Not Found** - No such scan. Check your scanId argument.
---
# Actions → Image Plagiarism Detector
## Image Plagiarism Detector Actions
Source: https://docs.copyleaks.com/reference/actions/image-plagiarism-detector/overview
> Search the web for unauthorized copies of an image.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks Image Plagiarism Detection API searches the web for copies of a submitted image, returning categorized matches - full matches and partial matches, each with the web pages where the image was found - in a single synchronous call.
## Endpoints
---
## Image Plagiarism Detection
Source: https://docs.copyleaks.com/reference/actions/image-plagiarism-detector/check
> Search the web for unauthorized copies of an image.
```bash cURL
curl --request POST \
--url https://api.copyleaks.com/v1/image-plagiarism-detector/my-scan-1/check \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--form 'image=@/path/to/my-photo.jpg' \
--form 'filename=my-photo.jpg' \
--form 'sandbox=false'
```
```python Python
import requests
url = 'https://api.copyleaks.com/v1/image-plagiarism-detector/my-scan-1/check'
headers = {'Authorization': 'Bearer YOUR_LOGIN_TOKEN'}
with open('my-photo.jpg', 'rb') as image_file:
files = {'image': ('my-photo.jpg', image_file, 'image/jpeg')}
data = {'filename': 'my-photo.jpg', 'sandbox': 'false'}
response = requests.post(url, files=files, data=data, headers=headers)
result = response.json()
print(f"Total matches: {result['matches']['score']['totalMatches']}")
print(f"Full matches: {result['matches']['score']['fullMatches']}")
print(f"Partial matches: {result['matches']['score']['partialMatches']}")
```
```javascript JavaScript
const imageFile = document.getElementById('fileInput').files[0];
const formData = new FormData();
formData.append('image', imageFile);
formData.append('filename', imageFile.name);
formData.append('sandbox', 'false');
const response = await fetch(
'https://api.copyleaks.com/v1/image-plagiarism-detector/my-scan-1/check',
{
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_LOGIN_TOKEN' },
body: formData,
}
);
const result = await response.json();
console.log('Total matches:', result.matches.score.totalMatches);
console.log('Matches:', result.matches.internet);
```
```json 200 OK
{
"developerPayload": "my-custom-data",
"scannedImage": {
"scanId": "my-scan-1",
"expectedCredits": 1,
"actualCredits": 1,
"creationTime": "2026-05-24T10:00:00Z",
"width": 1920,
"height": 1080,
"filename": "my-photo.jpg"
},
"matches": {
"internet": [
{
"url": "https://example.com/images/photo.jpg",
"matchType": 0,
"webPages": [
{ "url": "https://example.com/blog/my-post" },
{ "url": "https://example.org/news/article" }
]
},
{
"url": "https://example.com/thumbs/photo-thumb.jpg",
"matchType": 1,
"webPages": [
{ "url": "https://example.org/gallery" }
]
},
{
"url": "https://example.org/gallery/photo-sm.jpg",
"matchType": 1
}
],
"score": {
"totalMatches": 3,
"fullMatches": 1,
"partialMatches": 2
}
}
}
```
Search the web for copies of an image. Returns a list of full matches (exact or near-exact copies) and partial matches (cropped, resized, or modified versions), each with the web pages where the image was found - all in a single synchronous API call.
**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>**
Image Plagiarism Detection has a rate limit of **1,800 requests per 15 minutes** per user. If exceeded, requests will be rejected with a 429 status code until the rate limit window resets.
## Request
### Path Parameters
A unique scan ID provided by you. We recommend you use the same ID in your database to represent the scan. Using the same ID for the same file helps avoid duplicate scans caused by network issues. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Supported Content Type
Submit images using **multipart/form-data**.
**Headers:**
```http
Content-Type: multipart/form-data
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Body Parameters
Binary image file to check for plagiarism.
**Requirements:**
- **File size:** Less than 20MB
- **Max resolution:** 75 megapixels (width × height ≤ 75,000,000)
- **Formats:** JPG, JPEG, PNG, GIF, BMP, WebP, ICO
The name of the image file including its extension.
**Requirements:**
- Allowed extensions: `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.webp`, `.ico`
- `<= 255 characters`
Example: `"my-photo.jpg"`
Use sandbox mode to test your integration without consuming credits. Returns mock results.
An optional custom string you can attach to the request. It is echoed back unchanged in the response under `developerPayload`. Useful for correlating results with your own records.
## Responses
**200 OK** The image was successfully analyzed. See the [Image Plagiarism Response](/reference/data-types/authenticity/results/image-plagiarism-response) for the full response structure.
```json
{
"developerPayload": null,
"scannedImage": {
"scanId": "my-scan-1",
"expectedCredits": 1,
"actualCredits": 1,
"creationTime": "2026-05-24T10:00:00Z",
"width": 1920,
"height": 1080,
"filename": "my-photo.jpg"
},
"matches": {
"internet": [
{
"url": "https://example.com/images/photo.jpg",
"matchType": 0,
"webPages": [
{ "url": "https://example.com/blog/my-post" }
]
},
{
"url": "https://example.com/thumbs/photo.jpg",
"matchType": 1
}
],
"score": {
"totalMatches": 2,
"fullMatches": 1,
"partialMatches": 1
}
}
}
```
**400 Bad Request** Invalid request parameters, unsupported file format, or image validation failure (e.g. file too large, resolution too high, corrupt file).
**401 Unauthorized** Authentication or authorization issues.
**402 Payment Required** Insufficient credits.
**429 Too Many Requests** Rate limit exceeded. The request has been rejected.
**500 Internal Server Error** The server encountered an internal error.
---
# Actions → AI Text Detector
## AI Text Detection Actions
Source: https://docs.copyleaks.com/reference/actions/writer-detector/overview
> Detect the writer of a text.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks AI Detector API allows you to predict whether a text was written by a human or an AI.
## Endpoints
---
## AI Text Detector
Source: https://docs.copyleaks.com/reference/actions/writer-detector/check
> Differentiate between human-written and AI-written text.
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v2/writer-detector/my-scan-123/check \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"text": "Copyleaks is a comprehensive plagiarism detection platform...",
"sandbox": false,
"explain": true,
"sensitivity": 2
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.ai_detection_document import NaturalLanguageDocument
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
submission = NaturalLanguageDocument("Copyleaks is a comprehensive plagiarism detection platform...")
submission.set_sandbox(False)
submission.set_explain(True)
submission.set_sensitivity(2)
response = Copyleaks.AiDetectionClient.submit_natural_language(auth_token, "my-scan-123", submission)
print(response)
```
```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksNaturalLanguageSubmissionModel } = require('plagiarism-checker');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const submission = new CopyleaksNaturalLanguageSubmissionModel(
'Copyleaks is a comprehensive plagiarism detection platform...'
);
submission.sandbox = false;
submission.explain = true;
submission.sensitivity = 2;
await copyleaks.aiDetectionClient.submitNaturalTextAsync(auth, 'my-scan-123', submission);
```
```java title="Java" icon="java"
import classes.Copyleaks;
import models.submissions.aidetection.CopyleaksNaturalLanguageSubmissionModel;
String authToken = Copyleaks.login("your@email", "API_KEY");
CopyleaksNaturalLanguageSubmissionModel sub = new CopyleaksNaturalLanguageSubmissionModel(
"Copyleaks is a comprehensive plagiarism detection platform..."
);
sub.setSandbox(false);
sub.setExplain(true);
sub.setSensitivity(2);
Copyleaks.writerDetectorClient.submitNaturalLanguage(authToken, "my-scan-123", sub);
```
```json 200 OK
{
"modelVersion": "v5",
"results": [
{
"classification": 2,
"probability": 1,
"matches": [
{
"text": {
"chars": { "starts": [0], "lengths": [1509] },
"words": { "starts": [0], "lengths": [221] }
}
}
]
}
],
"summary": { "human": 0, "ai": 1 },
"scannedDocument": {
"scanId": "my-scan-123",
"totalWords": 221,
"actualCredits": 1,
"expectedCredits": 1,
"creationTime": "2023-01-10T10:07:58.9459512Z"
}
}
```
Use Copyleaks AI Content Detection to differentiate between human-written and AI-written text.
This endpoint will receive submitted text to be checked. At the end of the processing stage, the result will be shown as classifications. Text classification is divided into sections. Each section may have a different classification.
**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. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
A text string.
`>= 255 characters` `<= 100000 characters`
Use sandbox mode to test your integration with the Copyleaks API for free.
The language code of your content in ISO-639-1 format. See the full [list of supported languages](/reference/actions/miscellaneous/ai-detection-supported-languages).
If the `language` field is not supplied, our system will automatically detect the language of the content.
Example: `"en"`
Enable AI Logic feature for AI detection. For further information, please check the [AI Logic](/concepts/features/ai-logic) for a detailed breakdown of its structure and usage, and for full AI Detection response please check the [AI Detection Response](/reference/data-types/authenticity/results/ai-detection).
AI Logic explanations are returned for [six languages](/reference/actions/miscellaneous/ai-detection-supported-languages#ai-logic-supported-languages) only; for any other language the response contains the detection result without explanations.
Control the behavior of the AI detection.
- Detecting content copied directly from an LLM, like ChatGPT or Gemini, without edits.
- Detecting content from an LLM with minor changes, like tense adjustments or added words.
- Detecting content from an LLM that has been heavily modified using tools or manual edits.
`>= 1` `<= 3`
## Responses
**200 OK** - The command was executed.
```json
{
"modelVersion": "v5",
"results": [
{
"classification": 2,
"probability": 1,
"matches": [
{
"text": {
"chars": { "starts": [0], "lengths": [1509] },
"words": { "starts": [0], "lengths": [221] }
}
}
]
}
],
"summary": { "human": 0, "ai": 1 }
}
```
**400 Bad Request** - Bad request.
**401 Unauthorized** - Authorization has been denied for this request.
**429 Too Many Requests** - Too many requests have been sent. The request has been rejected.
## Next Steps
Learn how to use the AI Detection API to check if content was written by a human or generated by an AI.
Understand how AI logic can help you interpret the results of AI text detection.
Learn about the webhook that delivers AI detection results.
---
## Get Credit Balance
Source: https://docs.copyleaks.com/reference/actions/writer-detector/credits
> Get the amount of available credits in your account wallet.
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v2/writer-detector/credits \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN'
```
```json 200 OK
{
"credits": 382
}
```
Get the amount of available credits in your account wallet.
**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
### Headers
```http
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Responses
**200 OK** - The command was executed.
```json
{
"credits": 382
}
```
**401 Unauthorized** - Authorization has been denied for this request.
---
# Actions → AI Image Detector
## AI Image Detector Actions
Source: https://docs.copyleaks.com/reference/actions/ai-image-detector/overview
> Detect whether an image is AI-generated or partially AI-generated.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks AI Image Detection API analyzes whether an image was generated or partially generated by AI, with support for multipart and JSON submission. Both a synchronous and an asynchronous (webhook-based) flow are available.
## Endpoints
---
## AI Image Detector
Source: https://docs.copyleaks.com/reference/actions/ai-image-detector/check
> Detect whether an image is AI-generated or partially AI-generated.
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--form 'image=@/path/to/test-image.png' \
--form 'filename=test-image.png' \
--form 'sandbox=true' \
--form 'model=ai-image-1-ultra' \
--form 'maskType=heatmap' \
--form 'objectDetection=[{"object":"face"},{"object":"hand"}]'
```
```python title="Python" icon="python"
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.clients.image_detection_client import ImageDetectionClient
from copyleaks.models.ai_image_detection import (
CopyleaksAiImageDetectionRequestModel,
CopyleaksAiImageDetectionModels,
)
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
with open("test-image.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
payload = CopyleaksAiImageDetectionRequestModel(
base64=b64,
filename="test-image.png",
model=CopyleaksAiImageDetectionModels.AI_IMAGE_1_ULTRA,
sandbox=True,
)
client = ImageDetectionClient()
response = client.submit(auth_token, "my-scan-123", payload)
print(response)
```
```javascript title="JavaScript" icon="square-js"
const imageFile = document.getElementById('fileInput').files[0];
const formData = new FormData();
formData.append('image', imageFile);
formData.append('filename', imageFile.name);
formData.append('sandbox', 'true');
formData.append('model', 'ai-image-1-ultra');
formData.append('maskType', 'heatmap');
// Optional: objects to locate, sent as a JSON-encoded string in one form field
formData.append('objectDetection', JSON.stringify([{ object: 'face' }, { object: 'hand' }]));
const response = await fetch(
'https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check',
{
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_LOGIN_TOKEN' },
body: formData,
}
);
const result = await response.json();
```
```json 200 OK
{
"model": "ai-image-1-ultra",
"result": {
"starts": [0, 512, 1536, 2560],
"lengths": [256, 512, 768, 1024]
},
"summary": { "human": 0.3, "ai": 0.7 },
"isAiDetected": true,
"imageInfo": {
"shape": { "height": 1024, "width": 768 },
"metadata": {
"issuedTime": "2025-07-23T12:44:05",
"issuedBy": "OpenAI",
"appOrDeviceUsed": "OpenAI-API",
"contentSummary": "Created using generative AI"
}
},
"detectedObjects": [
{
"object": "face",
"mask": { "starts": [1024, 3072], "lengths": [512, 256] }
},
{
"object": "hand",
"mask": { "starts": [8192], "lengths": [128] }
}
],
"scannedDocument": {
"scanId": "my-scan-123",
"actualCredits": 1,
"expectedCredits": 1,
"creationTime": "2023-01-10T10:07:58.9459512Z"
}
}
```
Detect whether an image is AI-generated or partially AI-generated. Returns a detailed analysis with an RLE mask indicating AI-generated regions. Optionally, pass `objectDetection` to also locate specific objects in the image (for example a face or a hand) and receive a segmentation mask for each one in the same response.
AI Image Detection has wrapper support in the **Python SDK** via `ImageDetectionClient`. The JavaScript and Java SDKs don't yet expose a method for this endpoint, so those samples call the HTTP API directly.
**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>**
Image detection API has a rate limit of **900 requests per 15 minutes** per host. If exceeded, requests will be rejected with a 429 status code until the rate limit window resets.
## 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](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Supported Content Types
Submit images using **multipart/form-data** (recommended) or **JSON with base64**.
`multipart/form-data` sends the image file directly without base64 encoding overhead, making it more efficient for large images. Use `application/json` when you need to submit image data as a base64-encoded string.
#### Option 1: Multipart/Form-Data (Recommended)
**Headers:**
```http
Content-Type: multipart/form-data
Authorization: Bearer YOUR_LOGIN_TOKEN
```
#### Option 2: JSON with Base64
**Headers:**
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
The `Accept-Encoding: gzip` header enables response compression, reducing bandwidth usage and improving performance.
### Body Parameters
The image field used depends on the content type:
- **`multipart/form-data`** -> use the `image` field (binary file)
- **`application/json`** -> use the `base64` field (base64-encoded string)
Binary image file. Required when using `multipart/form-data`. Base64-encoded images are not accepted for multipart requests.
**Requirements:**
- **Size:** Minimum 512x512px, maximum 6000x4500px (27 megapixels)
- **File size:** Less than 32MB
- **Formats:** PNG, JPG, JPEG, BMP, WebP, HEIC/HEIF
Base64-encoded image data. Required when using `application/json` content type.
**Requirements:**
- **Size:** Minimum 512x512px, maximum 6000x4500px (27 megapixels)
- **File size:** Less than 32MB (before encoding)
- **Formats:** PNG, JPG, JPEG, BMP, WebP, HEIC/HEIF
The name of the image file including its extension.
**Requirements:**
- Allowed file extensions: `.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`, `.heic`, `.heif`
- `<= 255 characters`
The AI detection model to use for analysis.
- AI Image 1 Ultra: `"ai-image-1-ultra"`
The type of detection mask to return alongside the detection result. Use `"heatmap"` when you want a pixel-level visualization of how confidently each region of the image was flagged as AI-generated, or `"none"` when you only need the scores.
Supported values:
- `"binary"` (default) - Run-Length Encoded (RLE) mask of the regions flagged as AI-generated, returned as `result.starts` and `result.lengths`.
- `"heatmap"` - gradient overlay highlighting AI-generated regions with intensity proportional to confidence. Adds a `labels` array to `result` with one confidence band (`0`-`4`) per RLE run.
- `"none"` - no mask. The response omits the `result` object; every other field is unchanged.
Any other value is rejected with `400 Bad Request`.
Example: `"heatmap"`
Optional. A list of objects to locate and segment within the image. When provided, the response additionally includes a `detectedObjects` array - one entry per object found in the image, each with its Run-Length Encoded (RLE) segmentation mask. Objects that were requested but not found are omitted, so look entries up by `object` rather than by position.
Each entry wraps the object name in an object (`{ "object": "face" }`) so future per-entry fields can be added without a breaking change.
- Maximum 3 entries.
- Each entry's `object` value must be a non-empty string of at most 32 characters.
- Using `objectDetection` does not change the cost of the request.
**`multipart/form-data`:** send the list as a JSON-encoded string in a single form field, for example `objectDetection=[{"object":"face"},{"object":"hand"}]`.
**`application/json`:** send the list as a JSON array.
Example: `[{ "object": "face" }, { "object": "hand" }]`
Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.
## Responses
**200 OK** - The image was successfully analyzed.
```json
{
"model": "ai-image-1-ultra",
"result": {
"starts": [0, 512, 1536, 2560],
"lengths": [256, 512, 768, 1024]
},
"summary": { "human": 0.3, "ai": 0.7 },
"isAiDetected": true,
"detectedObjects": [
{ "object": "face", "mask": { "starts": [1024, 3072], "lengths": [512, 256] } }
]
}
```
When the request includes `maskType: "heatmap"`, `result` additionally carries a `labels` array - one confidence band (`0`-`4`) per RLE run. With `maskType: "none"` the `result` object is omitted altogether. `detectedObjects` is present only when the request included `objectDetection`. See the [AI Image Detection Response](/reference/data-types/ai-detector/ai-image-detection-response) reference.
**400 Bad Request** - Invalid request parameters, unsupported image format, or image processing issues.
**401 Unauthorized** - Authentication or authorization issues.
**402 Payment Required** - Insufficient credits.
**429 Too Many Requests** - Too many requests have been sent. The request has been rejected.
**500 Internal Server Error** - The server encountered an internal error or misconfiguration.
---
## AI Image Detector Async
Source: https://docs.copyleaks.com/reference/actions/ai-image-detector/submit
> Submit an image URL for AI-generated content detection. Results are delivered asynchronously via webhook.
Submit an image URL for AI-generated content detection. The endpoint is **asynchronous** - it returns `201 Created` immediately, and the detection results are delivered to your webhook URL once processing is complete.
Use this endpoint when you have a publicly reachable image URL and prefer a fire-and-forget submission. For an immediate, synchronous response with the image uploaded directly in the request, use [AI Image Detection](/reference/actions/ai-image-detector/check) instead.
Authentication is required. See [Login](/reference/actions/account/login) for how to obtain a bearer token.
This is a new endpoint and the official Copyleaks SDKs (Python, JavaScript, Java, C#, PHP, Ruby) don't yet expose a wrapper method for the async flow. The code samples below call the HTTP API directly. SDK support is planned - until then, use the raw HTTP pattern.
## Path parameters
A unique scan id provided by you. We recommend using the same id in your database to represent the scan in the Copyleaks database - this helps debug incidents and avoid duplicate scans for the same image. See [criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
Match pattern: ``[a-z0-9] !@$^&-+%=_(){}<>';:/.",~`|``
## Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Body parameters
Publicly accessible URL of the image file to analyze.
Example: `"https://example.com/my-image.png"`
The name of the image file including its extension.
**Supported extensions:** `.jpg`, `.jpeg`, `.png`, `.webp`, `.tiff`, `.bmp`, `.heic`, `.heif`
Example: `"image1.png"`
The AI image detection model to use for analysis.
- AI Image 1 Ultra: `"ai-image-1-ultra"`
Example: `"ai-image-1-ultra"`
The type of detection mask to include in the webhook payload. Use `"heatmap"` when you want a pixel-level visualization of how confidently each region of the image was flagged as AI-generated.
Supported values:
- `"binary"` (default) - Run-Length Encoded (RLE) mask of the regions flagged as AI-generated, returned as `result.starts` and `result.lengths`.
- `"heatmap"` - gradient overlay highlighting AI-generated regions with intensity proportional to confidence. Adds a `labels` array to `result` with one confidence band (`0`-`4`) per RLE run.
Example: `"heatmap"`
Optional. A list of objects to locate and segment within the image. When provided, the result delivered to your webhook additionally includes a `detectedObjects` array - one entry per object found in the image, each with its Run-Length Encoded (RLE) segmentation mask.
Each entry wraps the object name in an object (`{ "object": "face" }`) so future per-entry fields can be added without a breaking change.
- Maximum 3 entries.
- Each entry's `object` value must be a non-empty string of at most 32 characters.
Example: `[{ "object": "face" }, { "object": "hand" }]`
Optional custom headers to include when Copyleaks fetches the image from the provided `url`. Each entry is a two-element array: `["Header-Name", "Header-Value"]`.
Example: `[["X-Custom-Auth", "my-token"]]`
Webhook configuration for receiving the async results.
The URL that Copyleaks will POST the detection results to when processing is complete.
Example: `"https://your-server.com/webhook/receive-results"`
Optional custom headers to include in the webhook request. Each entry is a two-element array: `["Header-Name", "Header-Value"]`.
Example: `[["Authorization", "Bearer my-webhook-token"]]`
Use sandbox mode to test your integration with the [Copyleaks API](https://copyleaks.com/api) without consuming any credits. Submit images for AI detection and receive mock results simulating the API. Intended for development purposes only.
An optional string payload that Copyleaks will include in the webhook response, allowing you to correlate the callback with your internal data.
Example: `"order-id-12345"`
```bash title="cURL" icon="terminal"
curl --request PUT \
--url https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com/image1.png",
"fileName": "image1.png",
"model": "ai-image-1-ultra",
"maskType": "heatmap",
"webhooks": {
"url": "https://your-server.com/webhook/receive-results"
}
}'
```
```python title="Python" icon="python"
import requests
url = 'https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit'
headers = {
'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
'Content-Type': 'application/json'
}
payload = {
'url': 'https://example.com/image1.png',
'fileName': 'image1.png',
'model': 'ai-image-1-ultra',
'maskType': 'heatmap',
'webhooks': {
'url': 'https://your-server.com/webhook/receive-results'
}
}
response = requests.put(url, json=payload, headers=headers)
print(f"Submission status: {response.status_code}") # 201 Created
```
```javascript title="JavaScript" icon="square-js"
const response = await fetch(
'https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit',
{
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://example.com/image1.png',
fileName: 'image1.png',
model: 'ai-image-1-ultra',
maskType: 'heatmap',
webhooks: {
url: 'https://your-server.com/webhook/receive-results'
}
})
}
);
console.log('Submission status:', response.status); // 201 Created
```
```http title="HTTP" icon="globe"
PUT https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
{
"url": "https://example.com/image1.png",
"fileName": "image1.png",
"model": "ai-image-1-ultra",
"maskType": "heatmap",
"webhooks": {
"url": "https://your-server.com/webhook/receive-results"
}
}
```
```json 201 Created
{}
```
```json 400 Bad Request
{
"error": "Invalid request parameters."
}
```
```json 401 Unauthorized
{
"error": "Authentication or authorization failed."
}
```
```json 402 Payment Required
{
"error": "Insufficient credits."
}
```
```json 429 Too Many Requests
{
"error": "Rate limit exceeded."
}
```
```json 500 Internal Server Error
{
"error": "The server encountered an internal error."
}
```
## Webhook payload
When processing completes, Copyleaks sends a `POST` request to your webhook URL with the detection results. The payload follows the same shape as the synchronous [AI Image Detection](/reference/actions/ai-image-detector/check) response.
When the request included `maskType: "heatmap"`, the payload's `result` object additionally carries a `labels` array - one confidence band (`0`-`4`) per RLE run. See the [AI Image Detection Response](/reference/data-types/ai-detector/ai-image-detection-response) reference.
When the request included `objectDetection`, the payload additionally contains a `detectedObjects` array - one entry per object found in the image. Objects that were requested but not found are omitted, so look entries up by `object` rather than by position.
Present only when `objectDetection` was supplied in the request. One entry per object located in the image.
The object description from the request that this entry corresponds to.
The Run-Length Encoded (RLE) segmentation mask for this object.
Starting positions of each segment in the flattened 1D image array.
Lengths of each segment, corresponding to the `starts` array.
---
# Actions → AI Video Detector
## AI Video Detector Actions
Source: https://docs.copyleaks.com/reference/actions/ai-video-detector/overview
> Detect AI-generated content in videos via an async submit-and-webhook flow.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks AI Video Detection API analyzes whether a video was generated or partially generated by AI. Submit a video URL and receive granular audio and visual analysis via webhook when processing completes.
Submit a video and inspect the webhook response without writing code. Opens in a new tab.
## Endpoints
---
## AI Video Detection
Source: https://docs.copyleaks.com/reference/actions/ai-video-detector/submit
> Submit a video URL for AI-generated content detection. Results are delivered asynchronously via webhook.
Submit a video URL for AI-generated content detection. The endpoint is **asynchronous** - it returns `201 Created` immediately, and the detection results are delivered to your webhook URL once processing is complete.
Authentication is required. See [Login](/reference/actions/account/login) for how to obtain a bearer token.
**Try it without writing code** - open the [Video Detection Playground](https://api.copyleaks.com/dashboard/playground/video-detection) to submit a sample video and inspect the webhook response in your browser.
AI Video Detection is a new endpoint and the official Copyleaks SDKs (Python, JavaScript, Java, C#, PHP, Ruby) don't yet expose a wrapper method. The code samples below call the HTTP API directly. SDK support is planned - until then, use the raw HTTP pattern.
## Path parameters
A unique scan id provided by you. We recommend using the same id in your database to represent the scan in the Copyleaks database - this helps debug incidents and avoid duplicate scans for the same file. See [criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
Match pattern: ``[a-z0-9] !@$^&-+%=_(){}<>';:/.",~`|``
## Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Body parameters
Publicly accessible URL of the video file to analyze.
Example: `"https://example.com/my-video.mp4"`
Optional custom headers to include when Copyleaks fetches the video from the provided `url`. Each entry is a two-element array: `["Header-Name", "Header-Value"]`.
Example: `[["X-Custom-Auth", "my-token"]]`
Describes the HTTP method that is going to be executed on the specified `url`. Supported values: `GET`, `POST`, `PUT`.
The name of the video file including its extension.
**Requirements:**
- Must include a supported video extension
- `<= 255 characters`
**Supported extensions:** `.mp4`, `.avi`, `.mov`, `.mkv`, `.webm`, `.flv`, `.wmv`, `.mpg`, `.m4v`, `.3gp`, `.mxf`
Example: `"my-video.mp4"`
The AI detection model to use for analysis.
- AI Video 1 Pro: `"ai-video-1-pro"`
Example: `"ai-video-1-pro"`
Webhook configuration for receiving the async results.
The URL that Copyleaks will POST the detection results to when processing is complete.
Example: `"https://your-server.com/webhook/receive-results"`
Optional custom headers to include in the webhook request. Each entry is a two-element array: `["Header-Name", "Header-Value"]`.
Example: `[["Authorization", "Bearer my-webhook-token"]]`
Use sandbox mode to test your integration with the [Copyleaks API](https://copyleaks.com/api) without consuming any credits. Submit videos for AI detection and receive mock results simulating the API. Intended for development purposes only.
An optional string payload that Copyleaks will include in the webhook response, allowing you to correlate the callback with your internal data.
Example: `"order-id-12345"`
For testing, set `"sandbox": true`. Sandbox mode is free and returns mock results.
### Video requirements
**Returned as `400 Bad Request` at submit (synchronous):**
- Missing or invalid `scanId`, `filename`, `url`, `model`, or `webhooks`
- Unsupported file extension
- Filename longer than 255 characters
- Invalid `verb` value
**Delivered to your webhook as an error result (asynchronous, after download):**
- Duration outside 2 seconds-1 hour → `video_too_short` (67) / `video_too_long` (68)
- File larger than 512 MiB → `file_too_large` (6)
- Resolution below 360×360 → `video_resolution_too_low` (65)
- Frame rate below 16 FPS → `fps_too_low` (66)
- Undecodable codec → `unsupported_video_codec` (71)
- Corrupt or truncated file → `video_truncated` (70)
- Generic decode failure → `video_load_failed` (72)
## Webhook payload
When processing completes, Copyleaks sends a `POST` request to your webhook URL with the detection results. See [AI Video Detection Response](/reference/data-types/ai-detector/ai-video-detection-response) for the complete field reference.
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v1/ai-video-detector/my-video-scan-1/submit \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com/my-video.mp4",
"filename": "my-video.mp4",
"model": "ai-video-1-pro",
"sandbox": true,
"webhooks": {
"url": "https://your-server.com/webhook/receive-results"
}
}'
```
```python title="Python" icon="python"
import requests
url = 'https://api.copyleaks.com/v1/ai-video-detector/my-video-scan-1/submit'
headers = {
'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
'Content-Type': 'application/json'
}
payload = {
'url': 'https://example.com/my-video.mp4',
'filename': 'my-video.mp4',
'model': 'ai-video-1-pro',
'sandbox': True,
'webhooks': {
'url': 'https://your-server.com/webhook/receive-results'
}
}
response = requests.post(url, json=payload, headers=headers)
print(f"Submission status: {response.status_code}") # 201 Created
```
```javascript title="JavaScript" icon="square-js"
const response = await fetch(
'https://api.copyleaks.com/v1/ai-video-detector/my-video-scan-1/submit',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://example.com/my-video.mp4',
filename: 'my-video.mp4',
model: 'ai-video-1-pro',
sandbox: true,
webhooks: {
url: 'https://your-server.com/webhook/receive-results'
}
})
}
);
console.log('Submission status:', response.status); // 201 Created
```
```http title="HTTP" icon="globe"
POST https://api.copyleaks.com/v1/ai-video-detector/my-video-scan-1/submit
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
{
"url": "https://example.com/my-video.mp4",
"filename": "my-video.mp4",
"model": "ai-video-1-pro",
"sandbox": true,
"webhooks": {
"url": "https://your-server.com/webhook/receive-results"
}
}
```
```json 201 Created
{}
```
```json 400 Bad Request
{
"error": "Invalid request parameters."
}
```
```json 401 Unauthorized
{
"error": "Authentication or authorization failed."
}
```
```json 402 Payment Required
{
"error": "Insufficient credits."
}
```
```json 429 Too Many Requests
{
"error": "Rate limit exceeded."
}
```
```json 500 Internal Server Error
{
"error": "The server encountered an internal error."
}
```
## Example webhook delivery
```json
{
"model": "ai-video-1-pro",
"audioResult": {
"starts": [13000, 45000, 47000],
"lengths": [14000, 1000, 8700],
"exclude": {
"starts": [0, 3250, 5400, 7600, 10500],
"lengths": [2950, 1500, 1200, 650, 1050]
}
},
"visualResult": {
"starts": [11566, 29433],
"lengths": [6134, 26267],
"exclude": {
"starts": [],
"lengths": []
}
},
"summary": {
"audioAIRatio": 0.4902,
"visualAIRatio": 0.5817,
"overallAIRatio": 0.7487
},
"isAiDetected": true,
"videoInfo": {
"metadata": {
"issuedTime": "2026-03-17T13:14:57+00:00",
"issuedBy": "OpenAI",
"appOrDeviceUsed": "Sora",
"contentSummary": "Created using generative AI"
},
"duration": 55.7
},
"scannedVideo": {
"scanId": "my-video-scan-1",
"actualCredits": 1,
"expectedCredits": 1,
"creationTime": "2026-05-05T12:37:50Z"
}
}
```
---
# Actions → Grammar Checker
## Grammar Checker Actions
Source: https://docs.copyleaks.com/reference/actions/writing-assistant/overview
> Assess and improve writing with feedback on grammar, spelling, and sentence structure.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks Grammar Checker API allows you to get feedback on your writing. It provides suggestions for improving grammar, spelling, and sentence structure, helping you enhance the quality of your text.
## Endpoints
---
## Submit Text
Source: https://docs.copyleaks.com/reference/actions/writing-assistant/check
> Generate grammar, spelling, and sentence corrections for a given text.
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v1/writing-feedback/my-scan-123/check \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"text": "Copyleaks is a comprehensive plagiarism detection platform..."
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.writing_assistant_document import WritingAssistantDocument
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
submission = WritingAssistantDocument("Copyleaks is a comprehensive plagiarism detection platform...")
response = Copyleaks.WritingAssistantClient.submit_text(auth_token, "my-scan-123", submission)
print(response)
```
```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksWritingAssistantSubmissionModel } = require('plagiarism-checker');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const submission = new CopyleaksWritingAssistantSubmissionModel(
'Copyleaks is a comprehensive plagiarism detection platform...'
);
submission.sandbox = true;
await copyleaks.writingAssistantClient.submitTextAsync(auth, 'my-scan-123', submission);
```
```java title="Java" icon="java"
import classes.Copyleaks;
import models.submissions.writingassistant.CopyleaksWritingAssistantSubmissionModel;
String authToken = Copyleaks.login("your@email", "API_KEY");
CopyleaksWritingAssistantSubmissionModel sub = new CopyleaksWritingAssistantSubmissionModel(
"Copyleaks is a comprehensive plagiarism detection platform..."
);
sub.setSandbox(true);
Copyleaks.writingAssistantClient.submitText(authToken, "my-scan-123", sub);
```
```json 200 OK
{
"score": {
"corrections": {
"grammarCorrectionsCount": 2,
"grammarCorrectionsScore": 87,
"mechanicsCorrectionsCount": 9,
"mechanicsCorrectionsScore": 38,
"overallScore": 79
},
"readability": {
"score": 59,
"readabilityLevel": 5,
"readabilityLevelText": "10th to 12th Grader",
"readabilityLevelDescription": "Fairly difficult to read"
}
},
"scannedDocument": {
"scanId": "{scanId}",
"totalWords": 61,
"actualCredits": 1,
"expectedCredits": 1,
"creationTime": "2025-08-06T08:00:08.0429909Z"
}
}
```
Use Copyleaks Grammar Checker to generate grammar, spelling and sentence corrections for a given text.
This endpoint will receive submitted text to be checked. The response will show the suggested corrections to the input text.
**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. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
Text to produce Grammar Checker report for.
`>= 1 characters` `<= 25000 characters`
Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.
Grammar correction category weight in the overall score. `>= 0.0 <= 1.0`
Mechanics correction category weight in the overall score. `>= 0.0 <= 1.0`
Sentence structure correction category weight in the overall score. `>= 0.0 <= 1.0`
Word choice correction category weight in the overall score. `>= 0.0 <= 1.0`
The language code of your content. If not supplied, our system will automatically detect the language of the content.
Example: `"en"`
## Responses
**200 OK** - The command was executed.
```json
{
"score": {
"corrections": {
"grammarCorrectionsCount": 2,
"grammarCorrectionsScore": 87,
"overallScore": 79
}
},
"scannedDocument": {
"scanId": "{scanId}",
"totalWords": 61,
"creationTime": "2025-08-06T08:00:08.0429909Z"
}
}
```
**400 Bad Request** - Bad request.
**401 Unauthorized** - Authorization has been denied for this request.
**402 Payment Required** - User does not have enough credits.
**429 Too Many Requests** - Too many requests have been sent. The request has been rejected.
---
## Get Correction Types
Source: https://docs.copyleaks.com/reference/actions/writing-assistant/correction-types
> Get a list of correction types supported within the Grammar Checker API.
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v1/writing-feedback/correction-types/en
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
# Public endpoint no authentication required.
correction_types = Copyleaks.WritingAssistantClient.get_correction_types("en")
print(correction_types)
```
```json 200 OK
{
"correctionTypes": [
{
"title": "General",
"description": "A general correction detected.",
"message": "A general correction detected",
"id": 1,
"category": 2
}
]
}
```
Get a list of correction types supported within the Grammar Checker API. Correction types apply to all supported languages. The supplied language code for this request is used to determine the language of the texts returned.
This endpoint does not require authentication.
## Request
### Path Parameters
The language for the returned texts to be in. Language codes are in ISO 639-1 standard. Supported Values: en - English
## Response
**200 OK** - The command was executed.
```json
{
"correctionTypes": [
{
"title": "General",
"description": "A general correction detected.",
"message": "A general correction detected",
"id": 1,
"category": 2
},
{
"title": "Subject Verb Disagreement",
"description": "The subject and verb do not agree in number.",
"message": "Subject-verb disagreement detected",
"id": 2,
"category": 2
},
{
"title": "Noun Form",
"description": "Using an incorrect form of a noun (such as pluralization or possessive form) in a sentence.",
"message": "Use a different noun form",
"id": 3,
"category": 2
},
{
"title": "Verb Form",
"description": "Using an incorrect form of a verb (such as tense, aspect, or agreement) in a sentence results.",
"message": "Use a different verb form",
"id": 4,
"category": 2
},
{
"title": "Article",
"description": "Using the wrong article (a, an, or the) or omitting an article inappropriately in a sentence.",
"message": "Use the appropriate article",
"id": 5,
"category": 2
},
{
"title": "Preposition",
"description": "Using the wrong preposition or misplacing a preposition in a sentence.",
"message": "Incorrect preposition usage",
"id": 6,
"category": 2
},
{
"title": "Pronoun",
"description": "Using an incorrect pronoun or misplacing a pronoun in a sentence.",
"message": "Incorrect pronoun usage",
"id": 7,
"category": 2
},
{
"title": "Part of Speech",
"description": "Misusing or misidentifying a word's grammatical category, such as confusing a noun with a verb.",
"message": "Incorrect part of speech",
"id": 8,
"category": 2
},
{
"title": "Conjunction",
"description": "Misusing or misplacing conjunctions, which are words that connect words, phrases, or clauses in a sentence.",
"message": "Incorrect conjunction usage",
"id": 9,
"category": 2
},
{
"title": "Misused Word",
"description": "Words that are used incorrectly or inappropriately in a given context.",
"message": "Use a different word to convey the message",
"id": 10,
"category": 3
},
{
"title": "Homophone",
"description": "Confusing two words that phonetically sound similar but have a different meaning (e.g., \"their\" and \"there\" or \"to\" and \"too\").",
"message": "Incorrect homophone usage detected",
"id": 11,
"category": 3
},
{
"title": "Capitalization",
"description": "Word was not capitalized correctly (e.g. “paris” should be “Paris”).",
"message": "Incorrect capitalization",
"id": 12,
"category": 4
},
{
"title": "Hyphen",
"description": "Incorrect or inconsistent use of hyphens in a sentence.",
"message": "Hyphen usage is incorrect",
"id": 13,
"category": 4
},
{
"title": "Punctuation",
"description": "Incorrect use of punctuation marks, such as commas, periods, semicolons, or colons.",
"message": "Incorrect punctuation usage",
"id": 14,
"category": 4
},
{
"title": "Comma",
"description": "Incorrect use of commas in sentences.",
"message": "Incorrect comma usage",
"id": 15,
"category": 4
},
{
"title": "Apostrophe",
"description": "Incorrect use of apostrophes in sentences.",
"message": "Incorrect apostrophe usage",
"id": 16,
"category": 4
},
{
"title": "Space",
"description": "Missing or extra spaces detected in sentence.",
"message": "Missing or extra spaces",
"id": 17,
"category": 4
},
{
"title": "Spelling",
"description": "Misspelling of a word.",
"message": "Misspelling detected",
"id": 18,
"category": 4
},
{
"title": "Fused Sentence",
"description": "When two independent clauses are incorrectly joined without appropriate punctuation or conjunction.",
"message": "Fused sentence detected",
"id": 19,
"category": 1
},
{
"title": "Comma Splice",
"description": "Two independent clauses are incorrectly joined by a comma without a coordinating conjunction or appropriate punctuation.",
"message": "Comma splice detected",
"id": 20,
"category": 1
},
{
"title": "Sentence Fragments",
"description": "When a group of words appears to be a sentence but is incomplete because it lacks a subject, a predicate, or both.",
"message": "Ensure your sentence has a complete subject and predicate",
"id": 21,
"category": 1
},
{
"title": "Ineffective Construction",
"description": "Refers to sentences or phrases that are poorly constructed or lack clarity, making it difficult for readers to understand the intended meaning.",
"message": "Revise the sentence for better clarity and structure",
"id": 22,
"category": 1
},
{
"title": "Extra Words",
"description": "Sentences that contain unnecessary or redundant words, which can be removed for clearer and more concise writing.",
"message": "Sentence contains extra words",
"id": 23,
"category": 1
},
{
"title": "Missing Words",
"description": "Identifies sentences that are missing essential words, resulting in incomplete or unclear meaning.",
"message": "Sentence with missing words",
"id": 24,
"category": 1
},
{
"title": "Adjective Gender Agreement",
"description": "Detects errors in the gender agreement between adjectives and nouns.",
"message": "Gender agreement mismatch in adjectives",
"id": 25,
"category": 2
},
{
"title": "Adjective Number Agreement",
"description": "Highlights discrepancies in the number agreement between adjectives and nouns for improved grammatical precision.",
"message": "Number agreement error with adjectives",
"id": 26,
"category": 2
},
{
"title": "Article Gender Agreement",
"description": "Agreement between articles and nouns in terms of gender is incorrect, ensuring grammatical accuracy.",
"message": "Gender agreement error in articles",
"id": 27,
"category": 2
},
{
"title": "Article Number Agreement",
"description": "Number mismatch between articles and nouns creating inconsistency in how they refer to the same or similar elements in a sentence.",
"message": "Number agreement error in articles",
"id": 28,
"category": 2
},
{
"title": "Noun Gender Agreement",
"description": "Lack of agreement between nouns and their associated genders, ensuring grammatical harmony.",
"message": "Gender agreement error with nouns",
"id": 29,
"category": 2
},
{
"title": "Subjunctive Mood",
"description": "Identifies the incorrect usage of the subjunctive mood in sentences, ensuring proper expression of hypothetical or unreal situations.",
"message": "Subjunctive mood misuse",
"id": 30,
"category": 2
},
{
"title": "Compound Word Error",
"description": "Identifies incorrect compound word usage.",
"message": "Compound word usage error",
"id": 31,
"category": 2
},
{
"title": "Mood Inconsistency",
"description": "Detects inconsistencies in the expression of mood within a sentence, ensuring cohesive writing.",
"message": "Inconsistency in mood detected",
"id": 32,
"category": 2
},
{
"title": "Accent Error",
"description": "Highlights deviations in accents, promoting uniform language usage.",
"message": "Incorrect or missing usage of accents",
"id": 33,
"category": 4
},
{
"title": "Homoglyph Error",
"description": "Non-standard characters that resemble standard ones have been detected.",
"message": "Homoglyphs detected in text",
"id": 34,
"category": 2
}
]
}
```
**400 Bad Request** - Bad request. Language not supported.
### Body
List of correction types and corresponding user interface information.
Shortened capitalized name of the correction.
A short explanation of the correction.
A longer, more explicit explanation of the correction.
An identifier for the correction type.
Unsigned integer. Category of the correction type.
**Available Values:**
- `1` : Sentence Structure
- `2` : Grammar
- `3` : Word Choice
- `4` : Mechanics
`>= 1`
---
# Actions → Text Moderation
## Text Moderation Actions
Source: https://docs.copyleaks.com/reference/actions/text-moderation/overview
> Moderate text for harmful content.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks text moderation API allows you to moderate text for harmful content.
## Endpoints
---
## Moderate Text
Source: https://docs.copyleaks.com/reference/actions/text-moderation/check
> Instantly flag hateful, explicit, toxic, or otherwise risky content in any text.
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v1/text-moderation/my-scan-123/check \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"text": "Your text content to be moderated goes here.",
"sandbox": true,
"language": "en",
"labels": [
{ "id": "toxic-v1" },
{ "id": "profanity-v1" },
{ "id": "hate-speech-v1" }
]
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.TextModeration.Requests.CopyleaksTextModerationRequestModel import CopyleaksTextModerationRequestModel
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
submission = CopyleaksTextModerationRequestModel(
text="Your text content to be moderated goes here.",
sandbox=True,
language="en",
labels=[
{"id": "toxic-v1"},
{"id": "profanity-v1"},
{"id": "hate-speech-v1"},
],
)
response = Copyleaks.TextModerationClient.submit_text(auth_token, "my-scan-123", submission)
print(response)
```
```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksTextModerationRequestModel } = require('plagiarism-checker');
const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');
const submission = new CopyleaksTextModerationRequestModel({
text: 'Your text content to be moderated goes here.',
sandbox: true,
language: 'en',
labels: [
{ id: 'toxic-v1' },
{ id: 'profanity-v1' },
{ id: 'hate-speech-v1' },
],
});
await copyleaks.textModerationClient.submitTextAsync(auth, 'my-scan-123', submission);
```
```java title="Java" icon="java"
import classes.Copyleaks;
import models.request.TextModeration.CopyleaksTextModerationRequest;
import models.request.TextModeration.Label;
String authToken = Copyleaks.login("your@email", "API_KEY");
CopyleaksTextModerationRequest req = new CopyleaksTextModerationRequest(
"Your text content to be moderated goes here.",
true,
"en",
new Label[] {
new Label("toxic-v1"),
new Label("profanity-v1"),
new Label("hate-speech-v1"),
}
);
Copyleaks.textModerationClient.submitText(authToken, "my-scan-123", req);
```
```json 200 OK
{
"modelVersion": "v1",
"moderations": {
"text": {
"chars": {
"labels": [4, 4, 4, 2, 7, 6],
"starts": [15, 73, 138, 287, 407, 446],
"lengths": [4, 4, 4, 14, 12, 24]
}
}
},
"scannedDocument": {
"scanId": "scan-id",
"totalWords": 86,
"actualCredits": 1,
"expectedCredits": 1,
"creationTime": "2025-08-06T08:05:20.6787519Z"
}
}
```
The Copyleaks Text Moderation API provides real-time content moderation capabilities to help you maintain safe and appropriate content across your platform. This API automatically scans and flags potentially harmful content across multiple categories, enabling you to take appropriate action to protect your users and maintain community standards.
**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. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
The request body is a JSON object containing the text to scan.
Text to produce Text Moderation report for.
`>= 1 characters` `<= 25000 characters`
Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.
The language code of your content. If the `language` field is not specified, our system will automatically detect the language of the content.
Example: `"en"`
A list of label configurations to be used for the moderation process.
Identifier for the label. [List of moderation labels](/reference/data-types/moderation/text-moderation-labels/).
`>= 1 characters` `<= 32 characters`
## Responses
**200 OK** - The moderation report was returned successfully.
```json
{
"modelVersion": "v1",
"moderations": { "text": { "chars": { "labels": [4], "starts": [15], "lengths": [4] } } },
"scannedDocument": {
"scanId": "scan-id",
"totalWords": 86,
"creationTime": "2025-08-06T08:05:20.6787519Z"
}
}
```
**400 Bad Request** - Bad Request.
**401 Unauthorized** - Authorization has been denied for this request.
**402 Payment Required** - Text Moderation is not enabled to your account.
**429 Too Many Requests** - Too many requests have been sent. The request has been rejected.
---
# Actions → Downloads
## Downloads Actions
Source: https://docs.copyleaks.com/reference/actions/downloads/overview
> Download your scan reports.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks downloads API allows you to download your scan reports.
## Endpoints
---
## Export
Source: https://docs.copyleaks.com/reference/actions/downloads/export
> Export the full raw scan information and push it to your servers.
import ExportRequestBody from '/snippets/export-request-body.mdx';
```bash title="cURL" icon="terminal"
curl --request POST \
--url https://api.copyleaks.com/v3/downloads/my-scan-123/export/my-export-1 \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"results": [
{
"id": "my-result-id",
"verb": "POST",
"headers": [["header-key", "header-value"]],
"endpoint": "https://yourserver.com/export/export-id/results/my-result-id"
}
],
"pdfReport": {
"verb": "POST",
"endpoint": "https://yourserver.com/export/export-id/pdf-report"
},
"crawledVersion": {
"verb": "POST",
"endpoint": "https://yourserver.com/export/export-id/crawled-version"
},
"completionWebhook": "https://yourserver.com/export/export-id/completed",
"maxRetries": 3
}'
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.export import Export, ExportResult, ExportPdf, ExportCrawledVersion
auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")
result = ExportResult()
result.set_id("my-result-id")
result.set_endpoint("https://yourserver.com/export/export-id/results/my-result-id")
result.set_verb("POST")
pdf = ExportPdf()
pdf.set_endpoint("https://yourserver.com/export/export-id/pdf-report")
pdf.set_verb("POST")
crawled = ExportCrawledVersion()
crawled.set_endpoint("https://yourserver.com/export/export-id/crawled-version")
crawled.set_verb("POST")
export = Export()
export.set_results([result])
export.set_pdf_report(pdf)
export.set_crawled_version(crawled)
export.set_completion_webhook("https://yourserver.com/export/export-id/completed")
export.set_max_retries(3)
Copyleaks.export(auth_token, "my-scan-123", "my-export-1", export)
```
```json 204 No Content
{}
```
One of the most common patterns when integrating with our services is to submit a scan and download the full results as soon as the scan is completed. When the scan is completed, Copyleaks triggers a 'Completed' webhook to inform that the scan has been completed. At this point, you will have all the needed information (i.e. the 'result ids') to download and present the reports on your side. Since you may have a large number of documents to download (the results, crawled version of the text and the pdf-report), you may need to send many HTTP REST calls to execute to export the data from our services.
The 'Export' method makes this process easier by specifying the content you would like to export in a single call, and we will copy all the data according to your request. Then, we will fire an 'export-completed' webhook with the export results summary.
If you are using a distributed cloud storage system (like AWS buckets, Google buckets or Azure Storage), we can export the data directly to your storage without the involvement of your servers. To do so, create a Signed URL for each data item that you would like to export. By specifying the request method (verb) and optionally added headers, the writing to this storage will be triggered, as per your definition.
**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 new Id for the export process.
`>= 3 characters` `<= 36 characters`
The scan ID of the specific scan to export. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).
`>= 3 characters` `<= 36 characters`
### Headers
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
### Request Body
The request body is a JSON object containing the export configuration.
## Responses
**204 No Content** - The command was executed. The export started.
**400 Bad Request** - Bad request. One or more details in your request is wrong.
**401 Unauthorized** - Authorization has been denied for this request.
**404 Not Found** - The scan id that was specified doesn't exist.
**409 Conflict** - Conflict. An export task with the same Id already exists in the system.
## Next Steps
Learn about the different types of webhooks and how to handle them, including export completion webhooks.
Understand the details provided in the export completed webhook.
Learn how to present exported scan data to your users.
---
# Actions → Miscellaneous
## Miscellaneous Actions
Source: https://docs.copyleaks.com/reference/actions/miscellaneous/overview
> Get information about supported file types, languages, and more.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
The Copyleaks miscellaneous API allows you to get information about supported file types, languages, and more.
## Endpoints
---
## AI Detection Supported Languages
Source: https://docs.copyleaks.com/reference/actions/miscellaneous/ai-detection-supported-languages
> The 30 languages supported by the Copyleaks AI Content Detector, with ISO-639-1 codes. Omit the language field and the API auto-detects it.
Get a list of the supported languages for AI Content Detection.
This is a list of languages supported by the AI Content Detector. If the `language` field is not supplied, our system will automatically detect the language of the content.
## AI Detection Supported Languages
These are the language codes supported by our AI Content Detection, in `ISO-639-1` standard:
| Language | Code |
| :------------------------ | :--------- |
| English | `en` |
| Spanish | `es` |
| French | `fr` |
| Portuguese | `pt` |
| German | `de` |
| Italian | `it` |
| Russian | `ru` |
| Polish | `pl` |
| Romanian | `ro` |
| Dutch | `nl` |
| Swedish | `sv` |
| Czech | `cs` |
| Norwegian | `no` |
| Korean | `ko` |
| Japanese | `ja` |
| Chinese (Simplified) | `zh-CN` |
| Chinese (Traditional) | `zh-TW` |
| Arabic | `ar` |
| Bengali | `bn` |
| Bulgarian | `bg` |
| Croatian | `hr` |
| Greek | `el` |
| Hebrew | `he` |
| Hindi | `hi` |
| Hungarian | `hu` |
| Serbian | `sr` |
| Thai | `th` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Vietnamese | `vi` |
## AI Logic Supported Languages
[AI Logic](/concepts/features/ai-logic), the optional `explain` feature that adds phrase-level explanations to AI detection results, is currently available for six of the languages above:
| Language | Code |
| :------------------------ | :--------- |
| English | `en` |
| Spanish | `es` |
| French | `fr` |
| Portuguese | `pt` |
| German | `de` |
| Italian | `it` |
If you enable `explain` for any other supported language, AI detection still runs and you get the normal result, just without AI Logic explanations. Scans submitted through the submit endpoints also receive the `ai-insights-lang-unsupported` [scan alert](/reference/data-types/authenticity/scan-alerts) in the completion webhook. The synchronous [AI Text Detector](/reference/actions/writer-detector/check) endpoint has no alerts, so the explanations are simply absent. AI Logic is not available for source code files in any language.
## Frequently asked questions
### How many languages does the Copyleaks AI Detector support?
The AI Content Detector supports 30 languages, each identified by its ISO-639-1 code (for example `en`, `es`, `fr`, `zh-CN`).
### Do I have to specify the language for AI detection?
No. If you omit the `language` field, Copyleaks automatically detects the language of the submitted content. Set `language` only when you want to force a specific one.
### What language code format does the API use?
ISO-639-1 two-letter codes. Chinese is the exception, using `zh-CN` for Simplified and `zh-TW` for Traditional.
### Does the AI Detector support Chinese, Arabic, and Hebrew?
Yes. It supports Chinese (Simplified `zh-CN` and Traditional `zh-TW`), Arabic (`ar`), and Hebrew (`he`), among the 30 supported languages.
### Which languages support AI Logic explanations?
Six: English (`en`), Spanish (`es`), French (`fr`), Portuguese (`pt`), German (`de`), and Italian (`it`). AI detection itself works in all 30 languages. For the other 24, turning on `explain` returns the regular detection result with no explanations. See [AI Logic Supported Languages](/reference/actions/miscellaneous/ai-detection-supported-languages#ai-logic-supported-languages) for details.
---
## OCR Supported Languages
Source: https://docs.copyleaks.com/reference/actions/miscellaneous/ocr-supported-languages
> Get the list of languages the Copyleaks OCR engine supports for extracting text from images and scanned documents.
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v3/miscellaneous/ocr-languages-list
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
# Public endpoint no authentication required.
languages = Copyleaks.ocr_supported_langauges()
print(languages)
```
```json 200 OK
["af", "sq", "az", "...", "zu"]
```
Get a list of the supported languages for OCR
This is not a list of supported languages for the API, but only for the OCR files scan
## Response
**200 OK** - The supported language codes in ISO-639-1 standard.
```json
["af", "sq", "az", "...", "zu"]
```
---
## OCR Supported Languages
These are the language codes supported by our OCR scan in `ISO-639-1` standard:
We keep updating the list with new languages so we recommend [loading the list in runtime](/reference/actions/miscellaneous/ocr-supported-languages) rather than copying it to your code.
| Code | Language | Code | Language |
|--------|---------------|--------|---------------|
| af | Afrikaans | am | Amharic |
| ar | Arabic | az | Azerbaijani |
| be | Belarusian | bg | Bulgarian |
| bn | Bengali | bs | Bosnian |
| ca | Catalan | ceb | Cebuano |
| co | Corsican | cs | Czech |
| cy | Welsh | da | Danish |
| de | German | el | Greek |
| en | English | eo | Esperanto |
| es | Spanish | et | Estonian |
| eu | Basque | fa | Persian |
| fi | Finnish | fr | French |
| fy | Frisian | ga | Irish |
| gd | Scottish Gaelic | gl | Galician |
| gu | Gujarati | ha | Hausa |
| haw | Hawaiian | hi | Hindi |
| hmn | Hmong | hr | Croatian |
| ht | Haitian Creole | hu | Hungarian |
| hy | Armenian | id | Indonesian |
| ig | Igbo | is | Icelandic |
| it | Italian | iw | Hebrew |
| ja | Japanese | jw | Javanese |
| ka | Georgian | kk | Kazakh |
| km | Khmer | kn | Kannada |
| ko | Korean | ku | Kurdish |
| ky | Kyrgyz | la | Latin |
| lb | Luxembourgish | lo | Lao |
| lt | Lithuanian | lv | Latvian |
| ma | Marathi | mg | Malagasy |
| mi | Maori | mk | Macedonian |
| ml | Malayalam | mn | Mongolian |
| mr | Marathi | ms | Malay |
| mt | Maltese | my | Burmese |
| ne | Nepali | nl | Dutch |
| no | Norwegian | ny | Chichewa |
| pl | Polish | ps | Pashto |
| pt | Portuguese | ro | Romanian |
| ru | Russian | sd | Sindhi |
| si | Sinhala | sk | Slovak |
| sl | Slovenian | sm | Samoan |
| sn | Shona | so | Somali |
| sq | Albanian | sr | Serbian |
| st | Sesotho | su | Sundanese |
| sv | Swedish | sw | Swahili |
| ta | Tamil | te | Telugu |
| tg | Tajik | th | Thai |
| tl | Tagalog | tr | Turkish |
| uk | Ukrainian | ur | Urdu |
| uz | Uzbek | vi | Vietnamese |
| xh | Xhosa | yi | Yiddish |
| yo | Yoruba | zh-CN | Chinese (Simplified) |
| zh-TW | Chinese (Traditional) | zu | Zulu |
## Frequently asked questions
### What are OCR supported languages used for?
They apply only to OCR scans, where Copyleaks extracts text from images and scanned documents. This is not the general language list for plagiarism or AI detection.
### How do I get the current list of OCR languages?
Call `GET https://api.copyleaks.com/v3/miscellaneous/ocr-languages-list`. It is a public endpoint that needs no authentication. Copyleaks keeps adding languages, so load the list at runtime instead of hardcoding it.
### What language code format does OCR use?
ISO-639-1 codes (for example `en`, `fr`, `ar`), with `zh-CN` for Simplified Chinese and `zh-TW` for Traditional Chinese.
### Does OCR support non-Latin scripts like Arabic, Chinese, and Hindi?
Yes. The OCR engine supports 100+ languages, including Arabic (`ar`), Chinese (`zh-CN`, `zh-TW`), Hindi (`hi`), Japanese (`ja`), Korean (`ko`), and many more.
---
## Supported AI Text Detection File Types
Source: https://docs.copyleaks.com/reference/actions/miscellaneous/supported-ai-text-detection-file-types
> File formats accepted by the API
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v3/miscellaneous/supported-ai-text-detection-file-types
```
```json 200 OK
{
"supportedAiFileTypes": [
"pdf", "docx", "doc", "txt", "rtf", "xml",
"pptx", "ppt", "odt", "chm", "epub", "odp",
"ppsx", "pages", "xlsx", "xls", "csv",
"LaTeX", "html", "htm"
]
}
```
Get a list of the Supported AI Text Detection File Types.
## Response
**200 OK** - The command was executed.
```json
{
"supportedAiFileTypes": [
"pdf", "docx", "doc", "txt", "rtf", "xml",
"pptx", "ppt", "odt", "chm", "epub", "odp",
"ppsx", "pages", "xlsx", "xls", "csv",
"LaTeX", "html", "htm"
]
}
```
---
## Cross-Language Plagiarism
Source: https://docs.copyleaks.com/reference/actions/miscellaneous/supported-cross-languages
> Get the source and target languages supported for cross-language plagiarism detection with the Copyleaks API.
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v3/miscellaneous/allowed-cross-languages
```
```json 200 OK
{
"documentLanguages": ["da", "nl", "en", "...", "es"],
"resultLanguages": ["sq", "bg", "my", "ca", "hr", "cs", "da", "...", "vi"]
}
```
Cross-language plagiarism detection identifies content that has been translated from one language to another, helping catch plagiarism attempts where text is copied and translated to avoid detection.
This document provides information about the languages supported by Copyleaks for cross-language scans. The language codes are provided in the `ISO-639-1` standard.
## Response
**200 OK** - The supported language codes in `ISO-639-1` standard.
```json
{
"documentLanguages": [
"da",
"nl",
"en",
"...",
"es"
],
"resultLanguages": [
"sq",
"bg",
"my",
"ca",
"hr",
"cs",
"da",
"...",
"vi"
]
}
```
## Supported Languages for Cross-Language Scans
The following sections list the supported source and result languages for cross-language scans.
These language codes are provided in the `ISO-639-1` standard.
We keep updating the list with new languages so we recommend [loading the list in runtime](/reference/actions/miscellaneous/supported-cross-languages) rather than copying it to your code.
### Allowed Source Languages
The following languages can be used as the source language in a cross-language scan:
| Code | Language | Code | Language |
|------|-----------|------|-----------|
| da | Danish | fr | French |
| nl | Dutch | de | German |
| en | English | it | Italian |
| pt | Portuguese| ru | Russian |
| es | Spanish | | |
### Allowed Result Languages
The following languages can be used as the result language in a cross-language scan:
| Code | Language | Code | Language |
|------|------------|------|------------|
| sq | Albanian | gl | Galician |
| bg | Bulgarian | ka | Georgian |
| ca | Catalan | de | German |
| hr | Croatian | el | Greek |
| cs | Czech | hi | Hindi |
| da | Danish | hu | Hungarian |
| nl | Dutch | id | Indonesian |
| en | English | it | Italian |
| fi | Finnish | lv | Latvian |
| fr | French | lt | Lithuanian |
| mk | Macedonian | my | Burmese |
| fa | Persian | pl | Polish |
| pt | Portuguese | ro | Romanian |
| ru | Russian | sr | Serbian |
| sk | Slovak | sl | Slovenian |
| es | Spanish | sv | Swedish |
| tr | Turkish | uk | Ukrainian |
| ur | Urdu | vi | Vietnamese |
---
## Supported Plagiarism File Types
Source: https://docs.copyleaks.com/reference/actions/miscellaneous/supported-plagiarism-file-types
> File formats accepted by the API
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v3/miscellaneous/supported-plagiarism-file-types
```
```python title="Python" icon="python"
from copyleaks.copyleaks import Copyleaks
# Public endpoint no authentication required.
file_types = Copyleaks.supported_file_types()
print(file_types)
```
```json 200 OK
{
"textual": [
"pdf", "docx", "doc", "txt", "rtf", "xml",
"pptx", "ppt", "odt", "chm", "epub", "odp",
"ppsx", "pages", "xlsx", "xls", "csv", "LaTeX"
],
"ocr": ["gif", "png", "bmp", "jpg", "jpeg"]
}
```
Get a list of the supported plagiarism file types.
## Response
**200 OK** - The command was executed.
```json
{
"textual": [
"pdf", "docx", "doc", "txt", "rtf", "xml",
"pptx", "ppt", "odt", "chm", "epub", "odp",
"ppsx", "pages", "xlsx", "xls", "csv", "LaTeX"
],
"ocr": ["gif", "png", "bmp", "jpg", "jpeg"]
}
```
---
# Actions → Private Cloud Hub
## Private Cloud Hub Actions
Source: https://docs.copyleaks.com/reference/actions/private-cloud-hub/overview
> Manage your Private Cloud Hubs.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
A **Private Cloud Hub** is a private database exclusive to your organization, your documents are indexed into it and stay within your private environment, making them available for cross-comparison against future scans without ever being exposed to other Copyleaks customers.
You can create and manage your hubs from the [admin dashboard](https://admin.copyleaks.com/repositories). The endpoints below let you inspect and manage hub metadata programmatically for end-to-end usage (indexing documents, scanning against a hub), see the [Data Hubs concept guide](/concepts/features/data-hubs).
## Endpoints
---
## Get Repository Information
Source: https://docs.copyleaks.com/reference/actions/private-cloud-hub/info
> Get repository information such as credit consumption, metadata values and current status.
```bash title="cURL" icon="terminal"
curl --request GET \
--url https://api.copyleaks.com/v3/repositories/repository/my-repo-123/info \
--header 'Authorization: Bearer YOUR_LOGIN_TOKEN'
```
```json 200 OK
{
"id": "private-data-hub-id",
"name": "Private Data Hub Name",
"description": "Your Description",
"permission": 4,
"status": 0,
"maxCredits": 1000,
"currentCredits": 1000,
"maskingPolicy": 0,
"creationTime": "2024-09-09T10:43:52"
}
```
Get repository information such as credit consumption, metadata values and current status. A "Super Admin" or "Admin" role is required.
**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
The repository ID to get the info for. The repository ID can be fetched from the [Copyleaks Admin Dashboard](https://admin.copyleaks.com/repositories).
### Headers
```http
Authorization: Bearer YOUR_LOGIN_TOKEN
```
## Responses
**200 OK** - The command was executed.
```json
{
"id": "private-data-hub-id",
"name": "Private Data Hub Name",
"description": "Your Description",
"permission": 4,
"status": 0,
"maxCredits": 1000,
"currentCredits": 1000,
"maskingPolicy": 0,
"creationTime": "2024-09-09T10:43:52"
}
```
**400 Bad Request** - Bad Request.
**401 Unauthorized** - Authorization has been denied for this request.
**403 Forbidden** - Your organization role does not permit you to perform this request. This operation requires "Super Admin" or "Admin" role.
---
# Data Types
## Overview
Source: https://docs.copyleaks.com/reference/data-types/overview
> Explore the comprehensive Copyleaks API reference for data types, from scan results to webhook payloads.
Understand the structure of the data you'll work with. Our API reference provides detailed information on every data object, from scan results to webhook payloads, ensuring you can build robust and reliable integrations.
## Explore Our Data Models
Dive into the specifics of each data type to understand how to work with the Copyleaks API.
Explore the data types related to authenticity, including plagiarism, AI detection, and webhooks.
Explore the data types related to AI detection.
Explore the data types related to Grammar Checker.
Explore the data types related to content moderation.
---
# Data Types → Authenticity
## Authenticity
Source: https://docs.copyleaks.com/reference/data-types/authenticity/overview
> Explore the data types related to authenticity, including plagiarism, AI detection, and webhooks.
This section provides detailed information about the data types related to authenticity.
Explore the data types related to the Private Cloud Hub.
Detailed information about the results you can get from a scan.
Detailed information about the webhooks you can subscribe to for asynchronous event notifications.
Provides metadata and information about a scan that has been submitted to the Copyleaks API.
Tags used in scan results
All available alert type codes
API limits, requirements, and constraints
---
## Result Tags
Source: https://docs.copyleaks.com/reference/data-types/authenticity/result-tags
> Tags used in scan results
When scanning with Copyleaks, each result in your returned [Completion Webhook](/reference/data-types/authenticity/webhooks/scan-completed) may include one or more result tags.
These tags provide additional context or metadata about the scan results. Below you can find a full list of possible tags.
### Tag Types
Each tag is accompanied by a unique code, a title, and a description. Note that the title and description of these tags may be subject to change over time.
The title and description of the tags may change.
Code | Title | Description
---------|----------|---------
cross-language | Cross Language | Suspected cross-lingual plagiarism detected
code-license | License: [Code License] | The file is licensed under [Code License] license.
suspected-ai-generated | Suspected AI-Generated | This result is suspected to contain AI-generated text.
ai-source-match | AI Source Match| This result contains AI-generated text, originating from an internet source.
internal-ai-source-match | Internal AI Source Match | This result contains AI-generated text, originating from Copyleaks internal AI database.
## Next Steps
Learn more about the completed webhook and the information it provides.
Understand how AI-generated content is detected and tagged in scan results.
Explore how cross-language plagiarism is identified and tagged.
---
## Scan Alerts
Source: https://docs.copyleaks.com/reference/data-types/authenticity/scan-alerts
> All available alert type codes
When submitting documents, you may receive various types of alerts. These alerts provide important information about your scan results and any issues that occurred during processing. As an API user, you can use these alerts to improve the user experience by supporting more detection features and handling cases of failure.
Alerts are triggered for different scenarios, including:
- Features that failed to execute
- Text manipulation attempts and suspicious behavior
- Private Cloud Hub issues
Scan alerts are found in the [scan completion webhook](/reference/data-types/authenticity/webhooks/scan-completed) at:
```
notifications.alerts[]
```
Alert titles and messages may change over time as we improve our system. Each alert includes a specific code, category, and detailed message to help you understand what occurred.
## Categories
| id | Category |
|----|---------------------|
| 1 | General |
| 2 | AiContentDetection |
| 3 | CheatingDetection |
| 4 | WritingAssistant |
| 5 | CrossLanguage |
| 6 | InternalDatabase |
| 7 | Repository |
| 8 | ExcludeTemplate |
| 9 | PdfReport |
## Alerts
| Code | Title | Message | Category | Additional Data |
|----------------------------------|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|-------------------------------------------------------------------------|
| suspected-ai-text | Suspected Cheating: AI Text Detected | We are unable to verify that the text was written by a human. | 2 | [AI Content Detection Response](/reference/data-types/authenticity/results/ai-detection) |
| ai-detection-failed | AI Detection Failed | We were unable to validate that there was no AI text in the submitted document due to an internal error. | 2 | |
| file-type-not-supported | AI Detection Not Executed: File Type not Supported | The submitted file type is currently not supported for AI detection. | 2 | |
| ai-detection-lang-not-supported | AI Detection Not Executed: Language not Supported | The submitted language is currently not supported for AI detection. | 2 | |
| ai-detection-text-too-short | AI Detection Not Executed: Text too Short | The submitted text is too short for AI content detection. | 2 | |
| ai-insights-lang-unsupported | AI Insights: Unsupported Language | The submitted language is currently not supported for AI Insights. | 2 | [AI Logic Supported Languages](/reference/actions/miscellaneous/ai-detection-supported-languages#ai-logic-supported-languages) |
| ai-logic-source-code-unsupported | AI Logic: Source Code Unsupported | AI Logic does not support source code files. | 2 | |
| suspected-cheating-detected | Advanced Detection: Hidden Characters | We have detected the possible use of hidden characters to cheat the plagiarism scan. | 3 | |
| suspected-character-replacement | Advanced Detection: Character Replacement | We have detected possible use of special characters to cheat the plagiarism scan. | 3 | |
| suspected-white-text | Suspected Cheating: Invisible Text | We have detected a possible use of invisible text, switch to the textual version of the document to see all text. | 3 | |
| text-mostly-excluded | Advanced Detection: Major Text Exclusion | We have detected a possible cheating attempt to exclude the majority of text. | 3 | |
| cheat-detection-failed | Advanced Detection Failed | We were unable to validate that there was no cheating in the submitted document. | 3 | |
| writing-feedback-failed | Grammar Checker Failed | We were unable to produce a Grammar Checker report. | 4 | |
| writing-feedback-lang-not-supported | Grammar Checker Not Executed: Language not Supported | The submitted language is currently not supported for Grammar Checker. | 4 | |
| cross-language-same-as-doc-lang | Cross Language: Same Document Language | Submitted language and cross-language text are the same language. No credits were used. | 5 | |
| cross-language-unsupported-doc-lang | Cross Language: Unsupported Document Language | Your submitted document language is not supported for cross-language plagiarism detection. Cross language feature has been disabled for this scan. | 5 | |
| internal-db-forbidden-for-team | Shared Data Hub Team Policy Violation | Your organization does not allow scanning files against Copyleaks Shared Data Hub, this scan was not added or scanned against the Copyleaks Shared Data Hub. If you still wish to use the Shared Data Hub please contact your organization admin. | 6 | |
| unable-to-index | Add to Database Failed | We were unable to add your file to the database due to an internal error. | 6 | |
| repository-index-failed | Not Able to Index Against Repository | You do not have permission to index against `{RepositoryName}` or the repository does not exist. | 7 | |
| repository-scan-failed | Not Able to Scan Against Repository | You do not have permission to scan against `{RepositoryName}`. | 7 | |
| repository-full | This Private Cloud Hub is Full | Indexing to private cloud hub `{RepositoryName}` failed because the private cloud hub storage capacity has been reached. | 7 | |
| document-template-not-found | Document Template Not Found | We were unable to find the following exclusion document template:`{ScanIds}`. | 8 | |
| pdf-generation-failed | Unable to Generate PDF Report | The PDF report was not able to be generated. | 9 | |
## Next Steps
Learn how to receive and process notifications from Copyleaks, including scan alerts.
Review API limits and other technical details that might impact scan alerts.
Understand how to detect and handle various text manipulation attempts.
Learn more about detecting AI-generated text and related alerts.
---
## Scanned Document
Source: https://docs.copyleaks.com/reference/data-types/authenticity/scanned-document
> Detailed reference for the Scanned Document object, which contains metadata about a submitted scan.
The `scannedDocument` object provides metadata and information about a scan that has been submitted to the Copyleaks API.
The unique identifier for the scan that you provided during submission.
The total number of words detected in the submitted content.
The total number of words that were excluded from the scan based on your `exclude` settings.
The number of credits consumed by the scan. This will be `0` until the scan is completed.
The number of credits that are expected to be consumed by the scan upon completion.
The Coordinated Universal Time (UTC) timestamp indicating when the scan was created. Format: `YYYY-MM-DDTHH:mm:ss.sssssssZ`
An object containing metadata about the submitted file. For example, it can contain the `filename`.
An object indicating which scan features were enabled for this scan.
Indicates if plagiarism detection was enabled.
Indicates if AI-generated text detection was enabled.
Indicates if the AI Logic (explainable AI) feature was enabled.
Indicates if the Grammar Checker feature was enabled.
Indicates if the generation of a PDF report was enabled.
Indicates if cheat detection was enabled.
Indicates if AI source matching against internet sources was enabled.
Indicates if AI Source matching against internal sources was enabled.
Indicates if the citation checker was enabled.
The language code (ISO 639-1) of the language detected in the submitted content.
---
## Technical Specifications
Source: https://docs.copyleaks.com/reference/data-types/authenticity/technical-specifications
> Copyleaks API technical specifications: page definition (250 words = 1 page), file size limits, and scanning constraints.
This page describes the technical specifications of the Copyleaks API.
## Page Definition
A page is defined as up to **250 words**. This means that every 250 words (or portion thereof) in your document counts as one page for billing purposes.
How Page Counting Works:
- 1-250 words = 1 page
- 251-500 words = 2 pages
- 501-750 words = 3 pages
- etc.
## Input Limits
### Supported Plagiarism File Types
| Type | File Types List |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Textual: | `html`, `htm`, `txt`, `csv`, `rtf`, `xml`, `md` |
| Non-Textual: | `pdf`, `docx`, `doc`, `pptx`, `ppt`, `odt`, `chm`, `epub`, `odp`, `ppsx`, `pages`, `xlsx`, `xls`, `LaTeX` |
| Source code: | `ts`, `py`, `go`, `cs`, `c`, `h`, `idc`, `cpp`, `hpp`, `c++`, `h++`, `cc`, `hh`, `java`, `js`, `swift`, `rb`, `pl`, `php`, `sh`, `m`, `scala`, `css` |
You can access this list programmatically, for more info [click here](/reference/actions/miscellaneous/supported-plagiarism-file-types).
### Supported Textual File Types
All supported plagiarism file types are also supported when submitted online by URL.
### Supported Image Types (OCR)
The supported image files are `pdf, docx, gif, png, bmp, jpg and jpeg` . The files must contain textual content. Upload only.
You can access this list programmatically, for more info [click here](/reference/actions/miscellaneous/ocr-supported-languages).
### Supported Plagiarism Languages
| Setting | Description |
|------------------------------|-------------|
| **Supported Languages** | All languages supported by Unicode, including English, Spanish, French, Portuguese, Arabic, Russian, German, Greek, Chinese, Japanese, and more. [More info](https://unicode.org/standard/supported.html). |
| **Supported OCR Languages** | See full list [here](/reference/actions/miscellaneous/ocr-supported-languages). |
| **Supported Cross Languages** | See full list [here](/reference/actions/miscellaneous/supported-cross-languages). |
| **Maximum Document Length** | The maximum length allowed is **2000 pages** (500K words). |
### File Size
| Description | Max Upload File Size |
| ------------------------------------------------- | -------------------- |
| HTML files (`html`, `htm`, ...) | 5 MB |
| Text files (`txt`, `csv`) and source-code | 3 MB |
| Non-Textual Documents (`pdf`, `doc`, `docx`, ...) | 50 MB |
| Image Types (`jpg`, `png`, `bmp`, ...) | 25 MB |
## Rate Limit
An account by default has a rate of 10 requests per second. If you still need higher rates, feel free to [contact us](https://help.copyleaks.com/s/contactsupport).
Rate Limit Exceeded, If your host has reached its API limit, you will receive the HTTP error 429 (Too Many Requests) and you will be unable to authenticate with the Copyleaks API for 5 minutes.
## Maintenance Periods
When our servers are under maintenance you will receive a `503` HTTP status code. Please wait a full minute and try again.
For more information about the service status -[ Copyleaks System Status](https://status.copyleaks.com).
## Time
| Setting | Value |
|-----------------------------|---------------------|
| **Time Format** | `dd/MM/yyyy HH:mm:ss` |
| **Time Zone** | UTC |
| **Default HTTP Request Timeout** | 110 seconds |
## Scan Expiration
Your created scans using the [/v3/submit](/reference/actions/authenticity/submit-file) endpoints will be stored in Copyleaks servers for a specific duration of time. You can control the expiration of your scans in your submit request. Make sure you save your data before it expires:
| Type | hours |
| ------------------ | ----- |
| Max Expiration | 2880 |
| Default Expiration | 2880 |
## Frequently asked questions
### How does Copyleaks count pages for billing?
A page is defined as up to 250 words. Every 250 words (or portion thereof) counts as one page, so 1-250 words is 1 page, 251-500 words is 2 pages, and so on.
### What is the maximum file size I can submit?
It depends on the file type: 50 MB for non-textual documents (PDF, DOC, DOCX), 25 MB for images submitted to OCR, 5 MB for HTML files, and 3 MB for text and source-code files.
### What is the maximum document length?
2000 pages, which is approximately 500,000 words.
### What is the Copyleaks API rate limit?
10 requests per second by default. Exceeding it returns HTTP 429 (Too Many Requests) and blocks authentication for 5 minutes. Contact Copyleaks if you need a higher rate.
### How long are scans stored before they expire?
Scans are stored for 2880 hours (120 days) by default, which is also the maximum. You can set a shorter expiration in the submit request, so save your results before they expire.
---
# Data Types → Authenticity → Results
## Results Data Types
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/overview
> Explore the various data structures for scan results, including plagiarism, AI detection, and writing feedback.
This section provides detailed information about the different types of results you can receive from a Copyleaks scan. Each result type has a specific data structure, which is detailed in the pages below.
A snapshot of AI Detection results, providing data from the matched results.
A summary of the scan's findings, generated by our AI.
A snapshot of the submitted document as viewed by Copyleaks.
A snapshot of specific plagiarism results detected by Copyleaks.
A snapshot of writing feedback and corrections.
Response structure and field definitions for the Image Plagiarism Detection API.
---
## New Result
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/new-result
> A new result was found during the scan process.
import Results from '/snippets/results.mdx';
The new results webhook is triggered when a new plagiarism result is found during the scan process. __When you receive this webhook, the scan is still in progress.__
The current score of the scan up to this point.
The developer payload that was provided in the submit method.
## Example
```json
{
"score": 0,
"developerPayload": "string",
"internet": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"url": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
}
],
"database": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"scanId": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
}
],
"batch": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"scanId": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
}
],
"repositories": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"repositoryId": "string",
"scanId": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string",
"submittedBy": "string"
}
}
]
}
```
## Next Steps
Learn about the different types of webhooks and how to handle them.
Learn how to export scan results, including new plagiarism results.
Understand how to present new results to your users effectively.
---
## New Plagiarism Result
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/new-plagiarism-result
> A snapshot of specific results detected by Copyleaks. It provides the data from the matched results.
import NewPlagiarismResult from '/snippets/new-plagiarism-result.mdx';
A snapshot of specific results detected by Copyleaks. It provides the data from the matched results.
## Webhook HTTP verb
The HTTP verb for this webhook is upon developer request. You need to specify your verb while executing the [Export method](/reference/actions/downloads/export) See `results.verb` field.
We recommend you use the HTTP verb `PUT`. It will allow Copyleaks to override an existing file as needed.
## Example
```json
{
"statistics": {
"identical": 0,
"minorChanges": 0,
"relatedMeaning": 0
},
"text": {
"value": "Hello world!",
"pages": {
"startPosition": [
0
]
},
"comparison": {
"identical": {
"source": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
},
"suspected": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
}
},
"minorChanges": {
"source": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
},
"suspected": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
}
},
"relatedMeaning": {
"source": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
},
"suspected": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
}
}
}
},
"html": {
"value": "Hello world!
",
"comparison": {
"identical": {
"groupId": [
0
],
"source": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
},
"suspected": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
}
},
"minorChanges": {
"groupId": [
0
],
"source": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
},
"suspected": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
}
},
"relatedMeaning": {
"groupId": [
0
],
"source": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
},
"suspected": {
"chars": {
"starts": [
0
],
"lengths": [
1
]
},
"words": {
"starts": [
0
],
"lengths": [
1
]
}
}
}
}
}
}
```
## Next Steps
Learn how to use the export method to retrieve detailed scan results.
Understand how to present plagiarism results to your users effectively.
---
## AI Overview
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/ai-overview
> The Gen-AI Overview field: a markdown summary of each scan with central themes, key insights, and context drawn from historical data.
Copyleaks’ Gen AI thoroughly analyzes each scan, summarizing content, identifying central themes, pinpointing key insights, and leveraging historical data to provide a richer, context-driven perspective.
A markdown-formatted string containing the Gen-AI overview of the scan.
The version of the model used for the Overview generation.
## Example
```json
{
"overview": "### Historical Author Data:\n- Four scans analyzed with an average plagiarism similarity of 13.18%\n- 4 instances of AI-generated content detected\n\n### Current Plagiarism Detection:\n- 0% overall plagiarism\n- Main sources: \n - yard.com (3.0%, 74 words)\n - brainly.com (3.2%, 45 words)\n - llcattorney.com (1.3%, 29 words)\n - montrosedemocrats.org (3.0%, 12 words)\n\n### AI Content Detection:\n- 100% AI-written content detected\n\n### Grammar Checker:\n- 100% writing quality with no errors in grammar, sentence structure, word choice, and mechanics.",
"modelVersion": "v1"
}
```
## Next Steps
Learn more about the GenAI Scan feature and its capabilities.
Understand how AI logic can help you interpret the results of AI text detection.
Learn how to export scan results, including the AI Overview.
---
## AI Text Detection
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/ai-detection
> A snapshot of AI Text Detection results detected by Copyleaks. It provides the data from the matched results.
import AiDetectionModelVersion from '/snippets/ai-detection-model-version.mdx';
import ResultAiDetection from '/snippets/result-ai-detection.mdx';
import SummaryAiDetection from '/snippets/summary-ai-detection.mdx';
import Explain from '/snippets/explain.mdx';
## Example
```json
{
"modelVersion": "v7.1",
"results": [
{
"classification": 2,
"probability": 1,
"matches": [
{
"text": {
"chars": {
"starts": [
0
],
"lengths": [
1509
]
},
"words": {
"starts": [
0
],
"lengths": [
221
]
}
}
}
]
}
],
"summary": {
"human": 0,
"ai": 1
},
"explain": {
"patterns": {
"statistics": {
"aiCount": [
15.9636,
39.5495,
84.7079,
119.8710,
9.9233,
185.6670,
14.4536,
19.1995
],
"humanCount": [
0.8076,
1.5076,
3.8228,
8.5071,
0.3769,
4.2536,
0.3231,
1.1845
]
},
"text": {
"chars": {
"starts": [31, 55, 303, 909, 961, 987, 1129, 1775],
"lengths": [23, 32, 23, 33, 25, 30, 30, 19]
},
"words": {
"starts": [5, 9, 45, 135, 144, 148, 169, 257],
"lengths": [4, 6, 3, 6, 4, 5, 5, 3]
}
}
}
}
}
```
## Next Steps
Learn how to use the AI Detection API to check if content was written by a human or generated by an AI.
Understand how AI logic can help you interpret the results of AI text detection.
Learn how to export scan results, including AI detection data.
---
## Crawled Version
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/crawled-version
> A snapshot of the submitted document. It shows how Copyleaks viewed your submitted file.
import CrawledVersion from '/snippets/crawled-version.mdx';
import SummaryReferencesValidation from '/snippets/summary-citation-checker.mdx';
import ResultsReferencesValidation from '/snippets/results-citation-checker.mdx';
A snapshot of the submitted document. It shows how Copyleaks viewed your submitted file.
## Webhook HTTP verb
The HTTP verb for this webhook is upon developer request. You need to specify your verb while executing the [Export method](/reference/actions/downloads/export) See `crawledVersion.verb` field.
We recommend you use the HTTP verb `PUT`. It will allow Copyleaks to override an existing file as needed.
The crawled version is available in textual format, and if the `properties.includeHtml` field (in the `submit` method) is set to `true`, it is also in HTML format.
## Example
```json
{
"metadata": {
"words": 30,
"excluded": 2
},
"html": {
"value": "Example Domain
This domain is established to be used for illustrative examples in documents.",
"exclude": {
"starts": [
16
],
"lengths": [
14
],
"reasons": [
3
],
"groupIds": [
1
]
}
},
"text": {
"value": "Example Domain This domain is established to be used for illustrative examples in documents.",
"exclude": {
"starts": [
0
],
"lengths": [
14
],
"reasons": [
3
]
},
"pages": {
"startPosition": [
0
]
}
}
}
```
## Citation Checker
When `references.validate` is enabled, the crawled version includes a `referencesValidation` object with the validation `summary` and a `results` array (one entry per detected reference).
### Validation semantics
A reference is counted in `academicValidated` or `nonAcademicValidated` only when it is fully corroborated: the top suggestion matched the title and no checked signal is `false`. A signal that is absent or null is ignored, not held against the reference.
- A suggestion with `signals` of `{ "title": true }` only, with no year or authors checked, counts as validated.
- A suggestion with `{ "title": true, "year": false, "authors": false }` does not count as validated.
### References validation example
```json
{
"referencesValidation": {
"summary": {
"total": 2,
"academic": 1,
"academicValidated": 1,
"nonAcademicValidated": 0
},
"results": [
{
"type": "academic",
"textRanges": { "starts": [131], "lengths": [131] },
"htmlRanges": { "starts": [240], "lengths": [131], "groupIds": [0] },
"parsed": {
"title": "Attention Is All You Need",
"authors": ["Vaswani, A.", "Shazeer, N.", "Parmar, N."],
"year": 2017,
"journal": "Advances in Neural Information Processing Systems"
},
"suggestions": [
{
"url": "https://doi.org/10.48550/arXiv.1706.03762",
"doi": "10.48550/arXiv.1706.03762",
"title": "Attention Is All You Need",
"authors": ["Vaswani, A.", "Shazeer, N.", "Parmar, N.", "Uszkoreit, J."],
"publishedYear": 2017,
"modifiedYear": 2023,
"journal": "Advances in Neural Information Processing Systems",
"signals": { "title": true, "year": true, "authors": true }
}
]
},
{
"type": "nonAcademic",
"textRanges": { "starts": [500], "lengths": [100] },
"htmlRanges": { "starts": [620], "lengths": [100], "groupIds": [1] },
"parsed": {
"url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
"title": "Artificial intelligence",
"authors": ["Wikipedia"],
"year": 2024,
"journal": ""
},
"suggestions": [
{
"url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
"doi": "",
"title": "Artificial intelligence - Wikipedia",
"authors": ["Contributors to Wikimedia projects"],
"publishedYear": 2001,
"modifiedYear": 2026,
"journal": "",
"signals": { "title": true, "year": false, "authors": false }
}
]
}
]
}
}
```
## Next Steps
Learn how to use the export method to retrieve detailed scan results.
Understand how to present crawled versions and other scan data to your users.
---
## Image Plagiarism Response
Source: https://docs.copyleaks.com/reference/data-types/authenticity/results/image-plagiarism-response
> Response structure and field definitions for the Copyleaks Image Plagiarism Detection API.
The Copyleaks Image Plagiarism Detection API returns a synchronous response containing scan metadata and a categorized list of web locations where the submitted image was found.
## Response Properties
The custom string provided in the request, echoed back unchanged. `null` if not provided.
Metadata about the submitted image and the scan.
The scan ID provided in the request path.
The number of credits expected to be charged for this scan.
The number of credits actually charged for this scan.
UTC timestamp of when the scan was created (ISO 8601). Example: `"2026-05-24T10:00:00Z"`
Width of the submitted image in pixels.
Height of the submitted image in pixels.
The filename provided in the request.
The detection results.
All matching images found on the web, with full matches ordered first, then partial matches. Each image URL appears at most once.
The URL of the matching image.
The type of match:
- `0` - **Full**: Exact or near-exact copy of the submitted image.
- `1` - **Partial**: Cropped, resized, recolored, or otherwise modified version.
The web pages where this image was found. Omitted when the image was not located on any page.
The URL of the web page containing the matching image.
A summary of match counts.
Total number of matching images found.
Number of full matches (matchType `0`).
Number of partial matches (matchType `1`).
## Example Response
```json
{
"developerPayload": "my-custom-data",
"scannedImage": {
"scanId": "my-scan-1",
"expectedCredits": 1,
"actualCredits": 1,
"creationTime": "2026-05-24T10:00:00Z",
"width": 1920,
"height": 1080,
"filename": "my-photo.jpg"
},
"matches": {
"internet": [
{
"url": "https://example.com/images/photo.jpg",
"matchType": 0,
"webPages": [
{ "url": "https://example.com/blog/my-post" },
{ "url": "https://example.org/news/article" }
]
},
{
"url": "https://example.com/thumbs/photo-thumb.jpg",
"matchType": 1,
"webPages": [
{ "url": "https://example.org/gallery" }
]
},
{
"url": "https://example.org/gallery/photo-sm.jpg",
"matchType": 1
}
],
"score": {
"totalMatches": 3,
"fullMatches": 1,
"partialMatches": 2
}
}
}
```
An empty `matches.internet` array with all-zero scores means no matching content was found on the web.
## Next Steps
Step-by-step guide to submitting images and interpreting results.
Full API reference for the Image Plagiarism Detection endpoint.
---
# Data Types → Authenticity → Webhooks
## Webhooks Overview
Source: https://docs.copyleaks.com/reference/data-types/authenticity/webhooks/overview
> Get notified immediately when your scan status changes, without having to call any other methods.
import { EndpointRow } from '/snippets/endpoint-row.mdx';
A webhook is an automated message sent from an application when a specific event occurs. Think of it as a push notification for your server.
Instead of your application repeatedly asking the Copyleaks API, "Is the scan finished yet?" (a process known as polling), a webhook lets our servers notify you automatically as soon as an event happens. This approach is far more efficient and provides real-time updates.
Since authenticity scans can take time to complete, webhooks are essential for building a responsive and scalable integration. By using them, you can get immediate notifications for key events-like when a scan is completed, an error occurs, or the credit cost is calculated - without writing complex polling logic.
This page explains how to configure your endpoints to receive these events and what to expect from our system.
## System Events
Copyleaks system is able to notify you about a few different event types related to your scan. These events are critical for the scan success.
To allow us to fire your webhook, you will need to provide us with a valid HTTP(s) endpoint. You can do this by populating the `properties.webhooks.status` field in the submit method (URL, file, or OCR).
### Webhooks
### Suggested Endpoint Format
The recommended format for your webhook endpoint is:
```http
https://yoursite.com/copyleaks/{status}/SCAN_ID
```
The endpoint contains two dynamic parts:
1. **`{status}`** - This token is replaced by the Copyleaks server with the relevant event. Possible values include:
- ([**completed**](/reference/data-types/authenticity/webhooks/scan-completed)) - The scan completed successfully.
- **([error](/reference/data-types/authenticity/webhooks/error))** - The scan ended with an error.
- **([creditsChecked](/reference/data-types/authenticity/webhooks/credits-checked))** - Copyleaks inspected the submitted file and provides a cost for the scan.
- **([indexed](/reference/data-types/authenticity/webhooks/indexed))** - Copyleaks indexed the submitted file in its Shared Data Hub or repository.
2. **`SCAN_ID`** - This segment should be replaced with your actual process ID.
### Example
If your scan ID is `hello123`, your webhook endpoints would be:
- `https://yoursite.com/copyleaks/completed/hello123`
- `https://yoursite.com/copyleaks/error/hello123`
- `https://yoursite.com/copyleaks/creditsChecked/hello123`
Including the `SCAN_ID` in the webhook URL allows you to quickly identify and track the scan. While optional, it is highly recommended.
## New-Result Webhook
In addition to the `{status}` webhooks, there is a **new-result webhook** that reports newly found results as they are identified. This is useful for time-sensitive applications, providing a live stream of results without waiting for the scan to complete.
To use this webhook, populate the `properties.webhooks.newResult` field in the submit method (URL, file, or OCR).
## Client Requirements
To use the asynchronous model, your system must meet the following requirements:
- A web server connected to the internet.
- The ability to respond to webhook calls within **70 seconds** with an HTTP success code (2xx).
- Once a success code is received, the webhook will not be fired again for the same scan.
## Retry Policy
To ensure reliable delivery, Copyleaks implements an **automatic retry mechanism** in case of communication failures (e.g., server downtime, network instability).
If your server fails to respond or returns a **5xx error**, the webhook will be retried **up to 17 times**, following an **exponential backoff** strategy:
1, 2, 4, 8, 16, ..., **up to 65,535 seconds** between attempts.
To manually resend a webhook for a specific scan, use the [resend webhook](/reference/actions/authenticity/resend-webhook) endpoint.
## At-Least-Once Delivery Guarantee
Copyleaks follows an **"at-least-once"** delivery approach, ensuring that webhooks are always sent, even in cases of temporary failures.
While a webhook is guaranteed to be sent, it **may be delivered more than once** in rare cases. Your system should be designed to handle duplicate webhook notifications gracefully.
By implementing these best practices, you can ensure seamless integration with Copyleaks' asynchronous webhook system while maintaining the security and reliability of your application.
## Next Steps
Learn about the completed webhook and its contents.
Understand how to handle error webhooks and troubleshoot issues.
Learn about the webhook for checking credit costs before a scan.
Understand the webhook for documents indexed in the Copyleaks database.
Learn about the webhook that reports newly found results as they are identified.
Learn how to secure your webhook endpoints against unauthorized access.
---
## Scan Completed
Source: https://docs.copyleaks.com/reference/data-types/authenticity/webhooks/scan-completed
> The scan completed successfully.
import ScannedDocument from '/snippets/scanned-document.mdx';
import Results from '/snippets/results.mdx';
import Score from '/snippets/score.mdx';
import Notifications from '/snippets/notifications.mdx';
The `completed` event occurs once the scan process has been completed and the scan finished successfully.
Successful scans provide you all the output information from the scan process.
The current status of the scan. Possible values: `0` (Success), `1` (Error), `2` (CreditsChecked), `3` (Indexed)
The developer payload that was provided in the submit method.
`<= 512 characters`
General information about the scanned document.
A list of all the results that were found.
The aggregated score of all results.
A summary of the citation checker results, returned when `references.validate` was enabled for the scan. The webhook contains the summary only. The per-reference results, including the parsed citations and corroborating sources, are available in the [crawled version](/reference/data-types/authenticity/results/crawled-version#citation-checker).
An aggregated count of the references that were detected and validated.
The total number of references detected in the scanned content.
The number of detected references that were identified as academic.
The number of academic references that were fully corroborated against the Copyleaks academic citation index.
The number of non-academic references that were fully corroborated against their cited source.
A list of all the notifications that were found.
## Example
```json
{
"status": 0,
"developerPayload": "Custom developer payload",
"scannedDocument": {
"scanId": "string",
"totalWords": 0,
"totalExcluded": 0,
"credits": 0,
"creationTime": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
},
"results": {
"internet": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"url": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
}
],
"database": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"scanId": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
}
],
"batch": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"scanId": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string"
}
}
],
"repositories": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"repositoryId": "string",
"scanId": "string",
"metadata": {
"finalUrl": "string",
"canonicalUrl": "string",
"author": "string",
"organization": "string",
"filename": "string",
"publishDate": "string",
"creationDate": "string",
"lastModificationDate": "string",
"submittedBy": "string"
}
}
],
"internalAIData": [
{
"id": "string",
"title": "string",
"introduction": "string",
"matchedWords": 0,
"identicalWords": 0,
"similarWords": 0,
"paraphrasedWords": 0,
"totalWords": 0
}
],
"score": {
"identicalWords": 0,
"minorChangedWords": 0,
"relatedMeaningWords": 0,
"aggregatedScore": 0
}
},
"referencesValidation": {
"summary": {
"total": 0,
"academic": 0,
"academicValidated": 0,
"nonAcademicValidated": 0
}
},
"downloadableReport": {
"status": "Success = 0",
"report": "string"
},
"notifications": {
"alerts": [
{
"category": 2,
"code": "string",
"title": "string",
"message": "string",
"helpLink": "string",
"severity": 0,
"additionalData": "string"
}
]
}
}
```
## Next Steps
Learn about the different types of webhooks and how to handle them.
Learn how to export scan results, including new plagiarism results.
Understand how to present new results to your users effectively.
Explore the full list of scan alerts and their meanings.
---
## Credits Checked
Source: https://docs.copyleaks.com/reference/data-types/authenticity/webhooks/credits-checked
> Copyleaks inspected the submitted file and provides a cost for the scan.
import ScannedDocument from '/snippets/scanned-document.mdx';
Copyleaks supports a price check operation. In some cases, you won't know the exact length of your document, so using the price check will be helpful to understand how many credits are necessary. Copyleaks allows you to send your document and receive back the amount of credits that the system will require to complete a scan __(1 credit = 250 words)__.
To proceed with scanning the document after checking the credits needed, you should call the Start method.
Scans that are not triggered by calling the Start method within 48 hours will be deleted and will no longer be available.
The current status of the scan. Possible values: 0 (Success), 1 (Error), 2 (CreditsChecked), 3 (Indexed)
The developer payload that was provided in the submit method.
`<= 512` characters
The price of the scan. If you will continue scanning, this is the price you will pay.
General information about the scanned document.
## Example
```json
{
"status": 2,
"developerPayload": "Custom developer payload",
"credits": 1
}
```
## Next Steps
Learn how to initiate a scan after checking the credit cost.
Explore strategies for managing your Copyleaks credits effectively.
Learn about the different types of webhooks and how to handle them.
---
## Error
Source: https://docs.copyleaks.com/reference/data-types/authenticity/webhooks/error
> The scan ended with an error.
The `error` event happens as soon as the scan process reaches an end due to an error.
The current status of the scan. Possible values: 0 (Success), 1 (Error), 2 (CreditsChecked), 3 (Indexed)
The error type (e.g., `authentication_error`, `payment_error`, `invalid_request_error`, `api_error`).
The machine-readable error identifier (e.g., `invalid_credentials`, `insufficient_credits`).
Error code that represents the reason for failure. See below the full error table.
Human-readable error message that describes the reason for failure.
A URL to the documentation page for this error.
Additional details about specific parameters that caused the error.
The parameter name that caused the error.
A message describing the issue with this parameter.
The developer payload that was provided in the submit method.
`<= 512` characters
Copyleaks provides you with the specific error message describing the reason for the error. Some of the failures are related to incorrect configuration on your side. Others are related to Copyleaks server-side errors.
We are doing our best to successfully respond to all of your requests.
Still, sometimes we encounter an internal error. In that case, we will fix the problem as soon as possible. You will also get a unique ticket ID that will help identify the problem when contacting Copyleaks customer support.
For a complete reference of all the error codes and how to handle them, see [API Errors](/using-the-apis/api-errors).
## Example
```json
{
"status": 1,
"error": {
"type": "invalid_request_error",
"id": "missing_parameter",
"code": 1,
"message": "Bad request. One or several required parameters are missing or incorrect."
},
"developerPayload": "Custom developer payload"
}
```
## Next Steps
Complete reference of all API error codes and how to resolve them.
Learn about the different types of webhooks and how to handle them.
Understand how to implement an exponential backoff strategy for retrying requests.
Explore the full list of scan alerts and their meanings.
---
## Export Completed
Source: https://docs.copyleaks.com/reference/data-types/authenticity/webhooks/export-completed
> The export request is done.
Once the export request is done, a completion webhook is fired. When the webhook reaches your servers, please verify that all the requested data was copied correctly. To check that the commands finished successfully, check:
1. The `completed` flag should be equal to `true`.
2. Each `task.isHealthy` should be equal to `true`.
3. Each `task.httpStatusCode` should be equal to `2xx` (200, 204, …).
This flag gives an indication of whether the scan was completed without internal errors on the Copyleaks side. Possible values: true (Completed successfully), false (Error)
The developer payload that was provided in the submit method.
A List of completed tasks.
The endpoint address of the export task.
This flag gives an indication whether the scan was completed without internal errors on the Copyleaks side.
The status code reported by the customer servers. If the `tasks.isHealthy` is equal to false - this field will be null.
## Example
```json
{
"completed": true,
"developerPayload": "This is my payload",
"tasks": [
{
"endpoint": "https://yourserver.com/export/export-id/results/my-result-id",
"httpStatusCode": 200,
"isHealthy": true
},
{
"endpoint": "https://yourserver.com/export/export-id/pdf-report",
"httpStatusCode": 200,
"isHealthy": true
},
{
"endpoint": "https://yourserver.com/export/export-id/crawled-version",
"httpStatusCode": 200,
"isHealthy": true
}
]
}
```
## Next Steps
Learn how to initiate export requests for various scan artifacts.
Understand the different types of webhooks and how to handle them.
Learn how to present exported scan data to your users.
---
## Indexed
Source: https://docs.copyleaks.com/reference/data-types/authenticity/webhooks/indexed
> Copyleaks indexed the submitted file in its Shared Data Hub or repository.
Copyleaks allows users to upload and index their existing documents into the Copyleaks Shared Data Hub without performing a scan. This feature enables future submissions to be compared against these stored documents for enhanced plagiarism detection.
To activate the indexing mode, submit your content with the `properties.action=2` parameter. Indexing documents to the Copyleaks Shared Data Hub is free of charge.
Once the document is processed, a webhook will notify you of the indexing status:
- __Success:__ A webhook will confirm that your document has been indexed successfully.
- __Error:__ If indexing fails, an error webhook will be triggered, providing details about the reason for the failure.
The current status of the scan. Possible values: 0 (Success), 1 (Error), 2 (CreditsChecked), 3 (Indexed)
The developer payload that was provided in the submit method.
`<= 512` characters
## Example
```json
{
"status": 3,
"developerPayload": "Custom developer payload"
}
```
## Next Steps
Learn about the different types of webhooks and how to handle them.
Learn how to submit files for scanning, including enabling indexing.
Understand how to compare documents within your Private Cloud Hub and against other sources.
---
# Data Types → Authenticity → Private Cloud Hub
## Private Cloud Hub
Source: https://docs.copyleaks.com/reference/data-types/authenticity/private-cloud-hub/overview
> Explore the data types related to the Private Cloud Hub.
This section provides detailed information about the data types related to the Private Cloud Hub.
Data masking and privacy controls.
User roles and permissions.
Private Cloud Hub status codes and meanings.
---
## Masking Policy
Source: https://docs.copyleaks.com/reference/data-types/authenticity/private-cloud-hub/masking-policy
> Data masking and privacy controls
Copyleaks Private Cloud Hub allows the user to choose how to share data in Private Cloud Hubs between its users. The Masking Policy determines how data will be shown to users when a document from the Private Cloud Hub is matched against in a scan.
## Available Values
| ID | Masking Level | Description |
|----|----------------------------|-------------|
| **0** | **No Masking** | Users will be able to see the entire document. |
| **1** | **Mask Other User Documents** | If the user who initiated the scan is also the contributor of the document to the Private Cloud Hub - No masking will be applied. Otherwise, all document characters and words that do not match identically will be replaced and masked with a sequence of hashtags. |
| **2** | **Mask All Documents** | All document characters that do not match identically will be replaced with a sequence of hashtags. |
## Next Steps
Understand user roles and permissions within the Private Cloud Hub.
Check the status of your Private Cloud Hub, including storage capacity and usage.
Learn how to compare documents within your Private Cloud Hub and against other sources.
---
## Roles
Source: https://docs.copyleaks.com/reference/data-types/authenticity/private-cloud-hub/roles
> User roles and permissions
Private Cloud Hub provides a set of roles to control user access to your Hub. This is handy when having multiple users working with the same Private Cloud Hub.
## Available Roles
| ID | Role | Permissions |
|----|-------------|--------------|
| **1** | **Viewer** | - Access partial info of the repository metadata
- Scan against the repository documents |
| **2** | **Contributor** | - Full "Viewer" permissions
- Insert new documents to the repository
- Delete their submitted documents from the repository |
| **3** | **Admin** | - Full "Contributor" permissions
- Invite other users to use the repository
- Delete documents from the repository |
| **4** | **Super Admin** | - Full "Admin" permissions
- Delete all documents, including the entire repository
- Control and view billing information |
## Next Steps
Check the status of your Private Cloud Hub, including storage capacity and usage.
Learn about configuring masking policies for sensitive data within your Private Cloud Hub.
Understand how to compare documents within your Private Cloud Hub and against other sources.
---
## Status
Source: https://docs.copyleaks.com/reference/data-types/authenticity/private-cloud-hub/status
> Private Cloud Hub status codes and meanings
Each Private Cloud Hub maintains a status that can be used to know its state. This value can be used to identify issues with your Copyleaks Private Cloud Hubs.
## Available Values
| ID | Status | Description |
|----|-------------------------|-------------|
| **0** | **Running** | Private Cloud Hub is healthy. |
| **1** | **Pending For Deletion** | Private Cloud Hub is pending for deletion with all its documents and metadata. Private Cloud Hub is not available for use. |
| **2** | **Error** | Private Cloud Hub is not healthy. It's recommended to contact [**Copyleaks Support**](https://api.copyleaks.com/support/contactus) for help. |
| **3** | **Updating** | Maintenance processes are taking place. The Private Cloud Hub may not be available. |
| **4** | **Payment Required** | Private Cloud Hub is suspended because of missing or failed payment. |
## Next Steps
Understand user roles and permissions within the Private Cloud Hub.
Learn about configuring masking policies for sensitive data within your Private Cloud Hub.
Understand how to compare documents within your Private Cloud Hub and against other sources.
---
# Data Types → AI Detector
## AI Detection Data Types
Source: https://docs.copyleaks.com/reference/data-types/ai-detector/overview
> Explore the data types related to AI content detection for text and images.
This section provides detailed information about the data types returned by the AI Detection APIs.
Response structure for the AI Content Detection API, including classification results and detailed explanations.
Response structure for the AI Image Detection API, including summary scores and RLE mask data.
Webhook response structure for the AI Video Detection API, including audio/visual analysis and overall AI ratio.
---
## AI Text Detection Response
Source: https://docs.copyleaks.com/reference/data-types/ai-detector/ai-text-detector-response
> Response structure and field definitions for the Copyleaks AI Content Detection API, including classification results and detailed explanations.
import ResultAiDetection from '/snippets/result-ai-detection.mdx';
import SummaryAiDetection from '/snippets/summary-ai-detection.mdx';
import ScannedDocument from '/snippets/scanned-document.mdx';
The Copyleaks AI Content Detection API returns a comprehensive response that includes classification results, per-section `probability` values, and detailed explanations of the AI detection analysis. This response structure provides both high-level insights and granular details about detected AI-generated content patterns.
## Response Properties
The version of the AI detection model used (e.g., "v9.0").
An array of classification results for different sections of the text.
Metadata about the scan.
## Example Response
```json
{
"modelVersion": "v9.0",
"results": [
{
"classification": 2,
"probability": 0.7316979,
"matches": [
{
"text": {
"chars": {
"starts": [0],
"lengths": [554]
},
"words": {
"starts": [0],
"lengths": [73]
}
}
}
]
}
],
"summary": {
"human": 0.0,
"ai": 1.0
},
"scannedDocument": {
"scanId": "scan-id",
"totalWords": 73,
"totalExcluded": 0,
"credits": 1,
"expectedCredits": 1,
"creationTime": "2025-08-10T08:33:05.22225Z"
},
"explain": {
"patterns": {
"statistics": {
"aiCount": [1.2066389, 9.673915, 34.41001],
"humanCount": [0.18481831, 0.13894142, 0.33555666],
"proportion": [6.5287843, 69.625854, 102.54607],
"source": [1, 1, 1]
},
"text": {
"chars": {
"starts": [10, 96, 136],
"lengths": [25, 33, 33]
},
"words": {
"starts": [1, 12, 17],
"lengths": [4, 4, 5]
}
}
}
}
}
```
## Classification Codes
| Code | Classification | Description |
| ---- | -------------- | ----------------------------------------------------------------------- |
| 1 | Human | Content is likely written by a human |
| 2 | AI-generated | Content is likely generated by artificial intelligence |
## Next Steps
Learn how to use the AI Content Detection API to identify AI-generated text.
Explore the complete API reference for AI content detection.
Understand how AI Logic provides transparency in AI detection results.
---
## AI Image Detection Response
Source: https://docs.copyleaks.com/reference/data-types/ai-detector/ai-image-detection-response
> Response structure and field definitions for the Copyleaks AI Image Detection API, including summary scores and RLE mask data.
The Copyleaks AI Image Detection API returns a detailed response containing the analysis summary, image information, and a Run-Length Encoded (RLE) mask to identify AI-generated regions.
## Response Properties
The version of the AI detection model used for the analysis.
Contains the Run-Length Encoded (RLE) mask data. This can be used to visualize the AI-detected regions of the image. On the synchronous endpoint this object is omitted entirely when the request set `maskType: "none"`.
An array of starting positions for each AI-detected segment in the flattened 1D image array.
An array of lengths for each AI-detected segment, corresponding to the `starts` array.
Present only when the request included `maskType: "heatmap"`. One confidence band per segment, aligned with `starts` and `lengths`: an integer from `0` (lowest) to `4` (highest) indicating which confidence threshold that region reached. Use it to render a gradient overlay instead of a binary mask. Omitted for the default `binary` mask.
An object containing the overall proportion of human vs. AI-generated pixels.
The proportion of the image determined to be human-created. The value ranges from `0.0` to `1.0`.
The proportion of the image determined to be AI-generated. The value ranges from `0.0` to `1.0`.
Indicates whether the image was determined to be AI-generated.
An object containing metadata about the analyzed image.
The dimensions of the image.
The height of the image in pixels.
The width of the image in pixels.
Optional metadata extracted from the image file.
The timestamp (if available in EXIF data) indicating when the image was created.
The AI service or tool that created the image, if this information is present in the metadata.
The application or device used to create the image, if available in the metadata.
A summary of how the image was generated., if available in the metadata.
Present only when the request included `objectDetection`. One entry per object located in the image. Objects that were requested but not found are absent, so the array is not aligned by position with the request - look entries up by `object`.
The object description from the request that this entry corresponds to.
The Run-Length Encoded (RLE) segmentation mask for this object, in the coordinate space of `imageInfo.shape`.
An array of starting positions for each segment in the flattened 1D image array.
An array of lengths for each segment, corresponding to the `starts` array.
Metadata about the scan operation itself.
The unique identifier for this scan, provided by you in the request.
The actual number of credits consumed by the scan.
The expected number of credits for the scan.
The ISO 8601 timestamp indicating when the scan was created.
## Example Response
```json
{
"model": "ai-image-1-ultra",
"result": {
"starts": [0, 512, 1536, 2560],
"lengths": [256, 512, 768, 1024]
},
"summary": {
"human": 0.3,
"ai": 0.7
},
"isAiDetected": true,
"imageInfo": {
"shape": {
"height": 1024,
"width": 768
},
"metadata": {
"issuedTime": "2025-07-23T12:44:05",
"issuedBy": "OpenAI",
"appOrDeviceUsed": "OpenAI-API",
"contentSummary": "Created using generative AI"
}
},
"detectedObjects": [
{
"object": "face",
"mask": {
"starts": [1024, 3072],
"lengths": [512, 256]
}
}
],
"scannedDocument": {
"scanId": "my-scan-id-1",
"credits": 1,
"expectedCredits": 1,
"creationTime": "2023-01-10T10:07:58.9459512Z"
}
}
```
### Heatmap Result
When the request includes `maskType: "heatmap"`, the `result` object carries one confidence band per segment in `labels`:
```json
{
"result": {
"starts": [0, 512, 1536, 2560],
"lengths": [256, 512, 768, 1024],
"labels": [1, 2, 4, 3]
}
}
```
## Next Steps
Learn how to submit an image for AI detection and interpret the results.
Explore the complete API reference for the AI Image Detection endpoint.
---
## AI Video Detection Response
Source: https://docs.copyleaks.com/reference/data-types/ai-detector/ai-video-detection-response
> Webhook response structure and field definitions for the Copyleaks AI Video Detection API.
The Copyleaks AI Video Detection API delivers results asynchronously via webhook. The payload contains time-based detection data for the audio and visual tracks, overall AI ratios, video metadata, and scan details.
## Response properties
The version of the AI detection model used for the analysis.
Time-based AI detection results for the audio track. Positions and lengths are in milliseconds.
Start positions (in ms) of AI-detected audio segments.
Durations (in ms) of AI-detected audio segments, corresponding to each value in `starts`.
Segments of the audio track that were not scored and are excluded from the AI ratio calculations.
Start positions (in ms) of excluded audio ranges.
Durations (in ms) of excluded audio ranges.
Time-based AI detection results for the visual track. Positions and lengths are in milliseconds.
Start positions (in ms) of AI-detected visual segments.
Durations (in ms) of AI-detected visual segments, corresponding to each value in `starts`.
Segments of the visual track that were not scored and are excluded from the AI ratio calculations.
Start positions (in ms) of excluded visual ranges.
Durations (in ms) of excluded visual ranges.
Overall AI detection ratios calculated from the scored segments only. Segments listed in `exclude` are not included in any of these calculations.
Ratio of AI-detected audio duration to total audible duration. Excluded audio ranges are not counted. Range: 0.0-1.0.
Ratio of AI-detected visual duration to total visible duration. Excluded visual ranges are not counted. Range: 0.0-1.0.
Combined AI ratio across both audio and visual tracks, relative to the total video duration. Range: 0.0-1.0.
Indicates whether the video was determined to contain AI-generated content. Use this flag instead of interpreting the ratios yourself. For the exact score, see `summary.overallAIRatio`.
Information about the analyzed video.
Total duration of the video in seconds.
Optional metadata extracted from the video file (e.g. C2PA provenance data).
Timestamp (if available) indicating when the video was created.
The AI service or tool that created the video, if present in the metadata.
The application or device used to create the video, if available in the metadata.
A summary of how the video was generated, if available in the metadata.
Metadata about the scan operation itself.
The unique identifier for this scan, provided by you in the request.
The actual number of credits consumed by the scan.
The expected number of credits for the scan.
The ISO 8601 timestamp indicating when the scan was created.
## Example response
```json
{
"model": "ai-video-1-pro",
"audioResult": {
"starts": [13000, 45000, 47000],
"lengths": [14000, 1000, 8700],
"exclude": {
"starts": [0, 3250, 5400, 7600, 10500],
"lengths": [2950, 1500, 1200, 650, 1050]
}
},
"visualResult": {
"starts": [11566, 29433],
"lengths": [6134, 26267],
"exclude": {
"starts": [],
"lengths": []
}
},
"summary": {
"audioAIRatio": 0.4902,
"visualAIRatio": 0.5817,
"overallAIRatio": 0.7487
},
"isAiDetected": true,
"videoInfo": {
"metadata": {
"issuedTime": "2026-03-17T13:14:57+00:00",
"issuedBy": "OpenAI",
"appOrDeviceUsed": "Sora",
"contentSummary": "Created using generative AI"
},
"duration": 55.7
},
"scannedVideo": {
"scanId": "my-video-scan-1",
"actualCredits": 1,
"expectedCredits": 1,
"creationTime": "2026-05-05T12:37:50Z"
}
}
```
## Next steps
Submit a video for AI detection and interpret the webhook results.
The complete API reference for the AI Video Detection endpoint.
---
# Data Types → Writing
## Writing
Source: https://docs.copyleaks.com/reference/data-types/writing/overview
> Explore the data types related to Grammar Checker.
This section provides detailed information about the data types related to Grammar Checker.
Grammar Checker correction categories
A snapshot of Grammar Checker results detected by Copyleaks.
---
## Grammar Checker Object
Source: https://docs.copyleaks.com/reference/data-types/writing/writing-assistant
> A snapshot of Grammar Checker results detected by Copyleaks. It provides detailed data on writing quality, corrections, and readability.
import ScoreWritingFeedback from '/snippets/score-writing-feedback.mdx';
import CorrectionsWritingFeedbackResponse from '/snippets/corrections-writing-feedback-response.mdx';
import ScannedDocument from '/snippets/scanned-document.mdx';
The Grammar Checker object provides a comprehensive analysis of a submitted text, including scores, readability metrics, and detailed corrections.
An object containing the overall score, readability, and text statistics.
An object containing the detailed corrections for the text.
Metadata about the scan.
## Example
```json
{
"score": {
"corrections": {
"grammarCorrectionsCount": 2,
"grammarCorrectionsScore": 87,
"grammarScoreWeight": 1.0,
"mechanicsCorrectionsCount": 9,
"mechanicsCorrectionsScore": 38,
"mechanicsScoreWeight": 1.0,
"sentenceStructureCorrectionsCount": 0,
"sentenceStructureCorrectionsScore": 100,
"sentenceStructureScoreWeight": 1.0,
"wordChoiceCorrectionsCount": 1,
"wordChoiceCorrectionsScore": 93,
"wordChoiceScoreWeight": 1.0,
"overallScore": 79
},
"readability": {
"score": 59,
"readabilityLevel": 5,
"readabilityLevelText": "10th to 12th Grader",
"readabilityLevelDescription": "Fairly difficult to read"
},
"statistics": {
"sentenceCount": 5,
"averageSentenceLength": 12.2,
"averageWordLength": 5.5,
"readingTimeSeconds": 16.0,
"speakingTimeSeconds": 28.2
}
},
"corrections": {
"text": {
"chars": {
"types": [
5,
18,
3,
18,
18,
18,
18,
10,
18,
16,
18,
18
],
"starts": [
13,
22,
61,
104,
118,
136,
179,
233,
288,
347,
353,
374
],
"lengths": [
2,
10,
9,
6,
8,
35,
13,
9,
12,
4,
8,
11
],
"operationTexts": [
"an ",
"plagiarism ",
"businesses ",
"their ",
"original.",
"texts from the internet and data bases ",
"similarities.",
"multilingual ",
"positives, ",
"it's ",
"useful ",
"maintaining "
]
}
}
},
"scannedDocument": {
"scanId": "{scanId}",
"totalWords": 61,
"totalExcluded": 0,
"credits": 1,
"expectedCredits": 1,
"creationTime": "2025-08-11T06:46:01.2886658Z"
}
}
```
## Next Steps
Learn how to use the Grammar Checker API to detect and correct writing issues.
See a detailed list of all supported correction types and languages.
Learn how to export scan results, including Grammar Checker data.
---
## Correction Types
Source: https://docs.copyleaks.com/reference/data-types/writing/correction-types
> Grammar Checker correction categories
Each detected correction has an attached type. These types may be used to understand what error was detected and show it in the user interface.
You are able to fetch the list of correction types programmatically using the following [endpoint](/reference/actions/writing-assistant/correction-types).
## Categories
| id | Category|
|----|----------------|
| 1 | Sentence Structure|
| 2 | Grammar|
| 3 | Word Choice|
| 4 | Mechanics|
## Types
| ID | Title | Message | Description | Category |
|------|-------------------------|---------------------------------------|-------------------------------------------------------------------------------------------------------------------|----------|
| `1` | General | A general correction detected | A general correction detected. | 2 |
| `2` | Subject Verb Disagreement| Subject-verb disagreement detected | The subject and verb do not agree in number. | 2 |
| `3` | Noun Form | Use a different noun form | Using an incorrect form of a noun (such as pluralization or possessive form) in a sentence. | 2 |
| `4` | Verb Form | Use a different verb form | Using an incorrect form of a verb (such as tense, aspect, or agreement) in a sentence results. | 2 |
| `5` | Article | Use the appropriate article | Using the wrong article (a, an, or the) or omitting an article inappropriately in a sentence. | 2 |
| `6` | Preposition | Incorrect preposition usage | Using the wrong preposition or misplacing a preposition in a sentence. | 2 |
| `7` | Pronoun | Incorrect pronoun usage | Using an incorrect pronoun or misplacing a pronoun in a sentence. | 2 |
| `8` | Part of Speech | Incorrect part of speech | Misusing or misidentifying a word's grammatical category, such as confusing a noun with a verb. | 2 |
| `9` | Conjunction | Incorrect conjunction usage | Misusing or misplacing conjunctions, which are words that connect words, phrases, or clauses in a sentence. | 2 |
| `10` | Misused Word | Use a different word to convey the message | Words that are used incorrectly or inappropriately in a given context. | 3 |
| `11` | Homophone | Incorrect homophone usage detected | Confusing two words that phonetically sound similar but have a different meaning (e.g., "their" and "there" or "to" and "too"). | 3 |
| `12` | Capitalization | Incorrect capitalization | Word was not capitalized correctly (e.g., “paris” should be “Paris”). | 4 |
| `13` | Hyphen | Hyphen usage is incorrect | Incorrect or inconsistent use of hyphens in a sentence. | 4 |
| `14` | Punctuation | Incorrect punctuation usage | Incorrect use of punctuation marks, such as commas, periods, semicolons, or colons. | 4 |
| `15` | Comma | Incorrect comma usage | Incorrect use of commas in sentences. | 4 |
| `16` | Apostrophe | Incorrect apostrophe usage | Incorrect use of apostrophes in sentences. | 4 |
| `17` | Space | Missing or extra spaces | Missing or extra spaces detected in sentence. | 4 |
| `18` | Spelling | Misspelling detected | Misspelling of a word. | 4 |
| `19` | Fused Sentence | Fused sentence detected | When two independent clauses are incorrectly joined without appropriate punctuation or conjunction. | 1 |
| `20` | Comma Splice | Comma splice detected | Two independent clauses are incorrectly joined by a comma without a coordinating conjunction or appropriate punctuation. | 1 |
| `21` | Sentence Fragments | Ensure your sentence has a complete subject and predicate | When a group of words appears to be a sentence but is incomplete because it lacks a subject, a predicate, or both. | 1 |
| `22` | Ineffective Construction| Revise the sentence for better clarity and structure | Refers to sentences or phrases that are poorly constructed or lack clarity, making it difficult for readers to understand the intended meaning. | 1 |
| `23` | Extra Words | Sentence contains extra words | Sentences that contain unnecessary or redundant words, which can be removed for clearer and more concise writing. | 1 |
| `24` | Missing Words | Sentence with missing words | Identifies sentences that are missing essential words, resulting in incomplete or unclear meaning. | 1 |
| `25` | Adjective Gender Agreement | Gender agreement mismatch in adjectives | Detects errors in the gender agreement between adjectives and nouns. | 2 |
| `26` | Adjective Number Agreement | Number agreement error with adjectives | Highlights discrepancies in the number agreement between adjectives and nouns for improved grammatical precision. | 2 |
| `27` | Article Gender Agreement | Gender agreement error in articles | Agreement between articles and nouns in terms of gender is incorrect , ensuring grammatical accuracy. | 2 |
| `28` | Article Number Agreement | Number agreement error in articles | Number mismatch between articles and nouns creating inconsistency in how they refer to the same or similar elements in a sentence. | 2 |
| `29` | Noun Gender Agreement | Gender agreement error with nouns | Lack of agreement between nouns and their associated genders, ensuring grammatical harmony. | 2 |
| `30` | Subjunctive Mood | Subjunctive mood misuse | Identifies the incorrect usage of the subjunctive mood in sentences, ensuring proper expression of hypothetical or unreal situations. | 2 |
| `31` | Compound Word Error | Compound word usage error | Identifies incorrect compound word usage. | 2 |
| `32` | Mood Inconsistency | Inconsistency in mood detected | Detects inconsistencies in the expression of mood within a sentence, ensuring cohesive writing. | 2 |
| `33` | Accent Error | Incorrect or missing usage of accents | Highlights deviations in accents, promoting uniform language usage. | 4 |
| `34` | Homoglyph Error | Homoglyphs detected in text | Non-standard characters that appear identical or very similar but have a different meaning have been detected. | 2 |
## Next Steps
Learn how to use the Grammar Checker API to detect and correct writing issues.
Explore the complete API reference for Grammar Checker, including request and response details.
---
# Data Types → Moderation
## Moderation
Source: https://docs.copyleaks.com/reference/data-types/moderation/overview
> Explore the data types related to content moderation.
This section provides detailed information about the data types related to content moderation.
A comprehensive list of the content categories supported by the Copyleaks Text Moderation API.
---
## Text Moderation Labels
Source: https://docs.copyleaks.com/reference/data-types/moderation/text-moderation-labels
> A comprehensive list of the content categories supported by the Copyleaks Text Moderation API.
The Copyleaks Text Moderation API provides a flexible and powerful solution for identifying and managing a wide range of harmful or risky content. Our API supports a comprehensive set of moderation labels, allowing you to tailor the moderation process to your specific community standards.
## Supported Labels
| Label ID | Description |
| ------------------ | ------------------------------------------------------------------------------------ |
| `toxic-v1` | Harmful language that insults, demeans, or degrades in a general way, not necessarily aimed at a specific person. This category is reserved for language intended to cause emotional harm, not for references to illegal or toxic substances. |
| `profanity-v1` | Use of strong or offensive swear words. |
| `hate-speech-v1` | Language that demonizes or incites harm toward a group or individual based on inherent traits, often calling for violence or systemic discrimination. |
| `harassment-v1` | Targeted abuse that insults or degrades a specific person or group, focusing on personal traits or beliefs. This language aimed at a specific person or group that attacks their character or reputation, this can include defamatory or accusatory statements meant to harm someone’s standing. |
| `self-harm-v1` | References that encourage or normalize self-injurious behavior. |
| `adult-v1` | Explicit descriptions, references, or portrayals of sexual acts or behavior intended to evoke sexual arousal. This excludes non-sexual explicit content. |
| `violent-v1` | Language that incites or glorifies physical harm or injury. |
| `drugs-v1` | References, descriptions, or endorsements of the use, abuse, or distribution of drugs, including illegal substances or the misuse of legal drugs. |
| `firearms-v1` | Content discussing the use, possession, or distribution of guns and other weapons, especially when such discussions could promote or cause violence or unsafe practices. |
| `cybersecurity-v1` | Content related to computer security, including discussions on hacking, data breaches, and measures to hack digital systems or gain unauthorized access. |
## Usage
When submitting text for moderation, include the desired labels in your request. You can specify all labels or only the ones relevant to your use case:
**Request**
```http
POST https://api.copyleaks.com/v1/text-moderation/{scanId}/check
```
**Headers**
```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```
**Body**
```json
{
"text": "Your text content to be moderated goes here.",
"language": "en",
"labels": [
{ "id": "toxic-v1" },
{ "id": "profanity-v1" },
{ "id": "hate-speech-v1" },
{ "id": "harassment-v1" },
{ "id": "self-harm-v1" },
{ "id": "adult-v1" },
{ "id": "violent-v1" },
{ "id": "drugs-v1" },
{ "id": "firearms-v1" },
{ "id": "cybersecurity-v1" }
]
}
```
Full details about the request and response structure can be found in the [Text Moderation API Reference](/reference/actions/text-moderation/check/).
## Next Steps
Learn how to use the Text Moderation API to scan and moderate text content.
Explore the complete API reference for text moderation, including request and response details.
---
# Get started
## MCP Quickstart
Source: https://docs.copyleaks.com/mcp/quickstart
> Zero to a first Copyleaks result inside your AI agent, in six steps.
## Before you start
You need two things.
**1. A Copyleaks account you can already scan with.** Sign in to Copyleaks and check you can run a scan there on a paid balance. A subscription, a prepaid balance, or an account your organization pays for all work.
Free plans can't connect, and neither can an account whose plan has ended. A Copyleaks **API key doesn't count** - the API is a separate product, and having a key doesn't connect an agent.
**2. An AI tool with a place to add a connector.**
Claude, Codex, Gemini CLI, Antigravity, Cursor and VS Code all have a *Connectors* or *MCP* setting. A product without one can't connect, on any plan.
Once connected, all twelve tools work in every client. Larger files and images need a client that can run commands on your computer - see [what works where](/mcp/overview#what-you-need-and-what-works-where). In Claude Desktop, that's the Code tab.
---
## Step 1 - Add Copyleaks to your agent
The server is called `copyleaks_app`, and its address is `https://extensions.copyleaks.com/mcp`.
### Add it
**Claude Code** - one line:
```bash
claude mcp add --transport http copyleaks_app --scope user https://extensions.copyleaks.com/mcp
```
`--scope user` makes it available in every project on your machine. Then run `/mcp` inside a session to sign in.
**Claude Desktop or claude.ai** - go to **Customize → Connectors**, press **+ → Add custom connector**, paste the address above, then **Add → Connect**.
**Any other client** - copy its block from [Client setup](/mcp/client-setup). Blocks differ between clients.
---
## Step 2 - Approve what it can do
Your browser opens. Sign in to Copyleaks, review what your agent is asking for, and approve - you land back in your connector settings or terminal. [Permissions](/mcp/permissions) explains each one.
**Your agent can only do what you could do in Copyleaks.** It can't buy credits or change your plan, delete any scan, report, or profile, create share links, or see anything in another account.
---
## Step 3 - Start a new session
Agents load connectors when a session starts, so one added mid-conversation won't show up yet.
| Your agent | What to do |
|---|---|
| **Claude Desktop - Chat or Cowork tab** | **Quit the app completely and reopen it** - closing the window isn't enough. Then start a new chat or a new Cowork task |
| **claude.ai** | Reload the page, then start a new chat |
| **Claude Code** - terminal or the Code tab | Exit and relaunch. In an open session, `/mcp` picks it up without restarting |
| **Codex** · **Antigravity** | Exit and relaunch the CLI |
**In the Chat or Cowork tab**, open the tools menu in the message box and check Copyleaks is listed and enabled. Not there? Check you're signed in to the Claude account you added it on.
---
## Step 4 - Check it worked
Ask your agent:
> *"Check my Copyleaks credit balance."*
A number back means you're connected.
---
## Step 5 - Run your first scan
Paste a few paragraphs and ask:
> *"Check this for plagiarism and AI."*
Your agent submits the scan and checks back until it finishes. Ask how far along it is and you may get a percentage - never a finish time.
What comes back: your **`Plagiarism score`** and your **`AI score`**, as percentages to one decimal place, plus **which checks actually ran**.
**No `AI score`?** `AI Detection` needs at least **350 characters** - below that it doesn't run. A blank means *not measured*, not *nothing found*.
### Other ways to start a scan
| Ask for | What happens |
|---|---|
| *"Scan this file"* | Including PDFs, scanned pages and photos - Copyleaks pulls the text out and scans that |
| *"Scan these files"* | **Up to ten at a time.** Each is its own scan, run together rather than one after another |
| *"Scan this page"* | A web address, as long as it opens without signing in |
| *"Was this image AI-generated?"* | An image scan - about the picture, not the words in it. Needs a client that can run commands |
| *"Run that scan again"* | Re-checks an existing scan against current sources |
| *"…using my Client Reports profile"* | Runs it with the settings from a saved scan profile |
---
## Step 6 - Go deeper on the result
This is the part that isn't in the report. Keep asking:
> *"Which sources did I match?"*
> *"Show me the exact text that overlapped with the third one."*
> *"Walk me through everything flagged, in the order I wrote it."*
Your agent starts with the summary and goes deeper when you ask.
**To see the document itself, open the report.** Every finished scan comes with a link - `Open this scan in Copyleaks` - that opens your marked-up document.
---
## Worth knowing on day one
- **It uses your normal credits** - the same balance as scans in the app, with nothing extra to buy. [Limits and access](/mcp/limits)
- **Links that need a sign-in scan the login page.** Google Docs, SharePoint, Notion and the like return a sign-in page, and Copyleaks scans it and spends credits on it. Send the file instead. [Scanning](/mcp/scanning)
- **10 scans a minute, on every paid plan.** Extra work waits, and your agent carries on by itself.
- **Your own scans only.** Anything shared with you stays in Copyleaks.
---
## If something doesn't work
**No Copyleaks tools?** Start a new session (step 3). Still missing? You haven't signed in - `claude mcp login copyleaks_app`, or `/mcp` in a session. Anything else: [Troubleshooting](/mcp/troubleshooting).
---
## Where to go next
| | |
|---|---|
| **Everything you can ask for** | [Tools](/mcp/tools) - the twelve tools and what each one does |
| **Credits, limits and access** | [Limits and access](/mcp/limits) - throughput, who can connect, and how to disconnect |
| **Setup for your client** | [Client setup](/mcp/client-setup) - the exact block for each client |
| **How results work** | [Results](/mcp/results) - scores, matched sources, AI content and AI phrases |
---
## MCP Server
Source: https://docs.copyleaks.com/mcp/overview
> Run Copyleaks scans, read results, and manage scan profiles from any MCP-capable AI client.
There is nothing to install and no API key to paste.
**Requires a Copyleaks account that can run a scan in the app on a paid balance** - subscription, prepaid, or an organization-paid account. Free and lapsed accounts cannot connect, and a Copyleaks API key on its own is not a way in.
## What you need, and what works where
**You need an AI client with a place to add an MCP connector.** Claude (claude.ai, Claude Desktop, Claude Code), Codex, Gemini CLI, Antigravity, Cursor and VS Code all have one. A product without that setting can't connect, on any plan.
**All twelve tools work in every one of them, chat included.** The one difference is the upload step: a larger file or an image is sent to an upload address, which needs a client that can run a command on your machine.
| Capability | claude.ai · Claude Desktop **Chat** tab | Claude Desktop **Cowork** tab | Claude Desktop **Code** tab · Claude Code · Codex · Gemini CLI · Antigravity · Cursor · VS Code |
|---|---|---|---|
| All twelve tools - scan, results, history, profiles, balance | ✅ | ✅ | ✅ |
| Pasted text · web pages · small files | ✅ | ✅ | ✅ |
| Larger files | ⛔ | ⛔ | ✅ |
| Image scans | ⛔ | ⛔ | ✅ |
| Reads a folder you share | ⛔ | ✅ | ✅ |
Where a cell says no, upload the file or image in the Copyleaks app, then ask your agent to read the finished scan.
### Which Claude am I using?
Claude Desktop has three tabs - Chat, Cowork and Code - and the tab decides the column above.
| Where you are | What it is | How Copyleaks is added |
|---|---|---|
| **claude.ai** in a browser | Chat | **Customize → Connectors** |
| **Claude Desktop → Chat tab** | The same chat, as an app | The same connector - it follows your Claude account |
| **Claude Desktop → Cowork tab** | Works inside a folder you hand it; can run tasks on a schedule | The same connector as Chat |
| **Claude Desktop → Code tab** | **Claude Code** | `claude mcp add`, or `.mcp.json` - the same config as the terminal |
| **Claude Code** in a terminal, an IDE, or on the web | Claude Code | The same |
**Two tells.** The Code tab shows a terminal and file diffs; the Cowork tab shows a task plan and a folder you chose; Chat shows a conversation and nothing else.
## The endpoint
| | |
|---|---|
| **Server name** | `copyleaks_app` |
| **Endpoint** | `https://extensions.copyleaks.com/mcp` |
| **Transport** | Streamable HTTP (MCP 2025-06-18). Not SSE, not stdio |
| **Authorization** | OAuth 2.1 with PKCE (S256), advertised per RFC 9728 |
The endpoint names its own authorization server, so there is nothing to configure by hand.
---
# Connecting
## Permissions
Source: https://docs.copyleaks.com/mcp/permissions
> The six OAuth scopes the Copyleaks MCP server can request, and what each one grants.
Most clients request what they need automatically; where a client lets you name them, ask for the narrowest set that covers your work. The sign-in page shows you what is being requested before you approve it.
| Scope | Grants | Effect |
|---|---|---|
| `scans:read` | Read scan results and reports | Read only |
| `scans:run` | Submit new scans | Consumes credits |
| `profiles:read` | Read scan profiles and settings | Read only |
| `profiles:write` | Create and modify scan profiles | Changes config |
| `account:read` | Read account details and credit balance | Read only |
| `offline_access` | Refresh the session without signing in again | Recommended |
Without `offline_access`, you'll sign in again each time the session expires.
---
## Client setup
Source: https://docs.copyleaks.com/mcp/client-setup
> Config for Claude Code, the Claude chat apps, Gemini CLI, Antigravity, Codex CLI, Cursor, VS Code, and anything else.
Find your client below and copy its block - the URL field name differs between clients, and Antigravity connects through a bridge.
| Client | Config file | URL field | Auth |
|---|---|---|---|
| **Claude Code** - incl. the Code tab of Claude Desktop | `.mcp.json` / `~/.claude.json` | `url` + `"type":"http"` | Built-in OAuth |
| **Claude Desktop - Chat tab** · **Cowork tab** · **claude.ai** | UI only - Connectors | URL field in dialog | Built-in OAuth |
| **Gemini CLI** | `~/.gemini/settings.json` | `httpUrl` | Built-in OAuth |
| **Antigravity** | `~/.gemini/config/mcp_config.json` | `command` → `mcp-remote` | Via bridge |
| **Codex CLI** | `~/.codex/config.toml` | `url` | Built-in OAuth |
| **Cursor** | `~/.cursor/mcp.json` | `url` | Built-in OAuth |
| **VS Code** (Copilot) | `.vscode/mcp.json` | `url`, under `servers` | Built-in OAuth |
| **Other clients** | whatever it uses for stdio | `command` → `mcp-remote` | Via bridge |
Chat and Cowork can't send larger files or images - [what works where](/mcp/overview#what-you-need-and-what-works-where).
**After adding the server, start a new session.** Clients read their server list at startup, so a server added mid-conversation will not appear. Restart the CLI, or quit and reopen the desktop app - closing the window is not enough.
### Claude Code
Add the server. Use `--scope user` so it follows you into every project; drop the flag to keep it to the current directory.
```bash
claude mcp add --transport http copyleaks_app --scope user https://extensions.copyleaks.com/mcp
```
Start Claude Code, run `/mcp`, pick **copyleaks_app**, and sign in. The browser round-trip stores a token in your OS keychain - you will not be asked again until it expires.
Or sign in without a session: `claude mcp login copyleaks_app`. If the browser does not open, open the printed URL yourself. On a headless machine or over SSH, add `--no-browser` and paste the full redirect URL back at the prompt - over SSH, connect with `ssh -t` so the paste prompt works.
Confirm:
```bash
claude mcp list
claude mcp get copyleaks_app
```
A healthy server reports **✔ Connected**. **! Needs authentication** means the sign-in did not complete. **⏸ Pending approval** means a committed `.mcp.json` entry has not been approved on this machine yet - run `/mcp` and approve it.
**Sharing it with a team** - add it to `.mcp.json` at the project root and commit that file. Each teammate approves the server once and signs in with their own Copyleaks account; no credentials travel in the file.
```json
{
"mcpServers": {
"copyleaks_app": {
"type": "http",
"url": "https://extensions.copyleaks.com/mcp"
}
}
}
```
**A `url` with no `type` is silently skipped**
A JSON entry with a `url` and no `type` is read as a local command and skipped, with the message `MCP server "copyleaks_app" has a "url" but no "type"`. Config blocks written for other clients routinely omit it. **Always add `"type": "http"`.**
### The Claude Chat and Cowork tabs, and claude.ai
The Chat and Cowork tabs of Claude Desktop, and claude.ai, reach remote MCP servers as **custom connectors**. There is no `claude_desktop_config.json` entry for this - that file handles locally installed servers only.
1. Open **Customize → Connectors**.
2. Press **+**, then **Add custom connector**.
3. Paste `https://extensions.copyleaks.com/mcp` and leave **Advanced settings** untouched - the server registers the client for you.
4. Press **Add**, then **Connect**, and approve the permissions the sign-in page requests.
Connectors follow your Claude account, so one added on the web also appears in the desktop app's Chat and Cowork tabs.
**Team and Enterprise workspaces** - an Owner adds the connector once under **Organization settings → Connectors**. Every member then connects it from their own **Customize → Connectors** and signs in as themselves. The organization-level entry publishes the server; it does not share a session or a Copyleaks account.
#### Cowork
1. Open the **Cowork** tab and **choose a folder** - Cowork reads and writes only inside folders you share.
2. Describe the job in one message: *"Scan every `.docx` in this folder that changed since yesterday with my Client Reports profile, and write a summary to `originality-check.md`."*
3. To repeat it, save it as a **scheduled task**. A task that needs a folder on your computer runs on your computer, so the desktop app has to be open when it fires; a task that only reads past scans can run in the cloud with the app closed.
### Gemini CLI
```bash
gemini mcp add --transport http --scope user copyleaks_app https://extensions.copyleaks.com/mcp
```
Or write it into `~/.gemini/settings.json` (user scope) or `.gemini/settings.json` (project scope), which also lets you name the permissions you want and set a timeout:
```json
{
"mcpServers": {
"copyleaks_app": {
"httpUrl": "https://extensions.copyleaks.com/mcp",
"oauth": {
"enabled": true,
"scopes": ["scans:read", "scans:run", "profiles:read", "profiles:write", "account:read", "offline_access"]
},
"timeout": 30000
}
}
}
```
**`httpUrl`, not `url`**
In Gemini CLI, `url` means SSE and `httpUrl` means Streamable HTTP. Using `url` here makes the client open an SSE connection the server does not serve, and the failure looks like a network problem rather than a config mistake.
Verify with `/mcp`. `--trust` skips tool confirmations for writes too - use it only with read-only permissions.
### Antigravity
Antigravity keeps MCP configuration in `mcp_config.json` - globally at `~/.gemini/config/mcp_config.json`, or per-project at `.agents/mcp_config.json`. Connect Copyleaks through the `mcp-remote` bridge ([Anything else](#anything-else)), which needs Node.js installed:
```json
{
"mcpServers": {
"copyleaks_app": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://extensions.copyleaks.com/mcp",
"--static-oauth-client-info",
"{\"client_id\": \"mcp-copyleaks.com\"}"
]
}
}
}
```
Copy the block as it is, including the last two lines - they tell the bridge which Copyleaks sign-in client to use.
### Codex CLI
Codex reads MCP servers from `~/.codex/config.toml`. The table key becomes the server name, so use underscores rather than hyphens.
```toml
[mcp_servers.copyleaks_app]
url = "https://extensions.copyleaks.com/mcp"
auth = "oauth"
scopes = ["scans:read", "scans:run", "profiles:read", "profiles:write", "account:read", "offline_access"]
startup_timeout_sec = 30
tool_timeout_sec = 120
```
Then complete the sign-in once:
```bash
codex mcp login copyleaks_app
```
Codex accepts the smallest tool replies of any client listed here. On a document with very many matched sources, ask for a narrower view - one match type, one source type, or a minimum matched-word count - rather than everything at once.
### Cursor and VS Code
Cursor infers the transport from the URL, so a remote server needs nothing but the address:
```json
{
"mcpServers": {
"copyleaks_app": {
"url": "https://extensions.copyleaks.com/mcp"
}
}
}
```
Global config lives at `~/.cursor/mcp.json`, per-project at `.cursor/mcp.json`.
**VS Code with GitHub Copilot** follows the same shape in `.vscode/mcp.json`, under a `servers` key rather than `mcpServers`. Add the server through **MCP: Add Server → HTTP** and let the editor write the file, which avoids guessing the current schema.
### Anything else
Plenty of MCP clients still speak only stdio. Bridge them with `mcp-remote`, which runs locally, handles the OAuth sign-in in your browser, and proxies the session to the remote endpoint. Any client that can launch a command can use it.
```json
{
"mcpServers": {
"copyleaks_app": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://extensions.copyleaks.com/mcp"]
}
}
}
```
Treat the bridge as a compatibility shim, not a default. It caches its own sign-in under `~/.mcp-auth`.
---
# Using it
## Tools
Source: https://docs.copyleaks.com/mcp/tools
> The twelve Copyleaks tools an agent can call, and the parameters each one takes.
Twelve tools, grouped by the job they do.
### Scanning
#### `copyleaks_scan` - Run a Copyleaks scan
*Write · spends credits*
Runs a scan and returns a handle to check on. Accepts pasted text, a web address, files, or an uploaded image.
| Parameter | What it takes |
|---|---|
| `scan.text` | Text to scan, pasted directly. Capped at **25,000 characters** - send longer content as a file, which has no character ceiling |
| `scan.urls` | Web addresses, **up to ten per call**. Copyleaks fetches each one without your sign-ins |
| `scan.files` | Files to scan, each with its name and extension - `thesis.pdf`. **Up to ten per call**; send the rest as a second call |
| `scan.files[].size` | **Required when sending file content:** size in bytes before encoding. Checked against what arrived; a mismatch is refused rather than scanned |
| `scan.imageUpload` | The handle for an uploaded image, from `copyleaks_request_upload`. **The only way to scan an image** |
| `scan.imageName` | The image's file name including its extension, so the format is known |
| `scan.name` | What to call this scan in your Copyleaks account |
| `scan.profile` | The scan profile to use. Omit for your default |
**You don't choose the detectors per scan - the scan profile does.** Which detectors run comes from the profile named in `scan.profile`, or your account default when you omit it. Read a profile with `copyleaks_get_profiles` to see what it will run, or change it with `copyleaks_update_profile`.
`detections` in the results lists what actually ran - `AI Detection` skips text under 350 characters.
Returns immediately with a scan that is still running. Follow with `copyleaks_scan_status`, then `copyleaks_get_results`.
#### `copyleaks_rescan` - Re-run an existing scan
*Write · spends credits*
Runs an existing scan again against current sources, so a document can be re-checked as the web changes. Creates a new scan; the original and its results are unchanged.
#### `copyleaks_request_upload` - Get a place to send a file
*Write · costs no credits*
Returns an address to send one file to, and a handle that names that file in a later scan. Use it for anything past a small file, rather than sending bytes inside `copyleaks_scan`.
| Parameter | What it takes |
|---|---|
| `fileName` | The file's name including its extension. The extension decides which formats are accepted |
| `size` | The file's size in bytes, checked against the upload limit before anything is sent |
Send the file to the address, then start the scan with the handle. **The address works once** and also expires after a set time; the handle starts one scan. If either has been spent, ask for another. A failed upload does not spend the address.
### Reading results
#### `copyleaks_scan_status` - Check scan status
*Read-only*
Returns whether a scan is `running`, `complete`, or `failed`. While running, may include how far along it is as a percentage.
| Parameter | What it takes |
|---|---|
| `scan` | The scan to check |
| `waitSeconds` | Hold the call until the scan finishes, up to this many seconds (1–120). Omit to answer immediately |
No time estimate, and no notification when a scan finishes - check here, and wait between checks. **Prefer `waitSeconds`:** one call holds until the scan finishes or the wait runs out, counts as one read, and returns the current state either way - a timeout is an answer, not an error.
#### `copyleaks_get_results` - Get scan results
*Read-only*
Returns a completed scan's scores, counts, sources, and matched text.
| Parameter | What it takes |
|---|---|
| `scan` | The scan to read |
| `detail` | `scores`, `summary` (default), `detail`, or `full` |
| `matchTypes` | `Exact match`, `Minor changes`, `Paraphrased` |
| `sourceTypes` | `Web`, `Shared data hub`, `This Batch`, `Private cloud hub` |
| `source` | One matched source, by its title |
| `minMatchedWords` | Sources with at least this many matched words |
| `publishedAfter` / `publishedBefore` | ISO 8601 dates. Sources with no known publish date are excluded - and most have none |
| `minPhraseFrequency` | AI phrases at or above this frequency. `0` returns all of them |
| `page` | The `nextPage` value from a previous response |
| `pageBytes` | How many bytes one page may carry, measured as UTF-8 |
#### `copyleaks_get_flagged_segments` - List flagged segments in document order
*Read-only*
Returns every flagged part of a document **in the order it appears**, rather than grouped under the sources they matched. Use this to go through a document start to finish; use `copyleaks_get_results` to ask about a particular source.
Each segment carries its exact text, its type (`Exact match`, `Minor changes`, `Paraphrased`, **AI content**, or **AI phrases**), and - for a match - which source it overlaps and what that source says.
| Parameter | What it takes |
|---|---|
| `scan` | The scan to walk through |
| `page` | The `nextPage` value from a previous response. Omit for the first page |
| `pageBytes` | As above - UTF-8 bytes, 9,000 default, 500,000 max, always at least one segment per page |
### Past scans
#### `copyleaks_search_scans` - Search past scans
*Read-only*
Searches the scans you own. Use it to find a scan you are describing rather than naming - *"the one from June that scored over 30%."*
| Parameter | What it takes |
|---|---|
| `search` | Words from the scan's name. Omit to list your most recent scans |
| `sort` | How to order results: `newest` (default), `oldest`, `name`, `name reversed`, `highest plagiarism score`, `lowest plagiarism score`, `highest AI score`, `lowest AI score`, `type`, `type reversed` |
| `limit` | How many to return. 20 by default, 50 at most |
| `offset` | Which page, as an offset |
Search matches scan names only - no filter by date, status, score, type or folder. For a threshold, sort by score and page until it drops below; for dates or folders, page through and narrow yourself.
Each row carries the scan's `scanType` - `Text`, `File`, `Web page` or `Image` - and its `detections`, so you can narrow what comes back once you have it.
#### `copyleaks_get_scan` - Get one scan
*Read-only*
Returns one scan's title, date, type, score, and status. Use `copyleaks_get_results` for what it found.
### Scan profiles
#### `copyleaks_get_profiles` - Get scan profiles
*Read-only*
Returns your scan profiles and their settings. A scan profile is a saved set of scan settings you reuse by name - the same profiles you see in Copyleaks Scan Settings.
#### `copyleaks_create_profile` - Create a scan profile
*Write*
Creates a new profile from settings described in plain language, and returns what was saved. Setting names are the app's own:
| Group | Settings |
|---|---|
| `AI Detection` | `Sensitivity level`: `Cautious` · `Balanced` (default) · `Broad` |
| `Search sources` | `Web search` (`Entire web` / `Specific sites only` / `Exclude specific sites`) · `Shared data hub` · `Private cloud hub` · `Cross-check documents` |
| `Match settings` | `Match scope`: `Exact match` (always on) · `Minor changes` · `Paraphrased`. `Scan mode`: `Originality check` with `Performance mode` (`Quick scan` / `Standard` / `Comprehensive`), or `Copyright check` |
| `Cross-language search` | Each added language runs as a separate scan and multiplies the credit cost |
| `Security & Integrity` | `Safe Search` · `Mask Personal Data` · `Cheat Detection` |
| `Exclusions` | References & bibliography · Direct quotes · Citations · Table of Contents · Section headings · Page header and footer · Code comments |
If a setting is not included on your account, it is left out, the rest of the profile is saved, and you are told which setting and whether it is an add-on or part of a plan.
Creating a profile never changes which profile is your account default.
#### `copyleaks_update_profile` - Update a scan profile
*Write*
Changes named settings on an existing profile. Settings you do not name are left as they are. Returns the full profile as saved.
### Account
#### `copyleaks_get_account` - Get plan and credit balance
*Read-only*
Returns your credit balance, your plan, and which settings this account does not include - each marked as an add-on or as part of a plan.
**This is the only place credits appear.**
---
## How scanning works
Source: https://docs.copyleaks.com/mcp/scanning
> What an agent can send to Copyleaks, how it gets there, and what a scan costs.
### Three scan types
| Scan | Input | Answers |
|---|---|---|
| **`AI Detection`** | text | Which parts of this text were AI-written? |
| **`Plagiarism Detection`** | text | Which parts match something else, and what? |
| **AI image detection** | an image | Was this image AI-generated? |
**A scan is either text or image, never both.** The two text scans can run together on the same text; an image scan runs alone.
`Cheat Detection` and the `AI Source Match` tag are part of the plagiarism scan, not separate scans - see [Results](/mcp/results).
### OCR - PDFs, scans and photos
Both text scans accept files that are not plain text - a PDF, a scanned page, a photograph of a document. Copyleaks extracts the text and scans that. **That is still a text scan.**
| You want to know | Scan type |
|---|---|
| Is the writing in this PDF plagiarized? | **text** - extracted first |
| Is the text in this screenshot AI-written? | **text** - extracted first |
| Was this photo generated by AI? | **image** |
### The 350-character AI minimum
`AI Detection` needs at least **350 characters**. Below that it does not run at all and no AI score comes back - the scan still runs for plagiarism, which has no minimum.
**A blank AI score means *not measured*, never *nothing found*.** Your agent reports which checks actually ran.
### Long text goes as a file
Pasted text is capped at **25,000 characters**. A file has no character ceiling, so if a paste is refused for length, send the same content as a file instead.
### Getting a document to Copyleaks
An agent cannot pass a file from one connector to another. A Drive or Dropbox connection gives *your agent* the file; it does not give Copyleaks the file.
| Path | For | How |
|---|---|---|
| **Inline** | Small files | The file travels inside the scan request |
| **Upload** | Everything larger | Ask for an upload slot, send the file to it, then scan the handle |
**The maximum size depends on the file type.** When your agent asks for an upload address, the answer carries the exact limit for that file.
There's no fixed size between the two: it depends on how much room your agent has left in the conversation, and your agent chooses. Anything past a small file should use the upload slot, which keeps it out of the conversation.
The upload step needs a client that can run a command on your machine - [what works where](/mcp/overview#what-you-need-and-what-works-where). Without one, upload larger files in the Copyleaks app and ask your agent to read the scan.
### Images
**Copyleaks scans the image you actually have, byte for byte.** Any alteration - resizing, cropping, converting, re-saving - changes the answer. Your agent will not modify an image to make it fit; if it cannot send the original, it says so.
**An image always goes through the upload step, never inline**, so it needs a client that can run commands.
| Bound | | Checked |
|---|---|---|
| Maximum size | 33,554,432 bytes | at the upload slot, before the image is sent |
| Formats | PNG · JPEG/JPG · BMP | at the upload slot, before the image is sent |
| Minimum dimensions | 512 × 512 pixels | after the image is sent |
| Maximum | 27 megapixels | after the image is sent |
For any other format, **upload the image in Copyleaks and ask your agent to read the finished scan.**
An image refused on any of these bounds spends no credit. Size and format are refused before sending; an image outside the pixel bounds comes back as a failed scan with the reason.
An image scan returns a score and confirmation the picture was checked - nothing pixel-level. Open the report for anything visual.
### Web addresses
Scanning a web address means Copyleaks fetches it, without your sign-ins. So **Google Docs and Drive, SharePoint and OneDrive, Notion and Dropbox return a sign-in page, not your document.**
Copyleaks cannot tell the difference, so it scans that sign-in page and spends credits on it. Send the document as a file instead.
**To scan something in Drive, SharePoint or Notion,** save it to your computer and send the file.
A client that can run commands can save and upload it for you. In the Claude chat, attach the file yourself or upload it in the Copyleaks app.
### Several files at once
Up to **ten files** in one call, each its own scan, spending credits separately. Ten is a deliberate guard so one mistaken instruction cannot spend a large share of your balance - send the rest as a second call.
---
## How results work
Source: https://docs.copyleaks.com/mcp/results
> Scores, summaries, matched sources and matched text - reached deliberately, never dumped.
Results are **raw** - scores, counts, sources, and matched text. Your agent interprets, aggregates, and explains.
### The four levels
| Level | Returns |
|---|---|
| **`scores`** | The `Plagiarism score`, the `AI score`, and word counts. Nothing else |
| **`summary`** *(default)* | The scores, the word counts, and **how many sources matched** - not the sources themselves |
| **`detail`** | **The matched sources**, paged and filterable |
| **`full`** | Every match with its exact text on both sides, paged |
The default is narrow because a widely copied document can match hundreds of sources. Ask for `detail` to see which ones.
Scores are percentages, **0–100 to one decimal place** - `98.5`.
### Results, never the document
**Results are the flagged parts - matches, AI content, AI phrases and `Excluded text` - never the document itself**, which stays in Copyleaks. Nothing found is held back; every completed scan links to its report, `Open this scan in Copyleaks`.
### Match types
Strongest first. The same labels your report and scan settings use.
| Type | Means |
|---|---|
| `Exact match` | Text copied word for word |
| `Minor changes` | Small edits to vocabulary, grammar, or verb tense |
| `Paraphrased` | Restructured sentences and rewritten ideas - same meaning, different words |
### Where matches come from
| Source | Means |
|---|---|
| `Web` | The open internet |
| `Shared data hub` | Documents submitted by the Copyleaks community |
| `Private cloud hub` | Your own private library |
| `This Batch` | Your other files scanned in the same submission |
`This Batch` matches appear only when `Cross-check documents` is on, and count toward the score like any other match. If `This Batch` carries the whole score, check whether the same document was sent twice.
Any source may also carry the **`AI Source Match`** tag, meaning that source is itself AI-generated. It is a tag on a source, never a source type.
### AI results - two layers
**AI content** - passages identified as AI-written. **AI phrases** - specific phrases within that content. Phrases are always inside AI content, never a separate category.
Each AI phrase carries a **frequency**: how many times more often that phrase appears in AI writing than in human writing. A phrase at `220x` turns up 220 times more often in AI text. **Higher means more distinctive of AI writing - it does not mean the passage is more likely to be AI.**
### `Cheat Detection`
Where a plagiarism scan found them, hidden characters, white ink and text manipulation come back as flagged spans with their exact text and position - in `copyleaks_get_results` and in document order from `copyleaks_get_flagged_segments`.
### `Excluded text` is not `Excluded sources`
- **`Excluded text`** - content your profile's `Exclusions` left out of the score: references, quotes, citations, table of contents, headings, headers and footers, code comments.
- **`Excluded sources`** - sources *you* removed from the score afterwards.
---
## Limits and access
Source: https://docs.copyleaks.com/mcp/limits
> Credits, throughput, who can connect, what the connector can't do, and how to disconnect.
### Credits
Scans through an agent spend **the same credits** as scans in the app, on the same meter. When credits run out, scanning stops and your agent tells you; reading past scans keeps working.
A scan's cost is not quoted before or after. Your balance and plan are readable; the usage meter is the record.
### Throughput
Scans start at up to **10 per minute**, the same on every paid plan. **Each file and each web address counts as one scan**, so a ten-file call is ten scans against the minute.
Going over doesn't fail anything - the rest waits and your agent continues on its own. Scans run at the same time, not one after another.
Other requests can be rate-limited too; the refusal says how long to wait, and your agent waits.
### Access
**Paid app access is the gate.** Subscription, prepaid, or organization-paid all reach it. **No access on Free or lapsed accounts**, not even read-only. If your plan ends, the connector stops working with your other paid features; your scans and reports stay in your account, and reactivating restores access.
**One person, one connection.** A team is several individual connections, never a shared one - no admin view of a colleague's scans, no cross-member visibility, no team-level profiles.
**Each client you connect is its own connection**, with its own approval. Adding a second does not affect the first, and removing one leaves the others working.
Anything shared *with* you stays in Copyleaks. Your own scans only.
### Retention
A scan past its retention window can no longer be read, and the connector reports it as unavailable. **The window belongs to the scan itself, not to your current plan.**
### Where your content goes
Results you ask for are sent to your client and processed by the company that provides it - Anthropic, OpenAI, Google, or whoever makes the client you connected.
Scan settings apply exactly as in the app. To keep emails, phone numbers and card numbers out of your results, turn on `Mask Personal Data` in your scan profile.
### What the connector cannot do
| | |
|---|---|
| Buy credits or change your plan | Billing stays in Copyleaks |
| Delete anything | No scans, results, or profiles |
| Return the document you scanned | Results are the flagged parts. The report is where the document lives |
| Download a report | Report downloads stay in the app |
| Create share links | Publishing stays a deliberate act in the app |
| Open a scan shared with you | Your own scans only |
| Compare two documents against each other | Scan them together with `Cross-check documents` on; matches come back as `This Batch` |
| Run scheduled or recurring scans | The connector has no scheduler. Your agent may have one; each scheduled run spends credits per scan |
| Scan a folder as a unit | Send files, up to ten per call. An agent that can see your folder can list them for you |
### Disconnecting
Remove the connection **in your client**, where you added it. Access ends immediately; nothing is deleted.
**There is no connected-clients list in Copyleaks** - the connection lives on the client's side, so that is where it has to be removed. If you have lost access to the client itself, contact Copyleaks support.
| Client | How |
|---|---|
| **Claude Code** | `claude mcp logout copyleaks_app` then `claude mcp remove copyleaks_app` |
| **Claude Desktop (Chat · Cowork) / claude.ai** | **Customize → Connectors**, find Copyleaks, remove it. The Code tab is Claude Code - use the row above |
| **Codex CLI** | `codex mcp remove copyleaks_app`, or delete the `[mcp_servers.copyleaks_app]` block |
| **Gemini CLI · Cursor · VS Code** | Delete the `copyleaks_app` entry from the config file, then restart |
| **`mcp-remote` bridge** - Antigravity included | Delete the entry, **then remove the cached token from `~/.mcp-auth`** - the bridge stores its own, and deleting the config alone leaves it live |
---
# Help
## Troubleshooting
Source: https://docs.copyleaks.com/mcp/troubleshooting
> Symptoms, causes and fixes for a connection that will not behave.
### Check the endpoint first
Before blaming a client, check the endpoint from the same machine. This request is unauthenticated on purpose:
```bash
curl -sS -D - -o /dev/null \
-X POST https://extensions.copyleaks.com/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"2025-06-18","capabilities":{},
"clientInfo":{"name":"probe","version":"1"}}}'
```
A healthy server answers:
```
HTTP/2 401
www-authenticate: Bearer resource_metadata=
"https://extensions.copyleaks.com/.well-known/oauth-protected-resource/mcp"
```
**That 401 is the success case.** It proves the endpoint is reachable, terminating TLS correctly, and advertising its authorization server. A timeout, a 50x, or an HTML error page means the problem is your network, not your config.
Follow the chain one step further to see the permissions on offer:
```bash
curl -sS https://extensions.copyleaks.com/.well-known/oauth-protected-resource/mcp | jq .
```
Once connected, ask your agent to check your Copyleaks credit balance. If it answers, you are done.
### Symptoms and fixes
| Symptom | Why | Fix |
|---|---|---|
| **Added the connector, but no Copyleaks tools appear** | Clients read their server list when a session starts | Start a new session. On Claude Desktop, quit the app completely and reopen it - closing the window isn't enough. Still missing? You haven't signed in: `claude mcp login copyleaks_app`, or `/mcp` in a session |
| **Sign-in succeeds, but every call is unauthorized** | The stored token was issued by a different Copyleaks authorization server than the one this endpoint trusts | Remove the stored credential and sign in again. If your Copyleaks account is not served from `extensions.copyleaks.com`, contact Copyleaks support for the address that serves it |
| **`MCP server "…" has a "url" but no "type"`** | Claude Code reads a typeless entry as a local command and skips it | Add `"type": "http"`. `"streamable-http"` is accepted as an alias |
| **Needs authentication, repeatedly** | The stored token expired and was issued without `offline_access`, so there is no refresh token | Add `offline_access`, then sign in again. If it recurs within the hour, check the machine clock |
| **"Your connection expired"** | The connection to your Copyleaks account has expired | Reconnect Copyleaks in your agent's settings |
| **Connects, but exposes no tools** | Sign-in succeeded on a narrower permission set than the tools require | Remove any `scopes` / `includeTools` / `enabled_tools` narrowing, sign in again, then reintroduce limits once you know which tools you need. **On Gemini CLI and Antigravity, also check how many connectors you have enabled** - they cap the total tools loaded across all servers, and Copyleaks adds twelve |
| **The server is not listed at all** | The config landed in the wrong file or scope | Let the client write the file - `claude mcp add`, `gemini mcp add`, `codex mcp add`, or the editor's Add Server command. Read it back with `claude mcp get` or `/mcp` |
| **Added on claude.ai, but Claude Desktop doesn't have it** | The app didn't fully quit, or it's signed in to a different Claude account | Quit Claude Desktop completely and reopen it, and check it's the same Claude account. The **Code tab** is Claude Code - a connector from **Customize → Connectors** doesn't appear there; add it with `claude mcp add` |
| **Tools appear, but every call is refused** | No active paid plan | Reactivate in your Copyleaks account. Access ends with the plan |
| **Scans are refused but reading works** | No credits left | Add credits. Reading existing results is unaffected |
| **Works in the Chat tab, but "can't scan this file"** | The Chat tab has no upload step, so it can't send larger files | Switch to the **Code tab** of the same app, or upload the file in Copyleaks and ask your agent to read the scan |
| **`unable to verify the first certificate` · `SELF_SIGNED_CERT_IN_CHAIN`** | Your network inspects TLS and re-signs with a certificate authority your client's trust store does not know | Point the client at your organization's root certificate. Node-based clients (Claude Code, Gemini CLI, Antigravity, `mcp-remote`) read `NODE_EXTRA_CA_CERTS`; Python-based ones read `REQUESTS_CA_BUNDLE` or `SSL_CERT_FILE` |
| **`Client registration failed` · `invalid_client`** | The client tried to register itself with the authorization server and was refused | Confirm the client is on a current version, and that nothing on your network blocks the sign-in redirect. If it persists, contact Copyleaks support with the client name and version |
| **Connection error after signing in (CLI)** | The local redirect failed | Paste the full callback URL from the browser's address bar back at the prompt |
| **Works in one project, not another** | Scope | Re-add with `--scope user` |
| **A scan comes back `failed`** | The scan did not complete | Run it again. A failed scan spends nothing |
| **The browser never opened** | No usable browser on this machine | Open the printed URL yourself, or sign in with `--no-browser` and paste the redirect URL back at the prompt |
---