Skip to main content
POST
/
v2
/
observations
Record Observations
curl --request POST \
  --url https://api.opennous.cloud/v2/observations \
  --header 'Content-Type: application/json' \
  --data '
{
  "focus": "<string>",
  "observations": [
    {
      "kind": "<string>",
      "property": "<string>",
      "value": "<any>",
      "source": "<string>",
      "method": "<string>",
      "observed_at": {},
      "external_id": "<string>",
      "raw": {}
    }
  ]
}
'
The only write verb in the customer graph. Agents never overwrite, they record observations. Nous derives the new facts automatically from the full observation history and tells you which were recomputed.

​
Request

curl -X POST https://api.opennous.cloud/v2/observations \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "focus": "sarah@acme.com",
    "observations": [
      {
        "kind": "event",
        "property": "interaction.email_sent",
        "value": { "subject": "Q3 pricing", "body_snippet": "..." }
      },
      {
        "kind": "state",
        "property": "intent",
        "value": "evaluating",
        "source": "agent"
      }
    ]
  }'

​
Body

​
focus
string
required
Entity UUID, email, domain, or LinkedIn URL. Not a bare name — writes need a precise identifier so the entity can be created if it doesn’t exist yet.
​
observations
array
required
One or more observations to append. Each:

​
Response

{
  "entity_id": "a1b2c3d4-...",
  "recorded": 2,
  "claims_recomputed": ["intent"]
}
claims_recomputed lists the state properties whose claim was re-derived after this batch — your downstream UI can refetch only those.

​
The observation model

You’re appending to an immutable, append-only customer graph. Two reasons:
  1. The graph self-heals. When a new observation contradicts an old one, the affected facts recompute and the belief shifts. Nothing is ever “lost.”
  2. Every claim is auditable — epistemic_class + sources on every claim let your agent (and your audit log) see exactly which observations support it.
Use null value on a state observation to assert the fact ended — they left the company, the deal closed-lost, the email bounced.