HumanScore API
Check documents from your own code — a CMS, a review queue, a script. Submit text; get back the human/AI split with every passage marked and the reason for each call. Same detector, same limits and same history as the web app.
Authentication
Every request carries an API key as a bearer token. Keys are created on your zbackroom account page and work across every zbackroom app. A key acts as you: checks it creates count against your HumanScore plan and appear in your history.
Authorization: Bearer zbk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeep keys server-side. A key in browser code can be read by anyone who views source.
Base URL
https://humanscore.zbackroom.com/api/v1JSON in, JSON out. Successful responses wrap the result in data; errors carry an error message and an HTTP status that says what kind.
Limits
Documents are between 50 and 6,000 words. Your plan's allowance applies exactly as it does on the web — words per day on the free tiers, words per month on paid plans, with Pay-as-you-go top-ups charged automatically. A check that would exceed it is refused with 403 and a code of quota, before anything is charged.
Request rate: 100 POSTs and 1,000 GETs per hour per account. Over that you get 429 with a Retry-After header.
POST /checks — submit a document
A check takes 10–40 seconds. Pass wait: true to hold the request open for the result (up to 90 seconds); otherwise you get the pending check back at once and poll it.
curl https://humanscore.zbackroom.com/api/v1/checks \
-H "Authorization: Bearer zbk_..." \
-H "Content-Type: application/json" \
-d '{
"text": "The full document text, at least 50 words...",
"title": "Q3 blog draft",
"wait": true
}'Fields: text (required) — the document, plain text. title (optional) — how it's listed; defaults to the first line. wait (optional) — true to block for the result.
Responses: 201 with the finished check when wait was true and it completed in time; 202 with a pending check otherwise — poll GET /checks/{id} until status is done or failed. 400 for a bad body or too few words, 402 if a Pay-as-you-go top-up couldn't be charged, 403 when your allowance is used up.
{
"data": {
"id": "cmuc1x9k80003...",
"status": "done",
"title": "Q3 blog draft",
"wordCount": 812,
"humanPercent": 74,
"aiPercent": 26,
"engine": "humanscore/v1",
"summary": "A first-person post with concrete detail throughout; one section of general advice reads as generated.",
"passages": [
{
"label": "human",
"confidence": "high",
"reason": "Named people, a specific date and an aside that goes nowhere.",
"text": "When we started the team in 2020..."
},
{
"label": "ai",
"confidence": "medium",
"reason": "Even rhythm, a list of three, no specifics.",
"text": "Building a successful team requires..."
}
],
"error": null,
"createdAt": "2026-09-22T05:10:41.000Z",
"finishedAt": "2026-09-22T05:11:03.000Z",
"url": "https://humanscore.zbackroom.com/check/cmuc1x9k80003..."
}
}Percentages are by word count over the passages. confidence is low, medium or high; treat low as close to a guess. passages cover the whole document in order.
GET /checks/{id} — fetch a check
curl https://humanscore.zbackroom.com/api/v1/checks/cmuc1x9k80003... \
-H "Authorization: Bearer zbk_..."Same shape as above. 404 for an id that isn't yours.
GET /checks — list your checks
curl https://humanscore.zbackroom.com/api/v1/checks \
-H "Authorization: Bearer zbk_..."The 100 most recent, newest first, without passages — id, status, title, wordCount, the two percentages, timestamps and url.
Read the result honestly
This is an estimate, not proof. Fluent human writing is sometimes marked AI and edited AI text is sometimes missed. If you act on a result — flagging a submission, say — show the person the passages and reasons and let them answer; never treat a percentage on its own as a finding.
What's not in v1
File upload (send extracted text instead), deleting checks, and webhooks. Ask if you need one: contact@zbackroom.com.