API documentation

Authentication

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

Authorization: Bearer your-api-token

Base URL

https://proofed.ai/api/v1

Remote file URLs

Every endpoint that accepts a multipart file (“Submit a document”, “Submit reviewer feedback” and “Submit a fact-check”) also accepts a matching _url field, and we fetch the file from that URL for you. Pass either the file or the URL for each slot, never both.

Field pairs

Rules

• Supply exactly one of the upload or the URL for each slot. Reviewer feedback has three slots, and each one is independent, so you can mix uploads and URLs.
• 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). That extension decides how we read the file. If the Content-Disposition header names the file with a different extension, we change it to the URL’s extension.
• Downloads are capped at 96 MB and time out after 60 seconds.
• We follow up to 5 redirects and check each one against the rules above.
• We reject URLs that point at private, loopback, link-local or reserved IP ranges. We resolve the host name and check every IP address it returns.
• Signed query-string URLs (S3, GCS and Azure pre-signed links) work as they are: 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-US"

Errors

Policy and download failures come back as 422 validation errors on 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 98304 KB.

Document lifecycle

Every document moves through a series of statuses. Once you submit it, our AI reads the document, finds the issues and returns structured corrections.

How long processing takes depends on the document’s length. Send a webhook_url to hear when it finishes, or poll the “Get a document” endpoint.

Pricing

Proofreading costs 1 token per 1,000 words, rounded up, with a minimum of 1 token: a 3,420-word document costs 4 tokens and a 999-word one costs 1. A professional edit (professional_editor=true) adds +2 tokens per 1,000 words, rounded the same way, so the 3,420-word document costs 12 tokens with it. A fact-check costs 2 tokens per 1,000 words, rounded the same way, so the 3,420-word document costs 8 tokens to fact-check. That is the price alongside a proofread and on its own through “Submit a fact-check”. Hyperpowered costs 5 tokens per 1,000 words instead of 1. You pay it when you send hyperpowered=true from an account that has it. Every Hyperpowered document costs at least 5 tokens, and the 3,420-word document costs 20, or 36 with a professional edit and a fact-check. A human review by a Proofed editor costs $60 per 1,000 words, pro rata with no rounding up, so a 3,420-word document costs $205.20. You pay for it by card on the document’s page. Service accounts are not charged.

We count the words before we charge anything. The document records its cost in tokens_charged and its word count in word_count. If a document fails, we return its tokens.

Not enough tokens 402 Payment Required

Nothing is charged. The response says how many tokens the document needs and how many the account has.

{
  "message": "Insufficient tokens.",
  "tokens_required": 4,
  "tokens_available": 2
}

A file whose words cannot be counted

Nothing is charged. A file we cannot read returns 422. If the counting service is briefly unavailable, the response is 503 and you can retry the request.

{
  "message": "We couldn't read that file to count its words. Try again or contact us."
}

Submit a document

Upload a file for proofreading. Requires multipart/form-data. Costs 1 token per 1,000 words (see “Pricing”).

Parameters

Example

curl -X POST https://proofed.ai/api/v1/documents \
  -H "Authorization: Bearer your-api-token" \
  -F "file=@report.pdf" \
  -F "language=en-US" \
  -F "editing_phase=pre-edit" \
  -F "order_id=ORD-2026-0417" \
  -F "job_id=JOB-9812" \
  -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-US",
    "editing_phase": "pre-edit",
    "meta": {"jobid": 123, "campaign": "Q3-2026"},
    "order_id": "ORD-2026-0417",
    "job_id": "JOB-9812",
    "status": "pending",
    "source": "api",
    "correction_count": null,
    "word_count": 3420,
    "tokens_charged": 4,
    "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 a 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-US",
    "status": "completed",
    "source": "api",
    "correction_count": 5,
    "word_count": 3420,
    "tokens_charged": 4,
    "ai_tells": { "count": 1, "per_1000_words": 0.3 },
    "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 present only when the document was submitted with review=true. See “Human review by a Proofed editor” for details.

Cancel a document

