Skip to content

Create Knowledge Edge

POST /knowledge-edges

Draw a relation by hand. It lands confirmed: a person drew it deliberately.

A part_of edge that would close a cycle is a 422 (RULE KE-2), and a pair that already has this relation is a 409 rather than a silent no-op — the maintenance pass skips a related pair on purpose, and a human asking twice deserves to be told the answer.

Request body — `KnowledgeEdgeWrite`

Field	Type		Notes
`from_item_id`	string (uuid)	required	—
`to_item_id`	string (uuid)	required	—
`kind`	`part_of` \| `supports` \| `contradicts` \| `derived_from` \| `supersedes` \| `relates_to` \| `answers` \| `shares_topic`	required	—
`status`	`proposed` \| `confirmed` \| `rejected` \| null	optional	—
`criticality`	`low` \| `normal` \| `high`	optional	Default `"normal"`.
`notes`	string \| null	optional	—
`knowledge_set`	string \| null	optional	min length 1 max length 120

Responses

Status	Description	Body
`201`	Successful Response	`KnowledgeEdgeView`
`422`	Validation Error	`HTTPValidationError`

Example

The body shows the fields the schema always carries. Which combination is legal is a service rule the schema cannot express, so read the description above before copying this.

curl -X POST https://your-deployment.example.com/knowledge-edges \
  -H "Authorization: Bearer $COBRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "from_item_id": "0190a2f4-0000-7000-8000-000000000000",
       "to_item_id": "0190a2f4-0000-7000-8000-000000000000",
       "kind": "part_of"
     }'

Response — `KnowledgeEdgeView`

Field	Type		Notes
`id`	string (uuid)	required	—
`from_item_id`	string (uuid)	required	—
`to_item_id`	string (uuid)	required	—
`kind`	`part_of` \| `supports` \| `contradicts` \| `derived_from` \| `supersedes` \| `relates_to` \| `answers` \| `shares_topic`	required	—
`status`	`proposed` \| `confirmed` \| `rejected`	required	—
`criticality`	`low` \| `normal` \| `high`	required	—
`notes`	string \| null	required, nullable	—
`created_by`	`agent` \| `human` \| `maintenance`	required	—
`curated_by_id`	string (uuid) \| null	required, nullable	—
`curated_at`	string (date-time) \| null	required, nullable	—
`created_at`	string (date-time)	required	—
`updated_at`	string (date-time)	required	—