Manage your Files

library(formr)

# So this vignette runs offline, API calls are replayed from pre-recorded
# responses (vcr cassettes shipped with the package). With a real server you
# would instead call formr_api_authenticate() with your own host/credentials.
.formr_vcr <- requireNamespace("vcr", quietly = TRUE) &&
  nzchar(system.file("extdata/vcr_cassettes", package = "formr"))

if (.formr_vcr) {
  vcr::vcr_configure(
    dir = system.file("extdata/vcr_cassettes", package = "formr"),
    filter_sensitive_data = list(
      "formr-client-id-redacted"     = "dummy_client_id",
      "formr-client-secret-redacted" = "dummy_client_secret",
      "formr-host-redacted"          = "api.localhost"
    )
  )
  vcr::use_cassette("formr_api_authenticate", {
    formr_api_authenticate(host = "http://api.localhost",
      client_id = "dummy_client_id", client_secret = "dummy_client_secret",
      verbose = FALSE)
  })
}

Most complex studies require more than just survey spreadsheets. For example, you might need to host images for experimental stimuli.

While the Project Workflow (formr_api_push_project) syncs your files/ folder automatically, the functions below give you direct, granular control over the file storage of your run.

Listing Files

To see what files are currently attached to your run, use formr_api_files(). This returns a data frame containing the file names, their public URLs, and upload timestamps.

# List all files attached to the study
vcr::use_cassette("formr_api_upload_delete_flow", {
  files <- formr_api_files("test-run")
})

# View the first few files
head(files)
#> # A tibble: 1 × 5
#>      id name            path                           url   created            
#>   <int> <chr>           <chr>                          <chr> <dttm>             
#> 1   309 test_upload.txt assets/tmp/admin/v4eCM-ns0ZuB… http… 2026-02-02 19:05:26

The returned url column is particularly useful if you need to embed these assets in external emails or websites.

Uploading Files

You can upload files individually or in bulk. This is useful for quickly patching a missing image or adding a new stimulus without re-syncing the entire project.

Single File

# Not run: needs a live formr server.
# Upload a single logo
formr_api_upload_file("my-study-name", path = "assets/logo.png")

Multiple Files or Directories

The function is flexible: you can pass a vector of paths or a directory. If you pass a directory, formr will upload all files directly inside it.

# Not run: needs a live formr server.
# Upload multiple specific files
formr_api_upload_file("my-study-name", path = c("assets/img1.jpg", "assets/img2.jpg"))

# Upload an entire folder of stimuli
formr_api_upload_file("my-study-name", path = "assets/stimuli/")

Deleting Files

To keep your run clean, you can remove obsolete files.

# Not run: needs a live formr server.
# Delete a specific file
formr_api_delete_file("my-study-name", file_name = "old_logo.png")

# Delete a list of files
formr_api_delete_file("my-study-name", file_name = c("test1.jpg", "test2.jpg"))

Cleaning Up (Delete All)

If you are restructuring your study and want to start fresh, you can wipe all files. Use this with caution.

# Not run: needs a live formr server.
# Delete ALL files (prompts for confirmation)
formr_api_delete_all_files("my-study-name")