Update alignment prompt markets

Changes which markets one or more alignment prompts run in, and/or activates or deactivates them. Each entry in updates replaces that prompt’s markets entirely when country_codes is given — there is no add/remove, only “these are the markets now”. Unlike Update prompt markets for regular prompts, each entry can also flip is_active, because usage is SUM(slots) WHERE is_active — widening markets and reactivating a paused prompt spend the same way, so they price together on this endpoint.

Quota is checked once, as a net delta over the whole batch, not per prompt: shrinking or deactivating one prompt in the same call can offset growing another’s markets, so a customer sitting at their limit can still tidy up. A net reduction is never refused. That is also why this is bulk-shaped only — a single-prompt version could not offer that guarantee.

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


PATCH /v1/brands/{brand_id}/alignment/prompts/countries

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

Body

application/json

Field	Type	Required	Description
`updates`	`object[]`, 1-500	required	One entry per prompt to update
`updates[].prompt_id`	`uuid`	required	From List alignment prompts
`updates[].country_codes`	`string[]`, 1-20	optional	Replaces the prompt’s markets. A prompt must keep at least one
`updates[].is_active`	`boolean`	optional	Activate or deactivate the prompt. Not present on the regular-prompts version of this endpoint

Each entry needs country_codes and/or is_active — an entry with neither is rejected.

Request

cURL


curl --request PATCH \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts/countries' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: 9f2c81b0-5e3d-4a76-8c14-2b9f5e01d7ac' \
  --header 'Content-Type: application/json' \
  --data '{"updates": [{"prompt_id": "b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6", "country_codes": ["US", "GB", "SE"], "is_active": true}]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts/countries"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "9f2c81b0-5e3d-4a76-8c14-2b9f5e01d7ac",
    "Content-Type": "application/json",
}
payload = {
    "updates": [
        {"prompt_id": "b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6", "country_codes": ["US", "GB", "SE"], "is_active": True},
    ]
}
 
response = requests.patch(url, json=payload, headers=headers)
print(response.json())

JavaScript


const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '9f2c81b0-5e3d-4a76-8c14-2b9f5e01d7ac',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    updates: [
      {prompt_id: 'b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6', country_codes: ['US', 'GB', 'SE'], is_active: true},
    ],
  }),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/prompts/countries', 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/countries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    "updates" => [
      ["prompt_id" => "b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6", "country_codes" => ["US", "GB", "SE"], "is_active" => true],
    ],
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: 9f2c81b0-5e3d-4a76-8c14-2b9f5e01d7ac",
    "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/countries"
 
    payload := strings.NewReader(`{"updates": [{"prompt_id": "b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6", "country_codes": ["US", "GB", "SE"], "is_active": true}]}`)
 
    req, _ := http.NewRequest("PATCH", url, payload)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "9f2c81b0-5e3d-4a76-8c14-2b9f5e01d7ac")
    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/countries")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <api-key>'
request["Idempotency-Key"] = '9f2c81b0-5e3d-4a76-8c14-2b9f5e01d7ac'
request["Content-Type"] = 'application/json'
request.body = {
  updates: [
    {prompt_id: "b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6", country_codes: ["US", "GB", "SE"], is_active: true},
  ],
}.to_json
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "updated_prompt_ids": ["b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6"],
    "net_change": 2,
    "quota": {
      "limit": 50,
      "used": 46,
      "remaining": 4
    }
  },
  "request_id": "req_5c1e93f8a2074b6dbf30"
}

403 quota


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

400


{
  "error": {
    "code": "invalid_request",
    "message": "b4e91f2a-6c8d-4a17-9d35-2f7b81e4c9a6: \"UK\" is not a valid market code. Did you mean GB (United Kingdom)?",
    "request_id": "req_2d61f0ac48b34e59c7bd"
  }
}

429


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

Response fields

Field	Type	Description
`data.updated_prompt_ids`	`uuid[]`	required
`data.net_change`	`integer`	required. Slots gained (positive), freed (negative), or `0`. Each market on an active prompt is one slot; a deactivated prompt holds zero regardless of how many markets it lists
`data.quota`	`object`	Present only when `net_change` was positive
`data.quota.limit`	`integer \| null`	Your plan’s alignment-prompt limit, `null` if unlimited
`data.quota.used`	`integer`	Including this batch
`data.quota.remaining`	`integer`	What is left after this call
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
400	`invalid_request`	`updates` is empty, over 500 entries, contains a duplicate `prompt_id`, an entry with neither `country_codes` nor `is_active`, a `prompt_id` not found for this brand, an empty or over-20 `country_codes`, or an unsupported market code (the message names it and suggests the real one, e.g. `UK` -> `GB`)
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 net change would exceed your alignment-prompt allowance. Nothing is updated
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 updated. Retry shortly

Notes

is_active is new here, not on the regular-prompts endpoint. A tracked prompt cannot be paused at all, so Update prompt markets has no equivalent field. Alignment prompts can be, and pausing one frees its slots the same way deleting it would, without losing the prompt or its history.

Quota is a net delta across the whole batch, checked once. Growing one prompt from 1 to 3 markets while deactivating another frees that prompt’s slots in the same calculation — a batch that nets to zero or negative is never refused, even at 0 remaining allowance.

Deactivating zeroes out slots regardless of country_codes. If an entry sets is_active: false, its markets still get written when you also send country_codes, but they do not count toward usage while inactive. Reactivate later (with or without new country_codes) and its stored markets count again.

Validation is all-or-nothing. A prompt_id not found for this brand, a duplicate id in the same batch, an entry missing both fields, or an unsupported market code refuses the entire call and names the offender. Nothing is written unless every entry validates.

This replaces markets, it does not add or remove one. Send the complete new list for each prompt, including any markets you want to keep. To add SE to a prompt already tracking US, GB, send ["US", "GB", "SE"].

No re-execution is triggered. Adding a market or reactivating a prompt does not run it immediately — it starts being measured on the next daily alignment run, or an explicit Run alignment check call.

Prompt text and category are set elsewhere. Use Update alignment prompt for those — they carry no quota weight and are not accepted here.