delete_relations

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

Purpose

Retires named relations from the knowledge graph. Despite the name, nothing is physically removed: this is a lifecycle transition (active to voided) covered by the no-delete invariant, and re-creating the triple revives the same identity.

Arguments

Required: relations.

relations. Note: Each entry needs from, to (entity names), and relationType, matched exactly. Unknown endpoints and non-matching triples are silently skipped with zero contribution.

Result

JSON object with deleted (count of relations retired by this call).

Boundaries

Scope is enforced per endpoint: triples touching content outside the caller's project grants are silently skipped, never denied loudly, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Records an audit/history event per retired relation, then marks it void with voided stamps. Re-creating the same triple revives the original identity (history lives in the audit trail).

Errors

relations must be an array; entries need string from, to, and relationType. Unknown arguments are rejected (strict validator). The operation fails atomically (zero partial voids). deleted 0 with no error means nothing matched or nothing was visible.

Example

{
  "relations": [
    {
      "from": "Acme Print",
      "relationType": "supplies",
      "to": "Paul Pack"
    }
  ]
}

Result shape:

{
  "deleted": 1
}