---
title: "Add prompts"
method: POST
path: "/brands/{brandId}/prompts"
tags: ["prompts"]
---

# Add prompts

`POST /brands/{brandId}/prompts`

## Request

- Base URL: `https://shruwd.io/api/v1`
- URL: `https://shruwd.io/api/v1/brands/{brandId}/prompts`
- Auth: HTTP bearer

Batch, atomic. `intent` is required: it decides which diagnostic rules
apply. Text is 1–500 characters (ChatGPT's cap, the tightest engine's).
A duplicate of an active prompt is `409 duplicate_prompt`. If the batch
would exceed the plan's prompt allowance — one pool across every brand in
the workspace, not a per-brand limit — nothing is created and
`409 plan_limit` carries `limit`, `current` and `submitted`.

## Request body

- AddPromptsRequest
  - `prompts` NewPrompt[], required
    - `text` string, required
    - `intent` 'informational' | 'comparison' | 'commercial' | 'navigational' | 'problem', required: Why someone would ask the prompt. `informational` — learning about a topic. `comparison` — weighing named options. `commercial` — choosing what to buy. `navigational` — looking for a specific site or brand. `problem` — fixing something. The intent decides which diagnostic rules apply to the prompt's results.
    - `tags` string[]
    - `page` string, nullable: The page on the brand's own site that should answer this question. A full URL on one of the brand's own domains.

## Response `201`

Created.

- object
  - `prompts` Prompt[], required
    - `promptGroupId` string, required: Stable across edits. Use it for trends and for `PATCH`/`DELETE`.
    - `promptId` string, required: The current version's id. Changes when text or intent is edited.
    - `text` string, required
    - `intent` 'informational' | 'comparison' | 'commercial' | 'navigational' | 'problem', required: Why someone would ask the prompt. `informational` — learning about a topic. `comparison` — weighing named options. `commercial` — choosing what to buy. `navigational` — looking for a specific site or brand. `problem` — fixing something. The intent decides which diagnostic rules apply to the prompt's results.
    - `tags` string[], required
    - `active` boolean, required
    - `createdAt` string, date-time, required
    - `version` integer, required
    - `page` string, nullable, required: The page on the brand's own site that should answer this question, set by a person. Findings about it name this page. Null when none is set.

## Other responses

- `404`: `not_found`: no such resource in this workspace.
- `409`: `plan_limit` or `duplicate_prompt`.
- `422`: `invalid_prompt`, `invalid_intent`, `invalid_tags`, `invalid_page` (not a URL, or not on the brand's own domains: `details.domains`).
- `default`: Every failure has this body.

---

[API](https://skmtc.dev/shruwd/apis/shruwd-api.md) · [All operations](https://skmtc.dev/shruwd/apis/shruwd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shruwd/apis/shruwd-api/revisions/64a5da079928?raw)