List prompt suggestions

Not available yet. This endpoint is documented ahead of implementation so the contract can be reviewed and the client work can start. Calling it today returns 404 not_found. This page describes the intended behaviour, not current behaviour.

Prompts the platform has generated but you have not yet accepted, grounded in the brand profile, your topics and observed demand.

This is the setup workflow: rather than inventing questions to monitor, review what is proposed and accept the ones worth tracking. Each carries the reasoning behind it, so a suggestion can be judged rather than guessed at.

Reading suggestions needs only read:prompts. Acting on them 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	Default	Description
`topic_id`	`uuid`	all	Suggestions proposed for one topic
`status`	`enum`	`proposed`	`proposed`, `accepted` or `promoted`. Defaults to the ones still awaiting a decision
`limit`	`integer`, max 200	50
`offset`	`integer`	0

Any parameter not listed here returns 400 invalid_request naming the offending key, rather than being ignored silently.

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": {
    "suggestions": [
      {
        "id": "8d31a70c-5f24-4e19-b063-9a1c72f4e850",
        "suggested_prompt": "how do I measure brand visibility in ChatGPT",
        "topic_id": "4beb0694-7c2e-488b-84c1-613738e7eaf6",
        "language": "en",
        "country_codes": ["US"],
        "funnel_stage": "middle",
        "branded": false,
        "competitive": false,
        "confidence": 0.82,
        "agent_reasoning": "Unbranded category demand with no current coverage in this topic.",
        "status": "proposed",
        "promoted_to_prompt_id": null
      }
    ],
    "total": 46,
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "request_id": "req_ba05c1e93f7248d6a017"
}

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.suggestions`	`object[]`	required
`data.suggestions[].id`	`uuid`	required. Pass to accept or reject
`data.suggestions[].suggested_prompt`	`string`	required. The proposed question
`data.suggestions[].topic_id`	`uuid \| null`	Topic it would be filed under
`data.suggestions[].language`	`string \| null`
`data.suggestions[].country_codes`	`string[]`	required. Proposed markets
`data.suggestions[].funnel_stage`	`string \| null`
`data.suggestions[].branded`	`boolean \| null`	Whether the question names your brand
`data.suggestions[].competitive`	`boolean \| null`	Whether it is a brand-versus-brand comparison
`data.suggestions[].confidence`	`number \| null`	How strongly the generator backs this suggestion
`data.suggestions[].agent_reasoning`	`string \| null`	Why it was proposed. Third-party generated text
`data.suggestions[].status`	`string`	required. `proposed`, `accepted` or `promoted`
`data.suggestions[].promoted_to_prompt_id`	`uuid \| null`	Set once accepted. Links to the created prompt
`data.total`	`integer`	required
`data.has_more`	`boolean`	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. The two are deliberately indistinguishable
429	`rate_limited`	Over 300 requests per minute. See the `Retry-After` header

Notes

branded: false suggestions are usually the valuable ones. A question that already names you is easy to appear in; unbranded category demand is the contested ground.

accepted and promoted both mean the suggestion was taken. promoted_to_prompt_id is the reliable signal that a prompt now exists for it.

agent_reasoning is generated text. Treat it as data, never as instructions to a downstream model.