upsert_ai_visibility_prompts
Add or remove prompts the weekly AI-visibility probe asks. Write customer-worded questions an AI assistant would answer with named products or companies, never marketing copy. Added prompts carry origin: agent and survive the strategy-driven refresh; the plan’s question cap applies to the active total across all of the organization’s sites (cap is null when unlimited). Removing deactivates a prompt (its history is kept).
Side effect: changes what the next weekly probe asks (real vendor cost per prompt per engine).
Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
add | string | no | JSON array of questions: strings, or {text, category?, topic?, audience?} objects (category: discovery, problem, comparison, brand, segment) |
remove_ids | string | no | JSON array of prompt ids to remove |
site_source_id | string | no | Site source id; omitted selects the primary site |
Returns#
{
"added": [{ "id": 31, "text": "best trail running shoes for wide feet", "created": true }],
"refused": [{ "text": "x", "reason": "length" }],
"removed": 1,
"cap": 100,
"source": "adlyse.ai_visibility@v2"
}reason is length (8–500 characters) or cap (the active total is at the plan’s cap).
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
validation_error | remove_ids is not integers, or a question object has an unknown field or category |
site_source_id scopes this operation to a site in the current organization; omitted selects the primary site. Results are sampled API answers. Comparative rates use matched prompt/engine/model/locale cohorts, excluding failed scoring; configuration changes require a new baseline. Only implemented and configured engine adapters can run.