Manage knowledge entries — observations, references, preferences, and more.

Overview

Knowledge is the general storage layer that underpins skills. While skills have their own dedicated endpoints, knowledge entries of other types (observations, references, preferences) are managed here.

Type	Description
`skill`	Reusable agent instructions (use `/skills` endpoints instead)
`observation`	Learned facts or patterns
`reference`	Pointers to external resources
`preference`	User or team preferences

List Knowledge

GET /knowledge or POST /knowledge/list

Returns knowledge entries with cursor-based pagination.

Query Parameters

Field	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer	Max results (default 50, max 100)

Response

json

1{2  "data": [3    {4      "id": "know_abc123",5      "namespace": "myteam",6      "name": "api-rate-limits",7      "description": "Known rate limits for external APIs we integrate with",8      "type": "reference",9      "version_id": "ver_xyz789",10      "version": {11        "id": "ver_xyz789",12        "content": { "path": "content.md", "uri": "https://..." },13        "files": [],14        "tags": ["api", "infrastructure"],15        "metadata": {}16      },17      "visibility": "private",18      "created_at": "2026-01-15T10:30:00Z"19    }20  ],21  "next_cursor": "abc123",22  "has_more": true23}

Get Knowledge

GET /knowledge/{id}

Returns a single knowledge entry by ID.

Get Versions

GET /knowledge/{id}/versions or POST /knowledge/{id}/versions/list

Returns version history for a knowledge entry.

Get Lineage

GET /knowledge/{id}/lineage

Returns relationships: parents, siblings, forks, and duplicates.

json

1{2  "parents": [{ "id": "...", "name": "..." }],3  "siblings": [],4  "forks": [],5  "duplicates": []6}

Create Knowledge

POST /knowledge

Requires authentication.

Request

json

1{2  "name": "api-rate-limits",3  "description": "Known rate limits for external APIs",4  "type": "reference",5  "version": {6    "content": { "path": "content.md", "content": "# API Rate Limits\n\n..." },7    "tags": ["api", "infrastructure"],8    "metadata": { "source": "manual" }9  }10}

Field	Required	Description
`name`	yes	Kebab-case, immutable after creation
`description`	yes	What this knowledge contains
`type`	no	Entry type (default: `observation`)
`version.content`	yes	Content with path and text
`version.tags`	no	Searchable tags
`version.metadata`	no	Arbitrary key-value pairs

Response

Returns the created KnowledgeDTO.

Update Knowledge

POST /knowledge/{id}

Creates a new version. Same request body as create.

Delete Knowledge

DELETE /knowledge/{id}

Soft-deletes the entry.

Visibility

POST /knowledge/{id}/visibility

json

1{2  "visibility": "public"3}

Transfer Ownership

POST /knowledge/{id}/transfer

json

1{2  "team_id": "team_xyz789"3}

cURL Examples

bash

1# List knowledge entries2curl https://api.inference.sh/knowledge \3  -H "Authorization: Bearer inf_your_key"45# Create an observation6curl -X POST https://api.inference.sh/knowledge \7  -H "Authorization: Bearer inf_your_key" \8  -H "Content-Type: application/json" \9  -d '{10    "name": "deployment-order",11    "description": "Services must be deployed in dependency order",12    "type": "observation",13    "version": {14      "content": {15        "path": "content.md",16        "content": "# Deployment Order\n\nAlways deploy common-go before api."17      }18    }19  }'2021# Delete22curl -X DELETE https://api.inference.sh/knowledge/know_abc123 \23  -H "Authorization: Bearer inf_your_key"