Inspect API · Tagviu Docs

HTTP API

Inspect any public URL

The same pipeline that powers the web UI. Send a public http or https URL and receive score, diagnostics, platform previews, and image analysis. Loopback and private addresses are always blocked - use Dev Mode for those.

Endpoint

POST https://tagviu.orashus.com/api/inspect

Accept: application/json
Query: save (optional; presence persists a LocalPreview)
Body: { "url": "https://…" }; with ?save also usedBy (secret is the x-tagviu-api-key header)

?save persists a LocalPreview and adds data.url. Requires x-tagviu-dev: true and x-tagviu-api-key. The web UI does not set these flags.

Related routes

/r/[id] - public frozen report snapshot
/r/live?url=… - live inspection page (refreshes on each load)
/local-preview/[id] - ephemeral Dev Mode local preview

Response envelope

All responses use the same shape: message, status, and data.

fetch
Requested vs final URL, HTTP status, content type, HTML length.
rawMetadata
Standard, Open Graph, and Twitter tags as extracted from HTML.
normalizedMetadata
Resolved title, description, image, and fallbacks with source tracking.
diagnostics
Findings grouped by severity with suggested fixes.
tagviuScore
Score (0-100), category, and deduction breakdown.
platformPreviews
Simulated previews for X, Facebook, LinkedIn, and others.
platformCompatibility
Per-platform compatibility summary and warnings.
imageAnalysis
Live social image fetch - dimensions, format, reachability.
durationMs
End-to-end processing time in milliseconds.
url
Present only when ?save is set: the LocalPreview page (/local-preview/lp_…).

curl

Pipe to jq to pretty-print JSON

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page"}' \
  https://tagviu.orashus.com/api/inspect

Success (200)

{
  "message": "Inspection complete.",
  "status": 200,
  "data": {
    "fetch": { "finalUrl": "https://example.com/page", "status": 200, … },
    "tagviuScore": { "score": 87, "category": { … }, … },
    "diagnostics": [ … ],
    "platformPreviews": [ … ],
    "imageAnalysis": { … },
    "durationMs": 1240
  }
}

Error (4xx / 5xx)

{
  "message": "Enter a valid http or https URL.",
  "status": 400,
  "data": { "code": "INVALID_INPUT" }
}

Error codes

INVALID_INPUT
HTTP 400
Malformed JSON, missing url, or invalid save payload.
FORBIDDEN
HTTP 403
?save without x-tagviu-dev: true.
INVALID_URL
HTTP 400
URL failed client-side validation.
BLOCKED_HOST / BLOCKED_ADDRESS
HTTP 403
SSRF protection blocked the target (including localhost and private addresses).
UNSUPPORTED_PROTOCOL
HTTP 400
Only http and https are allowed.
TIMEOUT
HTTP 504
Remote page did not respond in time.
RESPONSE_TOO_LARGE
HTTP 413
Page or image exceeded size limits.
UNSUPPORTED_CONTENT_TYPE
HTTP 415
Target is not an HTML page.
HTTP_ERROR / FETCH_FAILED
HTTP 502
Remote server error or unreachable URL.
INTERNAL_ERROR
HTTP 500
Unexpected server error.

Code	HTTP	Meaning
INVALID_INPUT	400	Malformed JSON, missing url, or invalid save payload.
FORBIDDEN	403	?save without x-tagviu-dev: true.
INVALID_URL	400	URL failed client-side validation.
BLOCKED_HOST / BLOCKED_ADDRESS	403	SSRF protection blocked the target (including localhost and private addresses).
UNSUPPORTED_PROTOCOL	400	Only http and https are allowed.
TIMEOUT	504	Remote page did not respond in time.
RESPONSE_TOO_LARGE	413	Page or image exceeded size limits.
UNSUPPORTED_CONTENT_TYPE	415	Target is not an HTML page.
HTTP_ERROR / FETCH_FAILED	502	Remote server error or unreachable URL.
INTERNAL_ERROR	500	Unexpected server error.