Code Navigation

The Code Navigation API extracts structure, searches symbols, and expands symbols in source code already imported into OpenViking. Every uri must be a viking:// URI; import local code through the Resources API first.

Code entry points:

• openviking/server/routers/code.py - HTTP routes and request models
• openviking/parse/parsers/code/ast/code_tools.py - outline, search, and symbol expansion

API Reference

outline()

Extract the symbol outline of one source file.

Parameter	Type	Required	Description
uri	string	Yes	viking:// URI of an imported source file

HTTP API

POST /api/v1/code/outline
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/code/outline \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/project/src/main.py"}'

Response Example

result is a text outline suitable for display or direct Agent context.

{
  "status": "ok",
  "result": "viking://resources/project/src/main.py  [python, 24 lines]\n\nclass SessionService  L16-24\n\ndef main()  L8-12"
}

search()

Search symbols in supported source files below a URI. One request scans at most 200 files; when capped, result ends with a prompt to narrow the URI.

Parameter	Type	Required	Description
uri	string	Yes	File or directory URI to search recursively
query	string	Yes	Non-empty symbol name or search term

HTTP API

POST /api/v1/code/search
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/code/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/project/src","query":"SessionService"}'

Response Example

{
  "status": "ok",
  "result": "1 matches for \"SessionService\" (scanned 8 files)\n\nviking://resources/project/src/session.py\n  SessionService  L16-24"
}

expand()

Return the complete code block for one symbol in a source file.

Parameter	Type	Required	Description
uri	string	Yes	Source file URI containing the symbol
symbol	string	Yes	Non-empty symbol name to expand

HTTP API

POST /api/v1/code/expand
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/code/expand \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/project/src/main.py","symbol":"main"}'

Response Example

{
  "status": "ok",
  "result": "# viking://resources/project/src/main.py  L8-10  (main)\n\ndef main():\n    service = SessionService()\n    service.run()"
}

The current implementation returns business failures such as a non-viking:// URI, an empty query or symbol, or a non-text file with status="ok" and an Error: message in result. A request body missing required fields returns HTTP 400 with INVALID_ARGUMENT.

Current Client Support

These endpoints are currently server-only HTTP capabilities. They are not wrapped by the public Python, TypeScript, or Go SDKs or by the ov CLI, so this page shows only the HTTP tab.

Related Documentation

• Resources - import source code
• Retrieval - general semantic and pattern retrieval
• Content - read source file content