Skip to Content

List Files

Retrieve a paginated list of all files uploaded by the authenticated user. Supports filtering by status and namespace.

GET
/files

Retrieve a paginated list of all audio/video files you have uploaded. Supports filtering by status and namespace.

Overview

Use this endpoint to get basic information on every file you have uploaded, including status, metadata, and namespace assignments. Supports pagination with limit and offset query parameters.

Query Parameters

  • limit (integer, default 50): Maximum number of files to return (1-100)
  • offset (integer, default 0): Number of files to skip for pagination
  • status (string): Filter by processing status (processing, completed, failed, cancelled)
  • namespace_id (string): Filter by namespace ID. Only returns files belonging to this namespace. If not set, returns files from all namespaces.

Example Request

curl -G "https://api.vidnavigator.com/v1/files" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "offset=0" \
  --data-urlencode "status=completed"

Success Response

{
  "status": "success",
  "data": {
    "files": [
      {
        "id": "file_abc123",
        "name": "session.mp4",
        "size": 15728640,
        "type": "video/mp4",
        "duration": 330,
        "status": "completed",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z",
        "has_transcript": true,
        "namespace_ids": ["64a1b2c3d4e5f6789abc0001", "64a1b2c3d4e5f6789abc0002"],
        "namespaces": [
          { "id": "64a1b2c3d4e5f6789abc0001", "name": "default" },
          { "id": "64a1b2c3d4e5f6789abc0002", "name": "Client Calls" }
        ]
      }
    ],
    "total_count": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

API reference

Authorization

ApiKeyAuth
headerX-API-Key<token>

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Query Parameters

limit?integer

Maximum number of files to return

Range1 <= value <= 100
Default50
offset?integer

Number of files to skip for pagination

Range0 <= value
Default0
status?string

Filter by file status

Value in"processing""completed""failed""cancelled"
namespace_id?string

Filter by namespace ID. Only returns files belonging to this namespace. If not set, returns files from all namespaces.

Response Body

Files retrieved successfully

application/json
  1. response
status?"success"
Value in"success"
data?
Example Request
curl -X GET 'https://api.vidnavigator.com/v1/files'
Example Response
{  "status": "success",  "data": {    "files": [      {        "id": "string",        "name": "string",        "size": 0,        "type": "string",        "duration": 0,        "status": "pending",        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z",        "original_file_date": "2019-08-24T14:15:22Z",        "has_transcript": true,        "error_message": "string",        "scenes_status": "none",        "frames_analyzed": 0,        "scenes_error": {          "error": "frames_not_available",          "message": "string"        },        "namespace_ids": [          "string"        ],        "namespaces": [          {            "id": "string",            "name": "string"          }        ]      }    ],    "total_count": 0,    "limit": 0,    "offset": 0,    "has_more": true  }}

On this page