Update alignment category fact

Changes an existing fact’s text and/or its position within its scope. A fact’s category is fixed at creation: this endpoint can never move a fact between categories, or between a category and brand-wide — send category_id and it is refused as an unknown field.

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


PATCH /v1/brands/{brand_id}/alignment/category-facts/{fact_id}

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
`fact_id`	`uuid`	required	From List alignment category facts

Query parameters

None.

Body

application/json

Field	Type	Required	Description
`fact_text`	`string`, 1–1000 chars	required	The verified statement. Replaces the previous text entirely. Required on every call — resend the current text if you are only changing `sort_order`
`sort_order`	`integer`	optional	New position within the fact’s existing category (or brand-wide group). Omitted leaves it unchanged

Request

cURL


curl --request PATCH \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/category-facts/3f8b0e6a-9c42-4e17-8f0b-6c951a2d7e40' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"fact_text":"Enterprise plans include SSO via SAML and OAuth 2.0, and SCIM provisioning, at no extra cost.","sort_order":2}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/category-facts/3f8b0e6a-9c42-4e17-8f0b-6c951a2d7e40"
headers = {"Authorization": "Bearer <api-key>", "Idempotency-Key": "<unique-per-attempt>"}
payload = {
    "fact_text": "Enterprise plans include SSO via SAML and OAuth 2.0, and SCIM provisioning, at no extra cost.",
    "sort_order": 2,
}
 
response = requests.patch(url, json=payload, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <api-key>', 'Idempotency-Key': '<unique-per-attempt>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fact_text: 'Enterprise plans include SSO via SAML and OAuth 2.0, and SCIM provisioning, at no extra cost.',
    sort_order: 2,
  })
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/alignment/category-facts/3f8b0e6a-9c42-4e17-8f0b-6c951a2d7e40', options)
  .then(res => res.json()).then(res => console.log(res)).catch(err => console.error(err));

Response

200


{
  "data": {
    "fact": {
      "id": "3f8b0e6a-9c42-4e17-8f0b-6c951a2d7e40",
      "category_id": "b19f3c02-8e41-4b6a-9c17-5d2a781fe346",
      "fact_text": "Enterprise plans include SSO via SAML and OAuth 2.0, and SCIM provisioning, at no extra cost.",
      "sort_order": 2,
      "created_at": "2026-08-12T10:02:31.884Z",
      "updated_at": "2026-08-30T09:16:47.118Z"
    }
  },
  "request_id": "req_7d21b0af59c34e18b6ac"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Unknown field 'category_id'. Allowed: fact_text, sort_order.",
    "request_id": "req_4c81a0be29d34f1a6b72"
  }
}

404


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

403


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

Response fields

The fact after the change, in the same shape List alignment category facts returns its rows.

Field	Type	Description
`data.fact.id`	`uuid`	required
`data.fact.category_id`	`uuid \| null`	required. Unchanged by this call — see Notes
`data.fact.fact_text`	`string`	required
`data.fact.sort_order`	`integer`	required
`data.fact.created_at`	`timestamptz`	required
`data.fact.updated_at`	`timestamptz`	required
`request_id`	`string`	required

Errors

Status	Code	When
400	`invalid_request`	Unknown field (including `category_id`), a body missing `fact_text`, `fact_text` empty or over 1000 characters, or `sort_order` not an integer
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 fact does not exist or belongs to another brand
429	`rate_limited`	Over 60 requests per minute

Notes

fact_text is required on every call, not optional. Unlike sort_order, there is no partial update for it — to reposition a fact without changing its wording, resend the current fact_text alongside the new sort_order.

category_id cannot be changed here. An update never moves a fact between categories, or between a category and brand-wide. Sending category_id returns 400; to recategorise a fact, delete it with Delete alignment category facts and create it again in the category you want.

Idempotency-Key is required. See Idempotency.