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/v1

Both 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

refunded

Charged 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.

Header
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

GETwww.studysolutions.app/api/v1/balance

Your 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
curl https://www.studysolutions.app/api/v1/balance \
  -H "Authorization: Bearer $SS_API_KEY"
200 OK
{
  "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

POSTwww.studysolutions.app/api/v1/humanize

Rewrites 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

textstringrequired
The text to humanize. Up to 25,000 words.
modelstring
"studysolutions". Ryne AI is coming soon — until then "ryne" returns invalid_request.default "studysolutions"
streamboolean
Stream NDJSON events as paragraphs finish. See Streaming.default false
userstring
Your own ID for the end user, up to 128 characters. Lets you list one user's history.
storeboolean
Keep the result for history. false keeps nothing.default true

Response

idstring
Request ID. Also in the X-Request-Id header — quote it to support.
outputstring
The humanized document.
usageobject
input_words, words_charged (taken from your Humanizer words), output_words. cost_usd is their value at your price.
balanceobject
Your Extra Usage left: turnitin_checks, humanizer_words.
storedboolean
Whether the result was kept for history.
latency_msnumber
Time on our side, end to end.
200 OK
{
  "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.
Event 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.

POSTwww.studysolutions.app/api/v1/eligible-words

Body

textstringrequired
A paragraph or a whole document — typically a humanize output. Up to 250,000 characters.

One 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.

200 OK
{
  "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."}'
POSTwww.studysolutions.app/api/v1/synonyms

Body

wordstringrequired
One word, as it appears in the text.
sentencestring
The sentence the word is in. Alternatives then match its meaning and grammar; without it they are context-free.

Up to four alternatives, matched to the word's form. The list can be empty.

200 OK
{
  "object": "synonyms",
  "word": "keeps",
  "alternatives": ["stores", "holds", "preserves", "retains"]
}
cURL
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.

GETwww.studysolutions.app/api/v1/humanize/{id}

output is the document as last saved; original_output is what the humanizer returned.

200 OK
{
  "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 }
}
PATCHwww.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.

GETwww.studysolutions.app/api/v1/humanize

Results 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).

DELETEwww.studysolutions.app/api/v1/humanize/{id}

Deletes the result and its edits.

cURL
# 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

GETwww.studysolutions.app/api/v1/models

Public, no key needed. Lists the models.

studysolutionsdefault

Study Solutions · $0.05 per 1,000 words

ryneComing soon

Ryne AI · not available over the API yet

cURL
curl https://www.studysolutions.app/api/v1/models

Reference

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.

402 Payment Required
{
  "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
  }
}
StatusTypeWhen
400invalid_requestBody is not JSON, `text` is missing or empty, a field has the wrong type, or the model is not available yet.
413text_too_longOver 25,000 words (or 250,000 characters) in one request, or an edit over twice the size of its result.
401invalid_api_keyKey missing, malformed, unknown or revoked.
402insufficient_balanceBalance is below the cost of this request — or, on the free word tools and history, the account has never had balance.
403account_disabledThe account is suspended or deleted.
404not_foundNo stored result with that ID on this account: it was deleted, sent with store: false, or the run failed.
429concurrency_limit3 requests already in flight on this account. Retry when one finishes.
429rate_limitedOver 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.
502engine_errorThe engine failed mid-run. The charge is refunded.
504timeoutThe run took longer than 280 s. The charge is refunded.
503service_unavailableTemporary 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-Idstring
Same as the body id.
X-Concurrency-Limitnumber
Requests allowed in flight on your account.
X-Concurrency-Remainingnumber
Free slots when this request started.
Retry-Afterseconds
On 429 only.

Turnitin 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

POSTwww.studysolutions.app/api/v1/turnitin/preflight

Would 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

urlstringrequired
The document: a public https link to a PDF or DOCX.

The 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:

