AI Mentions API | LovableHTML Docs

Track your brand visibility across AI providers (ChatGPT, Claude, Perplexity, Gemini) programmatically. Create monitoring prompts with configurable cadence, filter by tags, and pull run results and performance stats.

All endpoints accept both session auth (dashboard) and API key auth (programmatic access).

API key access requires a Pro plan or above. Lower-tier API keys receive 403 { "error": "plan_required", "requiredPlan": "pro" }.

List Prompts

GET/api/ai-mentions/prompts

List all prompts for a domain with optional tag filtering.

Query Parameters

Parameter	Type	Description
`domain`required	string	Domain to list prompts for.
`tag`	string	Filter to prompts containing this tag.

Response Body

json

CopyDownload

[
  {
    "id": "uuid",
    "promptText": "What is the best tool for prerendering SPAs?",
    "intent": "info",
    "active": 1,
    "aiProviders": ["chatgpt", "claude", "perplexity", "gemini"],
    "tags": "brand,prerendering",
    "personaLocation": "{...}",
    "createdAt": "2026-03-15T00:00:00.000Z"
  }
]

Example

bash

CopyDownload

# List all prompts for a domain
curl "https://lovablehtml.com/api/ai-mentions/prompts?domain=your-app.com" \
  -H "x-lovablehtml-api-key: <API_KEY>"

# Filter prompts by tag
curl "https://lovablehtml.com/api/ai-mentions/prompts?domain=your-app.com&tag=brand" \
  -H "x-lovablehtml-api-key: <API_KEY>"

Create / Update / Delete Prompts

POST/api/ai-mentions/prompts

Create, update, or delete a prompt. Use the action field to specify the operation.

Request Body

Parameter	Type	Description
`action`required	"create" \| "update" \| "delete"	The operation to perform.
`domain`required	string	Domain the prompt belongs to (must be added to your account).
`id`	string	Prompt ID (required for update and delete).
`promptText`	string	The prompt text (required for create). E.g., "What is the best tool for prerendering SPAs?"
`intent`	"info" \| "trans" \| "comm"	Prompt intent (required for create). info = informational, trans = transactional, comm = commercial.
`providers`	string[]	AI providers to query. Default: all four ["chatgpt", "claude", "perplexity", "gemini"].
`monitorInterval`	"dynamic" \| "weekly" \| "monthly"	How often the prompt should run. Default: "dynamic".
`tags`	string	Comma-separated tags for categorization and filtering. Lowercase alphanumeric and hyphens only (e.g. "brand,competitor-analysis"). Max 10 tags, 64 characters each.
`active`	0 \| 1	Set prompt active (1) or inactive (0). Honored on update only — newly created prompts are always active.

Response Body (create)

json

CopyDownload

{
  "queued": 4
}

queued — Number of provider runs queued for the initial execution.

Response Codes

200

Success —

Operation completed.

204

No Content —

Update or delete completed.

401

Unauthorized —

Missing or invalid API key / session.

403

Forbidden —

domain_not_owned, api_key_domain_scope_mismatch, or prompt_limit_reached (plan prompt allocation exceeded).

Examples

javascript

CopyDownload

// Create a prompt
const response = await fetch(
  "https://lovablehtml.com/api/ai-mentions/prompts",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-lovablehtml-api-key": "<API_KEY>",
    },
    body: JSON.stringify({
      action: "create",
      domain: "your-app.com",
      promptText: "What is the best tool for prerendering SPAs?",
      intent: "info",
      monitorInterval: "monthly",
      providers: ["chatgpt", "claude", "perplexity", "gemini"],
      tags: "brand,prerendering",
    }),
  },
);

bash

CopyDownload

# Create a prompt
curl -X POST \
  "https://lovablehtml.com/api/ai-mentions/prompts" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{
    "action": "create",
    "domain": "your-app.com",
    "promptText": "What is the best tool for prerendering SPAs?",
    "intent": "info",
    "monitorInterval": "monthly",
    "providers": ["chatgpt", "claude", "perplexity", "gemini"],
    "tags": "brand,prerendering"
  }'

