List Files

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

Method

GET /v1/gallery/files

Query Parameters

folderId · uuid

Filter to a specific folder (omit to include all files).

page · integer

1-based page index (default 1).

limit · integer

Items per page (1–100, default 50).

type · string

all | image | video | document | audio (default all).

sortBy · string

created_at | updated_at | name | size (default created_at).

sortOrder · string

asc or desc (default desc).

search · string

Full-text search across name, translations, and tags.

tag · string

Filter by tag substring.

locale · string

Preferred locale for alt/description (en, fr, etc.).

fallbackLocale · string

Locale used when the preferred locale has no translation.

includeMeta · string

Set to 1 to include translation maps and supported languages in metadata.

Headers

Authorization · string

Bearer token (e.g. Authorization: Bearer YOUR_API_KEY)

Request Example

cURL

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"

Response

200 OK

{
  "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
  }
}

data · array

Array of file objects.

meta.total · integer

Total number of files matching the query.

meta.page · integer

Current page number.

meta.pageSize · integer

Number of items per page.

meta.hasMore · boolean

Whether more pages are available.

links.self · string

Link to the current page.

links.next · string | null

Link to the next page, or null if on the last page.

links.prev · string | null

Link to the previous page, or null if on the first page.