`
#### 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
## Working with AI Agents
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.
***
## July 12, 2026 New
**References Validation**
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 [References Validation concept](/concepts/features/references-validation), the [Validate References guide](/guides/authenticity/validate-references), or the [response schema](/reference/data-types/authenticity/results/crawled-version#references-validation).
---
## 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.
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 → 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).
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'
```
```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');
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"
}
},
"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.
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"`
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
}
```
**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 overlay to return alongside the detection result. Use this when you want a pixel-level visualization of which regions of the image were flagged as AI-generated.
Supported values:
- `"heatmap"` - gradient overlay highlighting AI-generated regions with intensity proportional to confidence.
Example: `"heatmap"`
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.
---
# 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, RAW, 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 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
},
"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 → 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` |
## 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.
---
## 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.
---
# 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 → 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`
---
# 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-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 references validation 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-references-validation.mdx';
import ResultsReferencesValidation from '/snippets/results-references-validation.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
]
}
}
}
```
## References Validation
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 reference validation 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#references-validation).
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.
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.
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.
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"
}
},
"scannedDocument": {
"scanId": "my-scan-id-1",
"credits": 1,
"expectedCredits": 1,
"creationTime": "2023-01-10T10:07:58.9459512Z"
}
}
```
## 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.
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
},
"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 → 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.
---
# 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.
---