Update prompt markets

Changes which markets one or more prompts are tracked in. Each entry in updates replaces that prompt’s markets entirely — there is no add/remove, only “these are the markets now”.

Quota is checked once, as a net delta over the whole batch, not per prompt: shrinking one prompt’s markets in the same call can offset growing another’s, 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:prompts scope, and the workspace must be enabled for API writes.


PATCH /v1/brands/{brand_id}/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 prompts
`updates[].country_codes`	`string[]`, 1-20	required	Replaces the prompt’s markets. A prompt must keep at least one

Request

cURL


curl --request PATCH \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/countries' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: 5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa' \
  --header 'Content-Type: application/json' \
  --data '{"updates": [{"prompt_id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852", "country_codes": ["US", "GB"]}]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts/countries"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa",
    "Content-Type": "application/json",
}
payload = {
    "updates": [
        {"prompt_id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852", "country_codes": ["US", "GB"]},
    ]
}
 
response = requests.patch(url, json=payload, headers=headers)
print(response.json())

JavaScript


const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    updates: [
      {prompt_id: '7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852', country_codes: ['US', 'GB']},
    ],
  }),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/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/prompts/countries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    "updates" => [
      ["prompt_id" => "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852", "country_codes" => ["US", "GB"]],
    ],
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: 5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa",
    "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/prompts/countries"
 
    payload := strings.NewReader(`{"updates": [{"prompt_id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852", "country_codes": ["US", "GB"]}]}`)
 
    req, _ := http.NewRequest("PATCH", url, payload)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa")
    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/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"] = '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa'
request["Content-Type"] = 'application/json'
request.body = {
  updates: [
    {prompt_id: "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852", country_codes: ["US", "GB"]},
  ],
}.to_json
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "updated_prompt_ids": ["7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852"],
    "net_change": 1,
    "quota": {
      "limit": 200,
      "used": 149,
      "remaining": 51
    }
  },
  "request_id": "req_5c1e93f8a2074b6dbf30"
}

403 quota


{
  "error": {
    "code": "quota_exceeded",
    "message": "Active prompt limit reached (200/200). This change needs 1 more slot, and 0 remain.",
    "request_id": "req_5c92e0da71b34f68a3df"
  }
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852: \"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 is one slot
`data.quota`	`object`	Present only when `net_change` was positive
`data.quota.limit`	`integer \| null`	Your plan’s active-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`, 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
403	`insufficient_scope`	The key does not carry `write:prompts`
403	`plan_required`	This workspace is not enabled for API writes
403	`quota_exceeded`	The net change would exceed your active-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

Quota is a net delta across the whole batch, checked once. Growing one prompt from 1 to 3 markets while shrinking another from 2 to 1 is a net change of +1, not +2 — the reduction is folded into the same check. A batch that is a net reduction or zero is never refused, even at 0 remaining allowance.

Validation is all-or-nothing. A prompt_id not found for this brand, a duplicate id in the same batch, 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 does not run the prompt in that market immediately — it starts being measured on the next scheduled run, the same as the app.