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.
Entries are indexed for hybrid keyword and semantic search. Use the workspace search UI, or call GET /suggest and GET /search with collections=knowledge (authentication required for private namespace entries).
Discovery
| Endpoint | Use case |
|---|---|
GET /suggest?q=... | Autocomplete and unified discovery (apps, skills, knowledge, pages) |
GET /search?q=...&collections=knowledge | Search only knowledge entries with filter control |
Authenticated requests include knowledge in your namespace. Unauthenticated /suggest returns public apps and skills only.
Tags on version.tags are searchable. After create or update, metadata is indexed immediately; full-content semantic search may lag until embedding completes.
| Type | Description |
|---|---|
skill | Reusable agent instructions (prefer /skills endpoints) |
concept | Domain concepts and definitions |
observation | Learned facts or patterns (default on create) |
reference | Pointers to external resources |
preference | User or team preferences |
person | People and contacts |
project | Project-scoped context |
agent-config | Agent configuration snippets |
Python callers can use the matching enums from inferencesh.types — see Python SDK — generated types.
Lifecycle
Each entry has a lifecycle field that describes how the platform treats freshness:
| Value | When to use |
|---|---|
permanent | Default. Stable facts, skills, and references that stay valid until you publish a new version. |
decay | Time-sensitive observations (runbooks, environment facts, integration notes) where confidence should decrease unless revalidated. |
Set lifecycle on create or when publishing a new version:
1{2 "name": "staging-db-host",3 "description": "Current staging database hostname",4 "type": "observation",5 "lifecycle": "decay",6 "version": {7 "content": {8 "path": "content.md",9 "content": "# Staging DB\n\n`db.staging.example.com`"10 }11 }12}Version freshness: For decay entries, version objects may include last_confirmed_at (RFC 3339) when the platform has recorded a confirmation. Use it in agents and dashboards to show how recently a fact was validated. The field is read-only on API responses — it is not part of the create/update request body.
Search: lifecycle is indexed on the knowledge collection. Scored GET /search results include knowledge fields you can filter or display in integrations; /suggest still applies its relevance score floor independently of lifecycle.
Most published skills stay permanent. Use decay for agent-captured observations and operational notes that should be revalidated over time.
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
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 Knowledge by Ref
GET /knowledge/{namespace}/{name}
Returns the latest version for a namespace and name (same ref format as belt know get).
GET /knowledge/{namespace}/{name}/versions/{versionId}
Returns a specific version. versionId is the short version id (the segment after @ in refs like acme/onboarding@abc123).
1curl https://api.inference.sh/knowledge/acme/onboarding \2 -H "Authorization: Bearer inf_your_key" \3 -H "X-API-Version: 2"45curl https://api.inference.sh/knowledge/acme/onboarding/versions/abc123 \6 -H "Authorization: Bearer inf_your_key" \7 -H "X-API-Version: 2"Requires read access to the entry. Permission failures return 404 or 403, consistent with other knowledge routes.
Get References
GET /knowledge/{id}/references
Returns content reference edges for a knowledge entry. Edges are created when version content is saved (mentions of other resources in markdown).
Response
1{2 "resource": {3 "id": "know_abc123",4 "namespace": "acme",5 "name": "onboarding",6 "type": "knowledge",7 "resource_kind": "skill",8 "description": "Onboarding checklist"9 },10 "references": [11 {12 "id": "app_xyz789",13 "namespace": "acme",14 "name": "deploy-helper",15 "type": "app",16 "resource_kind": "",17 "description": "Deployment helper app"18 }19 ],20 "referenced_by": [21 {22 "id": "know_def456",23 "namespace": "acme",24 "name": "runbook",25 "type": "knowledge",26 "resource_kind": "observation",27 "description": "Production runbook"28 }29 ]30}| Field | Meaning |
|---|---|
resource | The entry you queried |
references | Outgoing — knowledge, app, or agent resources mentioned in this entry's content |
referenced_by | Incoming — resources whose content mentions this entry |
Each ResourceRef includes id, namespace, name, type (knowledge, app, or agent), resource_kind (e.g. skill, observation for knowledge entries), and description.
Requires read access to the entry.
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 fork and version relationships: parents, siblings, forks, and duplicates.
1{2 "skill": {3 "id": "know_abc123",4 "namespace": "myteam",5 "name": "api-rate-limits",6 "version_count": 27 },8 "parents": [],9 "siblings": [],10 "forks": [],11 "duplicates": [],12 "fork_depth": 013}| Field | Meaning |
|---|---|
skill | The entry you queried |
parents | Entries this one was forked or derived from |
siblings | Other entries sharing the same parent |
forks | Entries forked from this one |
duplicates | Detected duplicate entries |
fork_depth | How many fork generations from the root parent |
Skills expose the same endpoint: GET /skills/{id}/lineage.
Requires read access to the entry.
Create Knowledge
POST /knowledge
Requires authentication.
Request
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 — one of the values in the table above (default: observation) |
lifecycle | no | permanent (default) or decay |
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
1{2 "visibility": "public"3}Transfer Ownership
POST /knowledge/{id}/transfer
1{2 "team_id": "team_xyz789"3}cURL Examples
1# List knowledge entries2curl https://api.inference.sh/knowledge \3 -H "Authorization: Bearer inf_your_key" \4 -H "X-API-Version: 2"56# Create an observation7curl -X POST https://api.inference.sh/knowledge \8 -H "Authorization: Bearer inf_your_key" \9 -H "X-API-Version: 2" \10 -H "Content-Type: application/json" \11 -d '{12 "name": "deployment-order",13 "description": "Services must be deployed in dependency order",14 "type": "observation",15 "version": {16 "content": {17 "path": "content.md",18 "content": "# Deployment Order\n\nAlways deploy common-go before api."19 }20 }21 }'2223# Delete24curl -X DELETE https://api.inference.sh/knowledge/know_abc123 \25 -H "Authorization: Bearer inf_your_key" \26 -H "X-API-Version: 2"