List Files - Genviral

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
  }
}

GET

api

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}`);
});

{
  "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. 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

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 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.

Upload File List Folders

​Query Parameters

​Response

​File Object

​Examples

​List all files

​Error Responses

Query Parameters

Response

File Object

Examples

List all files

Error Responses