List prompt suggestions

Prompts the platform has generated but you have not yet decided on, grounded in the brand profile, your topics and observed demand. Each carries the reasoning behind it, so a suggestion can be judged rather than guessed at.

This is the review queue: rather than inventing questions to monitor, review what Generate prompt suggestions proposed and accept the ones worth tracking with Accept prompt suggestions.

Requires only read:prompts. Acting on suggestions needs write:prompts.


GET /v1/brands/{brand_id}/prompts/suggestions

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands

Query parameters

Parameter	Type	Required	Description
`limit`	`integer`	optional	Rows per page, 1 to 100. Defaults to 20.
`cursor`	`string`	optional	Opaque cursor from the previous response. Treat it as a token, never construct one.
`topic_id`	`uuid`	optional	Restrict to suggestions generated for this topic. Includes the topic and its subtopics. A root topic returns everything beneath it; a subtopic returns only itself.
`request_id`	`uuid`	optional	Restrict to one generation batch (from Generate prompt suggestions).
`status`	`string`, repeatable	optional	Filter by status. One of: `proposed`, `accepted`, `rejected`, `promoted`. Defaults to proposed (the review queue) when omitted.

Request

cURL


curl --request GET \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/suggestions?limit=50' \
  --header 'Authorization: Bearer <api-key>'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/suggestions?limit=50"
 
headers = {"Authorization": "Bearer <api-key>"}
 
response = requests.get(url, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <api-key>'}
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/suggestions?limit=50', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/suggestions?limit=50",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>"
  ],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go


package main
 
import (
    "fmt"
    "net/http"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/suggestions?limit=50"
 
    req, _ := http.NewRequest("GET", url, nil)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
 
    res, _ := http.DefaultClient.Do(req)
 
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
 
    fmt.Println(string(body))
 
}

Ruby


require 'uri'
require 'net/http'
 
url = URI("https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/suggestions?limit=50")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api-key>'
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "topic_id": "9c2b1a4e-5d3f-4b8c-9e1a-2f7c6d8b3a10",
      "request_id": "3f1a9c2b-7e40-4b17-8e6a-3c05b91e7d22",
      "suggested_prompt": "What is the best AI visibility tracking tool for SaaS teams?",
      "language": "en",
      "country_codes": ["US"],
      "tag_ids": [],
      "intent": "commercial",
      "funnel_stage": "middle",
      "branded": false,
      "competitive": true,
      "agent_reasoning": "High-intent comparison query with no branded prompt covering this angle yet.",
      "confidence": 0.82,
      "evidence": {},
      "status": "proposed",
      "promoted_to_prompt_id": null,
      "rejected_reason": null,
      "created_at": "2026-08-30T09:16:47.118Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  },
  "request_id": "req_2f7b90c14ae8471da3cd"
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it in Settings to get a replacement.",
    "request_id": "req_8f21c0aa47b1490d2e63"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

429


{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 24 seconds.",
    "request_id": "req_31c9ba7f0e5d4a118cc2"
  }
}

Response fields

Field	Type	Description
`data[].id`	`uuid`	required. Use it with Accept / Reject / Edit prompt suggestions
`data[].topic_id`	`uuid \| null`	required
`data[].request_id`	`uuid`	required. The generation batch this suggestion came from
`data[].suggested_prompt`	`string`	required
`data[].language`	`string`	required
`data[].country_codes`	`string[]`	required
`data[].tag_ids`	`uuid[]`	required
`data[].intent`	`string \| null`	One of `informational`, `navigational`, `commercial`, `transactional`
`data[].funnel_stage`	`string \| null`	One of `top`, `middle`, `bottom`
`data[].branded`	`boolean`	required
`data[].competitive`	`boolean`	required
`data[].agent_reasoning`	`string \| null`	Why the agent proposed this prompt
`data[].confidence`	`number \| null`	0-1
`data[].evidence`	`object`	required. Supporting signals the agent used
`data[].status`	`string`	required. One of `proposed`, `accepted`, `rejected`, `promoted`
`data[].promoted_to_prompt_id`	`uuid \| null`	Set once accepted
`data[].rejected_reason`	`string \| null`	Set only when rejected with a reason
`data[].created_at`	`timestamptz`	required
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
400	`invalid_request`	A parameter is unknown or malformed. The message names it
401	`invalid_token`	The key is missing, malformed, or does not exist
401	`token_expired`	The key passed its expiry date
401	`token_revoked`	The key was revoked
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
429	`rate_limited`	Over 300 requests per minute

Notes

Defaults to proposed. Pass status explicitly to see suggestions you already decided on — useful for auditing what was accepted or rejected and why.

accepted vs promoted. Both mean the suggestion was accepted. promoted created a new prompt; accepted means the suggested text already matched an existing active prompt, so it was linked to that prompt instead of creating a duplicate. promoted_to_prompt_id is set either way.