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).

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).

Response Body (create)

json

CopyDownload

{
  "queued": 4,
  "skippedOverCap": 0
}

queued — Number of provider runs queued for the initial execution.
skippedOverCap — Number of runs skipped because the monthly response cap was reached.

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",
      "lastRunAt": 1710460800,
      "responses": 120,
      "mentions": 85,
      "visibilityPercent": 71,
      "avgSentiment": 42,
      "avgPosition": 2.3,
      "topCompetitors": [{ "name": "Prerender.io", "count": 15, "siteUrl": "https://prerender.io" }]
    }
  ],
  "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" }
  }
}

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": 115, "error": 5 }
  }
}

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>"

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.

All intervals still respect your plan's monthly response cap. If the cap is reached, runs are skipped regardless of the interval setting.