Read file or list directory

GET

/v1/workspaces/{workspace_id}/fs/{path}

const url = 'https://app.everruns.com/api/v1/workspaces/example/fs/example';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://app.everruns.com/api/v1/workspaces/example/fs/example

Parameters

Path Parameters

workspace_id

required

string

Workspace ID (wsp_<32-hex>)

path

required

string

File or directory path. Wildcard route: nested paths are literal /-separated segments, not a single URL-encoded value.

Query Parameters

recursive

boolean

List recursively

Responses

200

File content or directory listing

application/json

One of:

object
object

Complete file with content

object

content

File content. Encoding is controlled by the encoding field: plain UTF-8 text for text, base64-encoded bytes for base64. None for directories and when this is a metadata-only listing.

string | null

created_at

required

Timestamp when this entry was created (RFC 3339).

string format: date-time

encoding

Content encoding for the content field: text (UTF-8) or base64 (binary).

string

required

Internal database UUID for this file entry.

string format: uuid

is_directory

required

true when this entry represents a directory; false for a regular file.

boolean

is_readonly

required

Whether the entry was marked read-only at creation. Read-only entries cannot be edited or deleted by the session.

boolean

name

required

File or directory name (the last segment of path).

string

path

required

Absolute path within the session workspace (e.g. /notes.md).

string

session_id

required

UUID of the owning session.

string format: uuid

size_bytes

required

File size in bytes. 0 for directories.

integer format: int64

updated_at

required

Timestamp when this entry was last updated (RFC 3339).

string format: date-time

Response wrapper for list endpoints. All list endpoints return responses wrapped in a data field.

object

data

required

Array of items returned by the list operation.

Array<object>

File metadata without content

object

created_at

required

Timestamp when this entry was created (RFC 3339).

string format: date-time

required

Internal database UUID for this file entry.

string format: uuid

is_directory

required

true when this entry represents a directory; false for a regular file.

boolean

is_readonly

required

Whether the entry was marked read-only at creation. Read-only entries cannot be edited or deleted by the session.

boolean

name

required

File or directory name (the last segment of path).

string

path

required

Absolute path within the session workspace (e.g. /notes.md).

string

session_id

required

UUID of the owning session.

string format: uuid

size_bytes

required

File size in bytes. 0 for directories.

integer format: int64

updated_at

required

Timestamp when this entry was last updated (RFC 3339).

string format: date-time

Example

{
  "data": [
    {
      "created_at": "2026-05-25T10:14:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "is_directory": false,
      "is_readonly": false,
      "name": "notes.md",
      "path": "/notes.md",
      "session_id": "01933b5a-0000-7000-8000-000000000001",
      "size_bytes": 4096,
      "updated_at": "2026-05-25T10:15:30Z"
    }
  ]
}

404

Not found

500

Internal server error