Files

Import a file by URL

Changed on

Register a file from a URL. varg-hosted URLs (s3.varg.ai, uu.varg.ai, ...) are registered without re-uploading; external URLs are streamed to varg storage. SSRF-protected (private IPs and localhost are rejected).

post/files/import

Request

  • Base URL: https://api.varg.ai/v2
  • URL: https://api.varg.ai/v2/files/import
  • Auth: HTTP bearer

Headers

X-Workspace-Idstring

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

Request body

urlstring uri required
filenamestring
media_typestring
origin'upload' | 'generated'

Explicit provenance (defaults to generated for varg URLs, upload for external)

hashstring

sha256 of the bytes for dedup (sha256:<hex> or bare hex)

sizeinteger
workspace_idstring

File the import into this folder (id or slug). The X-Workspace-Id header also works.

metadataobject

Client-measured metadata (width, height, duration_ms, ...). Max 20 keys; non-scalar values and strings over 200 characters are dropped.

Response

File imported (or deduplicated). size can be 0 for varg-hosted URLs registered without bytes.

file_idstring required
urlstring required

Stable varg-hosted URL

hashstring nullable
sizeinteger required
media_typestring required
filenamestring nullable
titlestring nullable
subtitlestring nullable
metadataobject nullable
deduplicatedboolean required

true when an existing file with the same content was returned

origin'upload' | 'generated'

Present on /files/import responses

Changes