# Update a prompt
curl -X POST \
  "https://lovablehtml.com/api/ai-mentions/prompts" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{
    "action": "update",
    "domain": "your-app.com",
    "id": "<PROMPT_UUID>",
    "tags": "brand,updated-tag",
    "monitorInterval": "weekly"
  }'

# Delete a prompt
curl -X POST \
  "https://lovablehtml.com/api/ai-mentions/prompts" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{
    "action": "delete",
    "domain": "your-app.com",
    "id": "<PROMPT_UUID>"
  }'

Get Prompt Stats

GET/api/ai-mentions/prompt-stats

Get aggregated performance statistics for all prompts on a domain over a date range.

Query Parameters

Parameter	Type	Description
`domain`required	string	Domain to query stats for.
`from`	string	Start date (YYYY-MM-DD). Default: 30 days ago.
`to`	string	End date (YYYY-MM-DD). Default: today.
`provider`	"chatgpt" \| "claude" \| "perplexity" \| "gemini"	Filter to a specific provider.

Response Body

json

CopyDownload

{
  "prompts": [
    {
      "promptId": "uuid",
      "promptText": "What is the best tool for prerendering SPAs?",
      "intent": "info",
      "aiProviders": ["chatgpt", "claude", "perplexity", "gemini"],
      "tags": "brand,prerendering",
      "active": 1,
      "lastRunAt": "2026-03-15T00:00:00.000Z",
      "responses": 120,
      "mentions": 85,
      "visibilityPercent": 71,
      "avgSentiment": 42,
      "avgPosition": 2.3,
      "citationRate": 65,
      "topCompetitorSharePct": 22,
      "difficulty": 87,
      "topCompetitors": [
        {
          "name": "Prerender.io",
          "count": 15,
          "siteUrl": "https://prerender.io",
          "strength": 93
        }
      ],
      "range": { "from": "2026-02-14", "to": "2026-03-15" }
    }
  ],
  "summary": {
    "totalResponses": 120,
    "totalMentions": 85,
    "visibilityRate": 71,
    "avgPosition": 2.3,
    "avgSentiment": 42,
    "citationRate": 65,
    "totalCitations": 55,
    "topCompetitor": {
      "name": "Prerender.io",
      "mentions": 15,
      "siteUrl": "https://prerender.io"
    },
    "shareOfVoice": 68,
    "range": { "from": "2026-02-14", "to": "2026-03-15" }
  }
}

lastRunAt is an ISO 8601 timestamp string. difficulty is a 0–100 score (or -1 when not yet computed) analyzed based on past performance and competitors landscape in responses. topCompetitorSharePct is the share-of-voice percentage held by the largest competitor for this prompt. Each topCompetitors[].strength is a 0–100 ranking signal.

Example

bash

CopyDownload

curl "https://lovablehtml.com/api/ai-mentions/prompt-stats?domain=your-app.com&from=2026-02-01&to=2026-03-01" \
  -H "x-lovablehtml-api-key: <API_KEY>"

Get Runs

GET/api/ai-mentions/runs

Get individual prompt run results with filtering.

Query Parameters

Parameter	Type	Description
`domain`required	string	Domain to query runs for.
`promptId`	string	Filter to a specific prompt.
`provider`	"chatgpt" \| "claude" \| "perplexity" \| "gemini"	Filter to a specific provider.
`date`	string	Filter to a specific date (YYYY-MM-DD).
`from`	string	Start date (YYYY-MM-DD).
`to`	string	End date (YYYY-MM-DD).

Response Body

json

CopyDownload

{
  "runs": [
    {
      "id": "run-uuid",
      "promptId": "uuid",
      "dateUtc": "2026-03-15",
      "provider": "chatgpt",
      "status": "ok",
      "rawResponse": "Based on my research, the top tools for...",
      "mentionPosition": 2,
      "citationCount": 1,
      "sentiment": 45,
      "analysisText": "Brand was mentioned in position 2...",
      "competitorMentions": "[{\"name\": \"Prerender.io\", \"count\": 3}]",
      "citationDomains": "[\"example.com\"]",
      "createdAt": "2026-03-15T00:00:00.000Z"
    }
  ],
  "summary": {
    "total": 120,
    "byStatus": { "ok": 110, "answered": 5, "error": 5 }
  }
}

