Files

Start a large file upload

Changed on

Upload flow for files too large or awkward for POST /files (up to 200 MB):

  1. Call this endpoint with the file's media_type and, ideally, its size and sha256 hash.
  2. If the response has deduplicated: true, the file already exists in your account: use the returned file_id and url and skip the upload.
  3. Otherwise send the raw bytes with PUT {upload_url} (direct to storage), or PUT /files/upload/{session_id} (proxy_url) when your environment can only reach api.varg.ai. Use the Content-Type in headers. The session is valid for 1 hour and accepts one upload.
  4. The proxy PUT registers the file and returns file_id. If you uploaded to upload_url directly, register it afterwards with POST /files/import using public_url.

Send X-Workspace-Id (or workspace_id in the body) to file the upload into a folder.

post/files/upload-session

Request

  • Base URL: https://api.varg.ai/v2
  • URL: https://api.varg.ai/v2/files/upload-session
  • Auth: HTTP bearer

Headers

X-Workspace-Idstring

Folder (id or slug) to file the upload into. Wins over workspace_id in the body.

Request body

media_typestring

MIME type of the file. Defaults to application/octet-stream (the real type is then detected from the bytes on upload).

filenamestring
sizeinteger

File size in bytes (max 200 MB)

hashstring

sha256 of the file, with or without the sha256: prefix. Lets the API skip the upload when you already have the file.

workspace_idstring

Folder (id or slug) to file the upload into. X-Workspace-Id takes precedence.

Example request

{
  "media_type": "video/mp4"
}

Response

A new upload session, or the existing file when the hash matches

OR

Example response

{
  "proxy_url": "/v2/files/upload/file_abc123",
  "expires_in": 3600
}

Changes