refusal.codeMeaning
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.
200 OK · ready
{
  "object": "turnitin_preflight",
  "ok": true,
  "words": 2140
}
200 OK · refused
{
  "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

POSTwww.studysolutions.app/api/v1/turnitin/checks

Starts 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-Keystringrequired
Any unique string, 1–255 visible ASCII characters — a UUID is ideal. Keep it with your job: sending the same key again returns the same check (Idempotent-Replayed: true) and never charges twice.

Body

urlstringrequired
Public https 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_idstring
Instead of url: the id of an upload link you sent the file to.
filenamestring
The document's name on both reports and in downloads, 1–255 characters, no slashes. Defaults to the URL's last path segment, or the file's own name.
author_first_namestring
The author printed on both reports, up to 100 characters (with author_last_name). Without one the reports say "Student".
author_last_namestring
The author's last name, up to 100 characters.
exclusionsobject
Similarity filters. See Exclusions.
formatstring
The cover both reports print on: "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
The time zone the covers print their dates in: "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).

201 Created
{
  "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

POSTwww.studysolutions.app/api/v1/turnitin/uploads

For 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
The file's name, ending in .pdf or .docx. The check and its reports carry it.
sizeintegerrequired
The file's size in bytes, up to 25 MB.

PUT 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.

201 Created
{
  "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

GETwww.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"
GETwww.studysolutions.app/api/v1/turnitin/checks

Your 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).

cURL
# 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"
200 OK
{
  "object": "list",
  "data": [
    { "id": "tc_8f2c1e0b9d4a4c7f8e3b2a1d0c9e8f7a", "object": "turnitin_check", "status": "completed", "…": "…" }
  ],
  "has_more": false
}

Free

Reports

GETwww.studysolutions.app/api/v1/turnitin/checks/{id}/reports/similarity
GETwww.studysolutions.app/api/v1/turnitin/checks/{id}/reports/ai

The 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:

codeMeaning
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"
GETwww.studysolutions.app/api/v1/turnitin/checks/{id}/document

The 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

A completed check
{
  "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

idstring
tc_ and 32 hex characters.
statusstring
processing, completed or failed.
filenamestring
The document's name on both reports: your filename, else the URL's last path segment or the file's own name.
author_first_namestring | null
The author's first name printed on both reports, if you sent one.
author_last_namestring | null
The author's last name printed on both reports, if you sent one.
exclusionsobject
Every similarity filter the check ran with, defaults filled in.
formatstring
The cover both reports print on: feedback_studio or originality (your format, else your console's default).
timezonestring | null
The time zone the covers print their dates in, such as GMT+3 (your timezone, else your console's); null = UTC.
created_atstring
When the check was created (ISO 8601).
completed_atstring | null
When it completed; null until then.
similaritystring | null
The Similarity score ("7%", or "N/A"); null until completed.
aistring | null
The AI score (below); null until completed.
ai_errorstring | null
Why there is no AI score, when there is none.
reportsobject
similarity / ai: whether that PDF can be downloaded now; expires_at: when they go (24 hours after completion).
errorobject | null
On failure: code and message.
refundedboolean
True once a failed check's charge is back on your balance.
checks_chargednumber
Turnitin checks it took from your Extra Usage: 1, or 0 once refunded.
cost_usdnumber
Dollars, for checks paid from the old API balance before Extra Usage; 0 otherwise.
statusMeaning
processingCharged 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.
aiMeaning
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:

error.codeMeaning
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.
A failed check
{
  "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

bibliographyboolean
True excludes the bibliography / reference list.default false
quotesboolean
True excludes quoted material.default false
citationsboolean
True excludes in-text citations such as "(Smith, 2020)".default false
abstractboolean
True excludes the abstract.default false
methodsboolean
True excludes the methods section.default false
internetboolean
True excludes internet sources.default false
publicationsboolean
True excludes publication sources.default false
min_match_words0–1,000
Excludes matches shorter than N words (0 = off).default 0
min_source_words0–1,000
Excludes sources contributing fewer than N words (0 = off).default 0
min_source_percent0–100
Excludes sources contributing less than N% (0 = off).default 0
Request body
{
  "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.

422 Unprocessable Entity
{
  "error": {
    "type": "document_refused",
    "message": "Only PDF and Word (.docx) files can be checked.",
    "code": "unsupported_file"
  }
}
StatusTypeWhen
400invalid_requestNo 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).
401invalid_api_keyKey missing, malformed, unknown or revoked.
402insufficient_balanceBalance is below the price of a check — or, on the free endpoints, the account has never had balance.
403account_disabledThe account is suspended or deleted.
404not_foundNo check with that ID on this account.
404report_unavailablecode: not_ready (still processing), not_produced (failed, or no such report for this check) or expired (over 24 hours since completion).
409idempotency_conflictThis Idempotency-Key already started a check with a different URL, filename or exclusions.
422document_refusedcode: unreachable, unsupported_file, file_too_large, too_long or no_text. The Idempotency-Key is free again.
429concurrency_limit3 checks already processing on this account (GET /balance shows the account's limit). Retry when one finishes.
429rate_limitedOver a per-minute limit (120 preflights, 300 creates, 1,500 reads, 300 report downloads), or the service is busy. Wait the Retry-After seconds.
503service_unavailableTemporary 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.