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
}
}
Files
List Files
List partner files in the authenticated key scope
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
}
}
Retrieve a paginated list of partner files in the authenticated key scope.
Results are ordered by
createdAt descending, with the file ID as a stable
tie-breaker, so the newest-created media is always returned first.
This includes:
- direct uploads created via
POST /files - media ingested by partner posting flows
Query Parameters
number
default:"50"
Number of files to return. Must be an integer between
1 and 100.number
default:"0"
Number of files to skip for pagination. Must be an integer
>= 0.string
Filter by file type:
image or video.string
Optional context filter.
- Omit
contextto keep default partner-only results. - Use a single context (example:
ai-studio) or comma-separated contexts (example:ai-studio,media-upload). - Use
context=allto return all file contexts in your authenticated key scope.
string
Inclusive ISO 8601 lower bound on
createdAt (for example,
2026-08-01T00:00:00.000Z).string
Inclusive ISO 8601 upper bound on
createdAt. When both bounds are supplied,
until must be at or after since.Response
Successful requests return200 with:
files- Array of file objectstotal- Total count of matching fileslimit- Applied limitoffset- Applied offset
File Object
| Field | Type | Description |
|---|---|---|
id | string | Unique file identifier |
url | string | CDN URL for the file |
contentType | string | MIME type of the file |
filename | string | Original filename |
size | number | File size in bytes |
createdAt | string | ISO 8601 timestamp |
Examples
List partner 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>'
# Query every media context created during August 2026, newest first
curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/files?context=all&since=2026-08-01T00%3A00%3A00.000Z&until=2026-08-31T23%3A59%3A59.999Z' \
--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 invalid401- authentication failed (missing/invalid/revoked token)402 subscription_required- active Creator/Professional/Business plan required403 tier_not_allowed- Scheduler tier cannot use Partner API500 list_failed- Failed to retrieve files (retry)
Use
context=all to include AI-generated Studio media alongside uploads, and
use type to narrow the newest-first results to videos or images.