status is one of queued, running, answered, ok, or error. answered indicates the provider returned a response that has not yet been fully analyzed (e.g., sentiment/competitor extraction pending). ok indicates a fully analyzed run. competitorMentions and citationDomains are JSON-encoded strings.

Example

bash

CopyDownload

# Get all runs for a domain in a date range
curl "https://lovablehtml.com/api/ai-mentions/runs?domain=your-app.com&from=2026-03-01&to=2026-03-15" \
  -H "x-lovablehtml-api-key: <API_KEY>"

# Get runs for a specific prompt and provider
curl "https://lovablehtml.com/api/ai-mentions/runs?domain=your-app.com&promptId=<PROMPT_UUID>&provider=chatgpt" \
  -H "x-lovablehtml-api-key: <API_KEY>"

Get Visibility Reports

GET/api/ai-mentions/reports

List archived AI visibility reports for a domain, plus the status of today's report.

Query Parameters

Parameter	Type	Description
`domain`required	string	Domain to list reports for.
`limit`	number	Max number of reports to return (1–100). Default: 30. Reports are returned newest first.

Response Body

json

CopyDownload

{
  "reports": [
    {
      "id": "uuid",
      "dateUtc": "2026-03-15",
      "reportType": "auto",
      "weekStartUtc": "2026-03-13",
      "reportJson": "{\"version\":\"v3\",\"dateUtc\":\"2026-03-15\",...}",
      "reportMarkdown": "",
      "createdAt": "2026-03-15T00:00:00.000Z"
    }
  ],
  "todayStatus": {
    "hasReport": false,
    "runsComplete": false,
    "reportId": null
  }
}

reportType is usually "auto" for the current rolling AI mentions digest. Older rows may still contain legacy "daily" or "weekly" values. weekStartUtc is the start of the period covered by the report; for current auto-generated reports it marks the start of the active reporting window, while older daily rows may have null or a value matching dateUtc. reportJson is a JSON-encoded string conforming to the structured v2 / v3 payload schema (stats, quickSummary, actionItems, providerInsights / providerCount, competitorLandscape, citation opportunities, trendData, etc.); legacy reports may have reportMarkdown populated instead.

todayStatus describes the current UTC reporting window ending today:

hasReport — true if a report already exists for the current reporting window ending today.
runsComplete — true if all prompt runs in the current reporting window have finished (no queued, running, or answered runs remaining).
reportId — the existing report's id when hasReport is true.

Response Codes

200

Success —

Returns the report list and current reporting-window status.

401

Unauthorized —

Missing or invalid API key / session (invalid_api_key).

403

Forbidden —

domain_not_owned or api_key_domain_scope_mismatch (API key scoped to a different domain).

Example

javascript

CopyDownload

const response = await fetch(
  "https://lovablehtml.com/api/ai-mentions/reports?domain=your-app.com&limit=10",
  {
    headers: {
      "x-lovablehtml-api-key": "<API_KEY>",
    },
  },
);

const { reports, todayStatus } = await response.json();
const latest = reports[0];
const payload = latest?.reportJson ? JSON.parse(latest.reportJson) : null;

bash

CopyDownload

curl "https://lovablehtml.com/api/ai-mentions/reports?domain=your-app.com&limit=10" \
  -H "x-lovablehtml-api-key: <API_KEY>"

Monitor Intervals

The monitorInterval field controls how frequently the scheduler runs each prompt:

Interval	Behavior
`dynamic`	Re-check frequency adapts based on recent run analysis. If most recent runs produce the same result, the scheduler spaces out runs into daily rotations to reduce noise. If responses are changing, prompts are run daily or even multiple times a day. This is the default.
`weekly`	Runs once every 7 days. The scheduler skips the prompt if a successful run exists within the last 7 days.
`monthly`	Runs once every 30 days. The scheduler skips the prompt if a successful run exists within the last 30 days.