API Reference

RoastThisPage API

Programmatically roast any landing page and get structured scores, feedback, and fixes — straight from your codebase.

v1RESTJSON

Overview

The API exposes a single endpoint. POST a URL, get back an AI-generated roast with an overall score, per-category scores, and actionable fixes. No API key required — free and open.

POST/api/v1/roast

Endpoint

POSThttps://RoastThisPage.vercel.app/api/v1/roast

Fetches and analyzes a landing page. Returns a roast with scores, feedback, and top fixes.

Request body

urlrequired

string

The full URL of the landing page to roast. Must include the protocol (https://).

json

{ "url": "https://yoursite.com" }

Response

A successful response returns 200 OK with the following fields:

url

string

The URL that was roasted.

overallScore

number

Overall score from 0–100.

grade

string

Letter grade: A, B, C, D, or F.

roast

string

A brutal 2–3 sentence overall impression.

categories

array

Five scored categories: Headline, Value Proposition, Call-to-Action, Social Proof, Copy Quality. Each has name, score (0–10), and feedback.

fixes

array

Three specific, actionable fixes.

json

{
  "url": "https://yoursite.com",
  "overallScore": 62,
  "grade": "C",
  "roast": "This page has the energy of a LinkedIn post ...",
  "categories": [
    { "name": "Headline",         "score": 5, "feedback": "..." },
    { "name": "Value Proposition","score": 7, "feedback": "..." },
    { "name": "Call-to-Action",   "score": 6, "feedback": "..." },
    { "name": "Social Proof",     "score": 4, "feedback": "..." },
    { "name": "Copy Quality",     "score": 6, "feedback": "..." }
  ],
  "fixes": [
    "Rewrite your headline to focus on the outcome, not the feature.",
    "Add at least one testimonial above the fold.",
    "Change your CTA from 'Submit' to something action-oriented."
  ]
}

Examples

curl

curl -X POST https://RoastThisPage.vercel.app/api/v1/roast \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com"}'

javascript

const res = await fetch('https://RoastThisPage.vercel.app/api/v1/roast', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://yoursite.com' }),
})

const roast = await res.json()
console.log(roast.overallScore) // e.g. 62
console.log(roast.roast)        // the brutal quote

python

import requests

response = requests.post(
    'https://RoastThisPage.vercel.app/api/v1/roast',
    json={'url': 'https://yoursite.com'},
)

roast = response.json()
print(roast['overallScore'])  # e.g. 62
print(roast['roast'])         # the brutal quote

Errors

All errors return a JSON object with an error field describing the problem.

400

Bad Request

Missing or invalid url field, or the page could not be fetched.

408

Request Timeout

The target page took too long to load.

422

Unprocessable

The page exists but doesn't have enough content to analyze.

500

Server Error

Something went wrong on our end. Try again.

json

{ "error": "Couldn't fetch that URL. Make sure it's publicly accessible." }