# Prompts API

Paths on this page are relative to `https://shruwd.io/api/v1`.

| Method | Path | Scope | Role |
|---|---|---|---|
| `GET` | `/brands/{brandId}/prompts` | `read` | viewer |
| `POST` | `/brands/{brandId}/prompts` | `write` | editor |
| `PATCH` | `/prompts/{promptGroupId}` | `write` | editor |
| `DELETE` | `/prompts/{promptGroupId}` | `write` | editor |

A prompt is addressed by its **`promptGroupId`** — the identity that survives edits.
`promptId` is the current version and is returned for reference.

## List prompts

```bash
curl "https://shruwd.io/api/v1/brands/waitlister/prompts?engine=google_aio&from=2026-08-01" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"
```

Returns active prompts. Pass `engine`, `from` and `to` to include per-prompt coverage for
that window — mention rate, plus counts of answers that named nobody and prompts the
engine produced no AI answer for.

## Add prompts

Batch, and **atomic**.

```bash
curl -X POST "https://shruwd.io/api/v1/brands/waitlister/prompts" \
  -H "Authorization: Bearer $SHRUWD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      { "text": "best waitlist software for a product launch", "intent": "commercial" },
      { "text": "launchlist alternatives", "intent": "comparison", "tags": ["competitor"] }
    ]
  }'
```

| Field | Required | Notes |
|---|---|---|
| `text` | Yes | 1–500 characters, trimmed |
| `intent` | Yes | One of the five below. It decides which diagnostics apply |
| `tags` | No | Free-form, for grouping |

### Intents

| Intent | For |
|---|---|
| `commercial` | "Best X for Y" — a buyer ready to choose |
| `comparison` | "X vs Y", "alternatives to X" — where competitors get named |
| `informational` | "How does X work" — learning, not yet buying |
| `navigational` | Looking for a specific brand or page by name |
| `problem` | Describes the problem, not a product |

### Errors

| Code | Status | |
|---|---|---|
| `duplicate_prompt` | 409 | That text is already active on this brand |
| `plan_limit` | 409 | The batch would exceed your prompt cap |

> **Warning**
>
> `plan_limit` refuses the **whole batch**. Submitting 30 prompts against a 25-prompt plan
> gets you an error and the numbers — `details` carries `limit`, `current` and `submitted` —
> not 25 silently accepted. Prompts are counted across every brand in the workspace.

## Update a prompt

```bash
curl -X PATCH "https://shruwd.io/api/v1/prompts/$groupId" \
  -H "Authorization: Bearer $SHRUWD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent":"comparison"}'
```

Accepts `text`, `intent`, `tags` and `active`.

| Changing | Effect |
|---|---|
| `text` or `intent` | **Starts a new version.** Past measurements stay attached to the wording that produced them, and the new version starts from zero responses |
| `tags` or `active` | Updated in place. They do not change what is asked |

Reactivating with `active: true` counts as a creation against your plan limit.

## Remove a prompt

```bash
curl -X DELETE "https://shruwd.io/api/v1/prompts/$groupId" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"
```

Deactivates it. Nothing is deleted — it stops being asked from the next cycle on and its
history is kept. The slot is freed against your plan limit.

## Next steps

- [Entities](https://shruwd.io/docs/api/entities.md) — who you are measured against
- [Measurement](https://shruwd.io/docs/api/measurement.md) — reading what comes back