Capability reference
Every capability an API key can call, what it returns, and the scopes that grant it. A key needs any one of the listed scopes. All capabilities work on the key's project only.
To see what a specific key can call, use GET /v1/capabilities, or let your MCP client list its tools.
Setup
Capability | Returns | Scopes |
|---|---|---|
| Finds personas, competitors, monitors and prompts by name and returns their IDs. Suggests close matches when a name is misspelled | Analytics Read |
| Brand, domain, country, and the number of monitors, prompts, competitors and personas | Analytics Read, Monitors Read |
| Your monitors and their status | Analytics Read, Monitors Read |
| Your buyer personas with conversion potential and key pain point | Analytics Read, Monitors Read |
| Your tracked prompts, filterable by country, monitor, type, intent or persona | Analytics Read, Monitors Read |
| Files a proposal for a new persona, which a person confirms in Ansehn. See Capabilities API reference | Propose personas and schedules |
| Files a proposal for a new buying-simulation schedule with its credit estimate, which a person confirms in Ansehn | Propose personas and schedules |
Prompts and AI answers
Capability | Returns | Scopes |
|---|---|---|
| The recorded AI answers for one prompt, with brand mentions, citation share and sentiment | Analytics Read, Monitors Read |
| One prompt's runs, mention rate, response time, results per AI model and daily batches | Analytics Read, Monitors Read |
Scores and competitors
Capability | Returns | Scopes |
|---|---|---|
| Current visibility, share of voice, position, citation share and sentiment scores | Analytics Read |
| Daily trend of those scores | Analytics Read |
| Your scores next to your tracked competitors' scores | Analytics Read, Competitors Read |
| Your brand's sentiment score and how many answers it is based on | Analytics Read |
Citations
Capability | Returns | Scopes |
|---|---|---|
| Total citations, top citing domains, and the split between your domain, competitors and third parties | Analytics Read, Citations Read |
| The prompts and AI providers where a given domain was cited | Analytics Read, Citations Read |
| The most cited URLs with domain, citation count and owner type | Analytics Read, Citations Read |
| Which prompts and AI models cited one URL | Analytics Read, Citations Read |
Buying simulations
Capability | Returns | Scopes |
|---|---|---|
| Your win rate, filterable by persona, country or date | Analytics Read |
| Recent completed simulations, newest first | Analytics Read |
| One simulation's winner, persona, location, transcript excerpts and report | Analytics Read |
| A summary of a run: outcome, win-rate context and the competitors that won | Analytics Read |
| The full run history of one simulation schedule | Analytics Read |
| Schedules found by persona, question, AI engine or country | Analytics Read |
| Two AI engines compared: win rates, content gaps and recommendations | Analytics Read |
| Content gaps and recommendations combined across simulation reports | Analytics Read |
Buying simulation cockpit
These need a project on the current buying-simulation version. Otherwise they return a 503 unavailable error.
Capability | Returns | Scopes |
|---|---|---|
| How often your brand appears in buying conversations | Analytics Read |
| Your share of vendor mentions compared with competitors | Analytics Read |
| Your win rate per AI assistant | Analytics Read |
| The domains AI assistants cite in buying conversations | Analytics Read |
| The trend of presence, recommendations and win rate | Analytics Read |
| The strongest recent answer where your brand won | Analytics Read |
Content and pages
Capability | Returns | Scopes |
|---|---|---|
| Pages you published or changed, newest first | Analytics Read |
| Your own pages, with AI citations and AI crawler visits | Analytics Read |
| How many of your pages AI cited or visited, over up to 90 days | Analytics Read |
Server logs
Capability | Returns | Scopes |
|---|---|---|
| Log lines processed and AI crawler traffic from your uploaded server logs | Analytics Read, Server Logs Read |
Notes
getSentimentneeds sentiment to be enabled for your project. Otherwise it returns a 503unavailableerror.searchEntitiesalso returns competitors, so it needs Analytics Read.The two proposal capabilities change nothing by themselves. The key's creator confirms each proposal on the Setup proposals page in Ansehn. Keys can't confirm proposals, edit or archive anything, or send Slack or Teams messages. Those are only available in Copilot inside Ansehn.
Older keys can show the scope Legacy (no effect). It grants nothing.