> ## 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.

# Files SDK Reference

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

## Files

### List Files

Returns a list of the files that your account has access to. orq.ai sorts and returns the files by their creation dates, placing the most recently created files at the top.

<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.files.list(limit=10)

      # 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.files.list({
      limit: 10,
    });

    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],
        "project_id": Optional[str],
    }
    ```

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": {
            "file_id": str,
            "purpose": Literal["FILE_PURPOSE_UNSPECIFIED", "FILE_PURPOSE_RETRIEVAL", "FILE_PURPOSE_KNOWLEDGE_DATASOURCE", "FILE_PURPOSE_BATCH"],
            "file_name": str,
            "bytes_": str,
            "created_at": date,
            "project_id": str,
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        fileId: string;
        purpose: string;
        fileName: string;
        bytes: string;
        createdAt: Date;
        projectId: string;
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a File

Files are used to upload documents that can be used with features like Deployments.

<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.files.create(filename="example.file", content="<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.files.create({
      filename: "example.file",
      content: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "filename": str,  # required
        "content": str,  # required
        "purpose": Optional[Literal["FILE_PURPOSE_UNSPECIFIED", "FILE_PURPOSE_RETRIEVAL", "FILE_PURPOSE_KNOWLEDGE_DATASOURCE", "FILE_PURPOSE_BATCH"]],
        "content_type": Optional[str],
        "project_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      filename: string;  // required
      content: string;  // required
      purpose?: string;
      contentType?: string;
      projectId?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file": {
            "file_id": str,
            "purpose": Literal["FILE_PURPOSE_UNSPECIFIED", "FILE_PURPOSE_RETRIEVAL", "FILE_PURPOSE_KNOWLEDGE_DATASOURCE", "FILE_PURPOSE_BATCH"],
            "file_name": str,
            "bytes_": str,
            "created_at": date,
            "project_id": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      file: {
        fileId: string;
        purpose: string;
        fileName: string;
        bytes: string;
        createdAt: Date;
        projectId: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Get Content

Returns a presigned URL for downloading the file content by file ID.

<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.files.get_content(file_id_or_path="<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.files.getContent({
      fileIdOrPath: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

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

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

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

### Retrieve a File

Retrieves the details of an existing file object. After you supply a unique file ID, orq.ai returns the corresponding file object.

<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.files.get(file_id="<id>")

      # 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.files.get({
      fileId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file": {
            "file_id": str,
            "purpose": Literal["FILE_PURPOSE_UNSPECIFIED", "FILE_PURPOSE_RETRIEVAL", "FILE_PURPOSE_KNOWLEDGE_DATASOURCE", "FILE_PURPOSE_BATCH"],
            "file_name": str,
            "bytes_": str,
            "created_at": date,
            "project_id": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      file: {
        fileId: string;
        purpose: string;
        fileName: string;
        bytes: string;
        createdAt: Date;
        projectId: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a File

Permanently deletes a file and its stored content from the project.

<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.files.delete(file_id="<id>")

      # 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.files.delete({
      fileId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

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

### Update a File

Updates the metadata of an existing file object.

<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.files.update(file_id="<id>", file_name="example.file")

      # 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.files.update({
      fileId: "<id>",
      updateFileRequest: {
        fileName: "example.file",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "file": {
            "file_id": str,
            "purpose": Literal["FILE_PURPOSE_UNSPECIFIED", "FILE_PURPOSE_RETRIEVAL", "FILE_PURPOSE_KNOWLEDGE_DATASOURCE", "FILE_PURPOSE_BATCH"],
            "file_name": str,
            "bytes_": str,
            "created_at": date,
            "project_id": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      file: {
        fileId: string;
        purpose: string;
        fileName: string;
        bytes: string;
        createdAt: Date;
        projectId: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>