Prompts - Appeeky REST API & MCP Server

A prompt is a single user-style query the agent sends to each enabled AI model on every scan. Prompts always belong to an intent — together they’re the questions a real user might ask an assistant when looking for an app like yours. The bootstrap generates 5–8 prompts per intent automatically. You can edit, pause, archive, or add your own at any time. This page covers:

Endpoint	Purpose
`POST /v1/ai-visibility/:appId/intents/:intentId/prompts`	Add a custom prompt to an intent
`PATCH /v1/ai-visibility/:appId/prompts/:promptId`	Edit text, change style, pause, or archive
`DELETE /v1/ai-visibility/:appId/prompts/:promptId`	Archive (soft delete)

To list prompts under an intent, use GET /intents/:intentId — the response includes a prompts[] array.

Prompt styles

Every prompt has a style tag. Variety matters: 5 paraphrases of “best meditation app” don’t tell you anything new, but a problem-led prompt and a comparison prompt for the same intent often produce very different recommendations from the same model.

Style	What it looks like	When to use
`unbranded`	”best app for meditation”	Pure category visibility — does the assistant know about you at all?
`branded`	”is Calm or Headspace better for sleep?”	Discoverability when the user is comparison-shopping.
`problem`	”I struggle to fall asleep at night, what app can help me wind down?”	Real-world phrasing — picks up apps the assistant associates with the outcome rather than the category.
`use_case`	”an app I can use during my morning commute”	Scenario-driven discovery.
`comparison`	”alternatives to Calm”	Surfaces competitor benchmarking — useful for understanding who AI thinks is similar to a market leader.

The bootstrap aims to produce at least 3 different styles per intent. When you add prompts manually, picking a style outside what already exists for an intent gives you the most new signal.

Add a prompt

POST /v1/ai-visibility/:appId/intents/:intentId/prompts

Body

{
  "text": "what's a good app for tracking workouts and recovery on Apple Watch?",
  "style": "use_case"
}

Field	Type	Required	Description
`text`	string	Yes	The prompt the assistants will receive verbatim. 15–220 chars. Write it the way a real user would type it — conversational tone, lowercase ok, contractions ok.
`style`	string	No	One of `unbranded`, `branded`, `problem`, `use_case`, `comparison`. Defaults to `unbranded` if not provided or invalid.

Response

{
  "data": {
    "id": "p123...",
    "intentId": "9c1f...",
    "text": "what's a good app for tracking workouts and recovery on Apple Watch?",
    "promptStyle": "use_case",
    "status": "active",
    "source": "user"
  }
}

The prompt is added with status: "active" and will be included in the next scan. If you want it picked up immediately, follow with POST /scan.

Deduplication. Re-posting the same text under the same intent is a no-op — we fingerprint the normalised text and ignore duplicates. This is safe to use idempotently from import scripts.

Edit / pause / archive

PATCH /v1/ai-visibility/:appId/prompts/:promptId

{
  "text": "what's the best workout-tracking app for Apple Watch?",
  "style": "unbranded",
  "status": "active"
}

All fields optional. Common patterns:

// Pause a prompt (keep it but skip in next scans)
{ "status": "paused" }

// Re-classify the style without changing the text
{ "style": "comparison" }

// Reword
{ "text": "..." }

Editing text re-fingerprints the prompt; if the new text matches an existing one under the same intent, the update will fail silently and you’ll get the existing row’s text on the next read.

Delete (archive)

DELETE /v1/ai-visibility/:appId/prompts/:promptId

Soft-archive — historical answers stay in the database (so the dashboard’s per-prompt history doesn’t break) but the prompt is removed from the active rotation and from list endpoints.

Code examples

# Add a problem-led prompt to an intent
curl -X POST "https://api.appeeky.com/v1/ai-visibility/1234567890/intents/9c1f.../prompts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I have anxiety attacks at work, what app can calm me down quickly?",
    "style": "problem"
  }'

# Pause a prompt
curl -X PATCH "https://api.appeeky.com/v1/ai-visibility/1234567890/prompts/p123..." \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

# Archive a prompt
curl -X DELETE "https://api.appeeky.com/v1/ai-visibility/1234567890/prompts/p123..." \
  -H "X-API-Key: YOUR_API_KEY"

Tips for writing good prompts

Keep it conversational. “best meditation app for beginners” beats “Comprehensive evaluation of meditation applications for novice users”.
Avoid mentioning yourself. A prompt that names your app guarantees you’ll appear — but it doesn’t measure visibility, it measures the assistant’s willingness to repeat a name back.
One question per prompt. Compound questions confuse the assistants and yield messier mention extraction.
Cover the intent, not the feature. “an app that plays nature sounds” is too narrow if your intent is Reduce stress and anxiety to feel calm; “what helps me calm down before bed?” is better.
Add at least one prompt in each language you care about — assistants behave differently across languages (a Turkish prompt often produces a different competitor set than an English one for the same intent).

Credits

Endpoint	Cost
`POST /intents/:intentId/prompts`	1 credit
`PATCH /prompts/:promptId`	Free
`DELETE /prompts/:promptId`	Free

Listing prompts is part of the intent drill-down (2 credits).

Errors

Status	Code	When
400	INVALID_INPUT	`text` shorter than 15 chars or contains invalid characters
404	NOT_FOUND	Intent or prompt doesn’t exist or doesn’t belong to this app
401	—	Missing or invalid API key / JWT
429	—	Insufficient monthly credits

Documentation Index

​Prompt styles

​Add a prompt

​Body

​Response

​Edit / pause / archive

​Delete (archive)

​Code examples

​Tips for writing good prompts

​Credits

​Errors

​See also