Knowledge

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

Authenticated requests include knowledge in your namespace. Unauthenticated /suggest returns public apps and skills only.

→ Search concept · Search API

Tags on version.tags are searchable. After create or update, metadata is indexed immediately; full-content semantic search may lag until embedding completes.

Scoping

Knowledge versions can carry scope signals — short prefix:value tags that describe the environment where an entry was captured (repository, language, module, and so on). Scope helps semantic search and POST /suggest surface knowledge that matches your current project context.

Set scope on the version when creating or updating an entry:

1{2  "name": "api-patterns",3  "description": "Internal API conventions",4  "type": "observation",5  "version": {6    "content": { "path": "content.md", "content": "# API patterns\n\n..." },7    "scope": ["git:github.com/acme/api", "lang:go", "module:acme/api"]8  }9}

Scope is stored on each version (version.scope in API responses) and included in embedding text alongside tags for semantic search indexing. Keyword search still uses name, description, and tags only.

The belt CLI auto-collects scope from your current directory on belt know upload and belt suggest. Pass your own scope array when calling the REST API directly.

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:

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.

Project scope

Each version can carry a scope array — environment signals that tie an entry to a project or workspace. /suggest compares request scope tags with version scope to boost project-relevant knowledge in discovery results (overlap ranking). Entries without scope are global and appear everywhere.

Tags use prefix:value format:

belt know upload auto-collects scope from the current working directory unless you pass --global. belt suggest sends the same signals on every suggest call. belt plugin review attaches scope when saving knowledge from agent sessions.

Omit scope (or pass an empty array) for entries that should apply across all projects.

List Knowledge

GET /knowledge or POST /knowledge/list

Returns knowledge entries with cursor-based pagination. Requires authentication.

Request

Common filter fields: namespace, name, type, lifecycle, visibility, created_at, updated_at. Unknown filter or sort columns return 400. See Cursor pagination.

Text search: use search.fields such as name, description, namespace, or type. Fields not on the knowledge model are ignored.

Example — observations only:

1curl -X POST https://api.inference.sh/knowledge/list \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Content-Type: application/json" \5  -d '{6    "limit": 20,7    "filters": [{ "field": "type", "operator": "eq", "value": "observation" }]8  }'

Response

With X-API-Version: 2:

1{2  "items": [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        "content_hash": "a3f5c9e2b1d4...",15        "tags": ["api", "infrastructure"],16        "scope": ["git:github.com/myteam/api", "lang:go"],17        "metadata": {}18      },19      "visibility": "private",20      "created_at": "2026-01-15T10:30:00Z"21    }22  ],23  "next_cursor": "abc123",24  "has_next": true,25  "has_previous": false26}

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.

Content hash and conditional GET

Each version object includes a content_hash — a deterministic hash over the main content and supporting files. The hash changes when instructions or file payloads change, even if the version id stays the same.

Use content_hash to detect unchanged versions in sync jobs, skip redundant downloads, or compare entries across namespaces.

ETag caching

These read endpoints set an ETag response header from version.content_hash and honor If-None-Match:

When If-None-Match matches the current hash, the API returns 304 Not Modified with an empty body. Responses also include Cache-Control: no-cache — clients should revalidate on each request rather than treat the entry as immutable.

Example:

1# First fetch — note the ETag header2curl -i https://api.inference.sh/knowledge/acme/onboarding \3  -H "Authorization: Bearer inf_your_key" \4  -H "X-API-Version: 2"56# Conditional retry — 304 when content is unchanged7curl -i https://api.inference.sh/knowledge/acme/onboarding \8  -H "Authorization: Bearer inf_your_key" \9  -H "X-API-Version: 2" \10  -H 'If-None-Match: "a3f5c9e2b1d4..."'

The platform also uses content_hash internally for duplicate detection in lineage graphs and for collapsing identical skills in /suggest results.

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}

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}

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}

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}

JavaScript SDK

1import { inference } from '@inferencesh/sdk';23const client = inference({ apiKey: 'inf_your_key' });45const { items } = await client.knowledge.list({ limit: 50 });6const entry = await client.knowledge.getByName('myteam', 'deployment-order');78await client.knowledge.create({9  name: 'deployment-order',10  description: 'Services must deploy in dependency order',11  type: 'observation',12  version: {13    content: {14      path: 'content.md',15      content: '# Deployment Order\n\nDeploy common-go before api.',16    },17  },18});1920await client.knowledge.update('know_abc123', { description: 'Updated notes' });21await client.knowledge.delete('know_abc123');

→ JavaScript SDK · SDK overview

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"