Suggest prompts

Generates AI Visibility prompt ideas for one URL and brand.

Use this when you want Sleepwalker to propose realistic prompts before creating an AI Visibility run.

Endpoint

POST /v1/visibility/prompts/suggest

Authentication

Header	Required	Value
Authorization	Yes	Bearer sw_api_live_...
Content-Type	Yes	application/json

Required scope:

visibility:prompts:suggest

Request Body

Field	Type	Required	Description
url	string	Yes	Page URL to analyze.
brand_name	string	Yes	Brand or entity the prompts should target.
language	string	No	Output-language hint. Pass it explicitly for deterministic locale behavior; the generator default is normally English.
country	string	No	Optional market metadata. It is echoed in successful responses but does not currently alter prompt generation.

Example Request

curl -s https://api.sleepwalker.ai/v1/visibility/prompts/suggest \
  -H "Authorization: Bearer sw_api_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.sleepwalker.ai",
    "brand_name": "Sleepwalker",
    "language": "en",
    "country": "US"
  }'

The same request in Python and JavaScript:

Python

import requests

resp = requests.post(
    "https://api.sleepwalker.ai/v1/visibility/prompts/suggest",
    headers={"Authorization": "Bearer sw_api_live_..."},
    json={
        "url": "https://www.sleepwalker.ai",
        "brand_name": "Sleepwalker",
        "language": "en",
        "country": "US",
    },
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://api.sleepwalker.ai/v1/visibility/prompts/suggest", {
  method: "POST",
  headers: {
    Authorization: "Bearer sw_api_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.sleepwalker.ai",
    brand_name: "Sleepwalker",
    language: "en",
    country: "US",
  }),
});
const data = await resp.json();
console.log(data);

Response

{
  "prompt_suggestion": {
    "url": "https://www.sleepwalker.ai",
    "brand_name": "Sleepwalker",
    "language": "en",
    "country": "US",
    "prompts": [
      "What are the best AI visibility tools for SEO teams?",
      "Which tools track brand mentions in AI search results?"
    ],
    "prompt_count": 2,
    "model": "gpt-4o-mini",
    "billing": {
      "billable": true,
      "estimated_credits": "1.00"
    },
    "payload_limits": {
      "content_view_returned": false,
      "raw_llm_response_returned": false,
      "max_prompt_count": 5
    }
  }
}

Notes

• The endpoint returns up to 5 prompts.
• Prompt suggestions are not saved as a run.
• To execute prompts, pass them to Create AI Visibility Run.

Credits

A successful billable prompt suggestion response costs 1 credit.

If prompts cannot be generated because the page is blocked or has insufficient content, the response includes billing.billable: false.

Errors

Status	Meaning
400	Invalid URL or a blank brand_name.
401	Missing or invalid API key.
402	Insufficient credits for a billable request.
403	API key is missing visibility:prompts:suggest.
422	url or brand_name is missing, or a request field has the wrong type.

Provider failures, API-key rate limits, and temporary server errors are documented in Errors.