vaaya / docs / reference

Files & storage

A durable, per-account file library your agent writes once and reuses across tasks: uploads cost 1¢, reads and listing are free. Every stored file gets a short-lived download URL that any other service — a media model, a sandbox — can fetch directly.

When to use which

files/upload

Price

1¢

Quota

100MB per file · 2GB per account by default

URL lifetime

~1h (re-mint free with files/get)

Stores a file your agent has locally. It’s a two-step: the call returns a put_url to PUT the raw bytes to, plus the file_id and a get_url. Params: filename and size_bytes are required (the size is checked up front against quota); mime, tags (up to 10, each ≤40 chars), and note (≤500 chars) are optional.

# 1) reserve the upload — returns put_url, file_id, get_url
curl -X POST https://vaaya.ai/api/run/files/upload \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "size_bytes": 4194304,
    "tags": ["video-segmentation", "sample"],
    "note": "10s sample clip for trials"
  }'

# 2) PUT the raw bytes to the returned put_url
curl -X PUT --upload-file clip.mp4 "<put_url>"

Gotchas

• size_bytes is required up front — over quota, the call is rejected. Free space with files/delete on files you no longer need.
• Sample data for trial runs is the classic use — but any file a workflow produces or will need again later belongs here.

files/upload_from_url

Price

1¢

Quota

100MB per file

The server fetches a public URL directly into your library — no local download, no PUT step. Prefer this for anything already on the web. Params: url is required; filename, tags, and note are optional. Returns the file_id and a get_url.

curl -X POST https://vaaya.ai/api/run/files/upload_from_url \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf", "tags": ["research"], "note": "Q2 sector report"}'

files/get and files/list

Price

free

files/get takes a file_id and re-mints a fresh download URL (valid about an hour) plus the file’s metadata — call it any time an old get_url has expired. files/list returns your stored files (filename, tags, note, size, source, created date); filter with tags or query (a filename substring).

curl -X POST https://vaaya.ai/api/run/files/list \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["video-segmentation"]}'

files/delete

Deletes a stored file and frees its quota. Free — file_id is the only param.

Sharing files with other services

The get_url is a plain HTTPS link any external service can download from for about an hour — hand it to a media generation call as an input asset, or curl it from inside a sandbox to stage data into the box. When a URL expires, files/get mints a new one for free.