create_entities

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

Purpose

Creates entities in the knowledge graph, each with a name, type, and optional observations, project, aliases, and visibility. Names are unique: a repeated name resolves to the existing identity rather than duplicating it.

Arguments

Required: entities.

entities. Note: Each entry needs name and entityType; observations is a string list, aliases a free-form list, project a tag. Untagged creation needs an explicit untagged grant.

Result

JSON object with created (newly created plus revived count), total_requested, entity_ids (one per resolved entity), and observation_ids (for observations added by this call).

Boundaries

Every entry needs the write grant for its project, and the whole batch fails closed on the first denied entry. Duplicate names belonging to foreign projects answer entity name already exists, never revealing their content.

Lifecycle / side effects

Creations record an audit/history event each. A repeated name revives the same identity when retired (void stamps stay as last-void evidence) or reuses the live one, still accepting new observations, aliases, and project backfill on this call. Duplicate observation text is skipped by content identity.

Errors

entities must be an array; entries need string name and entityType. Unknown arguments are rejected (strict validator). Denied projects fail the whole batch with nothing half-applied (atomic).

Example

{
  "entities": [
    {
      "entityType": "vendor",
      "name": "Acme Print",
      "observations": [
        "Local print shop on High Street."
      ],
      "project": "shared-ops"
    }
  ]
}

Result shape:

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