POST /api/analyze — Submit Text for FME Analysis

POST /api/analyze is the core endpoint of the Rhetoric Audit API. You send article text and optional metadata; the FME V19.1 engine returns a structured forensic evaluation covering ideology classification, manipulation risk, logical fallacies, emotional resonance, source reliability, and more. Responses are cached by URL and content hash — repeated submissions of the same article return instantly at no cost.

Endpoint

POST https://www.rhetoricaudit.com/api/analyze
Content-Type: application/json

Request

string

required

The full text of the article to analyze. Must be between 100 and 100,000 characters. Strip HTML before submitting — the engine expects plain text.

string

The article title. Optional but recommended — improves classification accuracy and appears in the cached scan record.

string

The canonical URL of the article. Used to deduplicate identical content across requests. If omitted, deduplication falls back to a hash of the first 100 characters of text.

string

Your Rhetoric Audit user ID. Required to access the signed_free or paid tier. See Authentication.

string

A stable client-generated UUID. Required when no userId is present. At least one of userId or deviceId must be included.

string

default:"web"

Where the request originates. Accepted values: extension, web, api, share, popup. Pass api for third-party integrations. This value is stored in the scan event log.

Response

A successful 200 response includes all V18.6 core fields plus optional V19 additive fields when the V19 pipeline is active. The fields below are always present.

Identity and metadata

string

The FME schema version used to produce this response, e.g. "V18.6" or "19.1-bridge".

string

The LLM model that produced the analysis, e.g. "openai/gpt-4o-mini".

string

ISO 8601 timestamp of when the analysis was run (or when the cached scan was originally created).

string

The article title, echoed from the request or "Untitled" if not provided.

string

The normalized canonical URL, echoed from the request.

number

LLM round-trip time in milliseconds. 0 on cache hits.

Ideology classification

string

A short label describing the dominant philosophical framing of the article, e.g. "Nationalist Realism".

number

Score from -100 (far left) to 100 (far right).

number

Confidence in the ideology classification, 0–100.

boolean

true when the article’s ideological framing is intentionally ambiguous or multi-valent.

object

Scores for each of the ten FME ideology dimensions, each 0–100.

string

The ideology with the highest score.

string

The ideology with the second-highest score.

number

The numerical gap between the winner and second_place scores. A low gap combined with ambiguity_flag: true indicates weak classification.

Manipulation and logic

number

Overall manipulation risk, 0–100. Higher values indicate more persuasive technique density.

number

Density of logical fallacies relative to article length, 0–100.

array

Array of detected logical fallacies. Empty when none are found.

Show logic_fractures item fields

string

Name of the logical fallacy, e.g. "Ad Hominem" or "False Dichotomy".

string

The verbatim excerpt from the article where the fallacy appears.

string

A brief explanation of how this fallacy distorts the argument.

number

Quality of the evidentiary support in the article, 0–100.

Emotion and narrative

object

The three dominant emotional levers detected in the text.

string

The story structure the article follows, e.g. "Us vs. Them" or "Hero's Journey".

string

A prose description of information the article omits that would materially change its framing.

string

A detailed analytical narrative written at doctoral level, synthesizing all FME dimensions into a single interpretive summary.

Source and credibility

number

How transparent the article is about its intent and perspective, 0 (fully obfuscating) to 100 (fully informing).

string

Depth-of-knowledge rating: "DOK-1" through "DOK-4".

number

Publisher reliability score, 0–10. Derived from a known-publisher lookup table; for unknown publishers the LLM estimate is pulled toward the mean.

string

Predicted contribution to social volatility: "LOW", "MOD", or "HIGH".

string | null

Detected publisher name, or null if not identified.

string | null

Detected author name, or null if not identified.

Cache and quota

boolean

true if this response was served from the cache. Cache hits do not consume quota or credits.

string

Internal UUID of the scan record. Present on both cache hits and fresh analyses.

string

Short alphanumeric ID for this scan. Use it to retrieve the scan later via GET /api/scans/{shortcode} or share it at https://www.rhetoricaudit.com/s/{shortcode}.

boolean

Whether the scan is publicly accessible via its shortcode URL.

boolean

true when the requesting deviceId matches the device that originally created the scan.

string

The tier under which this request was processed: anon, signed_free, paid, or bench.

object | null

Present for anon and signed_free tiers; null for paid.

number

Remaining credit balance after this request. Only present for paid tier on cache misses.

Code examples

curl -X POST https://www.rhetoricaudit.com/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your article text goes here (minimum 100 characters)...",
    "title": "Example Article",
    "url": "https://example.com/article",
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "source": "api"
  }'

const response = await fetch('https://www.rhetoricaudit.com/api/analyze', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    text: 'Your article text goes here (minimum 100 characters)...',
    title: 'Example Article',
    url: 'https://example.com/article',
    deviceId: '550e8400-e29b-41d4-a716-446655440000',
    source: 'api',
  }),
});

const data = await response.json();
console.log(data.winner);                  // top ideology
console.log(data.manipulation_risk_score); // 0–100
console.log(data.shortcode);               // e.g. "abc123"

Error responses

Status	Meaning	When it occurs
`400`	Bad request	`text` is missing, under 100 chars, or no identity fields provided
`422`	Not an article	The junk filter rejected the content (e.g. login pages, blank tabs)
`429`	Rate limit exceeded	Daily quota exhausted for `anon` or `signed_free` tier
`500`	Analysis failed	Unexpected server error
`502`	Invalid AI response	The LLM returned malformed JSON that could not be parsed into the V18.6 schema
`503`	AI service unavailable	Both the primary and fallback AI models are unavailable — retry with exponential backoff

The 422 response includes a reason field with a short string describing why the content was rejected, and rejected: true. This is normal for pages that are not news articles — for example, the Chrome extension gates on this check client-side before sending to the API.

Overview

Endpoints

POST /api/analyze — Submit Text for FME Analysis

Endpoint

Request

Response

Identity and metadata

Ideology classification

Manipulation and logic

Emotion and narrative

Source and credibility

Cache and quota

Code examples

Error responses

​Endpoint

​Request

​Response

​Identity and metadata

​Ideology classification

​Manipulation and logic

​Emotion and narrative

​Source and credibility

​Cache and quota

​Code examples

​Error responses

Endpoint

Request

Response

Identity and metadata

Ideology classification

Manipulation and logic

Emotion and narrative

Source and credibility

Cache and quota

Code examples

Error responses