Create alignment category

Creates a category to group alignment prompts and claims under, for example “Pricing” or “Support” — the same as the “Add Category” button on the Alignment Prompts page.

The slug is derived from the name and must be unique within the brand. You cannot set it directly.

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


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

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
`name`	`string`, 1-100 chars	required	Its derived slug must be unique in the brand
`description`	`string`, up to 500 chars	optional

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/categories' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: 5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Pricing", "description": "Claims about cost, plans and billing."}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/categories"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa",
    "Content-Type": "application/json",
}
payload = {"name": "Pricing", "description": "Claims about cost, plans and billing."}
 
response = requests.post(url, json=payload, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Pricing',
    description: 'Claims about cost, plans and billing.',
  }),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/categories', 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/categories",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Pricing",
    "description" => "Claims about cost, plans and billing.",
  ]),
  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/alignment/categories"
 
    payload := strings.NewReader(`{"name": "Pricing", "description": "Claims about cost, plans and billing."}`)
 
    req, _ := http.NewRequest("POST", 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/alignment/categories")
 
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"] = '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa'
request["Content-Type"] = 'application/json'
request.body = {
  name: "Pricing",
  description: "Claims about cost, plans and billing.",
}.to_json
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "category": {
      "id": "8f3d2c1b-6a94-4e57-9c02-1b7f4d3a8e65",
      "name": "Pricing",
      "slug": "pricing",
      "description": "Claims about cost, plans and billing.",
      "sort_order": 0,
      "is_system": false,
      "active_prompt_count": 0
    }
  },
  "request_id": "req_7d21b0af59c34e18b6ac"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Invalid input for asky_alignment_category_create: name: name cannot be empty",
    "request_id": "req_2d61f0ac48b34e59c7bd"
  }
}

403 plan


{
  "error": {
    "code": "plan_required",
    "message": "This workspace is not enabled for API writes. Contact support to have it turned on.",
    "request_id": "req_9d4a7c1e3b5f48d0ac2e"
  }
}

404


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

409


{
  "error": {
    "code": "conflict",
    "message": "This brand already has a category with that name.",
    "request_id": "req_4c81a0be29d34f1a6b72"
  }
}

Response fields

Field	Type	Description
`data.category.id`	`uuid`	required. Use it as a `category_id` filter, or with Update / Delete alignment category
`data.category.name`	`string`	required
`data.category.slug`	`string`	required. Derived from the name, unique per brand
`data.category.description`	`string \| null`	required
`data.category.sort_order`	`integer`	required
`data.category.is_system`	`boolean`	required. Always `false` for a category created here
`data.category.active_prompt_count`	`integer`	required. Always `0` — a category has no prompts assigned to it yet at creation
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
400	`invalid_request`	Unknown field, empty or over-100-character `name`, or `description` over 500 characters
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
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
409	`conflict`	Another category in this brand already has that name
429	`rate_limited`	Over 60 requests per minute

Notes

Slugs are derived, not supplied. "Pricing" and "pricing" collide, and the second returns 409.

New categories are never is_system. That flag is reserved for a small set of categories seeded automatically; every category created here is false.

Assign prompts to it separately. This only creates the category. Use Create alignment prompt with category_id set, or Update alignment prompt to move an existing prompt into it.

Idempotency-Key is required. Reuse it when retrying an attempt and the original response is replayed rather than a second category being created. See Idempotency.