API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your Settings page after logging in.

Authorization: Bearer your-api-token

Base URL

https://proofed.ai/api/v1

Remote file URLs

Every endpoint that accepts a multipart file (Submit Document, Submit Reviewer Feedback, Submit Fact Check) also accepts a _url companion field that we fetch on your behalf. Pass either the file or the URL — never both for the same slot.

Field pairs

Rules

• Exactly one of the upload or URL form must be supplied per slot. Reviewer Feedback has two independent slots — you can mix an upload with a URL.
• Only http and https schemes are accepted.
• The URL path must end with one of the allowed extensions (pdf, docx, pptx, html, htm, txt, rtf, odt, epub). The URL extension wins — if Content-Disposition disagrees, we rewrite the filename to match.
• Downloads cap at 50 MB and a 60-second timeout.
• Up to 5 redirects are followed; each hop is re-validated against the rules above.
• URLs targeting private, loopback, link-local or reserved IP ranges are rejected. Hostnames are resolved and every returned IP is checked.
• Signed query-string URLs (S3, GCS, Azure pre-signed links) are supported verbatim — we pass the signature through unchanged.

Example

curl -X POST https://proofed.ai/api/v1/documents \
  -H "Authorization: Bearer your-api-token" \
  -F "file_url=https://bucket.s3.amazonaws.com/uploads/report.pdf?X-Amz-Signature=..." \
  -F "language=en"

Errors

Policy and download failures surface as 422 validation errors attached to the URL field. Common messages:

• URLs targeting private or reserved hosts are not allowed.
• URL must point at a file with one of these extensions: pdf, docx, ...
• Remote server returned HTTP 404 when fetching the file.
• File at document_url exceeds the maximum size of 51200 KB.

Document Lifecycle

Every document moves through a series of statuses. Once submitted, our AI proofreading engine reads the document, identifies issues, and returns structured corrections.

Typical processing time: 30 seconds to 5 minutes depending on document length. Larger documents use an agentic reading mode and may take up to 30 minutes.

Submit a Document

Upload a file for proofreading. Requires multipart/form-data. Consumes one token from your balance.

Parameters

Example

curl -X POST https://proofed.ai/api/v1/documents \
  -H "Authorization: Bearer your-api-token" \
  -F "file=@report.pdf" \
  -F "language=en" \
  -F "editing_phase=pre-edit" \
  -F "webhook_url=https://your-app.com/webhook" \
  -F "review=true" \
  -F "review_brief=Light proofread; preserve the author's voice." \
  -F 'meta={"jobid":123,"campaign":"Q3-2026"}'

Response 201 Created

{
  "data": {
    "uuid": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "filename": "report.pdf",
    "file_type": "pdf",
    "file_size": 102400,
    "language": "en",
    "editing_phase": "pre-edit",
    "meta": {"jobid": 123, "campaign": "Q3-2026"},
    "status": "pending",
    "source": "api",
    "correction_count": null,
    "webhook_url": "https://your-app.com/webhook",
    "submitted_at": null,
    "completed_at": null,
    "created_at": "2026-04-16T12:00:00+00:00"
  }
}

List Documents

Returns a paginated list of your documents, newest first. 20 per page.

Example

curl https://proofed.ai/api/v1/documents \
  -H "Authorization: Bearer your-api-token"

Get Document

Returns document details. The full corrections array is included on this endpoint but omitted from the list endpoint.

Response 200 OK

{
  "data": {
    "uuid": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "filename": "report.pdf",
    "file_type": "pdf",
    "file_size": 102400,
    "language": "en",
    "status": "completed",
    "source": "api",
    "correction_count": 5,
    "corrections_data": [
      {
        "type": "spelling",
        "original": "achivements",
        "corrected": "achievements",
        "context": "Misspelling",
        "page": 3
      }
    ],
    "webhook_url": "https://your-app.com/webhook",
    "submitted_at": "2026-04-16T12:00:05+00:00",
    "completed_at": "2026-04-16T12:00:42+00:00",
    "created_at": "2026-04-16T12:00:00+00:00",
    "download_url": "https://proofed.ai/api/v1/documents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download?expires=...&signature=...",
    "proofed_review": {
      "status": "delivered",
      "deadline": "2026-04-18T12:00:00+00:00",
      "word_count": 1234,
      "delivered_at": "2026-04-17T16:00:00+00:00",
      "download_url": "https://proofed.ai/api/v1/documents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/proofed-review/download?expires=...&signature=..."
    }
  }
}

The proofed_review block is only present when the document was submitted with review=true. See Human Review for details.

Cancel Document

Cancel a pending or processing document. Completed, failed, or already-cancelled documents cannot be cancelled (returns 422).

Cancellation is cooperative — if the AI is mid-call, it finishes that step and stops at the next turn boundary.

