Recommendations API endpoint
POST /v1/recommendations
Page-level next steps for one measured prompt: we inspect your page, your robots.txt and up to two pages the AI surfaces cited, then compare them.
Overview
There are three ways in. url alone runs a free technical check of that page (robots.txt crawler access, indexing, rendering) and suggests buyer questions. urlwith query first runs a citations check for that question, priced like /v1/citations and charged whether or not advice is found, then the page report. Or pass one saved requestId, trackerRunId or evidence array: saved results must belong to your account, be complete, and be under 30 days old; supplied evidence is marked unverified; query then picks one measured prompt, otherwise the largest gap is used. A report's own requestId reuses its citations check.
Pass url for the page that should answer the prompt. Without it we use the URL a citations check watched, a page on context.domain that the AI surfaces cited, or the closest match in that domain's sitemap. We fetch that page, its robots.txt and up to two cited pages as returned HTML, without running JavaScript, within a fixed request budget. Pages that refuse our fetcher may be read through Gemini URL context instead, labelled as such.
Findings we observe directly, such as crawler blocks, noindex or a missing page, come from code. Content recommendations quote the cited pages exactly. Any claim that your page lacks something is checked against its full returned text and by a separate coverage check, which drops topics your page already covers in other words or that conflict with how it describes the product.
A report costs $0.25 only when it includes page-comparison recommendations that pass those checks. If your page was found but could not be read, its suggestions compare only the cited pages and are free. Everything else is free. Invalid input returns 400; inaccessible IDs 404; identical in-flight requests 409. Completed identical requests replay free for two minutes.
Reference
/v1/recommendations$0.25 · only when the report includes verified page-comparison advice; everything else is free
Parameters
Request
curl https://www.cite42.dev/api/v1/recommendations \
-X POST \
-H "Authorization: Bearer $CITE42_API_KEY" \
-H "Content-Type: application/json" \
-d '{"requestId":"your-previous-request-id","url":"https://acme.example/guides/startup-crm","context":{"brand":"Acme CRM","goal":"Help startup teams evaluate us against alternatives"}}'Response
{
"mode": "evidence",
"status": "complete",
"source": "ai",
"message": "Page-level recommendations for “best startup CRM”, from 3 inspected pages.",
"scope": {
"query": "best startup CRM",
"brand": "Acme CRM",
"otherQueries": []
},
"inspection": {
"query": "best startup CRM",
"ownPage": {
"discovery": "input_url",
"note": "The page you supplied."
},
"pages": [
{
"id": "own",
"role": "own",
"url": "https://acme.example/guides/startup-crm",
"requestedUrl": "https://acme.example/guides/startup-crm",
"status": "inspected",
"method": "http",
"fetchedAt": "2026-09-29T10:00:03.000Z",
"httpStatus": 200,
"title": "The startup CRM guide",
"wordCount": 1180,
"headingCount": 9
},
{
"id": "cited-1",
"role": "cited",
"url": "https://reviews.example/best-startup-crm",
"requestedUrl": "https://reviews.example/best-startup-crm",
"status": "inspected",
"method": "http",
"fetchedAt": "2026-09-29T10:00:03.000Z",
"httpStatus": 200,
"citedBy": [
"chatgpt",
"perplexity"
],
"title": "Best CRM for startups",
"wordCount": 2410,
"headingCount": 14
},
{
"id": "cited-2",
"role": "cited",
"url": "https://saas-notes.example/crm-pricing",
"requestedUrl": "https://saas-notes.example/crm-pricing",
"status": "inspected",
"method": "http",
"fetchedAt": "2026-09-29T10:00:03.000Z",
"httpStatus": 200,
"citedBy": [
"gemini"
],
"title": "CRM pricing compared",
"wordCount": 1630,
"headingCount": 11
}
],
"robots": {
"url": "https://acme.example/robots.txt",
"status": "parsed",
"httpStatus": 200,
"fetchedAt": "2026-09-29T10:00:03.000Z",
"path": "/guides/startup-crm",
"crawlers": [
{
"token": "OAI-SearchBot",
"vendor": "OpenAI",
"purpose": "search",
"allowed": false,
"rule": "Disallow: /guides/"
},
{
"token": "PerplexityBot",
"vendor": "Perplexity",
"purpose": "search",
"allowed": true
},
{
"token": "GPTBot",
"vendor": "OpenAI",
"purpose": "training",
"allowed": false,
"rule": "Disallow: /"
}
]
},
"requests": {
"used": 5,
"limit": 15
},
"notes": []
},
"recommendations": [
{
"id": "access-1",
"kind": "crawler_access",
"priority": 1,
"effort": "small",
"fact": "https://acme.example/robots.txt disallows OAI-SearchBot (ChatGPT search) for /guides/startup-crm.",
"action": "If you want /guides/startup-crm to appear in those AI answers, allow these crawlers for that path in robots.txt, then re-check the file. Vendors can take about a day to pick up changes.",
"evidence": [
{
"id": "robots",
"kind": "inspected",
"measuredAt": "2026-09-29T10:00:03.000Z",
"url": "https://acme.example/robots.txt",
"detail": "OAI-SearchBot: Disallow: /guides/. OpenAI says sites opted out of OAI-SearchBot will not be shown in ChatGPT search answers, though they can still appear as navigational links."
}
],
"followUp": {
"primitive": "citations",
"input": {
"query": "best startup CRM",
"url": "https://acme.example/guides/startup-crm",
"models": [
"chatgpt",
"perplexity",
"gemini"
]
},
"metric": "watched URL citation presence",
"trackerDraft": {
"name": "Track AI citations",
"primitive": "citations",
"prompts": [
"best startup CRM"
],
"models": [
"chatgpt",
"perplexity",
"gemini"
],
"url": "https://acme.example/guides/startup-crm"
},
"instruction": "Recheck with the same prompt and surfaces. To create a tracker draft, choose a cadence and timezone first. Activation and paid runs require separate approval. Movement does not prove causation."
}
},
{
"id": "content-1",
"kind": "content_gap",
"priority": 2,
"effort": "medium",
"fact": "reviews.example (cited by ChatGPT, Perplexity) includes “Pricing starts at $12 per seat per month, billed annually”. Your page's returned HTML does not cover this: none of “pricing”, “per seat” appear, and a coverage check of the page found no passage on the topic.",
"action": "Compare the quoted pricing comparison coverage with your page and decide whether it belongs there.",
"suggestion": {
"kind": "inferred",
"text": "Pricing comparison: Add a \"Pricing\" section after the feature overview listing plan names, per-seat prices and billing terms you can verify, with a link to your pricing page. Check: Every listed price matches the current pricing page."
},
"evidence": [
{
"id": "cited-1-s4",
"kind": "inspected",
"measuredAt": "2026-09-29T10:00:03.000Z",
"url": "https://reviews.example/best-startup-crm",
"detail": "“Pricing starts at $12 per seat per month, billed annually” (section “Pricing”)"
},
{
"id": "own-text",
"kind": "inspected",
"measuredAt": "2026-09-29T10:00:03.000Z",
"url": "https://acme.example/guides/startup-crm",
"detail": "Searched the returned HTML text for: pricing, per seat."
}
],
"followUp": {
"primitive": "citations",
"input": {
"query": "best startup CRM",
"url": "https://acme.example/guides/startup-crm",
"models": [
"chatgpt",
"perplexity",
"gemini"
]
},
"metric": "watched URL citation presence",
"trackerDraft": {
"name": "Track AI citations",
"primitive": "citations",
"prompts": [
"best startup CRM"
],
"models": [
"chatgpt",
"perplexity",
"gemini"
],
"url": "https://acme.example/guides/startup-crm"
},
"instruction": "Recheck with the same prompt and surfaces. To create a tracker draft, choose a cadence and timezone first. Activation and paid runs require separate approval. Movement does not prove causation."
}
}
],
"metrics": [],
"omittedEvidence": 0,
"limitations": [
"Each report covers one prompt. Other measured prompts are listed in scope.otherQueries.",
"Pages were inspected as returned HTML without running JavaScript. Google renders JavaScript, so this is not every engine's view.",
"What a cited page contains does not show why it was cited, and matching it does not guarantee visibility."
],
"requestId": "…",
"billing": {
"cost": {
"microCredits": 25000,
"usd": "0.25"
},
"balance": {
"microCredits": 1336000,
"usd": "13.36"
}
}
}