Upload Endpoint Documentation

Endpoint

POST /api/upload

This endpoint allows you to upload video files to the platform. It supports both direct file uploads and chunked uploads for large files.

Authentication

The endpoint requires authentication through API key:

API Key: Include your API key in the request header:x-api-key: your_api_key_here

Request Parameters

Parameter	Type	Required	Description
file	File	Yes	The video file to upload
title	String	No	Title for the video. If not provided, filename will be used
description	String	No	Optional description for the video
folderId	String	No	Optional folder ID to organize the file. Use the Folders API to get available folder IDs

Response

Success Response (200)

{
  "fileId": "generated_file_id",
  "filename": "video.mp4",
  "size": 1048576,
  "viewUrl": "/watch/generated_file_id",
  "success": true
}

Error Responses

401 Unauthorized

{
  "error": "Authentication required. Either provide an API key or log in."
}

400 Bad Request

{
  "error": "No file provided"
}

Example Usage

Using cURL

curl -X POST https://zerostorage.net/api/upload \
  -H "x-api-key: your_api_key_here" \
  -F "file=@/path/to/your/file.mp4" \
  -F "title=My File Title" \
  -F "description=Optional description" \
  -F "folderId=your_folder_id_here"

Using PowerShell

$form = @{
    file = Get-Item -Path "C:\path\to\your\file.mp4"
    title = "My File Title"
    description = "Optional description"
    folderId = "your_folder_id_here"
}

$response = Invoke-RestMethod -Uri 'https://zerostorage.net/api/upload' \
    -Method Post \
    -Headers @{
        'x-api-key' = 'your_api_key_here'
    } \
    -Form $form

Folder Management

To organize your files into folders, you can use the folder management endpoints:

List Folders

Get all your folders to find folder IDs:

GET /api/folders?parentId=optional_parent_id&page=1&limit=20
Headers: x-api-key: your_api_key_here

Query Parameters:
• parentId (optional): Get subfolders of a specific folder
• page (optional): Page number for pagination (default: 1)
• limit (optional): Number of folders per page (default: 20)

Response includes folder IDs that you can use in upload requests.

Response Example:

{
  "folders": [
    {
      "id": "folder_id_here",
      "name": "My Documents",
      "description": "Important documents",
      "parent_id": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "_count": {
        "files": 5,
        "children": 2
      }
    },
    {
      "id": "another_folder_id",
      "name": "Videos",
      "description": "Video files",
      "parent_id": null,
      "created_at": "2024-01-10T14:20:00.000Z",
      "updated_at": "2024-01-10T14:20:00.000Z",
      "_count": {
        "files": 12,
        "children": 0
      }
    }
  ],
  "pagination": {
    "total": 2,
    "totalPages": 1,
    "currentPage": 1,
    "limit": 20
  }
}

Create Folder

Create a new folder:

POST /api/folders
Headers: x-api-key: your_api_key_here
Content-Type: application/json

{
  "name": "My Folder",
  "description": "Optional description",
  "parentId": "optional_parent_folder_id"
}

Response Example:

{
  "id": "new_folder_id_here",
  "name": "My Folder",
  "description": "Optional description",
  "parent_id": "optional_parent_folder_id",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "_count": {
    "files": 0,
    "children": 0
  }
}

Error Responses

401 Unauthorized

{
  "error": "Invalid API key"
}

400 Bad Request (Create Folder)

{
  "error": "Folder name is required"
}

404 Not Found (Create Folder)

{
  "error": "Parent folder not found"
}

Complete Workflow Example

Here's a complete example of how to create a folder and upload a file to it:

Step 1: Create a folder

curl -X POST https://zerostorage.net/api/folders \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project Files",
    "description": "Files for my project"
  }'

Step 2: Upload file to the folder

curl -X POST https://zerostorage.net/api/upload \
  -H "x-api-key: your_api_key_here" \
  -F "file=@/path/to/your/file.mp4" \
  -F "title=Project Video" \
  -F "folderId=returned_folder_id_from_step_1"

Notes

The endpoint supports various file formats including videos, images, and documents.
Uploads are processed asynchronously - the file will be available once processing is complete.
Large video files are automatically processed using HLS encoding for optimal streaming.
Use folder IDs to organize your files into a hierarchical structure.