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

# List Files

> Retrieve a list of files from your Hubsy Cloud account

## Overview

Retrieve a paginated list of files in your account or within a specific folder.

## Query Parameters

<ParamField query="folder_id" type="string">
  Filter files by folder ID. Omit to list files in root directory.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="per_page" type="integer" default="50">
  Number of items per page (max: 100)
</ParamField>

<ParamField query="sort" type="string" default="created_desc">
  Sort order. Options: `created_asc`, `created_desc`, `modified_asc`, `modified_desc`, `name_asc`, `name_desc`, `size_asc`, `size_desc`
</ParamField>

<ParamField query="type" type="string">
  Filter by file type: `image`, `video`, `audio`, `document`, `archive`, `other`
</ParamField>

<ParamField query="search" type="string">
  Search files by name
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.hubsy.cloud/v1/files?folder_id=folder_123&per_page=10 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hubsy.cloud/v1/files?folder_id=folder_123&per_page=10', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(data.data);
  ```

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

  response = requests.get(
      'https://api.hubsy.cloud/v1/files',
      params={'folder_id': 'folder_123', 'per_page': 10},
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  files = response.json()['data']
  ```

  ```php PHP theme={null}
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.hubsy.cloud/v1/files?folder_id=folder_123&per_page=10');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_API_KEY'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $data = json_decode($response, true);
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  Array of file objects

  <Expandable title="File Object">
    <ResponseField name="id" type="string">
      Unique file identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      File name with extension
    </ResponseField>

    <ResponseField name="size" type="integer">
      File size in bytes
    </ResponseField>

    <ResponseField name="type" type="string">
      MIME type (e.g., "image/jpeg", "application/pdf")
    </ResponseField>

    <ResponseField name="category" type="string">
      File category: `image`, `video`, `audio`, `document`, `archive`, `other`
    </ResponseField>

    <ResponseField name="folder_id" type="string">
      ID of parent folder, or `null` if in root
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when file was uploaded
    </ResponseField>

    <ResponseField name="modified_at" type="string">
      ISO 8601 timestamp of last modification
    </ResponseField>

    <ResponseField name="thumbnail_url" type="string">
      URL to file thumbnail (if available)
    </ResponseField>

    <ResponseField name="download_url" type="string">
      Direct download URL (expires in 1 hour)
    </ResponseField>

    <ResponseField name="is_shared" type="boolean">
      Whether file has active share links
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination Object">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      Items per page
    </ResponseField>

    <ResponseField name="total_items" type="integer">
      Total number of files
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "file_abc123",
      "name": "presentation.pdf",
      "size": 2458624,
      "type": "application/pdf",
      "category": "document",
      "folder_id": "folder_123",
      "created_at": "2024-01-15T10:30:00Z",
      "modified_at": "2024-01-15T10:30:00Z",
      "thumbnail_url": "https://cdn.hubsy.cloud/thumbs/file_abc123.jpg",
      "download_url": "https://cdn.hubsy.cloud/download/file_abc123?token=xyz",
      "is_shared": true
    },
    {
      "id": "file_def456",
      "name": "photo.jpg",
      "size": 1024000,
      "type": "image/jpeg",
      "category": "image",
      "folder_id": "folder_123",
      "created_at": "2024-01-14T15:20:00Z",
      "modified_at": "2024-01-14T15:20:00Z",
      "thumbnail_url": "https://cdn.hubsy.cloud/thumbs/file_def456.jpg",
      "download_url": "https://cdn.hubsy.cloud/download/file_def456?token=abc",
      "is_shared": false
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_items": 42,
    "total_pages": 5
  }
}
```

## Error Responses

<ResponseExample>
  ```json Invalid Folder ID theme={null}
  {
    "success": false,
    "error": {
      "code": "not_found",
      "message": "Folder not found"
    }
  }
  ```

  ```json Authentication Failed theme={null}
  {
    "success": false,
    "error": {
      "code": "authentication_failed",
      "message": "Invalid API key"
    }
  }
  ```

  ```json Rate Limit Exceeded theme={null}
  {
    "success": false,
    "error": {
      "code": "rate_limit_exceeded",
      "message": "Too many requests. Try again in 60 seconds."
    }
  }
  ```
</ResponseExample>

## Notes

* The `download_url` expires after 1 hour. Generate a new one by calling this endpoint again.
* Thumbnails are only available for images, videos, and PDFs
* Deleted files are not included in the list
* Maximum `per_page` value is 100