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

# Read by Path

> Resolve a path: returns a presigned URL for a file, or a listing for a folder.

<Note>
  **Polymorphic response:** The response shape depends on what exists at the path. Check the `ftype` field — `"file"` returns a download URL, `"folder"` returns a listing of direct children.
</Note>

## What this does

Reads whatever exists at the given path. If the path resolves to a **file**, returns a File object with a short-lived presigned download URL (15-minute TTL). If it resolves to a **folder**, returns a Folder object listing its direct children.

## Examples

<CodeGroup>
  ```bash cURL (file) theme={null}
  curl "https://api.cloudsquid.io/api/projects/my-project/files?path=/invoices/2024/jan.pdf" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```bash cURL (folder) theme={null}
  curl "https://api.cloudsquid.io/api/projects/my-project/files?path=/invoices/2024" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.cloudsquid.io/api/projects/my-project/files",
      params={"path": "/invoices/2024"},
      headers={"X-API-Key": "YOUR_API_KEY"}
  )
  node = response.json()

  if node["ftype"] == "file":
      print(f"Download URL: {node['url']}")
  else:
      for entry in node["entries"]:
          print(f"  {entry['ftype']}: {entry['name']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.cloudsquid.io/api/projects/my-project/files?path=/invoices/2024",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const node = await response.json();

  if (node.ftype === "file") {
    console.log("Download:", node.url);
  } else {
    node.entries.forEach(e => console.log(e.ftype, e.name));
  }
  ```
</CodeGroup>

File response (`200`):

```json theme={null}
{
  "ftype": "file",
  "name": "jan.pdf",
  "size": 48210,
  "mimetype": "application/pdf",
  "modified_at": "2026-06-01T12:00:00Z",
  "url": "https://storage.googleapis.com/presigned?..."
}
```

Folder response (`200`):

```json theme={null}
{
  "ftype": "folder",
  "name": "2024",
  "entries": [
    {
      "ftype": "file",
      "name": "jan.pdf",
      "size": 48210,
      "mimetype": "application/pdf",
      "modified_at": "2026-06-01T12:00:00Z",
      "url": "https://storage.googleapis.com/presigned?..."
    },
    {
      "ftype": "folder",
      "name": "archive"
    }
  ]
}
```


## OpenAPI

````yaml get /projects/{project_name}/files
openapi: 3.0.3
info:
  title: Cloudsquid
  description: This is the backend of cloudsquid specification
  termsOfService: cloudsquid.io
  contact:
    email: info@cloudsquid.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.11
servers:
  - url: https://api.cloudsquid.io/api
    description: API
security:
  - api-key: []
paths:
  /projects/{project_name}/files:
    parameters:
      - name: project_name
        in: path
        required: true
        description: The name of the project
        schema:
          type: string
    get:
      tags:
        - filesystem
      summary: Read a path
      description: >
        Read whatever exists at the given path. If the path resolves to a file,
        returns a

        short-lived presigned download URL. If it resolves to a folder, returns
        a JSON

        listing of its direct children.
      parameters:
        - name: path
          in: query
          required: true
          description: Absolute path inside the project
          schema:
            type: string
      responses:
        '200':
          description: File or folder
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/File'
                  - $ref: '#/components/schemas/Folder'
                discriminator:
                  propertyName: ftype
                  mapping:
                    file:
                      $ref: '#/components/schemas/File'
                    folder:
                      $ref: '#/components/schemas/Folder'
        '400':
          description: Bad or malformed request (invalid path)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Path does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Something unexpected happened
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    File:
      type: object
      description: A file object inside the filesystem
      properties:
        ftype:
          $ref: '#/components/schemas/FType'
        name:
          type: string
        size:
          type: integer
          description: size in bytes
        mimetype:
          type: string
        modified_at:
          type: string
          format: date-time
        url:
          type: string
          format: uri
          description: Presigned download url. 15min TTL.
      required:
        - name
        - ftype
    Folder:
      type: object
      description: A folder with multiple file entries.
      properties:
        ftype:
          $ref: '#/components/schemas/FType'
        name:
          type: string
        entries:
          type: array
          description: Direct children (folders only)
          items:
            oneOf:
              - $ref: '#/components/schemas/File'
              - $ref: '#/components/schemas/Folder'
            discriminator:
              propertyName: ftype
              mapping:
                file:
                  $ref: '#/components/schemas/File'
                folder:
                  $ref: '#/components/schemas/Folder'
      required:
        - ftype
        - name
    Error:
      type: object
      properties:
        errorMessage:
          type: string
      required:
        - errorMessage
    FType:
      type: string
      enum:
        - file
        - folder
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-API-Key

````