# Tools

> The twelve Copyleaks tools an agent can call, and the parameters each one takes.

Twelve tools, grouped by the job they do.

### Scanning

#### `copyleaks_scan` - Run a Copyleaks scan
*Write · spends credits*

Runs a scan and returns a handle to check on. Accepts pasted text, a web address, files, or an uploaded image.

| Parameter | What it takes |
|---|---|
| `scan.text` | Text to scan, pasted directly. Capped at **25,000 characters** - send longer content as a file, which has no character ceiling |
| `scan.urls` | Web addresses, **up to ten per call**. Copyleaks fetches each one without your sign-ins |
| `scan.files` | Files to scan, each with its name and extension - `thesis.pdf`. **Up to ten per call**; send the rest as a second call |
| `scan.files[].size` | **Required when sending file content:** size in bytes before encoding. Checked against what arrived; a mismatch is refused rather than scanned |
| `scan.imageUpload` | The handle for an uploaded image, from `copyleaks_request_upload`. **The only way to scan an image** |
| `scan.imageName` | The image's file name including its extension, so the format is known |
| `scan.name` | What to call this scan in your Copyleaks account |
| `scan.profile` | The scan profile to use. Omit for your default |

**You don't choose the detectors per scan - the scan profile does.** Which detectors run comes from the profile named in `scan.profile`, or your account default when you omit it. Read a profile with `copyleaks_get_profiles` to see what it will run, or change it with `copyleaks_update_profile`.

`detections` in the results lists what actually ran - `AI Detection` skips text under 350 characters.

Returns immediately with a scan that is still running. Follow with `copyleaks_scan_status`, then `copyleaks_get_results`.

#### `copyleaks_rescan` - Re-run an existing scan
*Write · spends credits*

Runs an existing scan again against current sources, so a document can be re-checked as the web changes. Creates a new scan; the original and its results are unchanged.

#### `copyleaks_request_upload` - Get a place to send a file
*Write · costs no credits*

Returns an address to send one file to, and a handle that names that file in a later scan. Use it for anything past a small file, rather than sending bytes inside `copyleaks_scan`.

| Parameter | What it takes |
|---|---|
| `fileName` | The file's name including its extension. The extension decides which formats are accepted |
| `size` | The file's size in bytes, checked against the upload limit before anything is sent |

Send the file to the address, then start the scan with the handle. **The address works once** and also expires after a set time; the handle starts one scan. If either has been spent, ask for another. A failed upload does not spend the address.

### Reading results

#### `copyleaks_scan_status` - Check scan status
*Read-only*

Returns whether a scan is `running`, `complete`, or `failed`. While running, may include how far along it is as a percentage.

| Parameter | What it takes |
|---|---|
| `scan` | The scan to check |
| `waitSeconds` | Hold the call until the scan finishes, up to this many seconds (1–120). Omit to answer immediately |

No time estimate, and no notification when a scan finishes - check here, and wait between checks. **Prefer `waitSeconds`:** one call holds until the scan finishes or the wait runs out, counts as one read, and returns the current state either way - a timeout is an answer, not an error.

#### `copyleaks_get_results` - Get scan results
*Read-only*

Returns a completed scan's scores, counts, sources, and matched text.

| Parameter | What it takes |
|---|---|
| `scan` | The scan to read |
| `detail` | `scores`, `summary` (default), `detail`, or `full` |
| `matchTypes` | `Exact match`, `Minor changes`, `Paraphrased` |
| `sourceTypes` | `Web`, `Shared data hub`, `This Batch`, `Private cloud hub` |
| `source` | One matched source, by its title |
| `minMatchedWords` | Sources with at least this many matched words |
| `publishedAfter` / `publishedBefore` | ISO 8601 dates. Sources with no known publish date are excluded - and most have none |
| `minPhraseFrequency` | AI phrases at or above this frequency. `0` returns all of them |
| `page` | The `nextPage` value from a previous response |
| `pageBytes` | How many bytes one page may carry, measured as UTF-8 |

#### `copyleaks_get_flagged_segments` - List flagged segments in document order
*Read-only*

Returns every flagged part of a document **in the order it appears**, rather than grouped under the sources they matched. Use this to go through a document start to finish; use `copyleaks_get_results` to ask about a particular source.

Each segment carries its exact text, its type (`Exact match`, `Minor changes`, `Paraphrased`, **AI content**, or **AI phrases**), and - for a match - which source it overlaps and what that source says.

| Parameter | What it takes |
|---|---|
| `scan` | The scan to walk through |
| `page` | The `nextPage` value from a previous response. Omit for the first page |
| `pageBytes` | As above - UTF-8 bytes, 9,000 default, 500,000 max, always at least one segment per page |

### Past scans

#### `copyleaks_search_scans` - Search past scans
*Read-only*

Searches the scans you own. Use it to find a scan you are describing rather than naming - *"the one from June that scored over 30%."*

| Parameter | What it takes |
|---|---|
| `search` | Words from the scan's name. Omit to list your most recent scans |
| `sort` | How to order results: `newest` (default), `oldest`, `name`, `name reversed`, `highest plagiarism score`, `lowest plagiarism score`, `highest AI score`, `lowest AI score`, `type`, `type reversed` |
| `limit` | How many to return. 20 by default, 50 at most |
| `offset` | Which page, as an offset |

Search matches scan names only - no filter by date, status, score, type or folder. For a threshold, sort by score and page until it drops below; for dates or folders, page through and narrow yourself.

Each row carries the scan's `scanType` - `Text`, `File`, `Web page` or `Image` - and its `detections`, so you can narrow what comes back once you have it.

#### `copyleaks_get_scan` - Get one scan
*Read-only*

Returns one scan's title, date, type, score, and status. Use `copyleaks_get_results` for what it found.

### Scan profiles

#### `copyleaks_get_profiles` - Get scan profiles
*Read-only*

Returns your scan profiles and their settings. A scan profile is a saved set of scan settings you reuse by name - the same profiles you see in Copyleaks Scan Settings.

#### `copyleaks_create_profile` - Create a scan profile
*Write*

Creates a new profile from settings described in plain language, and returns what was saved. Setting names are the app's own:

| Group | Settings |
|---|---|
| `AI Detection` | `Sensitivity level`: `Cautious` · `Balanced` (default) · `Broad` |
| `Search sources` | `Web search` (`Entire web` / `Specific sites only` / `Exclude specific sites`) · `Shared data hub` · `Private cloud hub` · `Cross-check documents` |
| `Match settings` | `Match scope`: `Exact match` (always on) · `Minor changes` · `Paraphrased`. `Scan mode`: `Originality check` with `Performance mode` (`Quick scan` / `Standard` / `Comprehensive`), or `Copyright check` |
| `Cross-language search` | Each added language runs as a separate scan and multiplies the credit cost |
| `Security & Integrity` | `Safe Search` · `Mask Personal Data` · `Cheat Detection` |
| `Exclusions` | References & bibliography · Direct quotes · Citations · Table of Contents · Section headings · Page header and footer · Code comments |

If a setting is not included on your account, it is left out, the rest of the profile is saved, and you are told which setting and whether it is an add-on or part of a plan.

Creating a profile never changes which profile is your account default.

#### `copyleaks_update_profile` - Update a scan profile
*Write*

Changes named settings on an existing profile. Settings you do not name are left as they are. Returns the full profile as saved.

### Account

#### `copyleaks_get_account` - Get plan and credit balance
*Read-only*

Returns your credit balance, your plan, and which settings this account does not include - each marked as an add-on or as part of a plan.

**This is the only place credits appear.**