AI Mentions API

Track your brand visibility across AI providers programmatically. Essential-level monitoring supports ChatGPT, Perplexity, and Gemini; Pro and above also support Claude and Google AI Overview. Create monitoring prompts with configurable cadence, filter by tags, and pull run results and performance stats.

An API key scoped to a specific domain is restricted to that domain.

API key access requires the Pro plan or above. A key on a lower plan receives 403 { "error": "plan_required", "requiredPlan": "agency" }. The agency string is the stored ID for the Pro plan.

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#

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

Example#

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

# Filter prompts by tag
curl "https://encited.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, e.g. ["chatgpt", "perplexity", "gemini"]. Pro and above can also use "claude" and "google_ai_overview". Availability and the per-prompt provider limit depend on your plan. Defaults to the providers available on your plan.
`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). Creating with 0 stores the prompt paused — it doesn't count toward your plan's monitor limit and no runs are scheduled until it's activated. Activating a paused prompt (update with 1) requires a free monitor slot and starts that day's monitoring runs.

Response Body (create)#

{
  "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.
403 Forbidden — domain_not_owned, api_key_domain_scope_mismatch, or prompt_limit_reached (plan prompt allocation exceeded).
404 Not Found — not_found — the prompt id does not exist for this domain (update only).

Examples#

// Create a prompt
const response = await fetch(
  "https://encited.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", "perplexity", "gemini"],
      tags: "brand,prerendering",
    }),
  },
);

# Create a prompt
curl -X POST \
  "https://encited.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", "perplexity", "gemini"],
    "tags": "brand,prerendering"
  }'

# Update a prompt
curl -X POST \
  "https://encited.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://encited.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" \| "google_ai_overview"	Filter to a specific provider.

Response Body#

{
  "prompts": [
    {
      "promptId": "uuid",
      "promptText": "What is the best tool for prerendering SPAs?",
      "intent": "info",
      "aiProviders": ["chatgpt", "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#

curl "https://encited.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" \| "google_ai_overview"	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#

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

# Get all runs for a domain in a date range
curl "https://encited.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://encited.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#

{
  "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 (invalid_api_key).
403 Forbidden — domain_not_owned or api_key_domain_scope_mismatch (API key scoped to a different domain).

Example#

const response = await fetch(
  "https://encited.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;

curl "https://encited.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.

AI Mentions API

List Prompts#

GET /api/ai-mentions/prompts#

Query Parameters#

Response Body#

Example#

Create / Update / Delete Prompts#

POST /api/ai-mentions/prompts#

Request Body#

Response Body (create)#

Response Codes#

Examples#

Get Prompt Stats#

GET /api/ai-mentions/prompt-stats#

Query Parameters#

Response Body#

Example#

Get Runs#

GET /api/ai-mentions/runs#

Query Parameters#

Response Body#

Example#

Get Visibility Reports#

GET /api/ai-mentions/reports#

Query Parameters#

Response Body#

Response Codes#

Example#

Monitor Intervals#

`GET /api/ai-mentions/prompts`#

`POST /api/ai-mentions/prompts`#

`GET /api/ai-mentions/prompt-stats`#

`GET /api/ai-mentions/runs`#

`GET /api/ai-mentions/reports`#