GET /api/scans/{shortcode} — Retrieve a Cached Scan

Every analysis produced by POST /api/analyze is assigned a shortcode — a short alphanumeric identifier that lets you retrieve or share that specific scan. This endpoint returns the full analysis result for any public scan without requiring authentication, making it useful for embedding results or building share flows.

What is a shortcode?

A shortcode is a short alphanumeric string, such as "abc123", returned in the shortcode field of every POST /api/analyze response. It is generated atomically on insert and is globally unique. You can:

Retrieve the scan via GET /api/scans/{shortcode}
Share the scan at https://www.rhetoricaudit.com/s/{shortcode}

Retrieve a scan

GET https://www.rhetoricaudit.com/api/scans/{shortcode}

Path parameter

Parameter	Type	Description
`shortcode`	string	The shortcode returned by `POST /api/analyze`

Authentication

No authentication is required to retrieve a public scan. If the scan owner has set it to private (isPublic: false), this endpoint returns 404.

Response

The response shape is identical to a POST /api/analyze response. All analysis fields are present, including shortcode, cached, isPublic, isOwner, and all FME scoring fields. See POST /api/analyze for the complete field reference.

Example

curl https://www.rhetoricaudit.com/api/scans/abc123

const res = await fetch('https://www.rhetoricaudit.com/api/scans/abc123');

if (res.status === 404) {
  console.error('Scan not found or private');
} else {
  const scan = await res.json();
  console.log(scan.winner);
  console.log(scan.manipulation_risk_score);
}

Error responses

Status	Body	When it occurs
`404`	`{ "error": "not found" }`	Shortcode does not exist or scan is set to private

Toggle scan privacy

Scan owners can control whether their scan is accessible via its shortcode URL.

POST https://www.rhetoricaudit.com/api/scans/{shortcode}/privacy
Content-Type: application/json

Request body

Field	Type	Required	Description
`device_id`	string	Yes	The `deviceId` used when the scan was originally created
`is_public`	boolean	Yes	`true` to make the scan publicly accessible, `false` to restrict it

Response

{ "ok": true, "is_public": false }

Error responses

Status	Body	When it occurs
`400`	`{ "error": "device_id required" }`	Missing or too-short `device_id`
`403`	`{ "error": "not owner" }`	The `device_id` does not match the scan’s owner
`404`	`{ "error": "not found" }`	Shortcode does not exist

Privacy is enforced by device_id rather than account authentication. If you lose the deviceId that was used when the scan was originally created, you will not be able to toggle the privacy of that scan.

Health check

GET /api/analyze returns a status object confirming the API is reachable and showing the current version. This is the same endpoint used for the POST analysis — a GET request to it never triggers analysis.

curl https://www.rhetoricaudit.com/api/analyze

{
  "status": "ok",
  "version": "3.0.0",
  "fme_prompt_version": "V18.6",
  "primary_model": "openai/gpt-4o-mini",
  "fallback_model": "openai/gpt-4.1-nano",
  "cache": "enabled",
  "service": "Rhetoric Audit FME Analysis API",
  "timestamp": "2026-05-09T12:00:00.000Z"
}

Overview

Endpoints

GET /api/scans/{shortcode} — Retrieve a Cached Scan

What is a shortcode?

Retrieve a scan

Path parameter

Authentication

Response

Example

Error responses

Toggle scan privacy

Health check

​What is a shortcode?

​Retrieve a scan

​Path parameter

​Authentication

​Response

​Example

​Error responses

​Toggle scan privacy

​Health check

What is a shortcode?

Retrieve a scan

Path parameter

Authentication

Response

Example

Error responses

Toggle scan privacy

Health check