> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FileSystems SDK Reference

> SDK reference for the FileSystems API, available in Node.js and Python.

## FileSystems

### List FileSystems

Retrieves a paginated list of file systems in the workspace. Use cursor-based pagination parameters to navigate through the results.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "search": Optional[str],
        "project_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      search?: string;
      projectId?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Literal["list"],
        "data": [{
            "id": Optional[str],
            "key": str,
            "display_name": str,
            "description": str,
            "project_id": str,
            "external_access": Literal["disabled", "read_only", "read_write"],
            "created_by_id": Optional[str],
            "updated_by_id": Optional[str],
            "created": str,
            "updated": str,
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
            "used_bytes": Optional[str],
            "used_inodes": Optional[str],
            "last_metered_at": Optional[str],
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: "list";
      data: {
        id?: string;
        key: string;
        displayName: string;
        description: string;
        projectId: string;
        externalAccess: "disabled" | "read_only" | "read_write";
        createdById?: string;
        updatedById?: string;
        created: string;
        updated: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
        usedBytes?: string;
        usedInodes?: string;
        lastMeteredAt?: string;
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a FileSystem

Creates a file system. Storage is provisioned lazily on first use by an agent run or MCP client.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.create(key="<key>", path="/etc/ppp")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.create({
      key: "<key>",
      path: "/etc/ppp",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "path": str,  # required
        "display_name": Optional[str],
        "description": Optional[str],
        "external_access": Optional[Literal["disabled", "read_only", "read_write"]],
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
      path: string;  // required
      displayName?: string;
      description?: string;
      externalAccess?: "disabled" | "read_only" | "read_write";
      sharing?: {
        allProjects?: Record<string, unknown>;
        selected?: {
          projectIds?: string[];
        };
        allowVersionPin?: boolean;
        allowFork?: boolean;
        autoGrantNewProjects?: boolean;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "key": str,
        "display_name": str,
        "description": str,
        "project_id": str,
        "external_access": Literal["disabled", "read_only", "read_write"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,
        "updated": str,
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
        "used_bytes": Optional[str],
        "used_inodes": Optional[str],
        "last_metered_at": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string;
      key: string;
      displayName: string;
      description: string;
      projectId: string;
      externalAccess: "disabled" | "read_only" | "read_write";
      createdById?: string;
      updatedById?: string;
      created: string;
      updated: string;
      sharing?: {
        allProjects?: Record<string, unknown>;
        selected?: {
          projectIds?: string[];
        };
        allowVersionPin?: boolean;
        allowFork?: boolean;
        autoGrantNewProjects?: boolean;
      };
      usedBytes?: string;
      usedInodes?: string;
      lastMeteredAt?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a FileSystem

Retrieves detailed information about a specific file system, including its quota and external access configuration.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.retrieve(file_system_key="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.retrieve({
      fileSystemKey: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "key": str,
        "display_name": str,
        "description": str,
        "project_id": str,
        "external_access": Literal["disabled", "read_only", "read_write"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,
        "updated": str,
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
        "used_bytes": Optional[str],
        "used_inodes": Optional[str],
        "last_metered_at": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string;
      key: string;
      displayName: string;
      description: string;
      projectId: string;
      externalAccess: "disabled" | "read_only" | "read_write";
      createdById?: string;
      updatedById?: string;
      created: string;
      updated: string;
      sharing?: {
        allProjects?: Record<string, unknown>;
        selected?: {
          projectIds?: string[];
        };
        allowVersionPin?: boolean;
        allowFork?: boolean;
        autoGrantNewProjects?: boolean;
      };
      usedBytes?: string;
      usedInodes?: string;
      lastMeteredAt?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a FileSystem

Permanently deletes a file system and every file stored in it. This cannot be undone.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.delete(file_system_key="<value>")

      assert res is not None

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.delete({
      fileSystemKey: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update a FileSystem

Updates the mutable file system configuration. The key is immutable.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.update(file_system_key="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.update({
      fileSystemKey: "<value>",
      updateFileSystemRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
        "display_name": Optional[str],
        "description": Optional[str],
        "path": Optional[str],
        "external_access": Optional[Literal["disabled", "read_only", "read_write"]],
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
      updateFileSystemRequest: {  // required
        displayName?: string;
        description?: string;
        path?: string;
        externalAccess?: "disabled" | "read_only" | "read_write";
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "key": str,
        "display_name": str,
        "description": str,
        "project_id": str,
        "external_access": Literal["disabled", "read_only", "read_write"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,
        "updated": str,
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
        "used_bytes": Optional[str],
        "used_inodes": Optional[str],
        "last_metered_at": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string;
      key: string;
      displayName: string;
      description: string;
      projectId: string;
      externalAccess: "disabled" | "read_only" | "read_write";
      createdById?: string;
      updatedById?: string;
      created: string;
      updated: string;
      sharing?: {
        allProjects?: Record<string, unknown>;
        selected?: {
          projectIds?: string[];
        };
        allowVersionPin?: boolean;
        allowFork?: boolean;
        autoGrantNewProjects?: boolean;
      };
      usedBytes?: string;
      usedInodes?: string;
      lastMeteredAt?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### List Files

Lists the files and folders stored in a file system. An empty path lists the file system root.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.list_files(file_system_key="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.listFiles({
      fileSystemKey: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
        "path": Optional[str],
        "depth": Optional[int],
        "max_entries": Optional[int],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
      path?: string;
      depth?: number;
      maxEntries?: number;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "path": str,
        "depth": int,
        "entries": [{
            "path": str,
            "name": str,
            "type": Literal["file", "dir", "symlink", "other"],
            "size_bytes": str,
            "modified": str,
        }],
        "entry_count": int,
        "truncated": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      path: string;
      depth: number;
      entries: {
        path: string;
        name: string;
        type: "file" | "dir" | "symlink" | "other";
        sizeBytes: string;
        modified: string;
      }[];
      entryCount: number;
      truncated: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete File

Deletes one file or folder. A folder that still has content is refused unless recursive is set.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.delete_file(file_system_key="<value>")

      assert res is not None

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.deleteFile({
      fileSystemKey: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
        "path": Optional[str],
        "recursive": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
      path?: string;
      recursive?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "path": str,
        "type": Literal["file", "dir", "symlink", "other"],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      path: string;
      type: "file" | "dir" | "symlink" | "other";
    }
    ```
  </CodeGroup>
</Expandable>

### Move File

Moves or renames one file or folder within the same file system. Missing destination folders are created.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.move_file(file_system_key="<value>", from_="<value>", to="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.moveFile({
      fileSystemKey: "<value>",
      moveFileSystemFileRequest: {
        from: "<value>",
        to: "<value>",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
        "from_": str,  # required
        "to": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
      moveFileSystemFileRequest: {  // required
        from: string;  // required
        to: string;  // required
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "from_": str,
        "to": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      from: string;
      to: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Stat File

Retrieves the metadata of one file or folder without transferring its content.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.stat_file(file_system_key="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.statFile({
      fileSystemKey: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
        "path": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
      path?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "path": str,
        "type": Literal["file", "dir", "symlink", "other"],
        "size_bytes": str,
        "mode": str,
        "modified": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      path: string;
      type: "file" | "dir" | "symlink" | "other";
      sizeBytes: string;
      mode: string;
      modified: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Create Folder

Creates a folder and every missing parent. Succeeds on a folder that already exists.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.file_systems.create_folder(file_system_key="<value>", path="/boot/defaults")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.fileSystems.createFolder({
      fileSystemKey: "<value>",
      createFileSystemFolderRequest: {
        path: "/boot/defaults",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file_system_key": str,  # required
        "path": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fileSystemKey: string;  // required
      createFileSystemFolderRequest: {  // required
        path: string;  // required
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "path": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      path: string;
    }
    ```
  </CodeGroup>
</Expandable>