Skip to main content
List the contents of a directory.

​
Python SDK

from openviking import OpenViking

client = OpenViking()

# Basic listing
entries = client.ls("viking://resources/")
for entry in entries:
    type_str = "dir" if entry['isDir'] else "file"
    print(f"{entry['name']} - {type_str}")

# Simple path list (URIs only)
paths = client.ls("viking://resources/", simple=True)
for path in paths:
    print(path)

# Recursive listing
all_entries = client.ls("viking://resources/", recursive=True)

​
HTTP API

curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/" \
  -H "X-API-Key: your-key"

GET /api/v1/fs/ls?uri=viking://resources/

​
Parameters

​
uri
string
required
Viking URI of the directory to list
​
simple
boolean
default:"false"
Return only relative paths instead of full entry objects
​
recursive
boolean
default:"false"
List all subdirectories recursively
​
output
string
default:"agent"
Output format: original or agent
​
abs_limit
integer
default:"256"
Abstract limit (only for agent output mode)
​
show_all_hidden
boolean
default:"false"
List all hidden files (like ls -a)
​
node_limit
integer
default:"1000"
Maximum number of nodes to list

​
Response

Returns an array of directory entries (or paths if simple=true).

​
Entry Object

​
name
string
File or directory name
​
size
integer
Size in bytes
​
mode
integer
File mode (Unix permissions)
​
modTime
string
ISO timestamp of last modification
​
isDir
boolean
true if directory, false if file
​
uri
string
Viking URI of the entry
​
meta
object
Optional metadata
{
  "status": "ok",
  "result": [
    {
      "name": "docs",
      "size": 4096,
      "mode": 16877,
      "modTime": "2024-01-01T00:00:00Z",
      "isDir": true,
      "uri": "viking://resources/docs/",
      "meta": {}
    },
    {
      "name": "README.md",
      "size": 1024,
      "mode": 33188,
      "modTime": "2024-01-01T12:00:00Z",
      "isDir": false,
      "uri": "viking://resources/README.md",
      "meta": {}
    }
  ],
  "time": 0.1
}

​
CLI

openviking ls viking://resources/ [--simple] [--recursive]