Orivfy Text Detection API

Old vs new · read this first

This section is the handoff summary for the frontend team. It states exactly what existed before, what this release adds, and what must remain untouched during migration.

Before this update (already integrated)

Important distinction: before this release, this standalone text service did not expose the improved Document authenticity engine or Citation verification. document-forensics is not being renamed or removed; it remains its own specialized endpoint.

New in this update (frontend opt-in)

What “no downtime” means here

• API compatibility: old frontend builds continue using all old routes unchanged while new frontend builds adopt the new routes.
• Frontend rollout: new features should be feature-flagged and enabled gradually; no big-bang replacement is required.
• Do not remove aliases: keep the Document authenticity compatibility alias until cached/older frontend clients have been retired.
• Infrastructure deployment: true zero-downtime server deployment requires a second ready API instance behind the load balancer. A restart of the current single-GPU instance has a model warm-up window and cannot itself guarantee zero transport downtime.

Frontend starting point: leave the current API client untouched. Create a separate documentScan client and a separate citationVerification client using the shared asynchronous polling helper in No-downtime frontend migration.

Authentication

Every REST request must include secret_key matching the server SECRET_KEY in .env. Invalid or missing key: 403.

• POST JSON — secret_key in the body alongside text.
• Multipart uploads — secret_key as a form field with file.
• Polling/report GETs — send X-API-Key: <secret_key>. A deprecated ?secret_key= fallback is accepted for migration only.

WebSockets: include secret_key in the first JSON frame.

Endpoints overview

Compatibility: the four existing scan paths and their request/response bodies are unchanged. New clients opt into the new paths; old clients continue operating during rollout.

Polar charts: POST …/ai-scan and POST …/deep-scan both return radar_axes[] — five heuristic dimensions (integer 0–100 each) keyed for stable UI bindings. Derived from submitted text, passage ai_score, and the verdict probability inferred on the server (same basis as Dashboard confidenceValue). Axis semantics and a reference table → Radar axes.

AI scan (passage)

/api/v1/scan/ai-scan — Full-passage classification: Human, AI, or Uncertain. Legacy field confidence is passage-level P(AI) (same numeric value as ai_score). Response includes radar_axes[] for polar charts (passage-aligned heuristics). Optional source_attribution when the passage is flagged AI (vendor hints: OpenAI, Gemini, Claude).

{
  "secret_key": "<server SECRET_KEY from .env>",
  "text": "Your passage …",
  "config": null
}

{
  "prediction": "AI",
  "confidence": 0.71,
  "is_mixed": false,
  "is_ai": true,
  "ai_score": 0.71,
  "mixed_score": 0.0,
  "human_score": 0.29,
  "radar_axes": [
    {"key": "ai_signal", "label": "AI Signal", "value": 71},
    {"key": "uniformity", "label": "Uniformity", "value": 62},
    {"key": "confidence", "label": "Confidence", "value": 71},
    {"key": "perplexity", "label": "Perplexity", "value": 54},
    {"key": "burstiness", "label": "Burstiness", "value": 58}
  ],
  "source_attribution": {
    "status": "ok",
    "likely_source": "openai",
    "likely_label": "OpenAI",
    "confidence": 0.42,
    "margin": 0.11,
    "candidates": [
      {"source": "openai", "label": "OpenAI", "score": 0.42},
      {"source": "gemini", "label": "Google Gemini", "score": 0.28}
    ],
    "source_display": {
      "kind": "single",
      "options": [{"source": "openai", "label": "OpenAI · ChatGPT"}],
      "show_confidence": true
    },
    "evidence": ["HF RoBERTa ChatGPT-detector affinity ≈ 62%"],
    "method": "hf_chatgpt_roberta+lmscan",
    "word_count": 312,
    "detail": null
  }
}

Deep scan (sentences)

/api/v1/scan/deep-scan — Sentence windows with neighbor context; each row exposes prediction, ai_probability (P(AI)), and optional model fields when enabled. Passage-level P(AI) appears as ai_score (alongside human_score). Dual verdicts: passage_verdict + distribution_verdict; distribution_confidence tiers the sentence-mix label. radar_axes[] mirrors the passage headline (same inputs as AI scan)—not recomputed from raw sentence-frequency counts alone.

{
  "secret_key": "<server SECRET_KEY from .env>",
  "text": "Your document …",
  "config": null
}

{
  "sentences": [
    {
      "sentence": "…",
      "prediction": "AI",
      "ai_probability": 0.94
    }
  ],
  "distribution_confidence": 0.72,
  "passage_verdict": "AI",
  "distribution_verdict": "AIWrittenHumanModified",
  "deep_labels": ["AI", "AIWrittenHumanModified"],
  "overall_prediction": "AI",
  "is_mixed": false,
  "mixed_ratio": 0.45,
  "ai_score": 0.71,
  "mixed_score": 0.12,
  "uncertain_sentence_ratio": 0.12,
  "human_score": 0.29,
  "radar_axes": [
    {"key": "ai_signal", "label": "AI Signal", "value": 71},
    {"key": "uniformity", "label": "Uniformity", "value": 62},
    {"key": "confidence", "label": "Confidence", "value": 68},
    {"key": "perplexity", "label": "Perplexity", "value": 54},
    {"key": "burstiness", "label": "Burstiness", "value": 58}
  ],
  "source_attribution": { }
}

