Developer APIv1
Requests use your Extra Usage — the same balance as the website.
API reference
REST and JSON over HTTPS. One key and one balance for both APIs.
https://www.studysolutions.app/api/v1Both APIs
Basics
Every request authenticates with your key and draws from your Extra Usage.
Overview
How it works
Your server sends a request with your key. We check the key, take what it costs from your Extra Usage, run the Humanizer or a Turnitin check, and answer. A request that fails gives its units back.
3
Humanize requests at a time
X-Concurrency-Limit
3
Turnitin checks at a time
limits.max_active_checks
0
refundedCharged when a request fails
its units come back, automatically
Keys
Authentication
Send your key as a Bearer token. x-api-key: ss_live_… also works. One key works for both APIs.
Authorization: Bearer ss_live_…- Keys start with ss_live_ and are shown once.
- We store a SHA-256 hash, never the key.
- One key per account. Lost it? Regenerate it.
- Regenerating is instant: the old key fails on its next request.
Call the API from your server. A key in browser or app code can be copied by anyone who loads it.
Endpoint
Balance
www.studysolutions.app/api/v1/balanceYour Extra Usage: turnitin_checks and humanizer_words left. limits is what may run at once on your account and usage what is running now — handy for showing capacity in your own app instead of waiting for a 429. balance_usd and humanize_words_available stay for older integrations.
curl https://www.studysolutions.app/api/v1/balance \
-H "Authorization: Bearer $SS_API_KEY"{
"object": "balance",
"turnitin_checks": 100,
"humanizer_words": 39588,
"balance_usd": 201.9794,
"humanize_words_available": 39588,
"currency": "usd",
"limits": {
"max_running_requests": 3,
"max_active_checks": 3
},
"usage": {
"running_requests": 1,
"active_checks": 2
}
}Billing
Pricing
Requests use your Extra Usage — the same balance as the website. Buy it on this page or on the website and use it in either place. Plan checks and words are for the website only.
1 check per Turnitin check
$2.00 a check, up to 25% off in bulk. Both reports, both PDFs.
Input words per humanize request
$0.05 per 1,000 words, up to 30% off in bulk.
Failures are free
A request or check that fails or times out gives its units back, automatically.
Never expires
Unused Extra Usage stays on your account.
Volume or reseller pricing
Your own price per check and per 1,000 words — write to support@studysolutions.app.
Humanizer API
Humanizer
Rewrite AI-generated text so it reads as human-written — in one request, or streamed paragraph by paragraph.
Start here
Quickstart
Create your key, export it as SS_API_KEY, and send text. The response is the humanized document, the words it took from your Extra Usage, and what is left.
curl https://www.studysolutions.app/api/v1/humanize \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Your AI-generated text goes here."}'Endpoint
Humanize
www.studysolutions.app/api/v1/humanizeRewrites AI-generated text so it reads as human-written. Formatting — headings, lists, blank lines — is kept. The reply comes back in the language you send.
Body
textstringrequiredmodelstring"studysolutions". Ryne AI is coming soon — until then "ryne" returns invalid_request.default "studysolutions"streambooleanuserstringstorebooleanResponse
idstringoutputstringusageobjectinput_words, words_charged (taken from your Humanizer words), output_words. cost_usd is their value at your price.balanceobjectturnitin_checks, humanizer_words.storedbooleanlatency_msnumber{
"id": "req_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a",
"object": "humanization",
"model": "studysolutions",
"output": "AI has reshaped how students learn…",
"usage": {
"input_words": 412,
"words_charged": 412,
"cost_usd": 0.0206,
"output_words": 405
},
"balance": {
"turnitin_checks": 100,
"humanizer_words": 39588
},
"balance_usd": 201.9794,
"stored": true,
"latency_ms": 3840
}balance_usd is the value of your Extra Usage at your prices, kept for older integrations.
Optional
Streaming
Without streaming you get one JSON body when the whole document is done. With "stream": true you get application/x-ndjson — one JSON event per line, one paragraph event per paragraph as it finishes — so your user sees text in seconds.
Paragraphs are written in parallel, so they can arrive out of order: place each by its index, which counts the non-blank lines of your text from 0 (blank lines are skipped, and a ``` code block counts as one). A repeated index is a revision, so replace what you have. done carries the exact document; done or error is always the last event.
startRequest accepted and charged. Carries id and usage.progressHow many paragraphs the document has.paragraphOne finished paragraph: index + text. Lines kept as they are (headings) come first; a revised paragraph is re-sent with the same index.doneThe assembled output, usage, what is left of your balance, and latency.errorThe run failed. The words go back to your balance. Ends the stream.{"type":"start","id":"req_8f2c…","model":"studysolutions","usage":{"input_words":412,"words_charged":412,"cost_usd":0.0206}}
{"type":"progress","paragraphs":3}
{"type":"paragraph","index":1,"text":"…"}
{"type":"paragraph","index":0,"text":"…"}
{"type":"paragraph","index":2,"text":"…"}
{"type":"done","id":"req_8f2c…","output":"…","usage":{…,"output_words":405},"balance":{"turnitin_checks":100,"humanizer_words":39588},"balance_usd":201.9794,"stored":true,"latency_ms":3840}const res = await fetch("https://www.studysolutions.app/api/v1/humanize", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SS_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ text, stream: true }),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
const paragraphs = [];
let buffer = "";
for (;;) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop();
for (const line of lines) {
if (!line) continue;
const event = JSON.parse(line);
if (event.type === "paragraph") paragraphs[event.index] = event.text;
if (event.type === "done") console.log(event.output, event.usage);
if (event.type === "error") throw new Error(event.error.message);
}
}Free
Word tools
The pieces of our own editor: which words are worth swapping, and replacements that fit the sentence. Any language — the answer comes back in the language you send. Free with your key.
www.studysolutions.app/api/v1/eligible-wordsBody
textstringrequiredOne entry per paragraph, numbered like the stream. Each word has start and end offsets into its paragraph (JavaScript string indices), so you can highlight it without splitting the text yourself.
{
"object": "eligible_words",
"paragraphs": [
{
"index": 0,
"words": [
{ "word": "Students", "start": 0, "end": 8 },
{ "word": "improve", "start": 13, "end": 20 },
{ "word": "learning", "start": 27, "end": 35 }
]
}
]
}curl https://www.studysolutions.app/api/v1/eligible-words \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Students can improve their learning when the school offers support."}'www.studysolutions.app/api/v1/synonymsBody
wordstringrequiredsentencestringUp to four alternatives, matched to the word's form. The list can be empty.
{
"object": "synonyms",
"word": "keeps",
"alternatives": ["stores", "holds", "preserves", "retains"]
}curl https://www.studysolutions.app/api/v1/synonyms \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"word": "keeps", "sentence": "The library keeps its rarest books in a cool room."}'Free
History & edits
Every successful humanization is kept, so you don't have to store it: fetch it by its id, list an end user's results, and save the edits your users make. Kept until you delete it. Send "store": false to keep nothing. We never use your text to train models.
www.studysolutions.app/api/v1/humanize/{id}output is the document as last saved; original_output is what the humanizer returned.
{
"id": "req_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a",
"object": "humanization",
"model": "studysolutions",
"user": "user_123",
"created_at": "2026-10-09T18:02:11.204Z",
"updated_at": "2026-10-09T18:09:40.517Z",
"input": "Artificial intelligence has fundamentally…",
"output": "AI has reshaped how students learn… (as last saved)",
"original_output": "AI has reshaped how students learn…",
"edits": 2,
"usage": { "input_words": 412, "output_words": 405, "cost_usd": 0.0206 }
}www.studysolutions.app/api/v1/humanize/{id}Body { "output": "..." }: saves your user's edited document as the next version and returns the result. The last 100 versions are kept; GET /humanize/{id}/edits lists them, newest first.
www.studysolutions.app/api/v1/humanizeResults newest first, with a short preview. Query: user (your end-user ID), limit (1–100, default 20), starting_after (the last id of the previous page).
www.studysolutions.app/api/v1/humanize/{id}Deletes the result and its edits.
# one result
curl https://www.studysolutions.app/api/v1/humanize/req_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a \
-H "Authorization: Bearer $SS_API_KEY"
# save your user's edited document
curl -X PATCH https://www.studysolutions.app/api/v1/humanize/req_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"output": "The edited document…"}'
# one end user's history, newest first
curl "https://www.studysolutions.app/api/v1/humanize?user=user_123&limit=20" \
-H "Authorization: Bearer $SS_API_KEY"Endpoint
Models
www.studysolutions.app/api/v1/modelsPublic, no key needed. Lists the models.
studysolutionsdefaultStudy Solutions · $0.05 per 1,000 words
ryneComing soonRyne AI · not available over the API yet
curl https://www.studysolutions.app/api/v1/modelsReference
Errors
Every error has the same shape. Branch on error.type; messages can change. insufficient_balance (not enough Humanizer words in your Extra Usage) adds humanizer_words and words_needed.
{
"error": {
"type": "insufficient_balance",
"message": "Not enough Extra Usage: this request needs 412 Humanizer words and the account has 120. Buy more at studysolutions.app/developers.",
"humanizer_words": 120,
"words_needed": 412,
"balance_usd": 0.006,
"cost_usd": 0.0206
}
}| Status | Type | When |
|---|---|---|
| 400 | invalid_request | Body is not JSON, `text` is missing or empty, a field has the wrong type, or the model is not available yet. |
| 413 | text_too_long | Over 25,000 words (or 250,000 characters) in one request, or an edit over twice the size of its result. |
| 401 | invalid_api_key | Key missing, malformed, unknown or revoked. |
| 402 | insufficient_balance | Balance is below the cost of this request — or, on the free word tools and history, the account has never had balance. |
| 403 | account_disabled | The account is suspended or deleted. |
| 404 | not_found | No stored result with that ID on this account: it was deleted, sent with store: false, or the run failed. |
| 429 | concurrency_limit | 3 requests already in flight on this account. Retry when one finishes. |
| 429 | rate_limited | Over a free endpoint's limit (a minute: 1,000 eligible-words, 120 synonyms, 1,000 history calls), or the service is busy. Wait the Retry-After seconds. |
| 502 | engine_error | The engine failed mid-run. The charge is refunded. |
| 504 | timeout | The run took longer than 280 s. The charge is refunded. |
| 503 | service_unavailable | Temporary problem on our side. Safe to retry. |
Reference
Limits
Input words per request
Taken from your Humanizer words when the request starts ($0.05 per 1,000 at the list price). A run that errors or times out gives them back.
3 requests at a time
Per account. The next one gets 429 with Retry-After — retry when one finishes. GET /balance shows your limit and what is running.
25,000 words per request
Longer documents: split on paragraph breaks and send in parts.
Timeouts
A run gets up to 280 s. Set your client timeout to 300 s.
Word tools and history are free
With your key. A minute: 1,000 eligible-words, 120 synonyms and 1,000 history calls. Over that, or when the service is busy: 429 with Retry-After.
Response headers
X-Request-IdstringX-Concurrency-LimitnumberX-Concurrency-RemainingnumberRetry-AftersecondsTurnitin API
Turnitin checks
Send a document; get its Similarity and AI scores and both PDF reports.
Start here
Quickstart
Export your key as SS_API_KEY. Then send a document by URL, poll the check until it completes, and download its two reports. The document has to be a public https link to a PDF or Word file that stays valid until the check finishes (6 hours is safe; a signed link is fine).
Similarity report
The match percentage, with every matching source highlighted, as the PDF.
AI report
The AI-writing score, with the flagged passages highlighted, as the PDF.
One check, both
Both scores and both PDFs for one Turnitin check. A failed check gives it back.
# 1. Start a check (a new Idempotency-Key for each check; the same one again to retry)
curl https://www.studysolutions.app/api/v1/turnitin/checks \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Content-Type: application/json" \
-d '{"url": "https://files.example.com/uploads/Essay.pdf"}'
# 2. Poll it every 20 seconds until "status" is "completed" or "failed"
CHECK_ID=tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a # the "id" from step 1
curl https://www.studysolutions.app/api/v1/turnitin/checks/$CHECK_ID \
-H "Authorization: Bearer $SS_API_KEY"
# 3. Download both reports (kept for 24 hours)
curl -o similarity.pdf https://www.studysolutions.app/api/v1/turnitin/checks/$CHECK_ID/reports/similarity \
-H "Authorization: Bearer $SS_API_KEY"
curl -o ai.pdf https://www.studysolutions.app/api/v1/turnitin/checks/$CHECK_ID/reports/ai \
-H "Authorization: Bearer $SS_API_KEY"Free
Preflight
www.studysolutions.app/api/v1/turnitin/preflightWould this document be checked? Free, stores nothing, charges nothing — run it before you charge your own customer. It downloads the file and applies the same rules as a check: the file type and size, readable text, and the word limit.
Body
urlstringrequiredThe answer is 200 either way. ok: true comes with words, the document's word count (or null when it could not be counted right now; the check applies the same rules). ok: false comes with a refusal:
unreachableThe file could not be downloaded from the URL. Use a public https link that stays valid until the check finishes.unsupported_fileNot a PDF or Word (.docx) file.file_too_largeOver 25 MB.no_textNo readable text: a scan or photos of pages. Export the original as a PDF with real text, or run it through OCR.too_longOver the word limit (50,000; max_words says which). Split the document and check each part.{
"object": "turnitin_preflight",
"ok": true,
"words": 2140
}{
"object": "turnitin_preflight",
"ok": false,
"refusal": {
"code": "too_long",
"message": "This document has about 61,200 words; a check reads up to 50,000. Split it into parts and check each one.",
"words": 61200,
"max_words": 50000
}
}curl https://www.studysolutions.app/api/v1/turnitin/preflight \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://files.example.com/uploads/Essay.pdf"}'Endpoint
Create a check
www.studysolutions.app/api/v1/turnitin/checksStarts a check and takes 1 Turnitin check from your Extra Usage: both scores and both PDFs. A check that fails gives it back, automatically.
Headers
Idempotency-KeystringrequiredIdempotent-Replayed: true) and never charges twice.Body
urlstringrequiredhttps link to the PDF or DOCX, up to 25 MB and 50,000 words. Or, instead of url, an upload_id (below), or the file itself as multipart.upload_idstringfilenamestringauthor_first_namestringauthor_last_name). Without one the reports say "Student".author_last_namestringexclusionsobjectformatstring"feedback_studio" (the assignment, class and institution under the title) or "originality" (only the institution). Without it, the default you pick under Report cover in your console above, else feedback_studio. The check echoes it as format.timezonestring"UTC", "GMT" or an offset from "GMT-12" to "GMT+14", half and three-quarter hours included ("GMT+5:30"); "UTC+3" and "+03:00" are read the same. Without it, the time zone you pick under Report cover in your console above, else UTC. The check echoes it as timezone.Or send the file itself as multipart/form-data, up to 4 MB: a file part plus the same optional fields as text (exclusions as JSON text). Larger files, up to 25 MB: use an upload link.
curl https://www.studysolutions.app/api/v1/turnitin/checks \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-F file=@Essay.pdf \
-F author_first_name=Maya \
-F author_last_name=Chen \
-F 'exclusions={"bibliography": true}'Unknown fields are refused, never ignored (400), so a misspelled filter can't quietly run a check without it. The answer is 201 with the check, status: "processing".
Retries are free
The same Idempotency-Key with the same request returns the first check. A freshly signed link to the same file counts as the same request (only the query string differs).
Conflicts are explicit
The same key with another document, filename, exclusions, author or format is a 409 idempotency_conflict. Use a new key for a new check.
Refused means free
A document_refused or 503 answer charges nothing, and frees the key for another try.
Keep the link alive
The document is read more than once while the check runs: keep the URL valid until it completes (6 hours is safe).
{
"id": "tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a",
"object": "turnitin_check",
"status": "processing",
"filename": "Essay.pdf",
"author_first_name": null,
"author_last_name": null,
"exclusions": {
"bibliography": false,
"quotes": false,
"citations": false,
"abstract": false,
"methods": false,
"internet": false,
"publications": false,
"min_match_words": 0,
"min_source_words": 0,
"min_source_percent": 0
},
"format": "feedback_studio",
"timezone": null,
"created_at": "2026-10-24T18:02:11.204Z",
"completed_at": null,
"similarity": null,
"ai": null,
"ai_error": null,
"reports": {
"similarity": false,
"ai": false,
"expires_at": null
},
"error": null,
"refunded": false,
"checks_charged": 1,
"cost_usd": 0
}# A new Idempotency-Key for each check; send the same one again to retry safely.
curl https://www.studysolutions.app/api/v1/turnitin/checks \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Content-Type: application/json" \
-d '{"url":"https://files.example.com/uploads/Essay.pdf"}'Free
Upload a file
www.studysolutions.app/api/v1/turnitin/uploadsFor a file you can't link to, up to 25 MB: get an upload link, PUT the file to it, then create the check with upload_id. Free; the check is charged as usual when you create it.
Body
filenamestringrequired.pdf or .docx. The check and its reports carry it.sizeintegerrequiredPUT the file's bytes to upload_url with upload_headers and without your API key, within an hour (expires_at); the link takes exactly that file. Then POST /turnitin/checks with { "upload_id": "tu_…" } and any of the usual fields. An upload can be checked for about a day. Up to 60 upload links a minute and 500 a day per account.
{
"object": "turnitin_upload",
"id": "tu_3f1a7c2e9b4d4e6f8a0b1c2d3e4f5a6b",
"filename": "Thesis.pdf",
"size": 7340032,
"upload_url": "https://…",
"upload_headers": {
"Content-Type": "application/pdf"
},
"expires_at": "2026-10-24T19:02:11.204Z"
}# 1. An upload link (free)
UPLOAD=$(curl -s https://www.studysolutions.app/api/v1/turnitin/uploads \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"filename\": \"Thesis.pdf\", \"size\": $(wc -c < Thesis.pdf)}")
# 2. PUT the file to it with its Content-Type (no API key)
curl -X PUT "$(echo "$UPLOAD" | jq -r .upload_url)" -H "Content-Type: application/pdf" --data-binary @Thesis.pdf
# 3. Start the check from it
curl https://www.studysolutions.app/api/v1/turnitin/checks \
-H "Authorization: Bearer $SS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d "{\"upload_id\": \"$(echo "$UPLOAD" | jq -r .id)\"}"Free
Get & list checks
www.studysolutions.app/api/v1/turnitin/checks/{id}The check as it is now — poll this. Another account's id, or an unknown one, is 404 not_found.
curl https://www.studysolutions.app/api/v1/turnitin/checks/tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a \
-H "Authorization: Bearer $SS_API_KEY"www.studysolutions.app/api/v1/turnitin/checksYour checks, newest first, each as last seen (to watch one finish, poll it by id). Query: limit (1–100, default 20), starting_after (the last id of the previous page).
# newest first; pass the last id as starting_after for the next page
curl "https://www.studysolutions.app/api/v1/turnitin/checks?limit=20" \
-H "Authorization: Bearer $SS_API_KEY"{
"object": "list",
"data": [
{ "id": "tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a", "object": "turnitin_check", "status": "completed", "…": "…" }
],
"has_more": false
}Free
Reports
www.studysolutions.app/api/v1/turnitin/checks/{id}/reports/similaritywww.studysolutions.app/api/v1/turnitin/checks/{id}/reports/aiThe PDF, while reports.similarity / reports.ai is true: for 24 hours after the check completes (reports.expires_at). Copy both to your own storage as soon as the check completes. Both download under the document's name (Essay.pdf), or with your own prefix for each report (AI_Essay.pdf / SIM_Essay.pdf) once you turn prefixes on in your console's API defaults.
Otherwise 404 report_unavailable, with a code:
not_readyThe check is still processing (or, for the submitted file, it is still being saved: retry in a minute).not_producedThe check failed, that report was not made for it (an AI report needs a document AI detection can read), or its file was not kept.expiredMore than 24 hours since the check completed: the report or file is gone.curl -o similarity.pdf https://www.studysolutions.app/api/v1/turnitin/checks/tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a/reports/similarity \
-H "Authorization: Bearer $SS_API_KEY"
curl -o ai.pdf https://www.studysolutions.app/api/v1/turnitin/checks/tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a/reports/ai \
-H "Authorization: Bearer $SS_API_KEY"AI highlights for 1–19%. Under 20% the AI report shows *% and highlights nothing. Add ?highlights=1 to the AI report download and a 1–19% report comes back with the flagged text highlighted and its exact score printed (12% detected as AI), header X-Highlights: applied, downloading as Essay (highlights).pdf. Any other report comes back as it is (X-Highlights: none), so it's safe to send on every AI download. Turn on AI highlights in your console's API defaults and a download without highlights gets them too; ?highlights=0 still gets the plain report.
# X-Highlights: applied (highlighted, exact score) or none (the report as it is)
curl -o ai.pdf "https://www.studysolutions.app/api/v1/turnitin/checks/tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a/reports/ai?highlights=1" \
-H "Authorization: Bearer $SS_API_KEY"www.studysolutions.app/api/v1/turnitin/checks/{id}/documentThe file the check was run on, exactly as we received it (PDF or Word, under your own filename), on the same window as the reports: for 24 hours after the check completes. Same errors as above.
# -OJ saves it under your own filename (Content-Disposition)
curl -OJ https://www.studysolutions.app/api/v1/turnitin/checks/tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a/document \
-H "Authorization: Bearer $SS_API_KEY"Reference
The check object
{
"id": "tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a",
"object": "turnitin_check",
"status": "completed",
"filename": "Essay.pdf",
"author_first_name": "Maya",
"author_last_name": "Chen",
"exclusions": {
"bibliography": true,
"quotes": false,
"citations": false,
"abstract": false,
"methods": false,
"internet": false,
"publications": false,
"min_match_words": 8,
"min_source_words": 0,
"min_source_percent": 0
},
"format": "feedback_studio",
"timezone": "GMT-5",
"created_at": "2026-10-24T18:02:11.204Z",
"completed_at": "2026-10-24T18:05:40.517Z",
"similarity": "7%",
"ai": "0%",
"ai_error": null,
"reports": {
"similarity": true,
"ai": true,
"expires_at": "2026-10-25T18:05:40.517Z"
},
"error": null,
"refunded": false,
"checks_charged": 1,
"cost_usd": 0
}Fields
idstringtc_ and 32 hex characters.statusstringprocessing, completed or failed.filenamestringfilename, else the URL's last path segment or the file's own name.author_first_namestring | nullauthor_last_namestring | nullexclusionsobjectformatstringfeedback_studio or originality (your format, else your console's default).timezonestring | nullGMT+3 (your timezone, else your console's); null = UTC.created_atstringcompleted_atstring | nullsimilaritystring | nullaistring | nullai_errorstring | nullreportsobjectsimilarity / ai: whether that PDF can be downloaded now; expires_at: when they go (24 hours after completion).errorobject | nullcode and message.refundedbooleanchecks_chargednumbercost_usdnumberprocessingCharged and running. Poll it.completedFinished: scores are set and the reports can be downloaded for 24 hours.failedDid not finish: error says why. Refunded in full.0%–100%The share of the document Turnitin flags as AI-written.*%Some AI writing, under 20%: Turnitin shows that range as an asterisk, without a number.N/AAI detection was not available for this document; ai_error says why (for example too short, over 30,000 words, or not a supported language).nullThe check has not completed.A failed check carries error.code and a message you can show your user. It is always refunded:
no_textNo readable text in the document (a scan or images of pages).unsupported_fileNot a file a check can read.password_protectedThe file is password-protected.too_longOver the word limit.processing_failedThe check could not be completed. Submit the document again.timed_outStill processing after 6 hours, so it was stopped.submit_failedThe check could not be started.{
"id": "tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a",
"object": "turnitin_check",
"status": "failed",
"filename": "Scan.pdf",
"error": {
"code": "no_text",
"message": "We couldn't find any text in this file to check. Scans and photos of pages can't be checked: export the original as a PDF with real text, or run it through OCR."
},
"refunded": true,
"checks_charged": 0,
"cost_usd": 0,
"…": "…"
}Optional
Exclusions
Filters for the Similarity report, the same settings as the Study Solutions website. Send only what you change; the check echoes every field back. internet and publications can't both be true. A field you leave out takes your default from the console's API defaults (off unless you set one); a field you send always wins, false and 0 included.
exclusions
bibliographybooleanquotesbooleancitationsbooleanabstractbooleanmethodsbooleaninternetbooleanpublicationsbooleanmin_match_words0–1,000min_source_words0–1,000min_source_percent0–100{
"url": "https://files.example.com/uploads/Essay.pdf",
"exclusions": { "bibliography": true, "quotes": true, "min_match_words": 8 }
}Guide
Polling
No webhooks
Your server polls. Reads are free and fast.
Every 15–30 seconds
Most checks finish within a few minutes.
6-hour ceiling
Still processing after 6 hours: stopped (timed_out) and refunded.
Then copy the PDFs
As soon as status is completed: they are kept for 24 hours.
At volume, keep a list of open check ids and poll each once a minute from a scheduled job; back off on 429 using Retry-After. The Quickstart shows the whole loop.
Reference
Errors
The same shape as every error; branch on error.type. document_refused and report_unavailable add a code; a too_long refusal adds words and max_words; insufficient_balance (no Turnitin checks left in your Extra Usage) adds turnitin_checks; concurrency_limit adds active_checks and limit. None of these charge anything.
{
"error": {
"type": "document_refused",
"message": "Only PDF and Word (.docx) files can be checked.",
"code": "unsupported_file"
}
}| Status | Type | When |
|---|---|---|
| 400 | invalid_request | No Idempotency-Key, body not JSON, an unknown field, url not an https link with a host name, a bad filename, or an unknown or wrongly typed exclusion (or internet and publications both excluded). |
| 401 | invalid_api_key | Key missing, malformed, unknown or revoked. |
| 402 | insufficient_balance | Balance is below the price of a check — or, on the free endpoints, the account has never had balance. |
| 403 | account_disabled | The account is suspended or deleted. |
| 404 | not_found | No check with that ID on this account. |
| 404 | report_unavailable | code: not_ready (still processing), not_produced (failed, or no such report for this check) or expired (over 24 hours since completion). |
| 409 | idempotency_conflict | This Idempotency-Key already started a check with a different URL, filename or exclusions. |
| 422 | document_refused | code: unreachable, unsupported_file, file_too_large, too_long or no_text. The Idempotency-Key is free again. |
| 429 | concurrency_limit | 3 checks already processing on this account (GET /balance shows the account's limit). Retry when one finishes. |
| 429 | rate_limited | Over a per-minute limit (120 preflights, 300 creates, 1,500 reads, 300 report downloads), or the service is busy. Wait the Retry-After seconds. |
| 503 | service_unavailable | Temporary problem on our side, or the check could not be started (refunded; the Idempotency-Key is free again). Safe to retry. |
Reference
Limits & pricing
1 Turnitin check per check
Taken from your Extra Usage when the check is created, for both reports (checks_charged: 1). See Pricing.
Never charged for failures
A check that fails gives its check back, automatically (refunded: true).
3 checks at a time
Per account. The next one gets 429 concurrency_limit with Retry-After. GET /balance shows your limit and how many are processing.
25 MB · 50,000 words
PDF or Word (.docx). AI detection reads up to 30,000 words: a longer document gets the Similarity report only, for the same one check. Over the word limit: split it and check each part.
Reports for 24 hours
After the check completes. Copy both PDFs right away.
6-hour ceiling
A check still processing after that is stopped and refunded.
Free with your key
Preflight, reads and report downloads. A minute: 120 preflights, 300 creates, 1,500 reads, 300 report downloads. Over that, or when the service is busy: 429 with Retry-After.