> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File

> Upload a new audio or video file for analysis and start processing.

**Supported formats:**
- Video: mp4, webm, mov, avi, wmv, flv, mkv
- Audio: m4a, mp3, mpeg, mpga, wav

**Processing options:**
- `wait_for_completion=false` (default): Returns immediately, processing happens in background
- `wait_for_completion=true`: Waits for complete processing before returning response

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

<CardGroup cols={2}>
  <Card title="Video Formats" icon="video">
    mp4, webm, mov, avi, wmv, flv, mkv
  </Card>

  <Card title="Audio Formats" icon="volume">
    m4a, mp3, mpeg, mpga, wav
  </Card>
</CardGroup>

### 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](/api-reference/endpoint/list-namespaces) for managing namespaces.

## Example Usage

<CodeGroup>
  ```bash cURL (Async) theme={null}
  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"
  ```

  ```bash cURL (Sync) theme={null}
  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=true"
  ```

  ```bash cURL (with namespace) theme={null}
  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 "namespace_ids=64a1b2c3d4e5f6789abc0002"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vidnavigator.com/v1/upload/file"
  headers = {"X-API-Key": "YOUR_API_KEY"}

  with open("video.mp4", "rb") as f:
      files = {"file": f}
      data = {"wait_for_completion": "false"}
      response = requests.post(url, headers=headers, files=files, data=data)

  result = response.json()
  print(f"File ID: {result['file_id']}")
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('file', fileInput.files[0]);
  formData.append('wait_for_completion', 'false');

  const response = await fetch('https://api.vidnavigator.com/v1/upload/file', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY'
    },
    body: formData
  });

  const result = await response.json();
  ```
</CodeGroup>

## Response Examples

All response variants include `data.file_info` with `namespace_ids` and `namespaces` reflecting the file's namespace assignments.

<AccordionGroup>
  <Accordion title="201 - Asynchronous Response">
    When `wait_for_completion` is `false` (the default), the API responds immediately with a file ID and a `processing` status.

    ```json theme={null}
    {
      "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" }
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="201 - Synchronous Response">
    When `wait_for_completion` is `true`, the API waits until processing is finished before responding.

    ```json theme={null}
    {
      "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
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="202 - Processing Timeout">
    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.

    ```json theme={null}
    {
      "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" }
          ]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml POST /upload/file
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  description: >-
    The VidNavigator Developer API provides programmatic access to video
    analysis, transcription, and search capabilities.


    ## Authentication

    All endpoints require API key authentication via the `X-API-Key` header:

    ```

    X-API-Key: YOUR_API_KEY

    ```


    ## Rate Limits

    Check the documentation for the rate limits for each endpoint.


    ## Error Handling

    The API uses standard HTTP status codes and returns error responses in JSON
    format:

    ```json

    {
      "status": "error",
      "error": "error_type",
      "message": "Human readable error message"
    }

    ```
  version: 1.0.0
  contact:
    name: VidNavigator Support
    url: https://vidnavigator.com/support
    email: support@vidnavigator.com
  license:
    name: Proprietary
    url: https://vidnavigator.com/terms
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Transcripts
    description: Extract transcripts from online videos
  - name: TikTok
    description: Scrape TikTok profile metadata and per-video stats
  - name: Files
    description: Manage uploaded audio/video files
  - name: Analysis
    description: AI-powered content analysis
  - name: Extraction
    description: >-
      Extract structured data from video and file transcripts using custom
      schemas
  - name: Namespaces
    description: Organize uploaded files into namespaces (folders)
  - name: Search
    description: Search videos and files using AI
  - name: System
    description: System health and information
  - name: Tweet Analysis
    description: Extract structured claims and metadata from X/Twitter tweets
paths:
  /upload/file:
    post:
      tags:
        - Files
      summary: Upload a file for analysis
      description: >-
        Upload a new audio or video file for analysis and start processing.


        **Supported formats:**

        - Video: mp4, webm, mov, avi, wmv, flv, mkv

        - Audio: m4a, mp3, mpeg, mpga, wav


        **Processing options:**

        - `wait_for_completion=false` (default): Returns immediately, processing
        happens in background

        - `wait_for_completion=true`: Waits for complete processing before
        returning response
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The audio or video file to upload
                wait_for_completion:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                    - '1'
                    - '0'
                    - 'yes'
                    - 'no'
                    - 'y'
                    - 'n'
                  default: 'false'
                  description: >-
                    If 'true', waits until processing is complete before
                    returning response
                namespace_ids:
                  type: string
                  description: >-
                    Optional namespace IDs to assign the file to. Accepts a
                    comma-separated string or a JSON array (e.g.,
                    '["ns1","ns2"]').
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  file_id:
                    type: string
                  file_name:
                    type: string
                  file_status:
                    type: string
                    enum:
                      - processing
                      - completed
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      file_info:
                        $ref: '#/components/schemas/FileInfo'
        '202':
          description: >-
            File uploaded but processing timed out (continues in background).
            Returned when wait_for_completion=true and processing exceeds 15
            minutes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - accepted
                  file_id:
                    type: string
                  file_name:
                    type: string
                  file_status:
                    type: string
                    enum:
                      - processing
                  message:
                    type: string
                  note:
                    type: string
                  data:
                    type: object
                    properties:
                      file_info:
                        $ref: '#/components/schemas/FileInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '413':
          $ref: '#/components/responses/StorageQuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/StorageNotConfigured'
components:
  schemas:
    FileInfo:
      type: object
      properties:
        id:
          type: string
          description: Unique file identifier
        name:
          type: string
          description: File name
        size:
          type: integer
          description: File size in bytes
        type:
          type: string
          description: MIME type
        duration:
          type: number
          description: Duration in seconds
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - cancelled
          description: Processing status
        created_at:
          type: string
          format: date-time
          description: Upload timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        original_file_date:
          type: string
          format: date-time
          description: Original file creation date
        has_transcript:
          type: boolean
          description: Whether transcript is available
        error_message:
          type: string
          description: Error message if processing failed
        namespace_ids:
          type: array
          items:
            type: string
          description: IDs of the namespaces this file belongs to
        namespaces:
          type: array
          items:
            $ref: '#/components/schemas/NamespaceRef'
          description: Resolved namespaces this file belongs to (with names)
    NamespaceRef:
      type: object
      description: Resolved namespace reference with ID and display name
      properties:
        id:
          type: string
          description: Namespace identifier
        name:
          type: string
          description: Namespace display name
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    PaymentRequired:
      description: Usage limit exceeded - upgrade required
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - limit_exceeded
              message:
                type: string
    StorageQuotaExceeded:
      description: Storage quota exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - storage_quota_exceeded
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - internal_server_error
              message:
                type: string
    StorageNotConfigured:
      description: File storage not configured on server
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - storage_not_configured
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key authentication. Include your VidNavigator API key in the
        X-API-Key header.

````