Skip to main content
POST
Import a file by URL

Authorizations

Authorization
string
header
required

varg API key (varg_...). Get one at app.varg.ai or run bunx vargai login. App sessions may alternatively send a Supabase JWT.

Headers

X-Workspace-Id
string

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

Body

application/json
url
string<uri>
required
filename
string
media_type
string
origin
enum<string>

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

Available options:
upload,
generated
hash
string

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

size
integer
workspace_id
string

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

metadata
object

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_id
string
required
url
string
required

Stable varg-hosted URL

size
integer
required
media_type
string
required
deduplicated
boolean
required

true when an existing file with the same content was returned

hash
string | null
filename
string | null
title
string | null
subtitle
string | null
metadata
object | null
origin
enum<string>

Present on /files/import responses

Available options:
upload,
generated