Create alignment prompt

Adds a question to run for brand alignment checks. Matches “Add Prompts → Single Prompt” on the Alignment Prompts page. Defaults to the US market when no country_codes are given, and consumes one alignment-prompt slot per market.

Requires the write:alignment scope, and the workspace must be enabled for API writes.


POST /v1/brands/{brand_id}/alignment/prompts

This spends quota, but does not run immediately. Unlike Create prompt, creating an alignment prompt does not trigger a run. It is picked up by the next daily alignment check (04:00 UTC), or you can trigger one yourself with Run alignment check. The slot is consumed the moment this call succeeds either way.

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required

Path parameters

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

Query parameters

None.

Any parameter you pass returns 400 invalid_request naming the offending key.

Body

application/json

Field	Type	Required	Description
`prompt_text`	`string`, 1–500 chars	required	The question to check
`category_id`	`uuid \| null`	optional	From List alignment categories. Leave unset for uncategorised
`country_codes`	`string[]`, up to 20	optional	Markets to check this prompt in. Defaults to `["US"]`. Each one consumes a slot

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: a3f5e921-c0aa-47b1-90d2-6b8e4c07a9d4' \
  --header 'Content-Type: application/json' \
  --data '{"prompt_text":"Does the brand offer a free trial?","category_id":"9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3","country_codes":["US","SE"]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "a3f5e921-c0aa-47b1-90d2-6b8e4c07a9d4",
    "Content-Type": "application/json",
}
payload = {
    "prompt_text": "Does the brand offer a free trial?",
    "category_id": "9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3",
    "country_codes": ["US", "SE"],
}
 
response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript


const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': 'a3f5e921-c0aa-47b1-90d2-6b8e4c07a9d4',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt_text: 'Does the brand offer a free trial?',
    category_id: '9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3',
    country_codes: ['US', 'SE'],
  }),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts', 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/alignment/prompts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "prompt_text" => "Does the brand offer a free trial?",
    "category_id" => "9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3",
    "country_codes" => ["US", "SE"],
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: a3f5e921-c0aa-47b1-90d2-6b8e4c07a9d4",
    "Content-Type: application/json"
  ],
]);
 
$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"
    "strings"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts"
 
    payload := strings.NewReader(`{"prompt_text":"Does the brand offer a free trial?","category_id":"9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3","country_codes":["US","SE"]}`)
 
    req, _ := http.NewRequest("POST", url, payload)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "a3f5e921-c0aa-47b1-90d2-6b8e4c07a9d4")
    req.Header.Add("Content-Type", "application/json")
 
    res, _ := http.DefaultClient.Do(req)
 
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
 
    fmt.Println(string(body))
 
}

Ruby


require 'uri'
require 'net/http'
require 'json'
 
url = URI("https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api-key>'
request["Idempotency-Key"] = 'a3f5e921-c0aa-47b1-90d2-6b8e4c07a9d4'
request["Content-Type"] = 'application/json'
request.body = {
  prompt_text: "Does the brand offer a free trial?",
  category_id: "9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3",
  country_codes: ["US", "SE"],
}.to_json
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "prompt": {
      "id": "a17c9e42-6b3d-4f18-9a05-2d7e84c1b9f6",
      "brand_id": "242546de-4cee-4a7d-952e-f6aa60c63ef8",
      "category_id": "9d1f3a52-6b8e-4c07-a9d4-2e8b41f5c9a3",
      "prompt_text": "Does the brand offer a free trial?",
      "is_active": true,
      "country_codes": ["US", "SE"]
    }
  },
  "request_id": "req_3a71be29c44d85b6ce0f"
}

403 quota


{
  "error": {
    "code": "quota_exceeded",
    "message": "Alignment prompt limit reached (50/50). This prompt needs 2 slots, and 0 remain.",
    "request_id": "req_5c92e0da71b34f68a3df"
  }
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Invalid input for asky_alignment_prompt_create: prompt_text: prompt_text cannot exceed 500 characters",
    "request_id": "req_2d61f0ac48b34e59c7bd"
  }
}

404


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

Response fields

Field	Type	Description
`data.prompt.id`	`uuid`	required. Use it with List alignment prompts
`data.prompt.brand_id`	`uuid`	required
`data.prompt.category_id`	`uuid \| null`	required
`data.prompt.prompt_text`	`string`	required
`data.prompt.is_active`	`boolean`	required. Always `true` on creation
`data.prompt.country_codes`	`string[]`	required. The markets actually used, after defaulting
`request_id`	`string`	required. Also returned as the `x-request-id` header

Errors

Status	Code	When
400	`invalid_request`	Unknown field, missing or over-long `prompt_text`, a bad country code, over 20 `country_codes`, or a `category_id` not on this brand
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
403	`insufficient_scope`	The key does not carry `write:alignment`
403	`plan_required`	This workspace is not enabled for API writes
403	`quota_exceeded`	The request would exceed your alignment-prompt allowance. Nothing is created
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
429	`rate_limited`	Over 60 requests per minute
503	`service_unavailable`	Your allowance could not be checked. Nothing is created. Retry shortly

Notes

Quota is per market, not per prompt, and it is a separate allowance from regular prompts. This endpoint spends alignment_prompts slots, not active_prompts — the two plan limits are tracked independently, so having room on one says nothing about the other. A prompt targeting three countries takes three slots, checked as one call before anything is written.

An empty country_codes array is not the same as omitting the field, but has the same effect. [] is accepted, not rejected, and the brand still defaults to ["US"]. Omit the field entirely if you mean the default.

Nothing runs until the next check. Creating the prompt reserves its slot immediately, but the question is only asked on the next daily alignment run (04:00 UTC) or an explicit Run alignment check call. Reading it back right away shows no claims yet — that is expected.

Duplicate text is not rejected. Unlike Create prompt, there is no uniqueness check on prompt_text here — the same question can exist twice for a brand.

If the allowance cannot be checked, nothing is created. A 503 here means the check itself was unavailable and we refused rather than guessing. Retry; it is transient.

Idempotency-Key is required. Reuse it when retrying and the original response is replayed rather than a second prompt being created and a second slot spent. See Idempotency.