The TurnItOut API.

curl https://turnitout.org/v1/usage \
  -H "Authorization: Bearer $TURNITOUT_KEY"

curl https://turnitout.org/v1/humanize \
  -H "Authorization: Bearer $TURNITOUT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: essay-8841" \
  -d '{"text": "The text to humanize…", "level": "balanced"}'

import os
import requests

API = "https://turnitout.org/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TURNITOUT_KEY']}"}

r = requests.post(f"{API}/humanize", headers=HEADERS, json={
    "text": open("essay.txt", encoding="utf-8").read(),
    "level": "balanced",
})
r.raise_for_status()
job = r.json()
print(job["id"], job["status"], job["words"])

// Node 18+ (fetch is built in)
const API = "https://turnitout.org/v1";
const headers = { Authorization: `Bearer ${process.env.TURNITOUT_KEY}` };

const res = await fetch(`${API}/humanize`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ text, level: "balanced" }),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const job = await res.json();
console.log(job.id, job.status, job.words);

{
  "id": "to_A1b2C3d4E5f6G7h8I9j0",
  "status": "queued",
  "level": "balanced",
  "words": 1200,
  "part_count": 1,
  "created_at": "2026-11-05T17:09:21Z"
}

curl https://turnitout.org/v1/humanize \
  -H "Authorization: Bearer $TURNITOUT_KEY" \
  -F "file=@essay.docx" \
  -F "level=light"

with open("essay.docx", "rb") as f:
    r = requests.post(f"{API}/humanize", headers=HEADERS,
                      files={"file": ("essay.docx", f)},
                      data={"level": "light"})
r.raise_for_status()
job = r.json()

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("essay.docx")]), "essay.docx");
form.append("level", "light");

const res = await fetch(`${API}/humanize`, { method: "POST", headers, body: form });
const job = await res.json();

curl https://turnitout.org/v1/humanize/to_A1b2C3d4E5f6G7h8I9j0 \
  -H "Authorization: Bearer $TURNITOUT_KEY"

import time

while True:
    job = requests.get(f"{API}/humanize/{job_id}", headers=HEADERS).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if job["status"] == "completed":
    print(job["ai_before"], "->", job["ai_after"], job["reached_target"])
    print(job["output_text"])
else:
    print(job["error"])

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

let job;
do {
  await sleep(3000);
  job = await (await fetch(`${API}/humanize/${id}`, { headers })).json();
} while (job.status === "queued" || job.status === "running");

if (job.status === "completed") console.log(job.ai_after, job.output_text);
else console.error(job.error);

{
  "id": "to_A1b2C3d4E5f6G7h8I9j0",
  "status": "completed",
  "level": "balanced",
  "language": "en",
  "words": 1200,
  "part_count": 1,
  "ai_before": 87,
  "ai_after": 4,
  "target_pct": 15,
  "reached_target": true,
  "words_changed_pct": 41.2,
  "error": null,
  "created_at": "2026-11-05T17:09:21Z",
  "completed_at": "2026-11-05T17:10:02Z",
  "output_text": "The rewritten text…"
}

curl "https://turnitout.org/v1/humanize/to_A1b2C3d4E5f6G7h8I9j0/output?format=docx" \
  -H "Authorization: Bearer $TURNITOUT_KEY" \
  -o essay.humanized.docx

r = requests.get(f"{API}/humanize/{job_id}/output", headers=HEADERS,
                 params={"format": "docx", "highlight": "true"})
r.raise_for_status()
with open("essay.humanized.docx", "wb") as f:
    f.write(r.content)

import { writeFile } from "node:fs/promises";

const res = await fetch(`${API}/humanize/${id}/output?format=docx`, { headers });
if (res.status === 409) throw new Error("not ready yet");
await writeFile("essay.humanized.docx", Buffer.from(await res.arrayBuffer()));

curl "https://turnitout.org/v1/humanize?limit=20" \
  -H "Authorization: Bearer $TURNITOUT_KEY"

curl "https://turnitout.org/v1/usage?month=2026-11" \
  -H "Authorization: Bearer $TURNITOUT_KEY"

POST /your-webhook HTTP/1.1
Content-Type: application/json
X-TurnItOut-Event: humanize.completed
X-TurnItOut-Signature: t=1762362602,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "event": "humanize.completed",
  "data": { "id": "to_A1b2C3d4E5f6G7h8I9j0", "status": "completed", "ai_after": 4, … }
}

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.TURNITOUT_WEBHOOK_SECRET;

function verify(header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries((header || "").split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// keep the raw body: the signature covers the exact bytes we sent
app.post("/turnitout-webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.get("X-TurnItOut-Signature"), req.body)) return res.sendStatus(400);
  const { event, data } = JSON.parse(req.body.toString("utf8"));
  // handle data.id once: a retry can deliver the same event again
  res.sendStatus(200);
});

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["TURNITOUT_WEBHOOK_SECRET"].encode()


def verify(header: str, body: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.strip().split("=", 1) for p in header.split(","))
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance:
        return False
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))


app = Flask(__name__)


@app.post("/turnitout-webhook")
def turnitout_webhook():
    if not verify(request.headers.get("X-TurnItOut-Signature", ""), request.get_data()):
        abort(400)
    event = request.get_json()
    # handle event["data"]["id"] once: a retry can deliver the same event again
    return "", 200

Idempotency-Key: order-2291-essay

{
  "error": {
    "code": "too_short",
    "message": "This strength needs at least 500 words."
  }
}