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

# List Files

> Retrieve gallery files with pagination, filtering, and localized metadata.

## Method

`GET` `/v1/gallery/files`

## Query Parameters

<ParamField query="folderId" type="uuid">Filter to a specific folder (omit to include all files).</ParamField>
<ParamField query="page" type="integer">1-based page index (default `1`).</ParamField>
<ParamField query="limit" type="integer">Items per page (`1`–`100`, default `50`).</ParamField>
<ParamField query="type" type="string">`all` | `image` | `video` | `document` | `audio` (default `all`).</ParamField>
<ParamField query="sortBy" type="string">`created_at` | `updated_at` | `name` | `size` (default `created_at`).</ParamField>
<ParamField query="sortOrder" type="string">`asc` or `desc` (default `desc`).</ParamField>
<ParamField query="search" type="string">Full-text search across name, translations, and tags.</ParamField>
<ParamField query="tag" type="string">Filter by tag substring.</ParamField>
<ParamField query="locale" type="string">Preferred locale for alt/description (`en`, `fr`, etc.).</ParamField>
<ParamField query="fallbackLocale" type="string">Locale used when the preferred locale has no translation.</ParamField>
<ParamField query="includeMeta" type="string">Set to `1` to include translation maps and supported languages in `metadata`.</ParamField>

## Headers

<ParamField header="Authorization" type="string">Bearer token (e.g. <code>Authorization: Bearer YOUR\_API\_KEY</code>)</ParamField>

## Request Example

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.voyantcloud.com/v1/gallery/files?limit=20&folderId=00000000-0000-0000-0000-000000000000&locale=fr&includeMeta=1" \
    -H "Authorization: Bearer $VOYANT_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.voyantcloud.com/v1/gallery/files?type=image&sortBy=name&locale=en&fallbackLocale=ro",
    {
      headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
    },
  )
  const payload = await response.json()
  ```

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

  resp = requests.get(
    "https://api.voyantcloud.com/v1/gallery/files",
    params={"search": "banner", "limit": 10, "includeMeta": "1"},
    headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}"},
  )
  files = resp.json()
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "gal_file_123",
        "workspaceId": "ws_abc",
        "name": "ws_abc/banner_summer.png",
        "originalName": "banner_summer.png",
        "size": 245812,
        "mimeType": "image/png",
        "storageProvider": "cf-images",
        "folderId": "00000000-0000-0000-0000-000000000000",
        "status": "completed",
        "metadata": {
          "altText": "Summer sail banner",
          "description": "Hero artwork for the 2025 campaign",
          "locale": "en",
          "translations": {
            "fr": {
              "altText": "Bannière croisière d'été",
              "description": "Visuel principal pour la campagne 2025"
            }
          },
          "supportedLanguages": ["en", "fr", "de"]
        },
        "publicUrls": {
          "primary": "https://cdn.voyantcloud.com/gallery/ws_abc/banner_summer.png",
          "variants": [
            { "name": "thumbnail", "url": "https://cdn.voyantcloud.com/.../w=200,h=200" },
            { "name": "large", "url": "https://cdn.voyantcloud.com/.../w=1600" }
          ]
        },
        "createdAt": "2025-02-10T08:15:00.000Z",
        "updatedAt": "2025-02-10T08:15:00.000Z"
      }
    ],
    "meta": {
      "total": 142,
      "page": 1,
      "pageSize": 50,
      "hasMore": true
    },
    "links": {
      "self": "/v1/gallery/files?page=1&limit=50",
      "next": "/v1/gallery/files?page=2&limit=50",
      "prev": null
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="array">Array of file objects.</ResponseField>
<ResponseField name="meta.total" type="integer">Total number of files matching the query.</ResponseField>
<ResponseField name="meta.page" type="integer">Current page number.</ResponseField>
<ResponseField name="meta.pageSize" type="integer">Number of items per page.</ResponseField>
<ResponseField name="meta.hasMore" type="boolean">Whether more pages are available.</ResponseField>
<ResponseField name="links.self" type="string">Link to the current page.</ResponseField>
<ResponseField name="links.next" type="string | null">Link to the next page, or `null` if on the last page.</ResponseField>
<ResponseField name="links.prev" type="string | null">Link to the previous page, or `null` if on the first page.</ResponseField>