Documents

{
  "doc_type": "docx",
  "filename": "report.docx",
  "suspicion_score": 0.34,
  "verdict": "Inconclusive",
  "signals": [ ],
  "editing_behaviour": { },
  "summary": "…"
}

{
  "job_id": "b7c2…",
  "kind": "document_scan",
  "filename": "invoice.pdf",
  "status": "queued",
  "stage_message": "Queued",
  "result": null,
  "error": null,
  "created_at": 1786300000.1,
  "updated_at": 1786300000.1
}

GET /api/v1/scan/document-scan/jobs/{job_id}
X-API-Key: <server SECRET_KEY>

{
  "batch_id": "8f09…",
  "status": "queued",
  "total_files": 2,
  "jobs": [
    {
      "job_id": "a1…",
      "kind": "document_scan",
      "filename": "contract.docx",
      "status": "queued",
      "stage_message": "Queued",
      "result": null,
      "error": null,
      "created_at": 1786300000.1,
      "updated_at": 1786300000.1
    }
  ],
  "poll_pattern": "/api/v1/scan/document-scan/jobs/{job_id}"
}

Citation verification

{
  "secret_key": "<server SECRET_KEY>",
  "text": "Document text containing citations …",
  "domain": "auto",
  "jurisdiction_preference": "both",
  "enable_context_check": true,
  "use_gemini": true,
  "max_citations": 200
}

After a completed job, download the optional report from /api/v1/citation/report/{session_id} using the returned result.session_id.

No-downtime frontend migration

What changed: the improved Orivfy Document authenticity engine is now presented by this service as Document scan. Citation verification is a separate new module. Both use asynchronous jobs so uploads and provider checks do not hold one HTTP request open. This is an additive release: no existing frontend call needs to be renamed or rewritten.

Compatibility matrix

Shared asynchronous job lifecycle

1. Create: POST the text or file. Accept HTTP 202 and save job_id.
2. Poll: GET the module’s job URL every 1–2 seconds using X-API-Key.
3. Continue: while status is queued or processing, display stage_message.
4. Complete: when status is done, read the module payload from result.
5. Fail safely: when status is error, stop polling and display error with a retry action.
6. Timeout: stop client polling after the UI’s chosen limit; preserve job_id so the user can retry status later.

Copy-ready frontend helper (TypeScript)

type AnalysisJob<T> = {
  job_id: string;
  kind: "document_scan" | "citation_verification";
  filename: string;
  status: "queued" | "processing" | "done" | "error";
  stage_message: string;
  result: T | null;
  error: string | null;
  created_at: number;
  updated_at: number;
};

async function pollJob<T>(
  jobPath: string,
  apiKey: string,
  signal?: AbortSignal,
): Promise<AnalysisJob<T>> {
  for (;;) {
    const response = await fetch(jobPath, {
      headers: { "X-API-Key": apiKey },
      cache: "no-store",
      signal,
    });
    if (!response.ok) throw new Error(`Job poll failed: ${response.status}`);
    const job = (await response.json()) as AnalysisJob<T>;
    if (job.status === "done") return job;
    if (job.status === "error") throw new Error(job.error || "Analysis failed");
    await new Promise(resolve => setTimeout(resolve, 1500));
  }
}

Document scan frontend flow

const form = new FormData();
form.append("secret_key", apiKey);
form.append("file", selectedFile);

const createdResponse = await fetch("/api/v1/scan/document-scan", {
  method: "POST",
  body: form,
  cache: "no-store",
});
if (createdResponse.status !== 202) {
  throw new Error(`Document scan was not queued: ${createdResponse.status}`);
}
const created = await createdResponse.json();
const completed = await pollJob(
  "/api/v1/scan/document-scan/jobs/{job_id}".replace("{job_id}", created.job_id),
  apiKey,
);
const documentResult = completed.result;

Document scan batch flow

const form = new FormData();
form.append("secret_key", apiKey);
for (const file of selectedFiles) form.append("files", file);

const createdResponse = await fetch("/api/v1/scan/document-scan/batch", {
  method: "POST",
  body: form,
  cache: "no-store",
});
if (createdResponse.status !== 202) {
  throw new Error(`Document batch was not queued: ${createdResponse.status}`);
}
const batch = await createdResponse.json();
const completedJobs = await Promise.all(
  batch.jobs.map(job =>
    pollJob(
      batch.poll_pattern.replace("{job_id}", job.job_id),
      apiKey,
    ),
  ),
);
const documentResults = completedJobs.map(job => job.result);

