Skip to main content
POST
/
upload
/
file
Upload a file for analysis
curl --request POST \
  --url https://api.vidnavigator.com/v1/upload/file \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file' \
  --form wait_for_completion=false \
  --form 'namespace_ids=<string>'
{
  "status": "success",
  "file_id": "<string>",
  "file_name": "<string>",
  "message": "<string>",
  "data": {
    "file_info": {
      "id": "<string>",
      "name": "<string>",
      "size": 123,
      "type": "<string>",
      "duration": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "original_file_date": "2023-11-07T05:31:56Z",
      "has_transcript": true,
      "error_message": "<string>",
      "namespace_ids": [
        "<string>"
      ],
      "namespaces": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  }
}
Upload audio or video files for transcription and analysis.

​
Overview

Upload your own audio or video files to VidNavigator for processing. The API supports a wide range of formats and provides flexible processing options.

​
Supported Formats

Video Formats

mp4, webm, mov, avi, wmv, flv, mkv

Audio Formats

m4a, mp3, mpeg, mpga, wav

​
Processing Options

  • Asynchronous (default): Returns immediately, processing happens in background
  • Synchronous: Waits for complete processing before returning response

​
Billing

File processing consumes transcription_hour usage for speech-to-text. 1 credit covers 1 hour of video/audio transcription. Uploaded files also count toward your storage quota.

​
Namespace Assignment

You can assign the uploaded file to one or more namespaces by including namespace_ids in the form data. This accepts a comma-separated string or a JSON array (e.g., '["ns1","ns2"]'). See Namespaces for managing namespaces.

​
Example Usage

curl -X POST "https://api.vidnavigator.com/v1/upload/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/your/video.mp4" \
  -F "wait_for_completion=false"

​
Response Examples

All response variants include data.file_info with namespace_ids and namespaces reflecting the file’s namespace assignments.
When wait_for_completion is false (the default), the API responds immediately with a file ID and a processing status.
{
  "status": "success",
  "file_id": "file_abc123",
  "file_name": "video.mp4",
  "file_status": "processing",
  "message": "File uploaded successfully and is being processed",
  "data": {
    "file_info": {
      "id": "file_abc123",
      "name": "video.mp4",
      "size": 15728640,
      "type": "video/mp4",
      "status": "processing",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z",
      "has_transcript": false,
      "namespace_ids": ["64a1b2c3d4e5f6789abc0001"],
      "namespaces": [
        { "id": "64a1b2c3d4e5f6789abc0001", "name": "default" }
      ]
    }
  }
}
When wait_for_completion is true, the API waits until processing is finished before responding.
{
  "status": "success",
  "file_id": "file_abc123",
  "file_name": "video.mp4",
  "file_status": "completed",
  "message": "File processed successfully",
  "data": {
    "file_info": {
      "id": "file_abc123",
      "name": "video.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" }
      ]
    },
    "transcript": [
      {
        "text": "Welcome to this tutorial...",
        "start": 0.0,
        "end": 3.5
      }
    ]
  }
}
When wait_for_completion is true and processing exceeds 15 minutes, the API returns a 202 Accepted response. Processing continues in the background — poll GET /file/{file_id} to check completion.
{
  "status": "accepted",
  "file_id": "file_abc123",
  "file_name": "video.mp4",
  "file_status": "processing",
  "message": "File uploaded but processing is still in progress",
  "note": "Processing is taking longer than expected. Use GET /file/{file_id} to check status.",
  "data": {
    "file_info": {
      "id": "file_abc123",
      "name": "video.mp4",
      "size": 15728640,
      "type": "video/mp4",
      "status": "processing",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z",
      "has_transcript": false,
      "namespace_ids": ["64a1b2c3d4e5f6789abc0001"],
      "namespaces": [
        { "id": "64a1b2c3d4e5f6789abc0001", "name": "default" }
      ]
    }
  }
}

Authorizations

​
X-API-Key
string
header
required

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

Body

multipart/form-data
​
file
file
required

The audio or video file to upload

​
wait_for_completion
enum<string>
default:false

If 'true', waits until processing is complete before returning response

Available options:
true,
false,
1,
0,
yes,
no,
y,
n
​
namespace_ids
string

Optional namespace IDs to assign the file to. Accepts a comma-separated string or a JSON array (e.g., '["ns1","ns2"]').

Response

File uploaded successfully

​
status
enum<string>
Available options:
success
​
file_id
string
​
file_name
string
​
file_status
enum<string>
Available options:
processing,
completed
​
message
string
​
data
object