add_observations

Category: knowledge
Access: write
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Appends observations to existing entities. The everyday way to grow what is known about people, vendors, and topics without touching entity identity.

Arguments

Required: observations.

observations. Note: Each entry needs entityName plus a contents string list. Non-string contents are skipped; absent contents still refresh the entity timestamp.

Result

JSON object with added (newly added plus revived count) and observation_ids.

Boundaries

Unknown entities and entities outside the caller's project grants are silently skipped with zero contribution, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Each addition records an audit/history event. Duplicate text is skipped by content identity; re-adding retired text revives the same observation identity with its original creation evidence intact.

Errors

observations must be an array; entries need a string entityName. Unknown arguments are rejected (strict validator). Failures add nothing (atomic).

Example

{
  "observations": [
    {
      "contents": [
        "Now offers same-day turnaround."
      ],
      "entityName": "Acme Print"
    }
  ]
}

Result shape:

{
  "added": 1,
  "observation_ids": [
    "<uuid>"
  ]
}