# isitcredible.com — API Documentation

The isitcredible.com API allows you to submit academic texts for automated peer review and retrieve results programmatically. Jobs are charged against your account balance. Top up your balance from your [account page](https://isitcredible.com/account).

**Base URL:** `https://isitcredible.com/api/v1`

---

## Authentication

Generate an API key from your [account page](https://isitcredible.com/account). 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 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. |

An optional code inspection add-on is available for any mode:

| Add-on | Extra cost | Description |
|--------|------------|-------------|
| `inspect_code=true` | +$5.00 | Reviewer 2 examines the logic of replication scripts and readmes. Does not run the code. Supply files via `code_files`. |

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.

**Response:**
```json
{"balance_cents": 1500, "balance_usd": 15.0}
```

---

### GET /api/v1/jobs

List your last 50 jobs.

**Response:**
```json
[
  {
    "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`

**Response:**
```json
{
  "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 /api/v1/jobs/{job_id}` until status is `completed`.

---

### POST /api/v1/jobs

Submit a document for analysis. Accepts `multipart/form-data`.

**Parameters:**

| Parameter | | Description |
|-----------|---|-------------|
| `main_file` | required | The document to review. Accepts **PDF**, **TXT**, or **Markdown (.md)**. Max 50 MB, 100,000 words. PDFs must not be encrypted and may not exceed 200 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."* |
| `webhook_url` | optional | URL to receive a POST when the job completes. |
| `inspect_code` | optional | Set to `true` to add code inspection (+$5.00). Supply code files via `code_files`. |
| `code_files` | optional | One or more script or readme files to inspect alongside the paper. Accepts `.py`, `.R`, `.do`, `.ado`, `.Rmd`, `.ipynb`, `.jl`, `.m`, `.sql`, `.sh`, `.txt`, `.md`, and similar. Do not include data files. Only used when `inspect_code=true`. |

**Response (202 Accepted):**
```json
{
  "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](https://isitcredible.com/account). |
| `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

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

# Submit a PDF (standard)
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 with code inspection
curl -X POST https://isitcredible.com/api/v1/jobs \
     -H "Authorization: Bearer iic_your_key" \
     -F "main_file=@paper.pdf" \
     -F "mode=standard" \
     -F "inspect_code=true" \
     -F "code_files=@analysis.py" \
     -F "code_files=@README.md"

# 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

```python
import requests, time

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

# Submit (standard, no code inspection)
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"]

# Submit with code inspection
with open("paper.pdf", "rb") as f, \
     open("analysis.py", "rb") as c1, \
     open("README.md", "rb") as c2:
    r = requests.post(
        f"{BASE}/jobs",
        headers=HEADERS,
        files=[
            ("main_file",  ("paper.pdf",    f,  "application/pdf")),
            ("code_files", ("analysis.py",  c1, "text/plain")),
            ("code_files", ("README.md",    c2, "text/plain")),
        ],
        data={"mode": "standard", "inspect_code": "true"}
    )
r.raise_for_status()
job_id = r.json()["job_id"]

# Poll until complete (jobs typically take 20–60 minutes)
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)
```

---

## Python SDK

A higher-level client is available via pip:

```bash
pip install isitcredible
```

```python
from isitcredible import Client, JobTimeoutError

client = Client("iic_your_api_key")

# Standard review
report = client.analyze("paper.pdf")
report.save("review.pdf")

# Extended review with code inspection
report = client.analyze(
    "paper.pdf",
    mode="extended",
    inspect_code=True,
    code_files=["analysis.py", "README.md"],
)
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](https://github.com/isitcredible/isitcredible-python) for the full method reference.

---

*isitcredible.com — automated peer review*