Ship page-quality checks inside your workflow

This is an asynchronous complete page-quality review API for external developers. text, html, and public URLs all run the same page-quality-review.full.v1 rules; public URLs also add desktop, mobile, browser-interaction, and visible-load evidence. The service never signs in to target pages or forwards your cookies or session.

The documentation is public. Only the API-key console requires a login. Sign in to the account center to create a key; the secret is shown once.

curl https://convertos.ai/api/v1/reviews/page-quality/REVIEW_ID \
  -H "Authorization: Bearer cvt_live_YOUR_KEY"

Create or manage API keys in the account center →

1. 01

   Sign in and create an API key.

2. 02

   Send text, html, or a public URL; every request runs the complete review.

3. 03

   Keep the job ID and poll statusUrl until completed or failed.

curl -X POST https://convertos.ai/api/v1/reviews/page-quality \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: review-001" \
  -d '{
    "sourceType": "url",
    "url": "https://example.com/article",
    "language": "en",
    "mode": "standard",
    "pageType": "blog_article",
    "targetJob": "Answer the searcher’s question and give them a next action."
  }'

{
  "ok": true,
  "job": {
    "id": "8c1b...",
    "status": "queued",
    "creditCost": 20,
    "statusUrl": "/api/v1/reviews/page-quality/8c1b..."
  }
}

A successful submission returns 202. Credits are reserved when the job is accepted and automatically refunded if the queue or review fails.

The Idempotency-Key header is optional but recommended. Reuse it when retrying a network request to avoid duplicate jobs or charges.

batch accepts 3 to 5 related pages. Every page runs the same complete review, followed by a cross-page similarity check. A batch can fail for structural sameness even when individual scores are high.

curl -X POST https://convertos.ai/api/v1/reviews/page-quality/batch \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-001" \
  -d '{
    "mode": "batch",
    "language": "en",
    "pages": [
      {"label":"Page A","sourceType":"url","url":"https://example.com/a","mode":"standard","pageType":"programmatic"},
      {"label":"Page B","sourceType":"url","url":"https://example.com/b","mode":"standard","pageType":"programmatic"},
      {"label":"Page C","sourceType":"url","url":"https://example.com/c","mode":"standard","pageType":"programmatic"}
    ]
  }'

Use the job.id or statusUrl returned by creation. Only the same API key that created the job can read it.

curl https://convertos.ai/api/v1/reviews/page-quality/REVIEW_ID \
  -H "Authorization: Bearer cvt_live_YOUR_KEY"

A completed job returns preflight, contracts, competitiveBaseline, seven dimensions, gates, caps, threshold, evidence, findings, and aiAnalysis. Rules cover technical facts and safety limits; AI judges intent, accuracy, evidence, originality, and E-E-A-T from the actual page and participates in the final verdict.

{
  "version": "page-quality-review.v1",
  "reviewProtocol": "page-quality-review.full.v1",
  "verdict": "iterate",
  "score": 74,
  "confidence": "medium",
  "mode": "standard",
  "sourceType": "html",
  "summary": "...",
  "gates": [{"name":"rendered_experience","outcome":"pass","reason":"..."}],
  "caps": {"applied": [], "finalScoreCap": null},
  "threshold": {"scoreRequired": 85, "minCoreDimension": 75, "coreDimensionsMeetMinimum": true},
  "aiAnalysis": {
    "provider": "agentsflare",
    "scope": "content_quality",
    "status": "completed",
    "verdict": "iterate",
    "score": 78,
    "summary": "...",
    "findings": [{
      "code": "AI_CONTENT_NEXT_STEP",
      "message": "The opening explains the topic but does not make the next action explicit.",
      "recommendation": "Add one concrete next step after the opening answer.",
      "evidence": "The opening section states the topic but contains no action instruction."
    }],
    "eeat": {
      "experience": {"score": 72, "status": "partial", "note": "Some practical examples are present, but first-hand experience is not established.", "evidence": "The page gives examples but does not identify a first-hand source."},
      "expertise": {"score": 80, "status": "partial", "note": "The topic is explained with relevant detail.", "evidence": "The page explains the criteria and tradeoffs."},
      "authoritativeness": {"score": 65, "status": "not_evidenced", "note": "No accountable authority is supplied.", "evidence": "No author organization or external citation is visible."},
      "trustworthiness": {"score": 74, "status": "partial", "note": "Claims are mostly bounded but proof is limited.", "evidence": "The page contains claims without nearby attributable sources."}
    }
  },
  "dimensions": {
    "contentIntent": { "score": 82, "status": "inspected", "notes": [] },
    "seoIndexability": { "score": 68, "status": "inspected", "notes": [] },
    "geoExtractability": { "score": 76, "status": "inspected", "notes": [] }
  },
  "metrics": {
    "wordCount": 820,
    "headingCount": 9,
    "h1Count": 1,
    "hasTitle": true,
    "hasDescription": true
  },
  "findings": [
    {
      "severity": "warning",
      "code": "IMAGE_ALT",
      "message": "...",
      "recommendation": "..."
    }
  ]
}

Each finding includes severity, code, message, and recommendation, so you can map it to your own issue tracker, workflow, or release gate.

Billing is based on input type, not result length; every input runs the complete review. Credits are reserved when the API accepts a job and automatically refunded when the queue or review fails.

These limits protect the shared queue and credit accounts. Your client should handle 429, 402, and 413 responses explicitly.

Deployment note: complete URL reviews require PAGE_REVIEW_BROWSER_WS_URL or BROWSERLESS_URL in production. Without a remote browser, the service does not fake rendered evidence or return a 500; it marks the browser evidence incomplete and keeps the result at iterate.

Errors use one JSON shape: ok=false, error.code, and error.message; some errors include details. Retry network timeouts or 5xx responses, but do not blindly retry invalid input or authentication errors.

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "This API key has reached 60 accepted reviews per minute.",
    "details": { "retryAfterSeconds": 60 }
  }
}