Create alignment category facts in bulk

Creates up to 500 facts in one request. Each fact is a verified statement about the brand that future Brand Alignment runs grade AI-stated claims against. Give each item a category_id to scope it to a category, or omit it for a brand-wide fact. Items can mix categories.

The request is all or nothing. If any item is invalid or names a category that does not belong to the brand, nothing is created.

Use Create alignment category fact for a single fact. Get category ids from List alignment categories.

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


POST /v1/brands/{brand_id}/alignment/category-facts/bulk

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
`facts`	`array`, 1–500 items	required	The facts to create, in order
`facts[].fact_text`	`string`, 1–1000 chars	required	The verified statement. Cannot be empty
`facts[].category_id`	`uuid \| null`	optional	Scope the fact to this category. Omit or send `null` for a brand-wide fact

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/category-facts/bulk' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"facts":[{"category_id":"b19f3c02-8e41-4b6a-9c17-5d2a781fe346","fact_text":"Enterprise plans include SSO via SAML and OAuth 2.0 at no extra cost."},{"fact_text":"Founded in Stockholm in 2019."}]}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/category-facts/bulk"
headers = {"Authorization": "Bearer <api-key>", "Idempotency-Key": "<unique-per-attempt>"}
payload = {
    "facts": [
        {
            "category_id": "b19f3c02-8e41-4b6a-9c17-5d2a781fe346",
            "fact_text": "Enterprise plans include SSO via SAML and OAuth 2.0 at no extra cost.",
        },
        {"fact_text": "Founded in Stockholm in 2019."},
    ]
}
 
response = requests.post(url, json=payload, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <api-key>', 'Idempotency-Key': '<unique-per-attempt>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    facts: [
      {
        category_id: 'b19f3c02-8e41-4b6a-9c17-5d2a781fe346',
        fact_text: 'Enterprise plans include SSO via SAML and OAuth 2.0 at no extra cost.',
      },
      {fact_text: 'Founded in Stockholm in 2019.'},
    ],
  })
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/category-facts/bulk', options)
  .then(res => res.json()).then(res => console.log(res)).catch(err => console.error(err));

Response

200


{
  "data": {
    "facts": [
      {
        "id": "e4a1c8f0-6b39-4d72-8a95-1f0c3e7b4d62",
        "category_id": "b19f3c02-8e41-4b6a-9c17-5d2a781fe346",
        "fact_text": "Enterprise plans include SSO via SAML and OAuth 2.0 at no extra cost.",
        "sort_order": 2,
        "created_at": "2026-10-08T09:16:47.118Z",
        "updated_at": "2026-10-08T09:16:47.118Z"
      },
      {
        "id": "0c7d2e91-3fa4-4b18-9e6d-52a1b8c4f073",
        "category_id": null,
        "fact_text": "Founded in Stockholm in 2019.",
        "sort_order": 5,
        "created_at": "2026-10-08T09:16:47.118Z",
        "updated_at": "2026-10-08T09:16:47.118Z"
      }
    ],
    "created": 2
  },
  "request_id": "req_7d21b0af59c34e18b6ac"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "This brand has 950 facts; adding 120 would exceed the limit of 1000 facts per brand. Delete facts first, or contact support.",
    "request_id": "req_4c81a0be29d34f1a6b72"
  }
}

403


{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the \"write:alignment\" scope, which your token does not have.",
    "request_id": "req_2a71d0ce38f14b9c7d05"
  }
}

404


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

Response fields

Field	Type	Description
`data.facts`	`array`	required. The created facts, in the order sent
`data.facts[].id`	`uuid`	required. Use it as `fact_id` with Update / Delete alignment category facts
`data.facts[].category_id`	`uuid \| null`	required. `null` means brand-wide
`data.facts[].fact_text`	`string`	required
`data.facts[].sort_order`	`integer`	required
`data.facts[].created_at`	`timestamptz`	required
`data.facts[].updated_at`	`timestamptz`	required
`data.created`	`integer`	required. How many facts were created
`request_id`	`string`	required. Also returned as the `x-request-id` header

Errors

Status	Code	When
400	`invalid_request`	Unknown field, `facts` empty or over 500 items, a `fact_text` empty or over 1000 characters, or the brand would exceed 1000 facts
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, this key is not allowed to reach it, or a `category_id` does not exist for this brand
429	`rate_limited`	Over 60 requests per minute

Notes

All or nothing. The facts are created in one statement. A request that fails creates none of them, so retrying it cannot leave duplicates of the ones that got through.

A brand holds at most 1000 facts. Every fact is sent to the model on every alignment check, so the limit counts all categories together. A request that would cross it is refused whole.

Facts append in the order sent. Within each category (and within the brand-wide group), new facts are placed after the existing ones, in the order they appear in facts.

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