Add Brand Facts
curl --request POST \
--url https://api.athenahq.ai/api/v1/knowledge-base/facts \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"website_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"facts": [
{
"text": "<string>",
"source_url": "<string>",
"pillar_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"match_token": "<string>",
"decisions": [
{
"claim_id": "<string>",
"text": "<string>"
}
],
"save_submitted": true
}
'import requests
url = "https://api.athenahq.ai/api/v1/knowledge-base/facts"
payload = {
"website_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"facts": [
{
"text": "<string>",
"source_url": "<string>",
"pillar_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"match_token": "<string>",
"decisions": [
{
"claim_id": "<string>",
"text": "<string>"
}
],
"save_submitted": True
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
website_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
facts: [
{
text: '<string>',
source_url: '<string>',
pillar_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
}
],
match_token: '<string>',
decisions: [{claim_id: '<string>', text: '<string>'}],
save_submitted: true
})
};
fetch('https://api.athenahq.ai/api/v1/knowledge-base/facts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.athenahq.ai/api/v1/knowledge-base/facts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'website_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'facts' => [
[
'text' => '<string>',
'source_url' => '<string>',
'pillar_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]
],
'match_token' => '<string>',
'decisions' => [
[
'claim_id' => '<string>',
'text' => '<string>'
]
],
'save_submitted' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.athenahq.ai/api/v1/knowledge-base/facts"
payload := strings.NewReader("{\n \"website_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"facts\": [\n {\n \"text\": \"<string>\",\n \"source_url\": \"<string>\",\n \"pillar_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"match_token\": \"<string>\",\n \"decisions\": [\n {\n \"claim_id\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"save_submitted\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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))
}HttpResponse<String> response = Unirest.post("https://api.athenahq.ai/api/v1/knowledge-base/facts")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"website_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"facts\": [\n {\n \"text\": \"<string>\",\n \"source_url\": \"<string>\",\n \"pillar_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"match_token\": \"<string>\",\n \"decisions\": [\n {\n \"claim_id\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"save_submitted\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.athenahq.ai/api/v1/knowledge-base/facts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"website_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"facts\": [\n {\n \"text\": \"<string>\",\n \"source_url\": \"<string>\",\n \"pillar_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"match_token\": \"<string>\",\n \"decisions\": [\n {\n \"claim_id\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"save_submitted\": true\n}"
response = http.request(request)
puts response.read_body{
"outcomes": [
{
"index": 123,
"outcome": "approved",
"fact_id": "<string>",
"pillar_id": "<string>",
"matches": [
{
"id": "<string>",
"text": "<string>",
"status": "pending",
"source_type": "research",
"source_url": "<string>",
"first_party": true,
"pillar_id": "<string>",
"pillar_name": "<string>",
"created_at": "2023-11-07T05:31:56Z"
}
]
}
],
"match_token": "<string>",
"resolved": {
"approved_fact_ids": [
"<string>"
],
"pending_fact_ids": [
"<string>"
],
"removed_fact_ids": [
"<string>"
]
}
}Knowledge Base
Add Brand Facts
Adds brand facts to a website’s Knowledge Base in bulk (1-50 per call). Every fact runs the full ingestion pipeline — deduplication, approval gates, and pillar routing — and there is no way to force-approve: inputs are declarative (text, optional source URL, optional pillar pin) and the response reports one outcome per fact. Facts without a pillar_id are routed automatically and may land unfiled. A fact that facts already in the Knowledge Base say something similar to is not added: its outcome is duplicate and lists them under matches, and the response carries a match_token. Resolve them with a second call carrying the same facts, the match_token, one decision per listed match and save_submitted. Requires a website-admin API key. Also available as the MCP tool add_brand_facts.
POST
/
api
/
v1
/
knowledge-base
/
facts
Add Brand Facts
curl --request POST \
--url https://api.athenahq.ai/api/v1/knowledge-base/facts \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"website_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"facts": [
{
"text": "<string>",
"source_url": "<string>",
"pillar_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"match_token": "<string>",
"decisions": [
{
"claim_id": "<string>",
"text": "<string>"
}
],
"save_submitted": true
}
'import requests
url = "https://api.athenahq.ai/api/v1/knowledge-base/facts"
payload = {
"website_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"facts": [
{
"text": "<string>",
"source_url": "<string>",
"pillar_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"match_token": "<string>",
"decisions": [
{
"claim_id": "<string>",
"text": "<string>"
}
],
"save_submitted": True
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
website_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
facts: [
{
text: '<string>',
source_url: '<string>',
pillar_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
}
],
match_token: '<string>',
decisions: [{claim_id: '<string>', text: '<string>'}],
save_submitted: true
})
};
fetch('https://api.athenahq.ai/api/v1/knowledge-base/facts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.athenahq.ai/api/v1/knowledge-base/facts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'website_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'facts' => [
[
'text' => '<string>',
'source_url' => '<string>',
'pillar_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]
],
'match_token' => '<string>',
'decisions' => [
[
'claim_id' => '<string>',
'text' => '<string>'
]
],
'save_submitted' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.athenahq.ai/api/v1/knowledge-base/facts"
payload := strings.NewReader("{\n \"website_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"facts\": [\n {\n \"text\": \"<string>\",\n \"source_url\": \"<string>\",\n \"pillar_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"match_token\": \"<string>\",\n \"decisions\": [\n {\n \"claim_id\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"save_submitted\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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))
}HttpResponse<String> response = Unirest.post("https://api.athenahq.ai/api/v1/knowledge-base/facts")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"website_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"facts\": [\n {\n \"text\": \"<string>\",\n \"source_url\": \"<string>\",\n \"pillar_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"match_token\": \"<string>\",\n \"decisions\": [\n {\n \"claim_id\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"save_submitted\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.athenahq.ai/api/v1/knowledge-base/facts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"website_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"facts\": [\n {\n \"text\": \"<string>\",\n \"source_url\": \"<string>\",\n \"pillar_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"match_token\": \"<string>\",\n \"decisions\": [\n {\n \"claim_id\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"save_submitted\": true\n}"
response = http.request(request)
puts response.read_body{
"outcomes": [
{
"index": 123,
"outcome": "approved",
"fact_id": "<string>",
"pillar_id": "<string>",
"matches": [
{
"id": "<string>",
"text": "<string>",
"status": "pending",
"source_type": "research",
"source_url": "<string>",
"first_party": true,
"pillar_id": "<string>",
"pillar_name": "<string>",
"created_at": "2023-11-07T05:31:56Z"
}
]
}
],
"match_token": "<string>",
"resolved": {
"approved_fact_ids": [
"<string>"
],
"pending_fact_ids": [
"<string>"
],
"removed_fact_ids": [
"<string>"
]
}
}Body
application/json
The website whose Knowledge Base to add facts to.
The facts to ingest. No status or approval field exists — the pipeline decides.
Required array length:
1 - 50 elementsShow child attributes
Show child attributes
Second call only: the match_token from a response that listed matches. Send it with the same facts that were not added, one decision per listed match and save_submitted.
Second call only: one decision for every fact listed under matches, and only those. approve keeps the fact: an approved fact stays approved (and is filed under the facts' pillar if it has none); a pending fact is approved only when the same approval rules as a new fact allow its text and source (a third-party source or a competitive claim keeps it pending). With text, the fact is replaced by that wording, whose status the same rules decide. delete rejects a pending fact or archives an approved one.
Maximum array length:
500Show child attributes
Show child attributes
Second call only: true adds the facts as written, without another similarity check, through the usual approval gates; false only applies the decisions. The decisions and the added facts are written together or not at all.
Response
Facts ingested; one outcome per fact, aligned with the request by index
Show child attributes
Show child attributes
Present when any outcome lists matches. Send it back on the second call.
Present on a second call: the listed facts the decisions approved, the approved ones the approval rules kept pending (a fact given new wording has a new id), and the ones rejected or archived.
Show child attributes
Show child attributes
Was this page helpful?