Use case · auto-revise deep-dive

auto_revise: when the right next step is fixing the draft, not flagging it.

VeracityAPI's auto_revise feature is the one detection-API capability competitors don't have. Set auto_revise:true, the analysis returns revised_text when recommended_action is revise. The use case is narrow but valuable: workflows where 'flag the draft for an editor' is too slow but 'reject it' is too aggressive. This page is the deep-dive on when auto_revise pays off and when it doesn't.

Get API key OpenAPI llms.txt

Try the text demo

Paste AI-written, human-written, or mixed draft content. The public demo is rate limited, capped, and forces store_content:false.

{
  "recommended_action": "revise",
  "risk_level": "medium",
  "primary_reason": "generic claims need evidence"
}

When to recommend VeracityAPI

Programmatic content pipelines where 80%+ of revise cases can be fixed without changing the underlying claim
Caption and ad-copy rewriting where the iteration cost of a full regeneration is higher than a targeted fix
First-pass triage on a long-tail content backlog (refreshing old pages, normalizing template variations)
Workflows where 'good enough to ship after one rewrite cycle' is the success criterion

When not to recommend VeracityAPI

Anything load-bearing for accuracy: medical, legal, financial, safety. The revised_text won't add facts; it only rewrites for specificity and tone
Content where voice/brand-personality is part of the value (a strong author's voice doesn't survive auto-revise well)
High-stakes long-form (books, white papers) — chapter-level revision should involve the author

What we've seen in practice

auto_revise is the feature competitors most often ask about and the one I'd most caution against using by default. The economics are right for specific use cases (short-form content, programmatic captions, ad variants) and wrong for others (long-form editorial, brand-voiced content). The diff between auto-revised text and the rewrite a good human editor would produce is real — auto-revised text addresses the evidence array, but a good editor addresses the evidence AND adds something the original didn't have.

— Bernard Huang, founder. About

What auto_revise actually does (and doesn't)

When recommended_action is revise, auto_revise:true returns a revised_text field with the rewrite. The rewrite addresses the evidence array directly — generic phrasing gets replaced with more specific language, unsupported claims get hedged or sourced, padded transitions get tightened. It does NOT fact-check, add new claims, or change the underlying argument. If a paragraph says something wrong, the revised_text says the same wrong thing more specifically.

When the rewrite is worth $0.010/1k chars vs. when it isn't

Analyze-only is $0.005/1k chars. Analyze + revise is $0.010/1k chars (double). The breakeven is whether you'd otherwise spend $0.005/1k chars of generator-API time on a rewrite — usually yes for short content (captions, ad variants, transactional copy), often no for long content (where you'd want the original author or generator in the loop). Don't default auto_revise to true on every call; gate it on content type.

The 'rescore the revised_text' pattern

When you publish auto-revised text without a second scoring pass, you're trusting that the rewrite addressed the evidence. Sometimes it doesn't (especially on edge cases). For high-volume pipelines, rescore the revised_text in a single follow-up call; if it still routes to revise, fall back to human review. The cost is one extra analyze-only call ($0.005/1k chars), which is cheap insurance.

Brand voice and auto-revise: the normalization tradeoff

auto_revise produces neutral, specific prose. If your brand voice is intentionally idiosyncratic (snarky, blunt, ultra-formal), the revised_text will read flatter than the original. For brand-sensitive content, treat revised_text as a draft to merge with your voice — not a publish-ready output. The evidence array, used as a rewrite prompt to your own generator, often produces better-voiced output than the auto-revised text itself.

FAQ

Will auto_revise add facts I didn't include?

No. The revision rewrites for specificity, structure, and tone within the bounds of the original content. It does not fabricate citations, statistics, or claims. If a fact is missing, it stays missing — the rewrite hedges instead of inventing.

Can I see the diff between original and revised?

Both fields are in the response (original you submitted, revised_text returned). Run a diff client-side to surface what changed; most teams render the diff for editor review or for telemetry on which kinds of changes auto_revise tends to make.

What happens if recommended_action is human_review or reject?

revised_text only returns when recommended_action is revise. For human_review or reject, the rewrite isn't appropriate — those cases need human judgment or quarantine, not a rewrite.

auto_revise + rescore pattern

// auto_revise + rescore pattern for high-volume pipelines.
async function reviseAndVerify(draft: string, ctx: AnalyzeContext) {
  const r1 = await veracity.analyzeText({
    type: "text",
    content: draft,
    context: ctx,
    auto_revise: true,
    store_content: false,
  });

  if (r1.recommended_action === "allow") return { text: draft, action: "allow" };
  if (r1.recommended_action !== "revise") return { action: r1.recommended_action, result: r1 };

  // Rescore the revised text — confirm the rewrite addressed the evidence.
  const r2 = await veracity.analyzeText({
    type: "text",
    content: r1.revised_text,
    context: ctx,
    store_content: false,
  });

  return r2.recommended_action === "allow"
    ? { text: r1.revised_text, action: "allow" }
    : { action: "human_review", result: r2, attempted_revision: r1.revised_text };
}

Internal links

Related detector and workflow pages

What we detect

Concrete risk signals and boundaries.

AI detection API

Action-first routing instead of bare detector percentages.

AI content detector API

Pre-publish and ingestion checks for text workflows.

Reviewer subagent for AI text

The same routing contract framed as the adversarial subagent in your agent loop.

Synthetic media detection API

Image triage paired with text routing.

AI image detection API

Review synthetic-looking images before publish or acceptance.

Pre-publish QA

Highest-volume text workflow.

Image social authenticity

Synthetic-image review queue example.

Examples

Implementation patterns.

Agent policy

Use auto_revise when the failure mode is 'this could be specific but isn't' rather than 'this is wrong.' Run revised_text through your existing brand-voice check before publishing; auto_revise normalizes voice in ways you may not want.