> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

> Add, edit, pause, or remove the user-style prompts the AI Visibility agent sends to ChatGPT, Gemini, Claude, and Perplexity

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](/docs/ai-visibility-intents) — 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](/docs/ai-visibility-intents) — 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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/docs/ai-visibility-scan-settings).

> **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
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "text": "what's the best workout-tracking app for Apple Watch?",
  "style": "unbranded",
  "status": "active"
}
```

All fields optional. Common patterns:

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # 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"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const HEADERS = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

  // Bulk-add prompts under one intent
  const intentId = "9c1f...";
  const promptsToAdd = [
    { text: "alternatives to Headspace that are cheaper", style: "comparison" },
    { text: "an app for meditating during my lunch break",  style: "use_case"   },
    { text: "I keep forgetting to meditate, what app sends good reminders?", style: "problem" },
  ];

  for (const p of promptsToAdd) {
    await fetch(
      `https://api.appeeky.com/v1/ai-visibility/1234567890/intents/${intentId}/prompts`,
      { method: "POST", headers: HEADERS, body: JSON.stringify(p) }
    );
  }
  ```
</CodeGroup>

***

## 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](/docs/ai-visibility-intents) (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                                 |

***

## See also

* [Intents](/docs/ai-visibility-intents) — list/drill-down + intent CRUD
* [Answers](/docs/ai-visibility-answers) — see the actual AI responses for each prompt
* [Scan & Settings](/docs/ai-visibility-scan-settings) — re-scan after adding new prompts