REST API
POST /v1/facts
Write a single subject-predicate-object fact.
Shortcut for writing a single structured fact. Internally this composes a sentence and routes through the same extraction pipeline as POST /v1/episodes, so the response shape is identical.
Scope required: write
Request
POST /v1/facts
Authorization: Bearer ck_live_...
Content-Type: application/json{
"subject": "Nandini Kulkarni",
"predicate": "promoted_to",
"object": "Staff Engineer",
"group_id": "default",
"extract_intent": false
}| Field | Type | Required | Notes |
|---|---|---|---|
subject | string, ≤ 240 chars | yes | The actor / source entity |
predicate | string, ≤ 120 chars | yes | The relation. Underscores are converted to spaces when synthesizing the sentence. |
object | string, ≤ 240 chars | yes | The target entity |
group_id | string | no ("default") | Sub-namespace within your project |
extract_intent | bool | no (false) | Same semantics as /v1/episodes. See Intents. |
The composed sentence Breeth ingests is:
{subject} {predicate-with-spaces} {object}So predicate: "promoted_to" becomes "promoted to" inside the prose.
Response
Identical shape to POST /v1/episodes.
When to use facts vs episodes
Use POST /v1/episodes when… | Use POST /v1/facts when… |
|---|---|
| You have natural-language prose (chat turn, journal entry, doc paragraph) | You already have structured S-P-O data and want a fast write path |
| The content carries multiple distinct facts | The fact is atomic and you want it written as a single edge |
| You want intent annotation on rich content | You want a minimal-overhead structured ingest |
They land in the same graph
There's no semantic distinction in storage. A fact written via /v1/facts is indistinguishable from the same fact extracted from prose via /v1/episodes.
Examples
curl -X POST https://api.thebreeth.com/v1/facts \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "Sridhar Cheeti",
"predicate": "prefers",
"object": "async Rust over Go"
}'r = httpx.post(
"https://api.thebreeth.com/v1/facts",
headers={"Authorization": f"Bearer {KEY}"},
json={
"subject": "Sridhar Cheeti",
"predicate": "prefers",
"object": "async Rust over Go",
},
)await fetch("https://api.thebreeth.com/v1/facts", {
method: "POST",
headers: {
"Authorization": `Bearer ${KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
subject: "Sridhar Cheeti",
predicate: "prefers",
object: "async Rust over Go",
}),
});