Skip to main content
GET
/
api
/
partner
/
v1
/
folders
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/folders?media_type=upload&limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Folders retrieved",
  "data": {
    "folders": [
      {
        "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "name": "Product Shots",
        "media_type": "upload",
        "parent_folder_id": null,
        "path": "/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "file_count": 12,
        "subfolder_count": 2,
        "preview_files": [
          {
            "id": "file_1",
            "url": "https://cdn.vireel.io/...",
            "content_type": "image/jpeg"
          }
        ],
        "created_at": "2026-03-01T09:00:00.000Z",
        "updated_at": "2026-03-01T09:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}
Returns paginated folders for one media_type at a hierarchy level.

​
Query Parameters

​
media_type
string
required
Folder media type: ai_image, ai_video, upload, or slideshow.
​
parent_folder_id
string
Optional parent folder ID. Omit to list root-level folders.
​
limit
number
default:"50"
Number of folders to return (1-100).
​
offset
number
default:"0"
Number of folders to skip.

​
Response

  • folders - Folder summaries (file_count, subfolder_count, preview_files)
  • total - Total matching folders
  • limit / offset - Applied pagination values
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/folders?media_type=upload&limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Folders retrieved",
  "data": {
    "folders": [
      {
        "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "name": "Product Shots",
        "media_type": "upload",
        "parent_folder_id": null,
        "path": "/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "file_count": 12,
        "subfolder_count": 2,
        "preview_files": [
          {
            "id": "file_1",
            "url": "https://cdn.vireel.io/...",
            "content_type": "image/jpeg"
          }
        ],
        "created_at": "2026-03-01T09:00:00.000Z",
        "updated_at": "2026-03-01T09:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

​
Error Responses

  • 400 invalid_query_parameter - query validation failed
  • 401 / 403 - auth/entitlement failure
  • 500 folders_list_failed - unexpected folder query failure