Create Knowledge Grant

POST /knowledge-grants

Grant an agent access to a base it does not own — explicitly, or dynamically.

KnowledgeService.grant was written, validated and unit-tested at M7 and called by nothing: the explicit grant created alongside a base was the only authorization anybody could produce, and annex 10 §4’s dynamic control existed in the schema only. This route is the caller.

Idempotent by the row’s own unique key: granting the same agent the same access twice returns the incumbent rather than conflicting, because the second call asked for a state that already holds.

Role floor

Requires admin 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.

Request body — KnowledgeGrantWrite

Field	Type		Notes
agent_id	string (uuid)	required	—
kb_id	string (uuid) | null	optional	—
kb_kind	string | null	optional	max length 60
dynamic_scope	string | null	optional	max length 40
mode	read | write	optional	Default "read".

Responses

Status	Description	Body
201	Successful Response	KnowledgeGrantView
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

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-grants \
  -H "Authorization: Bearer $COBRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "agent_id": "0190a2f4-0000-7000-8000-000000000000"
     }'

Response — KnowledgeGrantView

Field	Type		Notes
id	string (uuid)	required	—
agent_id	string (uuid)	required	—
kb_id	string (uuid) | null	required, nullable	—
kb_kind	string | null	required, nullable	—
dynamic_scope	string | null	required, nullable	—
mode	read | write	required	—
created_at	string (date-time)	required	—