Developer documentation
Build scan, report, billing, and referral flows with the Oraclewriter API.
The API is REST-based and JSON-first, with multipart upload support for documents. The endpoints below cover account auth, uploads, scans, reports, token billing, writing actions, and referrals.
Base URL
/v1
Authenticated request
curl -X POST /v1/scans \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text":"Paste at least 50 characters here"}'Authentication
Bearer tokens
Register or log in to receive an access token. Send it on protected requests with the Authorization header.
Authorization: Bearer YOUR_TOKEN
Authenticate
Register or log in, then send the returned token as Authorization: Bearer <token> on protected requests.
Upload or paste
Send raw text directly to scans, or upload TXT, DOCX, and PDF files first when you need extraction.
Create a scan
A scan costs tokens. The response starts queued, so poll the scan endpoint until completed or failed.
Review the result
Use probabilities, confidence, feature breakdown, suspicious segments, and rationale as review evidence, not proof.
Resume drafts
Writing documents autosave server-side so students can return to the latest draft and restore snapshots.
Buy tokens
Use billing packages and checkout endpoints to add tokens through Paystack when balances are low.
Qualify referrals
Referral bonuses are waived until the referred account completes a token purchase.
Scan request
{
"text": "At least 50 characters of text to review",
"file_id": null,
"webhook_url": "https://example.com/oraclewriter/webhook",
"metadata": {
"assignment_id": "ENG-204"
}
}Scan result fields
Endpoint reference
Customer API routes
Protected routes accept bearer tokens. File upload uses multipart/form-data; other write endpoints use JSON.
Check whether the API service is available. No authentication required.
Create an account. Optional referral_code is accepted, but the referrer is rewarded only after the new user buys tokens.
Exchange email and password for a short-lived bearer token.
Return the signed-in user, token balance, and referral code.
Upload TXT, DOCX, or PDF and receive extracted text plus a file_id for scanning.
Create a probabilistic AI-authorship scan from raw text or a previous upload.
List the latest scans for the authenticated user.
Fetch status, probabilities, rationale, suspicious segments, and model metadata.
Download a report payload for a completed scan.
Delete one of the authenticated user's scans.
Create an editable student draft for the Writing Partner.
List saved writing drafts for the authenticated user.
Load editable HTML, plain text, references, and timestamps for one draft.
Autosave the latest draft content and references.
List recent version snapshots for a draft.
Restore an older draft version into the current editable draft.
Delete one saved writing draft.
Return the user's token balance, scan cost, writing-action cost, referral reward, and referral code.
List active token packages available for checkout.
Start a Paystack checkout for a token package.
Verify a returned Paystack reference and credit purchased tokens for the authenticated user.
List recent token package purchases for the authenticated user.
Debit tokens for rewrite, humanize, chat, or citation writing actions.
Return referral link and qualified referral count.
Receive signed Paystack charge.success events and credit token purchases after server-side verification.