Developer Docs

FirstVisit API Reference

Integrate AI-powered website analysis into any platform. Authenticate with an API key, send a URL, and get structured feedback in seconds.

Authentication

All API requests require a Bearer token in the Authorization header. Create your API key from the Integrations page.

Authorization: Bearer fv_live_YOUR_KEY

Rate limits: API requests count toward your plan's monthly analysis limit (Free: 7/mo, Starter: 30/mo, Pro: unlimited).

Endpoints

POST/api/v1/analyze

Run a full first-visit analysis on a website.

Request Body

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

Response

{
  "analysisId": "550e8400-e29b-41d4-a716-446655440000"
}

Returns the analysis ID. Use the GET endpoint below to retrieve full results (analysis can take 15–45 seconds).

POST/api/v1/roast

Generate a savage website roast with shareable results.

Request Body

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

Response

{
  "roastId": "550e8400-e29b-41d4-a716-446655440000"
}

Returns the roast ID. Use the GET endpoint below to retrieve full results.

GET/api/v1/analyses/:id

Retrieve a completed analysis by ID. Returns scores, AI feedback, persona reactions, journey simulation, and conversion tips.

Response

{
  "id": "...",
  "url": "https://example.com",
  "trustScore": 72,
  "clarityScore": 65,
  "conversionScore": 58,
  "firstImpression": "...",
  "confusionPoints": ["..."],
  "improvementSuggestions": ["..."],
  "conversionTips": [...],
  "personaFeedback": [...],
  "journeySimulation": [...],
  ...
}

Full analysis record including all scores, AI feedback, messaging optimization, persona feedback, journey simulation, and structured conversion tips.

GET/api/v1/roasts/:id

Retrieve a completed roast by ID.

Response

{
  "id": "...",
  "url": "https://example.com",
  "verdict": "Lost cause",
  "savageryScore": 87,
  "roastLines": ["..."],
  "whatItThinksItDoes": "...",
  "whatItActuallyDoes": "...",
  "bounceTimeEstimate": 3,
  "oneNiceThing": "...",
  "tldr": "..."
}

Full roast record with all roast lines and metadata.

Error Codes

Status	Meaning
400	Invalid request (bad URL or payload)
401	Missing or invalid API key
404	Resource not found
429	Monthly plan limit exceeded — upgrade for more
500	Internal server error

Code Examples

cURL

# Run an analysis
curl -X POST https://first-visit-three.vercel.app/api/v1/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fv_live_YOUR_KEY" \
  -d '{"url": "https://example.com"}'

# Retrieve results
curl https://first-visit-three.vercel.app/api/v1/analyses/ANALYSIS_ID \
  -H "Authorization: Bearer fv_live_YOUR_KEY"

JavaScript / Node.js

const API_KEY = "fv_live_YOUR_KEY";
const BASE = "https://first-visit-three.vercel.app/api/v1";

// Run an analysis
const { analysisId } = await fetch(`${BASE}/analyze`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({ url: "https://example.com" }),
}).then((r) => r.json());

// Wait for processing, then retrieve
const analysis = await fetch(
  `${BASE}/analyses/${analysisId}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then((r) => r.json());

console.log(analysis.trustScore, analysis.clarityScore);

Python

import requests

API_KEY = "fv_live_YOUR_KEY"
BASE = "https://first-visit-three.vercel.app/api/v1"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

# Run an analysis
resp = requests.post(
    f"{BASE}/analyze",
    json={"url": "https://example.com"},
    headers=HEADERS,
)
analysis_id = resp.json()["analysisId"]

# Retrieve results (after processing completes)
result = requests.get(
    f"{BASE}/analyses/{analysis_id}",
    headers=HEADERS,
).json()

print(result["trustScore"], result["clarityScore"])

Need help? Manage API keys · Back to Dashboard