Create fact

Adds a verified statement about the brand. Brand Alignment compares what AI search engines say about the company against these, so you can catch misrepresentations before they shape buyer perception. Same list as the Facts tab of the Brand Profile page.

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


POST /v1/brands/{brand_id}/facts

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, rather than being ignored silently.

Body

application/json

Field	Type	Required	Description
`fact_text`	`string`, 1–300 chars	required	The statement to check AI responses against
`sort_order`	`integer`, 0–10000	optional	Display position. Defaults to the end of the list

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/facts' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"fact_text":"Asky was founded in 2025 and is headquartered in Stockholm."}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/facts"
 
headers = {"Authorization": "Bearer <api-key>",
    "Idempotency-Key": "<unique-per-attempt>"}
 
payload = {"fact_text": "Asky was founded in 2025 and is headquartered in Stockholm."}
 
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({"fact_text": "Asky was founded in 2025 and is headquartered in Stockholm."})
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/facts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Response

200


{
  "data": {
    "fact": {
      "id": "9f2c1d84-6b31-4a2e-9c77-1e5b0a3f8d42",
      "fact": "Asky was founded in 2025 and is headquartered in Stockholm.",
      "sort_order": 3
    }
  },
  "request_id": "req_7d21b0af59c34e18b6ac"
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it in Settings to get a replacement.",
    "request_id": "req_8f21c0aa47b1490d2e63"
  }
}

403


{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not carry the scope this endpoint requires.",
    "request_id": "req_2a71d0ce38f14b9c7d05"
  }
}

404


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

Response fields

Field	Type	Description
`data.fact.id`	`uuid`	required. Use it to update or delete the fact
`data.fact.fact`	`string`	required. The statement text
`data.fact.sort_order`	`integer`	required. Display position
`request_id`	`string`	required. Also returned as the `x-request-id` header

Errors

Status	Code	When
400	`invalid_request`	An unknown field, empty `fact_text`, or a value over its limit
401	`invalid_token`	The key is missing, malformed, or does not exist
403	`insufficient_scope`	The key does not carry `write:brand_profile`
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
429	`rate_limited`	Over 60 requests per minute. See the `Retry-After` header

Notes

Facts are brand-level. Alignment categories can also carry their own facts; those are authored inside a category and are not reachable here, matching the Facts tab.

Read them back through Get brand profile, whose verified_facts array carries each id and sort_order.

Idempotency-Key is required. Send a unique value per attempt and reuse it when retrying that attempt, so a lost response does not become a duplicate fact. See Idempotency.