Relations
Add, replace or retire a relation
POST/relations
Scopegraph:writeRoleOwner, admin or analystBilling1 credit per call
Writes one versioned change. add creates a live edge beside existing ones; replace supersedes named edges, every LLM-derived edge, or all edges with the new one; retire supersedes with no replacement. Adding an edge the pipeline already holds promotes it to yours instead of duplicating it. Human decisions outrank the pipeline: the scheduled refresh never overwrites an edge a person or key wrote.
Headers
Idempotency-Keystringoptional
1–128 visible ASCII characters. Retrying with the same key returns the original response; reusing it for different input returns 409.
Body
fromKindenumrequired
customer · account_person
fromIduuidrequired
relationTypeenumrequired
matches_icp · matches_persona · interested_in_use_case · uses_product · discussed_competitor
toKindenumrequired
icp · persona · use_case · product · competitor
toIduuidoptional
Required for add and replace.
modeenumrequired
add · replace · retire
replace{ scope, relationIds? }optional
replace only. scope is named · all_llm · all; named requires relationIds.
retireRelationIduuidoptional
retire only.
evidencestringoptional
Up to 2000 characters.
reasonstringrequired
Why this change is being made. 1–500 characters. Stored in the audit trail.
Response
addedRelation | null
retiredRelation[]
revivedRelation | null
confirmedRelation | null
liveIdstring | null