Upload reference files

Create uploads with files:write scope. The endpoint returns an upload URL; it does not accept file bytes in the initial JSON request.

1. Request an upload

curl --fail-with-body https://app.verbatik.com/api/v1/files \
  -H "Authorization: Bearer $VERBATIK_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: product-upload-001' \
  -d '{"filename":"product.png","content_type":"image/png","size":2480123}'

Use the actual byte size of your file. The 201 response includes upload_url, upload_headers, url, and expires_at.

2. Upload the file bytes

Send an HTTP PUT to the returned upload_url, using the exact upload_headers and the file as the request body. This goes to storage; do not attach your Verbatik API key to the storage request.

For a PNG, after assigning the returned upload URL to UPLOAD_URL:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: image/png' \
  --data-binary @product.png

Upload URLs expire after 15 minutes. If an upload URL has expired, create a new upload request with a new idempotency key.

3. Use the media URL

After the PUT succeeds, pass the response's url in the appropriate generation input slot. Do not pass upload_url, which is only for transferring the bytes.

Current limits

The generation model can impose stricter format, duration, or reference limits. Uploaded URLs are public media URLs; do not treat them as private workspace documents.