canonical: https://jentic.com/apis/gptzero.com/gptzero

# GPTZero API

GPTZero is an AI-text detection service used widely in education and publishing to score whether a passage was written by a human or generated by a large language model. The v2 API exposes seven endpoints across single-text scoring, document file analysis, batch submission, and report retrieval, returning per-document and per-sentence probability scores plus optional perplexity and burstiness metrics. It is designed for teachers, editors, and platform integrity teams who need a programmatic signal on AI-generated content.

## For AI agents

Score text or uploaded documents for AI-generation likelihood with per-sentence breakdowns. Supports single-document, batch, and report retrieval flows.

## Scope

Does not generate text, run plagiarism scans, or detect AI-generated images - use for AI-text detection scoring only.

## Capabilities

- Score a passage of text for AI authorship via POST `/predict/text`
- Analyse uploaded documents (PDF, DOCX, TXT) through POST `/predict/files`
- Submit a batch of documents for asynchronous scoring via POST /batch
- Poll batch status and retrieve per-document scores from GET `/batch/{batchId}`
- Pull historical detection reports with GET /reports and GET `/reports/{reportId}`

## Use cases

### School-Wide Submission Screening

Schools submitting student work into a GPTZero workflow use POST /batch to send a class-worth of essays in one request, then poll GET `/batch/{batchId}` until results are ready. The per-sentence scoring helps teachers see exactly which passages triggered the model. Detection is probabilistic - schools should treat the score as a triage signal and pair it with a conversation with the student.

Example prompt: POST /batch with 30 essay bodies, poll GET `/batch/{batchId}` every 10 seconds until status=complete, then surface essays with score above 0.7.

### Editorial Content Authenticity Check

Publishers screen freelance submissions through POST `/predict/text` or `/predict/files` to flag pieces that may be AI-generated for additional review. The endpoint returns overall and per-sentence probabilities plus perplexity metrics, giving editors a defensible signal before contracting with a writer. The API does not authenticate authorship - it scores statistical likelihood only.

Example prompt: POST `/predict/text` with a 1500-word draft and route the submission to a senior editor when document_classification is 'AI-generated'.

### Document File Analysis

POST `/predict/files` accepts PDF, DOCX, and TXT uploads, extracting the text server-side and returning the same scoring shape as `/predict/text.` This avoids the agent having to parse mixed file formats locally and keeps OCR and extraction logic on GPTZero's side. Maximum file size is bounded by the user's plan tier.

Example prompt: POST `/predict/files` with a multipart upload of a PDF and return the per-paragraph AI-generation probabilities.

### Account-Level Report Auditing

Compliance and academic-integrity teams pull historical detections via GET /reports for retention or audit purposes. GET `/reports/{reportId}` returns the full prior verdict including the input text snapshot, score, and timestamp, supporting policies that require evidence to be preserved alongside the decision.

Example prompt: Call GET /reports?limit=50, filter to the past 7 days, and produce a summary of how many submissions exceeded the 0.7 threshold.

### Agent Detection via Jentic

An agent moderating user-generated content uses Jentic to discover GPTZero, load `/predict/text`, and execute with the user's submission. The X-API-Key is held in Jentic's Jentic One instance, so the agent never sees the raw secret. The agent reasons over the returned probability and decides whether to escalate.

Example prompt: Use the Jentic SDK to search 'detect ai-generated text', load POST `/predict/text`, and execute with the user-submitted body.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/predict/text` | Synchronously score a text passage for AI authorship |
| POST | `/predict/files` | Score an uploaded PDF, DOCX, or TXT document |
| POST | `/batch` | Submit a batch of documents for asynchronous scoring |
| GET | `/batch/{batchId}` | Poll batch status |
| GET | `/batch/{batchId}/results` | Retrieve per-document batch results |
| GET | `/reports` | List historical detection reports |
| GET | `/reports/{reportId}` | Retrieve a specific historical report |

## Key resources

- **Predict Text** — Synchronous scoring for a single text passage
- **Predict Files** — Synchronous scoring for uploaded document files
- **Batch** — Asynchronous batch submission and polling
- **Reports** — Historical detection reports for the account

## Why Jentic

- **Setup:** Wiring the GPTZero API by hand means setting the X-API-Key header and routing each request to the right endpoint for synchronous text, file uploads, or batch jobs and their result polling yourself. Through Jentic you install once, import GPTZero from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** GPTZero takes the text to score in the request body, and while a batch id appears in read paths (`/batch/{batchId}`), the detection operations are body-driven, so limit the agent to the operations it needs, such as predict/text or reading a batch result. You choose the operations it may call, so the agent cannot reach anything you have not included.
- **Credential handling:** Your GPTZero X-API-Key is stored once, encrypted, by your own Jentic One instance and injected as the header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'detect ai-generated text', and Jentic returns predict/text or predict/files with their request schemas so the agent picks the synchronous or document path without reading the spec.

## Related APIs

- **Winston AI API** — Competing AI-content detection plus image detection, plagiarism, and fact-checking
- **OpenAI API** — The model often producing the text being scored - pair generation with detection
- **Anthropic Messages API** — Claude completions that pair with GPTZero scoring after generation

## FAQ

### What authentication does the GPTZero API use?

GPTZero uses an API key sent in the X-API-Key header. Generate keys in the GPTZero dashboard and rotate them per environment. Through Jentic, the X-API-Key is stored in your Jentic One instance and injected at execution time so the agent never handles the raw secret.

### Can I score a PDF directly with this API?

Yes. POST `/predict/files` accepts a multipart upload of PDF, DOCX, or TXT files and returns the same scoring shape as `/predict/text.` GPTZero handles text extraction server-side, so the agent does not need a local PDF parser.

### What are the rate limits for the GPTZero API?

The OpenAPI spec does not declare rate limits. Limits are enforced at the gateway tied to your plan tier. Free and education tiers have stricter monthly word quotas; paid tiers raise the per-minute concurrency. Cache identical text bodies to avoid duplicate spend.

### How do I submit a batch of documents through Jentic?

Search Jentic for 'submit a batch of documents for ai detection', load POST /batch, and execute with the document array. Then call GET `/batch/{batchId}` to poll status and GET `/batch/{batchId}/results` to retrieve per-document scores once status is complete.

### What does the per-sentence breakdown contain?

Both `/predict/text` and `/predict/files` return a sentence-level array where each entry includes the sentence text and an AI-generation probability. This lets reviewers see exactly which passages triggered the model rather than relying only on a document-level score.

### Is the GPTZero API free?

GPTZero offers a free tier with limited monthly words and a paid tier with higher quotas, batch access, and priority concurrency. Education customers can apply for institution-wide pricing. Pricing is published on gptzero.me.

### Can I limit what my agent is allowed to do with the GPTZero API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which GPTZero operations the agent may call and which credentials it may use. GPTZero's detection is body-driven, so you can allow only the operations the agent needs, such as POST `/predict/text` for single passages or GET `/batch/{batchId}/results` to read a batch outcome, while withholding others like POST /batch or GET /reports. Anything you have not included stays out of reach, so the agent cannot submit new batches or pull historical reports unless you permit those operations.