link_task_entity

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

Purpose

Creates a manual link between a task and a knowledge-graph entity. Manual links always win: an existing auto-discovered link for the pair is upgraded rather than duplicated.

Arguments

Required: task_id, entity_name.

task_id.
entity_name.

Result

JSON object with the decision record (decision_id, task_id, entity_id, entity_name, decision accepted, score, rank_at_decision, model_version, label_progress) plus link_type (manual) and created_at for the link.

Boundaries

Both the task and the entity must be visible under the caller's project grants. An invisible task answers Task not found; an unknown or invisible entity answers Entity not found; neither leaks the other side.

Lifecycle / side effects

Records an accepted manual decision and creates (or revives and upgrades) the link in one atomic unit, clearing any prior removal marker for the pair. Re-linking an existing manual link refreshes it rather than duplicating it.

Errors

Missing task_id or entity_name is rejected by validation. Unknown arguments are rejected (strict validator). Unknown or out-of-scope endpoints answer not-found. Failures link nothing (atomic).

Example

{
  "entity_name": "Acme Print",
  "task_id": "<uuid>"
}

Result shape:

{
  "created_at": "<iso-8601>",
  "decision": "accepted",
  "decision_id": "<uuid>",
  "entity_name": "Acme Print",
  "link_type": "manual",
  "task_id": "<uuid>"
}