---
title: "Draft prompts and competitors from the brand's homepage"
method: POST
path: "/brands/{brandId}/setup-suggestions"
tags: ["brands"]
---

# Draft prompts and competitors from the brand's homepage

`POST /brands/{brandId}/setup-suggestions`

## Request

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

Reads the brand's homepage and sitemap and drafts prompts (as many as the
workspace's prompt pool has room for, 10 to 25), each with the page on the
brand's site that should answer it when one does, and up to six competitors,
for a person to review. Nothing is added to the brand: add the prompts that
are kept with `POST /brands/{brandId}/prompts`, passing each one's `page`,
and each competitor with `POST /brands/{brandId}/entities`.

Returns the stored draft (200, `generated: false`) when one exists, unless
`regenerate` is true. A new draft (201) takes from a few seconds to about a
minute. Three drafts per brand and ten per workspace per rolling day:
`429 suggestion_limit`, with `details.retryAfterSeconds`. `503 not_configured`
when drafting is unavailable; setup works without it.

## Request body

- object
  - `regenerate` boolean: Replace the stored draft with a new one.

## Response `200`

The stored draft; nothing was drafted.

- SetupSuggestionsResult
  - `suggestions` SetupSuggestions, required: A draft for a person to review. Nothing in it is tracked or measured until it is added.
    - `brandId` string, required
    - `sourceUrl` string, nullable, required: The page it was read from. Null when the site could not be fetched and the draft rests on the name and domain.
    - `prompts` object[], 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.
      - `page` string, nullable, required: The page on the brand's site that should answer it, chosen from the site's own pages. Null when none does. Send it with the prompt when adding it; findings about the question name it.
    - `competitors` object[], required
      - `name` string, required: As answers write it: the brand people name, not a product line.
      - `domain` string, nullable, required: Registrable domain, when the draft was confident of one.
      - `aliases` string[], required: Other exact spellings answers use for the same company. Never a short or common word. Send them with the name when adding the competitor.
      - `contextTerms` string[], required: Only for a name that needs context terms (six characters or fewer, or an ordinary English word); empty otherwise.
    - `generatedAt` string, date-time, required
  - `generated` boolean, required: False when the stored draft was returned.

## Other responses

- `201`: A new draft.
- `404`: `not_found`: no such resource in this workspace.
- `429`: `suggestion_limit`: the day's drafts are used up. `details.retryAfterSeconds` says when the next is possible.
- `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)