Upload a file through the API

Upload an asset by requesting a signed URL, sending the file bytes to storage, and checking the resulting upload record.

Before you start

Use Bash, curl, and jq in a temporary working directory. You need a Veryfront API key with write access to the target project. Replace the placeholders below.

bash
export VERYFRONT_API_KEY="<API_KEY>"
export VERYFRONT_PROJECT="<PROJECT_SLUG_OR_ID>"
API_BASE="${VERYFRONT_API_URL:-https://api.veryfront.com}"

printf 'Example project asset.\n' > example.txt
UPLOAD_SIZE=$(wc -c < example.txt | tr -d '[:space:]')

Steps

  1. Request a signed URL for the file's path, content type, and actual byte size.
  2. Send the file to that URL with every returned required header.
  3. Find the upload record and verify its status and size.

Try it with REST

POST /projects/{project_reference}/uploads

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/uploads" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --argjson size "$UPLOAD_SIZE" \
    '{file_path: "assets/example.txt", content_type: "text/plain", size: $size}')" \
  -o upload-response.json

UPLOAD_URL=$(jq -er '.file_upload_url' upload-response.json)
UPLOAD_ID=$(jq -er '.upload_id' upload-response.json)
jq -r '.required_headers | to_entries[] | "\(.key): \(.value)"' \
  upload-response.json > upload-headers.txt

The response reserves an upload. It doesn't transfer the file. Send the bytes in a separate request:

bash
curl --silent --show-error --fail-with-body \
  --request PUT \
  --header @upload-headers.txt \
  --upload-file example.txt \
  "$UPLOAD_URL"

Use the returned headers exactly. The storage request uses the signed URL, not your Veryfront bearer key. Keep upload-response.json out of source control because it contains that URL.

Verify

GET /projects/{project_reference}/uploads

bash
curl --silent --show-error --fail-with-body \
  "$API_BASE/projects/$VERYFRONT_PROJECT/uploads?path=assets%2F&limit=100" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -o uploads.json

jq --arg id "$UPLOAD_ID" \
  '.data[] | select(.type == "file" and .id == $id) | {id, file_name, status, size}' \
  uploads.json

Find example.txt, confirm its size matches UPLOAD_SIZE, and wait for status: "active". Repeat the list request if activation is still pending. If there are more results, follow page_info pagination before concluding that the record is missing.

If the PUT fails, inspect the storage error and check the required headers, file size, and URL expiry. Request a new upload URL when the original is no longer valid. A failed upload record needs investigation rather than being treated as a completed asset.

Open the asset in Studio's Uploads panel to inspect its contents. Uploads are separate from source files and searchable knowledge. Uploading an asset doesn't create a source file or index it for retrieval.

API reference