Skip to main content
Agents never overwrite. They observe. record appends one or more observations to the customer graph, which re-derives the affected facts and tells you which ones changed.

​
Parameters

NameTypeRequiredDescription
focusstring✓Email or entity UUID — needs a precise identifier so the entity can be created if it doesn’t exist
observationsarray✓One or more observations to record
Each observation:
FieldTypeRequiredDescription
kind"event" or "state"✓event = an interaction; state = a fact
propertystring✓e.g. interaction.email_sent, interaction.call_held, job_title, pipeline_stage
valueanyEvent detail, or the fact value. Use null on a state observation to assert the fact ended
sourcestringWhere the signal came from. Default: agent

​
Examples

Sent an email: 
{
  "focus": "sarah@acme.com",
  "observations": [
    {
      "kind": "event",
      "property": "interaction.email_sent",
      "value": { "subject": "Q3 pricing", "body_snippet": "Quick note on…" }
    }
  ]
}
Learned their title changed: 
{
  "focus": "sarah@acme.com",
  "observations": [
    { "kind": "state", "property": "job_title", "value": "VP of Engineering" }
  ]
}
A fact ended (they left the company): 
{
  "focus": "sarah@acme.com",
  "observations": [
    { "kind": "state", "property": "job_title", "value": null }
  ]
}

​
Returns

Recorded 1 observation.
Facts updated: job_title.
(entity_id: a1b2c3d4-...)
Facts updated lists the state properties whose claim was re-derived after the batch — useful for downstream refresh logic.

​
The observation model

Two reasons agents observe instead of update:
  1. The graph self-heals. A new observation contradicts an old one and the affected facts recompute, pulling the belief back toward truth. Nothing is “lost.”
  2. Every claim is auditable — epistemic_class + sources on every claim trace back to the observations that produced it.

​
Backed by

POST /v2/observations — see the HTTP reference for the raw JSON shape.