Skip to main content
Folder item behavior depends on folder media type:
  • slideshow folder -> item IDs are slideshow IDs
  • ai_image, ai_video, upload folder -> item IDs are file IDs

​
Path Parameters

​
folderId
string
required
Folder ID.

​
List Items

Query params:
  • limit (1-100, default 50)
  • offset (default 0)
cURL
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/folders/{{folder_id}}/items?limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

​
Add Items

cURL
curl --request POST \
  --url https://www.genviral.io/api/partner/v1/folders/{{folder_id}}/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "item_ids": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ]
  }'

​
Remove Items

cURL
curl --request DELETE \
  --url https://www.genviral.io/api/partner/v1/folders/{{folder_id}}/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "item_ids": [
      "11111111-1111-1111-1111-111111111111"
    ]
  }'

​
Example Response (List)

Response
{
  "ok": true,
  "code": 200,
  "message": "Folder items retrieved",
  "data": {
    "media_type": "upload",
    "item_type": "file",
    "items": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "url": "https://cdn.vireel.io/...",
        "content_type": "image/jpeg",
        "filename": "slide-1.jpg",
        "size": 524288,
        "created_at": "2026-03-01T09:00:00.000Z",
        "added_at": "2026-03-01T09:05:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

​
Error Responses

  • 400 invalid_query_parameter - invalid limit/offset
  • 400 invalid_json - malformed body for POST/DELETE
  • 422 invalid_path - folderId is not a valid UUID
  • 422 invalid_folder_media_type - folder media type is not supported by Partner folder APIs
  • 404 not_found - folder not visible in key scope
  • 404 item_not_found - one or more item IDs are not visible in key scope
  • 422 invalid_payload - missing/invalid item_ids
  • 500 folder_items_list_failed / folder_items_add_failed / folder_items_remove_failed - unexpected failure