If a human review is attached: when the review is pending or submitted, cancellation also cancels the review (and fires a proofed_review.canceled webhook). When the review is in_progress or delivered the cancel returns 422 — proofed.com cannot cancel it from our side; contact support.

Response 200 OK

{
  "message": "Document cancelled."
}

Document Fields

Correction Shape

Each entry in corrections_data follows this shape. The AI produces both replacement corrections (with a suggested fix) and comments (judgment calls flagged for a human editor to review).

Webhooks

If you provide a webhook_url when submitting a document, we will send a POST request to that URL when processing reaches a terminal state (completed or failed).

Webhook Payload

{
  "event": "document.completed",
  "document": {
    "uuid": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "filename": "report.pdf",
    "status": "completed",
    "correction_count": 5,
    "download_url": "https://proofed.ai/api/v1/documents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download?expires=...&signature=..."
  },
  "timestamp": "2026-04-16T12:00:42+00:00"
}

The event field is document.{status}, e.g. document.completed or document.failed. Webhook delivery is retried up to 3 times with a 30-second delay between attempts. Any non-2xx response is treated as a failure and retried.

document.completed payloads include a download_url — a time-limited signed URL (24h) for the AI-proofread output file. The signature is the auth; do NOT send a Bearer token to it. The field is absent if no processed file was produced.

To fetch the full corrections, call the Get Document endpoint using the uuid from the payload.

Download Proofread File

Streams the AI-proofread output file. Filename is proofed-{original-name}.

Authentication is by signed URL only — do NOT send an Authorization header. Use the URL we provide in download_url on the Get Document response or in the document.completed webhook payload. The URL is valid for 24 hours from issue; each Get Document response generates a fresh URL with a fresh expiry.

Returns 403 if the signature is invalid or expired. Returns 404 if no processed file exists for the document or the file is missing on disk.

curl "$DOWNLOAD_URL" -o proofed-report.pdf

Polling & Live Status

If you cannot receive webhooks, poll the Get Document endpoint. We recommend a 15-second interval while status is pending or processing. Documents typically complete within 1–5 minutes.

Pseudocode

while document.status in ("pending", "processing"):
    sleep(15)
    document = get_document(uuid)

if document.status == "completed":
    process_corrections(document.corrections_data)
else:
    handle_failure(document.status)

Human Review (proofed.com)

Optional follow-on stage: after the AI proofread completes, send the document to proofed.com for review by a human editor. The editor returns a final reviewed file, which you fetch via a signed URL.

Free add-on for now — review=true does not consume an extra token.

curl -X POST https://proofed.ai/api/v1/documents \
  -H "Authorization: Bearer your-api-token" \
  -F "file=@report.pdf" \
  -F "webhook_url=https://your-app.com/webhook" \
  -F "review=true" \
  -F "review_brief=Light proofread; preserve the author's voice."

"proofed_review": {
  "status": "delivered",
  "deadline": "2026-04-18T12:00:00+00:00",
  "word_count": 1234,
  "delivered_at": "2026-04-17T16:00:00+00:00",
  "download_url": "https://proofed.ai/api/v1/documents/{uuid}/proofed-review/download?expires=...&signature=..."
}

curl "$DOWNLOAD_URL" -o report-reviewed.pdf

{
  "event": "proofed_review.delivered",
  "document": {
    "uuid": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "filename": "report.pdf"
  },
  "proofed_review": {
    "status": "delivered",
    "delivered_at": "2026-04-17T16:00:00+00:00",
    "download_url": "https://proofed.ai/api/v1/documents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/proofed-review/download?expires=...&signature=..."
  },
  "timestamp": "2026-04-17T16:00:01+00:00"
}

{
  "event": "proofed_review.failed",
  "document": { "uuid": "...", "filename": "report.pdf" },
  "proofed_review": {
    "status": "failed",
    "error_text": "proofed.com submit failed: HTTP 502"
  },
  "timestamp": "2026-04-17T12:01:00+00:00"
}

{
  "event": "proofed_review.canceled",
  "document": { "uuid": "...", "filename": "report.pdf" },
  "proofed_review": { "status": "canceled" },
  "timestamp": "2026-04-17T12:01:00+00:00"
}

Editor Quality Reviews

Proofed.ai also offers an editor quality review feature: upload an original document and an editor's version, and the AI assesses the editor's work against a baseline proofread. The output is a structured feedback report with a score and categorised findings.

What it produces

• An overall score: Excellent, Good Work, Minor Changes Needed, Significant Rework Needed, or Unacceptable.
• A narrative summary explaining strengths and areas for improvement.
• Categorised feedback: caught correctly, missed issues, introduced errors, unnecessary changes, and good editorial judgment.
• Statistics: catch rate, counts by category, severity breakdown.
• A downloadable DOCX feedback report.