Keep each file’s job_id, status, error, and result separate so one failed file does not hide successful files in the same user-selected batch.

Recommended UI mapping for documentResult.outcome:

• Use requires_manual_review as the workflow control; do not infer it from colors.
• Show risk_score as a risk indicator, not calibrated probability or accuracy.
• Render limitations[] and allow model_evidence.status or optional tools to be unavailable.
• Use stable evidence keys (category, code, severity, description); ignore unknown future fields.

Citation verification frontend flow

const createdResponse = await fetch("/api/v1/citation/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    secret_key: apiKey,
    text: documentText,
    domain: "auto",
    jurisdiction_preference: "both",
    enable_context_check: true,
    use_gemini: true,
    max_citations: 200,
  }),
  cache: "no-store",
});
if (createdResponse.status !== 202) {
  throw new Error(`Citation verification was not queued: ${createdResponse.status}`);
}
const created = await createdResponse.json();
const completed = await pollJob(
  "/api/v1/citation/jobs/{job_id}".replace("{job_id}", created.job_id),
  apiKey,
);
const { session_id, summary, items } = completed.result;

• Summary cards: total_citations, green_count, yellow_count, red_count, compliance_index.
• For each item, render citation_text, status, classification, existence_verified, and evidence links.
• green = verified; yellow = mismatch/typo/review; red = not verified. Always include text labels for accessibility.
• Build the PDF report URL by replacing {session_id} in /api/v1/citation/report/{session_id}.

Recommended release sequence

1. Backend first: deploy and smoke-test discovery/OpenAPI plus the new routes. Leave all existing frontend calls untouched.
2. Frontend code, feature off: ship job types, polling helper, result components, and retry/error states behind flags.
3. Internal rollout: enable Document scan for staff/test users and compare displayed evidence with raw API responses.
4. Public document rollout: enable gradually; keep the old Document authenticity alias available during cached-client rollout.
5. Citation rollout: enable separately because it uses external providers and may have different latency/error behavior.
6. Rename UI: after validation, change visible copy from “Document authenticity” to “Document scan.” Do not redirect or remove stable legacy scan routes.

Secret handling: the current API contract accepts secret_key because that is how the already-integrated text service authenticates. Prefer calling this service through your own server-side frontend/API proxy; do not compile a production server secret into public browser JavaScript.

WebSocket · explanations

Open WebSocket → send one JSON text frame. Use wss: when API is HTTPS.

{
  "secret_key": "…",
  "prediction": "AI",
  "overall_prediction": "AI",
  "passage_verdict": "AI",
  "distribution_verdict": "AIWrittenHumanModified",
  "confidence": 0.71,
  "distribution_confidence": 0.72,
  "text": "",
  "ai_score": 0.71,
  "human_score": 0.29,
  "mixed_score": 0.12,
  "radar_axes": [
    {"key": "ai_signal", "label": "AI Signal", "value": 71},
    {"key": "uniformity", "label": "Uniformity", "value": 62},
    {"key": "confidence", "label": "Confidence", "value": 68},
    {"key": "perplexity", "label": "Perplexity", "value": 54},
    {"key": "burstiness", "label": "Burstiness", "value": 58}
  ],
  "sentences": [
    {
      "sentence": "…",
      "prediction": "Human",
      "ai_probability": 0.19
    }
  ]
}

Field semantics

Privacy: scans processed in memory; benchmarks only under evaluation_results/.

Labels & confidence

Passage verdict (AI scan & deep scan)

From passage P(AI) vs server threshold ± mixed_offset (default 0.5 ± 0.05):

• P(AI) > 0.55 → AI
• P(AI) < 0.45 → Human
• else → Uncertain (is_mixed: true on AI scan)

On AI scan responses, confidence and ai_score are the same passage-level P(AI) (kept under both names only for backwards compatibility).

Distribution verdict (deep scan only)

Derived from distribution_confidence (0.6 × passage certainty + 0.4 × sentence AI rate):

Source attribution

When passage verdict is AI and text has ≥ 50 words: fused lmscan stylometrics + optional HF ChatGPT-detector. UI should prefer source_display (single, dual, or uncertain) over raw candidates.

Sentence rows

• Each item is one context window (target sentence + neighbors).
• prediction — AI or Human (argmax).
• ai_probability — P(AI) for that window; 0.45–0.55 counts toward uncertain_sentence_ratio.

Radar axes (radar_axes[])

Five deterministic 0–100 integers for polar / spider charts—not extra classifier endpoints. Derived from submitted text, passage-scale ai_score (P(AI)) and the headline verdict probability produced during inference on the wire (aligned with Dashboard confidenceValue rounding).

For UI parity, render radar_axes alongside headline verdict, deep labels (when present), and sentence tallies so charts stay in sync with copy and meters.

Swagger · OpenAPI

/docs · Schema /api/v1/openapi.json