The Ontology Layer · Reference

Fetch

Resolve a search hit's opaque ref to its full content object.

fetch resolves one search hit's opaque ref to its full content object. Search gives you a snippet and a ref; fetch gives you the whole thing — the file body, the full issue, the PR description.

http

GET /projects/{project_id}/knowledge/fetch?ref=<opaque_ref>

Request

The ref comes verbatim from a search or discover hit. Do not construct it by hand — its grammar is source-specific and may change (Refs & resource URIs).

bash

curl -G "$ONTOLOGY_URL/projects/$PROJECT_ID/knowledge/fetch" \
  -H "X-API-Key: $INTERNAL_SERVICE_KEY" \
  --data-urlencode "ref=code|acme__platform__main|acme__platform__src/auth/session.py"

Response

json

{
  "ref": "code|acme__platform__main|acme__platform__src/auth/session.py",
  "source": "code",
  "provider": null,
  "title": "session.py",
  "content": "import ...\n\ndef validate_session(token: str) -> Principal:\n    ...",
  "url": null,
  "metadata": { "language": "python", "lines": 142 }
}

Tenancy is enforced here

The source is read from the ref's prefix, and the owning retriever validates that the ref belongs to your project — its repos, bindings, or scope — before returning anything. A forged or cross-tenant ref resolves to nothing and returns:

http

404 Not Found
{ "detail": "No object for ref '<ref>'" }

A ref that used to resolve but no longer does (deleted file, closed external resource) also returns 404, and the miss is recorded for auditing. See Governance & tenancy.

Next: Activity timeline.