The Knowledge API · Reference

Fetch

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

Fetch resolves a search hit's opaque ref to its full content object. Where search gives you the summary, fetch gives you the detail — the entity, its type, its content, and its neighborhood in the graph.

Request

bash

POST /projects/:project_id/knowledge/fetch

Headers:

Header	Required	Description
`X-API-Key`	One of	Service-level key for server-to-server calls
`Authorization`	One of	`Bearer <jwt>` for user-scoped calls
`Content-Type`	Yes	`application/json`

Body:

json

{
  "ref": "code:github:acme/api:main:src/auth/verify.ts:verifySession"
}

Field	Type	Required	Description
`ref`	string	Yes	The opaque ref from a search hit

Response

json

{
  "ref": "code:github:acme/api:main:src/auth/verify.ts:verifySession",
  "source": "code",
  "entity_type": "function",
  "title": "verifySession",
  "content": {
    "signature": "async function verifySession(token: string): Promise<Principal>",
    "body": "// full function body here...",
    "file_path": "src/auth/verify.ts",
    "start_line": 42,
    "end_line": 78,
    "language": "typescript",
    "repository": "acme/api",
    "branch": "main"
  },
  "relations": [
    { "type": "calls", "target": "code:github:acme/api:main:src/auth/jwt.ts:decodeJwt", "target_title": "decodeJwt" },
    { "type": "called_by", "target": "code:github:acme/api:main:src/middleware/auth.ts:authMiddleware", "target_title": "authMiddleware" },
    { "type": "reads_from", "target": "database:postgresql:auth-db:public.sessions", "target_title": "public.sessions" },
    { "type": "referenced_by", "target": "work_items:jira:PROJ-412", "target_title": "PROJ-412: Rotate session tokens on privilege change" }
  ]
}

The graph neighborhood

The relations array is the key difference between fetch and a file read. A file read gives you the code. Fetch gives you the code *and* what it calls, what calls it, which tables it reads from, and which work items reference it — the entity's neighborhood in the ontology.

Each relation carries a target ref you can in turn fetch, enabling graph traversal one hop at a time.

Stale refs

A ref that was valid but whose entity no longer exists returns:

json

{
  "error": "not_found",
  "message": "The ref was syntactically valid but the entity no longer exists. It may have been deleted or renamed.",
  "ref": "code:github:acme/api:main:src/auth/old-verify.ts:verifySession"
}

HTTP status: 404.

Invalid refs

A malformed ref or a ref from another project returns:

json

{
  "error": "bad_request",
  "message": "The ref is malformed or does not belong to this project.",
  "ref": "not-a-valid-ref"
}

HTTP status: 400.

Next: Activity.