Docs
Knowledge API & MCP · Reference

Knowledge API

The HTTP surface of the Ontology Layer, endpoint by endpoint.

This is the complete HTTP surface of the Ontology Layer's knowledge routes. Every endpoint is scoped by project_id and requires authentication. Base URL is your deployment's ONTOLOGY_LAYER_URL.

Endpoints at a glance

MethodPathPurpose
GET/projects/{project_id}/knowledge/discoverMap available sources, counts, sync state
POST/projects/{project_id}/knowledge/searchRanked search across sources
GET/projects/{project_id}/knowledge/fetch?ref=Resolve a ref to full content
POST/projects/{project_id}/knowledge/activityTime-ordered events

Each has its own page with request and response shapes: discover, search, fetch, activity.

The two payload types

Every search or activity hit is a KnowledgeHit; every fetch result is a KnowledgeObject:

ts
type KnowledgeHit = {
  source: string;              // "code" | "graph" | "work_items" | ...
  provider: string | null;     // "github" | "jira" | null
  ref: string;                 // opaque, fetch()-resolvable
  title: string;
  snippet: string;             // default ""
  score: number;               // normalized [0, 1]
  url: string | null;
  timestamp: string | null;    // ISO-8601 when time-bearing
  resource_uri: string | null; // ontology://<project>/<source>/...
  metadata: Record<string, unknown>;
};

type KnowledgeObject = {
  ref: string;
  source: string;
  title: string;
  content: string;             // full, source-specific body
  provider: string | null;
  url: string | null;
  metadata: Record<string, unknown>;
};

A minimal end-to-end call

bash
# 1. discover  2. search  3. fetch the top hit
PROJECT=acme-platform
BASE="$ONTOLOGY_URL/projects/$PROJECT/knowledge"
AUTH=(-H "X-API-Key: $INTERNAL_SERVICE_KEY")

curl "$BASE/discover" "${AUTH[@]}"

REF=$(curl -s "$BASE/search" "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"query":"session validation","top_k":1}' | jq -r '.results[0].ref')

curl -G "$BASE/fetch" "${AUTH[@]}" --data-urlencode "ref=$REF"

For agents, the same operations are exposed as MCP tools — see MCP tool catalog. For failure modes and caps, see Errors & limits.

Next: MCP overview.