API Documentation - Is It Credible?

Base URL

https://isitcredible.com/api/v1

Authentication

Generate an API key from your account page. Include it as a Bearer token in every request:

Authorization: Bearer iic_your_api_key_here

Keys require a verified email address. They are stored as one-way hashes — if you lose a key, revoke it and generate a new one.

Report Types

Each job is submitted with a mode parameter:

Mode	Price	Description
`standard`	$5.00	A full simulated peer review report: methodological critique, identified issues, and directions for future research.
`extended`	$7.00	Everything in standard, plus an editorial note advising how to respond to the review, and a proofreading pass.

Prices may change. Registered account holders will be notified by email before any change takes effect.

Endpoints

GET /api/v1/credits Return current account balance

{"balance_cents": 1500, "balance_usd": 15.0}

GET /api/v1/jobs List your last 50 jobs

[
  {
    "uuid": "a1b2c3d4",
    "status": "completed",
    "mode": "standard",
    "title": "On the Origins of...",
    "authors": "Smith, J. et al.",
    "audit_date": "2026-03-06T14:22:00"
  }
]

GET /api/v1/jobs/{job_id} Get status and metadata for a job

When status is completed or published, a report_url field is included.

Terminal statuses: completed, published, failed, suspended

{
  "uuid": "a1b2c3d4",
  "status": "completed",
  "mode": "standard",
  "title": "On the Origins of...",
  "authors": "Smith, J. et al.",
  "discipline": "Economics",
  "audit_date": "2026-03-06T14:22:00",
  "report_url": "https://isitcredible.com/api/v1/jobs/a1b2c3d4/report"
}

GET /api/v1/jobs/{job_id}/report Download the finished PDF or TXT report

Accepts an optional query parameter format (default: pdf). Set to txt for plain text.

Returns the report as application/pdf or text/plain. Returns 425 Too Early if the report is not yet ready — poll GET /jobs/{job_id} until status is completed.

POST /api/v1/jobs Submit a document for analysis

Accepts multipart/form-data.

Parameter		Description
`main_file`	required	The document to review. Accepts PDF, TXT, or Markdown (.md). Max 50 MB, 200,000 words. PDFs must not be encrypted and may not exceed 600 pages.
`mode`	optional	`standard` (default, $5.00) or `extended` ($7.00).
`user_note`	optional	Context for the reviewer, e.g. "This is a draft chapter on Victorian economic history."

Returns 202 Accepted:

{
  "job_id": "a1b2c3d4",
  "status": "processing",
  "mode": "standard",
  "message": "Job submitted. Poll GET /api/v1/jobs/a1b2c3d4 for status."
}

Error Reference

Code	Meaning
`401`	Missing or invalid API key.
`402`	Insufficient balance. Top up at your account page.
`403`	Email address not verified. Log in to resend the verification link.
`404`	Job not found, or does not belong to your account.
`400`	Invalid input — file too large, word/page limit exceeded, unsupported file type, encrypted PDF, or invalid `mode`.
`425`	Report not ready yet. Keep polling.
`500`	Server error.

Examples

curl

# Check balance
curl https://isitcredible.com/api/v1/credits \
     -H "Authorization: Bearer iic_your_key"

# Submit a PDF
curl -X POST https://isitcredible.com/api/v1/jobs \
     -H "Authorization: Bearer iic_your_key" \
     -F "main_file=@paper.pdf" \
     -F "mode=standard" \
     -F "user_note=This is a draft journal article in economics."

# Submit a plain-text or Markdown file
curl -X POST https://isitcredible.com/api/v1/jobs \
     -H "Authorization: Bearer iic_your_key" \
     -F "main_file=@paper.md" \
     -F "mode=standard"

# Poll for status
curl https://isitcredible.com/api/v1/jobs/a1b2c3d4 \
     -H "Authorization: Bearer iic_your_key"

# Download report (once status is 'completed')
curl -OJ https://isitcredible.com/api/v1/jobs/a1b2c3d4/report?format=txt \
     -H "Authorization: Bearer iic_your_key"

Python

import requests, time

API_KEY = "iic_your_key"
BASE    = "https://isitcredible.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Submit (works with .pdf, .txt, or .md)
with open("paper.pdf", "rb") as f:
    r = requests.post(
        f"{BASE}/jobs",
        headers=HEADERS,
        files={"main_file": f},
        data={"mode": "standard", "user_note": "Draft economics paper."}
    )
r.raise_for_status()
job_id = r.json()["job_id"]
print(f"Submitted: {job_id}")

# Poll until complete (jobs typically take 20–60 minutes)
# Save job_id before polling — if your process times out the job keeps running
# and you can resume by polling job_id again later.
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS).json()
    print(f"Status: {job['status']}")
    if job["status"] in ("completed", "published"):
        break
    if job["status"] in ("failed", "suspended"):
        raise RuntimeError(f"Job {job['status']}")
    time.sleep(60)

# Download PDF
report = requests.get(f"{BASE}/jobs/{job_id}/report", headers=HEADERS)
report.raise_for_status()
with open("report.pdf", "wb") as f:
    f.write(report.content)
print("Report saved to report.pdf")

# Download TXT version
report_txt = requests.get(f"{BASE}/jobs/{job_id}/report", headers=HEADERS, params={"format": "txt"})
report_txt.raise_for_status()
with open("report.txt", "w") as f:
    f.write(report_txt.text)
print("Text report saved to report.txt")

Python SDK

A higher-level client is available via pip:

pip install isitcredible

from isitcredible import Client, JobTimeoutError

client = Client("iic_your_api_key")

# One-liner: submit, poll, and download
report = client.analyze("paper.pdf")
report.save("review.pdf")

# Handle timeouts — the job keeps running on the server
try:
    report = client.analyze("paper.pdf", timeout=3600)
except JobTimeoutError as e:
    print(f"Still running. Resume with: client.wait('{e.job_id}')")

# Webhook management
client.create_webhook("https://yourapp.com/webhook")
hooks = client.list_webhooks()

The SDK handles polling, retries, downloading, and webhook management automatically. See the SDK README for full details.