How to access

Admin users can submit reviews at /admin/reviews/submit in the proofed.ai web app. Users with the George permission can submit at /reviews/submit. DOCX files with track changes are fully supported — we read the "final accepted" version of the editor's work.

Reviewer Feedback

Reviewer Feedback (internal codename "Huxley") compares a reviewer's final copy against the editor's final copy, infers why the reviewer made each change by matching it to the style guide, and returns rule-grouped feedback the reviewer can scan, adjust, and send to the editor. Designed to save reviewers time when giving constructive feedback.

Lifecycle

Feedback jobs move through pending → processing → completed / failed / cancelled, the same states as documents. Typical runtime: 2–6 minutes depending on document length and number of differences.

curl -X POST https://proofed.ai/api/v1/reviewer-feedback \
  -H "Authorization: Bearer your-api-token" \
  -F "editor_file=@editor-final.docx" \
  -F "reviewer_file=@reviewer-final.docx" \
  -F "language=en" \
  -F "style_guide_url=https://stylus.proofedapps.com/api/style-guides/abc-123" \
  -F "webhook_url=https://your-app.com/webhook" \
  -F "order_id=ORD-2026-0417" \
  -F "job_id=JOB-9812"

{
  "data": {
    "uuid": "7c2a1d5e-3f4b-4c6d-8e9f-0a1b2c3d4e5f",
    "editor_filename": "editor-final.docx",
    "reviewer_filename": "reviewer-final.docx",
    "language": "en",
    "status": "pending",
    "style_guide_url": "https://stylus.proofedapps.com/api/style-guides/abc-123",
    "webhook_url": "https://your-app.com/webhook",
    "order_id": "ORD-2026-0417",
    "job_id": "JOB-9812",
    "narrative": null,
    "finding_count": null,
    "diff_count": null,
    "report_available": false,
    "submitted_at": null,
    "completed_at": null,
    "created_at": "2026-04-17T15:00:00+00:00"
  }
}

curl https://proofed.ai/api/v1/reviewer-feedback \
  -H "Authorization: Bearer your-api-token"

{
  "data": {
    "uuid": "7c2a1d5e-3f4b-4c6d-8e9f-0a1b2c3d4e5f",
    "editor_filename": "editor-final.docx",
    "reviewer_filename": "reviewer-final.docx",
    "language": "en",
    "status": "completed",
    "style_guide_url": "https://stylus.proofedapps.com/api/style-guides/abc-123",
    "webhook_url": "https://your-app.com/webhook",
    "order_id": "ORD-2026-0417",
    "job_id": "JOB-9812",
    "narrative": null,
    "finding_count": 3,
    "diff_count": 14,
    "summary": "Three recurring themes across your edit...",
    "tone_notes": "Keep it constructive — the editor caught most of the heavy lifting.",
    "findings": [
      {
        "rule_slug": "currency-abbreviations",
        "rule_name": "Currency in Billions",
        "rule_description": "Abbreviate as bn.",
        "summary": "Use bn for currency in the billions.",
        "examples": [
          { "paragraph": "14", "from": "$4 billion", "to": "$4bn" }
        ]
      }
    ],
    "report_available": true,
    "submitted_at": "2026-04-17T15:00:05+00:00",
    "completed_at": "2026-04-17T15:03:42+00:00",
    "created_at": "2026-04-17T15:00:00+00:00"
  }
}

{
  "message": "Reviewer feedback cancelled."
}

curl https://proofed.ai/api/v1/reviewer-feedback/{uuid}/report \
  -H "Authorization: Bearer your-api-token" \
  -o feedback.docx

{
  "event": "reviewer-feedback.completed",
  "reviewer_feedback": {
    "uuid": "7c2a1d5e-3f4b-4c6d-8e9f-0a1b2c3d4e5f",
    "editor_filename": "editor-final.docx",
    "reviewer_filename": "reviewer-final.docx",
    "status": "completed",
    "order_id": "ORD-2026-0417",
    "job_id": "JOB-9812",
    "finding_count": 3,
    "diff_count": 14
  },
  "timestamp": "2026-04-17T15:03:42+00:00"
}

Fact Check

Verify factual claims in a document against your Stylus style guide's ground truth and the live web. Requires the Fact Check permission on your account. Findings are returned per-claim with a verdict (verified, contradicted, or unverifiable), the reasoning, and source citations.

curl -X POST https://proofed.ai/api/v1/fact-checks \
  -H "Authorization: Bearer your-api-token" \
  -F "document=@article.pdf" \
  -F "language=en" \
  -F "style_guide_url=https://stylus.proofedapps.com/api/style-guides/abc-123" \
  -F "webhook_url=https://your-app.com/webhook"

Error Codes