Skip to main content
GET
/
api
/
partner
/
v1
/
files
import fetch from "node-fetch";

const response = await fetch(
  "https://www.genviral.io/api/partner/v1/files?limit=20",
  {
    headers: {
      Authorization: "Bearer <token>",
    },
  }
);

const { data } = await response.json();
console.log(`Found ${data.total} files`);
data.files.forEach((file) => {
  console.log(`${file.filename}: ${file.url}`);
});

{
  "ok": true,
  "code": 200,
  "message": "Files retrieved",
  "data": {
    "files": [
      {
        "id": "abc123",
        "url": "https://cdn.vireel.io/partner-api/workspaces/workspace_123/abc123.mp4",
        "contentType": "video/mp4",
        "filename": "promo-video.mp4",
        "size": 15728640,
        "createdAt": "2025-01-20T14:30:00.000Z"
      },
      {
        "id": "def456",
        "url": "https://cdn.vireel.io/partner-api/workspaces/workspace_123/def456.jpg",
        "contentType": "image/jpeg",
        "filename": "slide-1.jpg",
        "size": 524288,
        "createdAt": "2025-01-20T14:25:00.000Z"
      }
    ],
    "total": 42,
    "limit": 20,
    "offset": 0,
    "context": null
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.genviral.io/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve a paginated list of partner files in the authenticated key scope. This includes:
  • direct uploads created via POST /files
  • media ingested by partner posting flows

​
Query Parameters

​
limit
number
default:"50"
Number of files to return. Must be an integer between 1 and 100.
​
offset
number
default:"0"
Number of files to skip for pagination. Must be an integer >= 0.
​
type
string
Filter by file type: image or video.
​
context
string
Optional context filter.
  • Omit context to keep default partner-only results.
  • Use a single context (example: ai-studio) or comma-separated contexts (example: ai-studio,media-upload).
  • Use context=all to return all file contexts in your authenticated key scope.

​
Response

Successful requests return 200 with:
  • files - Array of file objects
  • total - Total count of matching files
  • limit - Applied limit
  • offset - Applied offset

​
File Object

FieldTypeDescription
idstringUnique file identifier
urlstringCDN URL for the file
contentTypestringMIME type of the file
filenamestringOriginal filename
sizenumberFile size in bytes
createdAtstringISO 8601 timestamp

​
Examples

​
List all files

import fetch from "node-fetch";

const response = await fetch(
  "https://www.genviral.io/api/partner/v1/files?limit=20",
  {
    headers: {
      Authorization: "Bearer <token>",
    },
  }
);

const { data } = await response.json();
console.log(`Found ${data.total} files`);
data.files.forEach((file) => {
  console.log(`${file.filename}: ${file.url}`);
});

# List all files
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?limit=20' \
  --header 'Authorization: Bearer <token>'

# List only videos
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?type=video&limit=10' \
  --header 'Authorization: Bearer <token>'

# Paginate through results
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?limit=20&offset=20' \
  --header 'Authorization: Bearer <token>'

# Query AI Studio + media uploads contexts
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?context=ai-studio,media-upload&limit=20' \
  --header 'Authorization: Bearer <token>'

# Query all file contexts in key scope
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/files?context=all&limit=20' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Files retrieved",
  "data": {
    "files": [
      {
        "id": "abc123",
        "url": "https://cdn.vireel.io/partner-api/workspaces/workspace_123/abc123.mp4",
        "contentType": "video/mp4",
        "filename": "promo-video.mp4",
        "size": 15728640,
        "createdAt": "2025-01-20T14:30:00.000Z"
      },
      {
        "id": "def456",
        "url": "https://cdn.vireel.io/partner-api/workspaces/workspace_123/def456.jpg",
        "contentType": "image/jpeg",
        "filename": "slide-1.jpg",
        "size": 524288,
        "createdAt": "2025-01-20T14:25:00.000Z"
      }
    ],
    "total": 42,
    "limit": 20,
    "offset": 0,
    "context": null
  }
}

​
Error Responses

  • 400 invalid_query_parameter - one or more query parameters are invalid
  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 500 list_failed - Failed to retrieve files (retry)
Use the type filter to quickly find videos or images when building slideshows or selecting media for posts.