List Knowledge Items

GET /knowledge-items

A flat collection filtered by kb_id, not /knowledge-bases/{id}/items.

Annex 05 §1.2 settles it in one line — “deeper nesting becomes a filtered collection instead: /knowledge-items?kb_id=…” — and the reason survives the appeal to authority: three of the four item placements (agent, subject, conversation) have no kb_id at all, so a nested route could not address them. A curator’s real question is “what is pending across everything I own”, which is one page here and a fan-out over every base under the nested form. The routes that are nested in this API — /agents/{id}/revisions, /runs/{id}/steps — are for children that cannot exist without the parent. An item can.

The three axes of annex 10 §1.1 are each filterable, on purpose: item_scope (who can see it), kind (how it is used) and curation_state (is it trusted). Two of three is the surface that reads complete and cannot answer “what did the agent write privately that is still pending”.

Role floor

Requires viewer or above. The floor is a minimum, not a grant: scope filtering still applies on top of it, and a resource in another tenant answers 404 rather than 403.

Parameters

Name	In	Type		Notes
kb_id	query	string (uuid) | null	optional	—
item_scope	query	kb | agent | subject | conversation | null	optional	—
kind	query	fact | rule | open_question | hub | null	optional	—
curation_state	query	pending | reviewed | promoted | superseded | retired | null	optional	—
origin	query	human | agent | import | derived | null	optional	who authored it
agent_id	query	string (uuid) | null	optional	agent-placed items
persona_id	query	string (uuid) | null	optional	items written by this overlay
session_id	query	string (uuid) | null	optional	conversation-placed items
subject_kind	query	user | guest | null	optional	—
subject_id	query	string | null	optional	—
q	query	string | null	optional	substring of content or title
include_structural	query	boolean	optional	include hubs Default false.
created_after	query	string (date-time) | null	optional	—
created_before	query	string (date-time) | null	optional	—
viewer_agent_id	query	string (uuid) | null	optional	read as this agent: unlocks its private bases
limit	query	integer	optional	Default 50. min 1 max 200
cursor	query	string | null	optional	—
offset	query	integer | null	optional	min 0

Responses

Status	Description	Body
200	Successful Response	Page_KnowledgeItemView_
422	Validation Error	HTTPValidationError

Only the success paths are declared

Any operation may also answer any status in the error catalogue, and every failure body is the platform envelope — including the 422 this document types as HTTPValidationError.

Example

curl -X GET https://your-deployment.example.com/knowledge-items \
  -H "Authorization: Bearer $COBRE_TOKEN"

Response — Page_KnowledgeItemView_

Field	Type		Notes
items	KnowledgeItemView[]	required	—
next_cursor	string | null	optional	—
total	integer | null	optional	—