Build on Shruwd

Prompts API

Manage the fixed set of questions Shruwd asks each engine every cycle.

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

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

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/prompts?engine=google_aio&from=2026-08-01" `
  -Headers @{ Authorization = "Bearer $env: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.

curl -X POST "https://shruwd.io/api/v1/brands/northwind/prompts" \
  -H "Authorization: Bearer $SHRUWD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      { "text": "best project management software for small teams", "intent": "commercial" },
      { "text": "planwell alternatives", "intent": "comparison", "tags": ["competitor"] }
    ]
  }'

$body = @{
  prompts = @(
    @{ text = "best project management software for small teams"; intent = "commercial" },
    @{ text = "planwell alternatives"; intent = "comparison"; tags = @("competitor") }
  )
} | ConvertTo-Json -Depth 4

Invoke-RestMethod -Method Post -Uri "https://shruwd.io/api/v1/brands/northwind/prompts" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" } `
  -ContentType "application/json" -Body $body

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. Up to 20
`page`	No	The page on your own site that should answer it. Findings about the question name it

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
`invalid_page`	422	`page` is not a URL on your own site. `details.domains` lists them

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, including brands your key cannot reach.

Update a prompt

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

Invoke-RestMethod -Method Patch -Uri "https://shruwd.io/api/v1/prompts/$groupId" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" } `
  -ContentType "application/json" `
  -Body '{"intent":"comparison"}'

Accepts text, intent, tags, active and page.

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. The page carries over
`tags`, `active` or `page`	Updated in place. They do not change what is asked

page is the page on your own site that should answer the question. Findings about the question name it from the next measurement; null clears it. A finding with no page to name has recommendation.target null, and its subjectRef is the promptGroupId to set one on.

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

Remove a prompt

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

Invoke-RestMethod -Method Delete -Uri "https://shruwd.io/api/v1/prompts/$groupId" `
  -Headers @{ Authorization = "Bearer $env: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 — who you are measured against
Measurement — reading what comes back