Cancel a pending or processing document. Completed, failed or already-canceled documents cannot be canceled (the request 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 and the review is pending or submitted, canceling also cancels the review (and sends a proofed_review.canceled webhook). When the review is in_progress or delivered, the cancel returns 422, because we cannot cancel the Proofed order from our side. Contact support.

Response 200 OK

{
  "message": "Document canceled."
}

Diff (tracked changes)

Turn two versions of a document into one file that shows what changed. A DOCX comes back with real Word tracked changes; HTML and blocks get del/ins markup; a PDF gets annotations; PPTX gets native comments.

This endpoint is synchronous. No AI model runs, so there is nothing to poll for, and the response body is the file. Expect a second or two for a short document and up to a minute for a long PDF.

The edited copy is required; the original usually is not

Always send the edited copy. It can be a clean copy with no tracked changes of its own: adding the tracked changes is this endpoint’s job. For the original, you have three options, and only one of them needs an upload:

• Send original_file yourself.
• Send order_id, and we use the original from the completed pre-edit we already hold for that order. We match your explicit order_id first, then the order-prefixed file name convention (“51656_report.docx”).
• Send document_id (the uuid from a previous submission) to name the pre-edit exactly.

We search only your own documents. If none of the three gives us an original, you get a 422 rather than an empty diff. A file with no changes in it and a file we could not build are different answers, and you should not have to guess which one you got.

Parameters

Response

200, with the file as the body. Content-Disposition names it “tracked-changes-<your file name>”. The X-Diff-Original-Source header says which original we used: “upload”, or “pre-edit:<uuid>” when we found it for you.

422 when the edited copy is missing, when no original can be found or when the two files are in different formats. 502 when we could not build the diff itself.

Examples

# Both files, saving the result
curl -X POST https://proofed.ai/api/v1/diff \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "original_file=@original.docx" \
  -F "editor_file=@edited.docx" \
  -o tracked-changes.docx

# Let us find the original from the order number
curl -X POST https://proofed.ai/api/v1/diff \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "editor_file=@edited.docx" \
  -F "order_id=51656" \
  -F "author=Editorial Team" \
  -o tracked-changes.docx

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 give a webhook_url when you submit a document, we send a POST request to that URL when processing ends (completed or failed).

Webhook payload

{
  "event": "document.completed",
  "document": {
    "uuid": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "filename": "report.pdf",
    "status": "completed",
    "correction_count": 5,
    "order_id": "ORD-2026-0417",
    "job_id": "JOB-9812",
    "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. We retry delivery up to 3 times, 30 seconds apart. We treat any non-2xx response as a failure and retry it.

document.completed payloads include a download_url: a signed URL, valid for 24 hours, for the AI-proofread output file. The signature is the authentication, so do not send a Bearer token to it. The field is missing if no processed file was produced.

To fetch the full corrections, call the “Get a document” endpoint with the uuid from the payload.

Download the proofread file

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

Authentication is by signed URL only, so do not send an Authorization header. Use the download_url from the “Get a document” response or the document.completed webhook payload. The URL is valid for 24 hours from issue; each “Get a document” response gives 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 and live status

If you cannot receive webhooks, poll the “Get a document” endpoint. We recommend a 15-second interval while status is pending or processing. How long a document takes depends on its length.

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 by a Proofed editor

An optional extra step: after the AI proofread completes, you can send the document to a Proofed editor for a human review. The editor returns a final reviewed file, which you fetch from a signed URL.

A review costs $60 per 1,000 words, paid by card on the document’s page at proofed.ai. The API cannot take a card, so we refuse review=true from an account that pays for reviews with a 402, before anything is stored or charged. Send the document without it, then choose “Get a human review” on its page. Service accounts are not charged and can ask with review=true.

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

ProofedAI also offers editor quality reviews: upload an original document and an editor’s version, and the AI assesses the editor’s work against a baseline proofread. You get a structured feedback report with a score and categorized findings.

What it produces

• An overall score: Excellent, Satisfactory, Minor changes needed or Major changes needed.
• A narrative summary of strengths and areas for improvement.
• Categorized feedback: caught correctly, missed issues, introduced errors, unnecessary changes and good editorial judgment.
• Statistics: catch rate, counts by category and a severity breakdown.
• A downloadable DOCX feedback report.

How to access

Admins submit reviews at /admin/reviews/submit in the ProofedAI web app. Users with editor review access submit at /reviews/submit. DOCX files with tracked changes are fully supported: we read the “final accepted” version of the editor’s work.

Reviewer feedback

Reviewer feedback compares a reviewer’s final copy with the editor’s final copy. It works out why the reviewer made each change by matching it to the style guide, then returns feedback grouped by rule that the reviewer can scan, adjust and send to the editor. It saves reviewers time when they give constructive feedback.

Lifecycle

Feedback jobs move through pending → processing → completed / failed / cancelled, the same states as documents. How long a job takes depends on the document’s length and the 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 "original_file=@original-pre-edit.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",
    "original_filename": "original-pre-edit.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",
    "original_filename": "original-pre-edit.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 did 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.",
        "origin": "missed",
        "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 canceled."
}

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

# with your API token
curl https://proofed.ai/api/v1/reviewer-feedback/{uuid}/delta \
  -H "Authorization: Bearer your-api-token" \
  -o tracked-changes.docx

# or with the signed delta_url from the job (no token required)
curl -L "$DELTA_URL" -o tracked-changes.docx

{
  "event": "reviewer-feedback.completed",
  "reviewer_feedback": {
    "uuid": "7c2a1d5e-3f4b-4c6d-8e9f-0a1b2c3d4e5f",
    "editor_filename": "editor-final.docx",
    "reviewer_filename": "reviewer-final.docx",
    "original_filename": "original-pre-edit.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

Check the factual claims in a document against your Stylus style guide’s ground truth and the live web. Each claim comes back 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