create_relations

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

Purpose

Creates typed relations between entities, such as depends-on or produces. Relations only ever join two visible, live entities.

Arguments

Required: relations.

relations. Note: Each entry needs from, to (entity names), and relationType. Entries with a missing endpoint are silently skipped.

Result

JSON object with created (newly created plus revived count), total_requested, and relation_ids.

Boundaries

Both endpoints must be live and visible under the caller's project grants; anything else is silently skipped with zero contribution, so callers cannot probe foreign content by name. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Each creation records an audit/history event. Duplicate triples are skipped; re-creating a retired triple revives the same relation identity with its history preserved.

Errors

relations must be an array; entries need string from, to, and relationType. Unknown arguments are rejected (strict validator). Failures create nothing (atomic).

Example

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

Result shape:

{
  "created": 1,
  "relation_ids": [
    "<uuid>"
  ],
  "total_requested": 1
}