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
}
}
Folders
List Folders
List folders by media type and parent level in the authenticated key scope
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
string
required
Folder media type:
ai_image, ai_video, upload, or slideshow.string
Optional parent folder ID. Omit to list root-level folders.
string
Inclusive ISO-8601 lower bound for folder
created_at.string
Inclusive ISO-8601 upper bound for folder
created_at. Must be at or after since.number
default:"50"
Number of folders to return (
1-100).number
default:"0"
Number of folders to skip.
Response
folders- Folder summaries (file_count,subfolder_count,preview_files)total- Total matching folderslimit/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 failed401/403- auth/entitlement failure500 folders_list_failed- unexpected folder query failure