NCEAS · mbjones · Mar 27, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 21, 2026
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -6,3 +6,4 @@
 ^docs$
 ^pkgdown$
 ^.*\.Rproj$
+^revdep$
diff --git a/.gitignore b/.gitignore
@@ -48,3 +48,6 @@ po/*~
 # RStudio Connect folder
 rsconnect/
 docs
+
+# revdepcheck folder
+revdep/
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: vegbankr
 Title: Interface to the 'VegBank' Vegetation Plot Database
-Version: 0.9.0
-Date: 2026-03-20
+Version: 1.0.0
+Date: 2026-03-26
 Authors@R: c(
     person("Jim", "Regetz",
         email = "regetz@nceas.ucsb.edu",
@@ -18,7 +18,11 @@ Authors@R: c(
     person("Jeanette", "Clark",
         email = "jclark@nceas.ucsb.edu",
         role = c("aut"),
-        comment=c(ORCID = "0000-0003-4703-1974"))
+        comment=c(ORCID = "0000-0003-4703-1974")),
+    person("Maggie", "Klope",
+        email = "mmklope@nceas.ucsb.edu",
+        role = c("aut"),
+        comment=c(ORCID = "0000-0003-3926-7039"))
     )
 Description: Provides a programmatic interface to 'VegBank', the
     vegetation plot database of the Ecological Society of America's
@@ -41,14 +45,16 @@ RoxygenNote: 7.3.3
 Imports:
     DBI,
     base64enc,
+    cli,
     curl,
     dplyr,
     duckdb,
     httr2,
     jsonlite,
     nanoparquet,
     purrr,
-    rlang
+    rlang,
+    tidyr
 Suggests:
     DT,
     knitr,

diff --git a/NAMESPACE b/NAMESPACE
@@ -20,6 +20,7 @@ export(vb_count_stratum_methods)
 export(vb_count_taxon_importances)
 export(vb_count_taxon_observations)
 export(vb_count_user_datasets)
+export(vb_create_dataset)
 export(vb_debug)
 export(vb_get)
 export(vb_get_base_url)
@@ -51,12 +52,25 @@ export(vb_set_token)
 export(vb_undebug)
 export(vb_unset_token)
 export(vb_upload)
+export(vb_upload_community_classifications)
 export(vb_upload_community_concepts)
+export(vb_upload_cover_methods)
 export(vb_upload_plant_concepts)
 export(vb_upload_plot_observations)
+export(vb_upload_stratum_methods)
+export(vb_upload_taxon_interpretations)
+export(vb_validate_community_concepts)
+export(vb_validate_cover_methods)
+export(vb_validate_plant_concepts)
+export(vb_validate_plot_observations)
+export(vb_validate_stratum_methods)
+import(cli)
 import(curl)
+import(dplyr)
 import(httr2)
 import(nanoparquet)
+import(tidyr)
+importFrom(jsonlite,toJSON)
 importFrom(rlang,"!!!")
 importFrom(rlang,"!!")
 importFrom(rlang,":=")

diff --git a/NEWS.md b/NEWS.md
@@ -1,6 +1,27 @@
+# vegbankr 1.0.0
+
+Production release of the VegBank API client, version 1.0.0 on 2026-03-26.
+
+New features:
+
+- write validation function [#78](https://github.com/NCEAS/vegbankr/issues/78) 
+- Support new "minimal" detail when getting various entities [#88](https://github.com/NCEAS/vegbankr/issues/88)
+- Document and test updated search behavior [#90](https://github.com/NCEAS/vegbankr/issues/90)
+- Fully support the VegBank 2.0.0 write API [#92](https://github.com/NCEAS/vegbankr/issues/92)
+- Add functions for remaining VegBank upload endpoints [#93](https://github.com/NCEAS/vegbankr/issues/93)
+- Support creation of user datasets [#94](https://github.com/NCEAS/vegbankr/issues/94)
+- Add user-friendly upload data validation [#79](https://github.com/NCEAS/vegbankr/issues/79)
+- Support status parameter in concept/observation getters [#99](https://github.com/NCEAS/vegbankr/issues/99)
+- make upload output more easily understandable without lots of scrolling [#100](https://github.com/NCEAS/vegbankr/issues/100)
+- Add upload sanity tests that can be run locally [#102](https://github.com/NCEAS/vegbankr/issues/102)
+
+Bug fixes: 
+
+- logical bug when vb_refresh_tokens() fails to get a token [#81](https://github.com/NCEAS/vegbankr/issues/81)
+
 # vegbankr 0.9.0
 
-First production release of the VegBank API client;
+First production release of the VegBank API client, version 0.9.0 on 2026-03-20.
 
 - Initial API development release
 - Complete coverage of read API endpoints

diff --git a/R/utils.R b/R/utils.R
@@ -25,7 +25,7 @@ vb_set_base_url <- function(vb_base_url, port) {
 #' Gets the base URL for the VegBank API. If previously set by the user,
 #' e.g. via `vb_set_base_url()`, this will be pulled from the global
 #' option (`vegbank.base_api_url`). If this option is unset, the package
-#' default value of "https://api.vegbank.org" will be used.
+#' default value of `https://api.vegbank.org` will be used.
 #'
 #' @returns A length-one character vector containing the base URL string
 #' @seealso [vb_set_base_url()]
@@ -132,15 +132,18 @@ send <- function(request, skip_auth = FALSE) {
 
   if (!skip_auth) {
     # If the access token is expired but the refresh token is
-    # still valid, update tokens before retrying the request.
-    if (!is.null(vb_get_access_token()) && (!vb_access_token_is_valid() || (Sys.time() + 30) < jwt_expiry_time(vb_get_access_token()))) {
+    # still valid, update tokens before trying the request.
+    if (!is.null(vb_get_access_token()) && (!vb_access_token_is_valid() || jwt_expiry_time(vb_get_access_token()) < (Sys.time() + 30))) {
       if (vb_refresh_token_is_valid()) {
         message("Access token expired; refreshing tokens...")
         vb_refresh_tokens()
+        if (!is.null(token) && !vb_access_token_is_valid()) {
+          message("Access token expired and token refresh failed. Please re-authenticate at https://api.vegbank.org/login to get new tokens.")
+          stop("Re-authenticate and call vb_set_token() to set a new token.", call. = FALSE)
+        }
       } else {
         message("Access token expired and no valid refresh token available. Please re-authenticate at https://api.vegbank.org/login to get new tokens.")
-        stop("Re-authenticate and call vb_set_token() to set a new token.",
-             call. = FALSE)
+        stop("Re-authenticate and call vb_set_token() to set a new token.", call. = FALSE)
       }
     }
 

diff --git a/R/vb_create_dataset.R b/R/vb_create_dataset.R
@@ -0,0 +1,97 @@
+#' Create a VegBank dataset
+#'
+#' @description
+#' Use the VegBank API to create a user dataset, which defines a
+#' collection of plot observations that can be cited in VegBank.
+#'
+#' @param name A single character string giving the dataset name. Must be 100
+#'   characters or fewer.
+#' @param description A single character string describing the dataset.
+#' @param observations A character vector of observation codes. Each element
+#'   must match the pattern \code{"ob.<positive_integer>"} (e.g.
+#'   \code{"ob.2948"}), and must refer to a plot observation in VegBank. The
+#'   vector must not be empty.
+#' @param dry_run Logical indicating whether to perform a dry run. If `TRUE`,
+#'   the API will validate the data without committing changes to the database.
+#'   Default is `FALSE`.
+#'
+#' @return The processed response object from the VegBank API documenting what
+#'   (if anything) was successfully created in VegBank.
+#'
+#' @examples
+#' \dontrun{
+#' vb_create_dataset(
+#'   name = "Test Dataset 001",
+#'   description = "A test dataset containing 10 observations",
+#'   observations = paste0("ob.", 2948:2957)
+#' )
+#' }
+#'
+#' @export
+vb_create_dataset <- function(name, description, observations,
+                              dry_run = FALSE) {
+
+  # Validate inputs
+  if (!is.character(name) || length(name) != 1L || is.na(name)) {
+    stop("`name` must be a single non-NA character string.")
+  }
+  if (nchar(name) > 100L) {
+    stop("`name` must be 100 characters or fewer.")
+  }
+
+  if (!is.character(description) || length(description) != 1L ||
+        is.na(description)) {
+    stop("`description` must be a single non-NA character string.")
+  }
+
+  if (!is.character(observations) || length(observations) == 0L) {
+    stop("`observations` must be a non-empty character vector.")
+  }
+
+  ob_pattern <- "^ob\\.[1-9][0-9]*$"
+  invalid <- observations[!grepl(ob_pattern, observations)]
+  if (length(invalid) > 0L) {
+    stop(
+      "`observations` contains invalid codes: ",
+      paste(invalid, collapse = ", ")
+    )
+  }
+
+  request <- build_dataset_request(name, description, observations, dry_run)
+  response <- send(request)
+  handle_vb_upload_response(response)
+}
+
+#' Build httr2 request for POST /user-datasets
+#'
+#' @param name A single character string giving the dataset name.
+#' @param description A single character string describing the dataset.
+#' @param observations A character vector of VegBank observation codes.
+#' @param dry_run Logical indicating whether to perform a dry run. If `TRUE`,
+#'   the API will validate the data without committing changes to the database.
+#'   Default is `FALSE`.
+#'
+#' @return An httr2 response
+#'
+#' @import httr2
+#' @importFrom jsonlite toJSON
+#' @noRd
+build_dataset_request <- function(name, description, observations,
+                                  dry_run = FALSE) {
+  # Assemble payload
+  json_payload <- list(
+    name = name,
+    description = description,
+    data = list(observation = as.list(observations))
+  ) |> jsonlite::toJSON(pretty = TRUE, auto_unbox = TRUE)
+
+  # Build request
+  request <- request(vb_get_base_url()) |>
+    req_url_path_append("user-datasets") |>
+    req_method("POST") |>
+    req_url_query(dry_run = dry_run) |>
+    req_headers("Content-Type"  = "application/json") |>
+    req_body_raw(json_payload, type = "application/json")
+
+  return(request)
+}
diff --git a/R/vb_get.R b/R/vb_get.R
@@ -20,8 +20,10 @@
 #'   between the two options. If not specified, defaults to `TRUE` for
 #'   collection queries and `FALSE` for single-record queries.
 #' @param search Optional search string for filtering results based on full-text
-#'   search. Available for: plot-observations, plant-concepts, community-concepts,
-#'   projects, and parties.
+#'   search or the resource's vb_code (the latter of which is functionally
+#'   equivalent to using the `vb_code` argument directly). Available for:
+#'   plot-observations, plant-concepts, community-concepts, projects, and
+#'   parties.
 #' @param sort Optional string for sorting results. Prepend with "-" for
 #'   descending order (e.g., "-obs_count"). Available for:
 #'   \itemize{
@@ -32,6 +34,15 @@
 #'     \item \strong{parties:} "default", "surname", "organization_name",
 #'           "obs_count"
 #'   }
+#' @param status Optional string for limiting results by status, with
+#'   default equivalent to 'any' if unset. Available for:
+#'   \itemize{
+#'     \item \strong{plot-observations:} "any", "current"
+#"     \item \strong{plant-concepts:} "any", "current", "accepted",
+#"           "current_accepted"
+#'     \item \strong{community-concepts:} "any", "current", "accepted",
+#'           "current_accepted"
+#'   }
 #' @param detail Character string specifying level of detail. All endpoints
 #'   support "full" detail. For those that support "minimal" detail, this is the
 #'   default for collection queries, otherwise the default is "full". Plot
@@ -257,68 +268,72 @@ vb_get_stratum_methods <- function(vb_code = NULL, limit = 100, offset = 0,
 #' @rdname vb_get
 #' @export
 vb_get_plant_concepts <- function(vb_code = NULL, limit = 100, offset = 0,
-                                  parquet = NULL, search = NULL,
+                                  parquet = NULL, search = NULL, status = NULL,
                                   with_nested = NULL, ...) {
   resource <- "plant-concepts"
   vb_key <- get_vb_key(resource)
   is_collection <- is.null(vb_code) || substr(vb_code, 1, 2) != vb_key
   if (missing(parquet)) parquet <- if (is_collection) TRUE else FALSE
   if (missing(with_nested)) with_nested <- if (is_collection) FALSE else TRUE
-  vb_get(resource, vb_code, parquet = parquet, search = search,
+  vb_get(resource, vb_code, parquet = parquet, search = search, status = status,
          with_nested = with_nested, limit = limit, offset = offset, ...)
 }
 
 #' @rdname vb_get
 #' @export
 vb_get_taxon_observations <- function(vb_code = NULL, limit = 100,
                                       offset = 0, parquet = NULL,
-                                      search = NULL,
+                                      search = NULL, detail = NULL,
                                       with_nested = NULL, ...) {
   resource <- "taxon-observations"
   vb_key <- get_vb_key(resource)
   is_collection <- is.null(vb_code) || substr(vb_code, 1, 2) != vb_key
   if (missing(parquet)) parquet <- if (is_collection) TRUE else FALSE
+  if (missing(detail)) detail <- if (is_collection) "minimal" else "full"
   if (missing(with_nested)) with_nested <- if (is_collection) FALSE else TRUE
-  vb_get(resource, vb_code, parquet = parquet, search = search,
+  vb_get(resource, vb_code, parquet = parquet, search = search, detail = detail,
          with_nested = with_nested, limit = limit, offset = offset, ...)
 }
 
 #' @rdname vb_get
 #' @export
 vb_get_taxon_importances <- function(vb_code = NULL, limit = 100,
-                                     offset = 0, parquet = NULL,
+                                     offset = 0, parquet = NULL, detail = NULL,
                                      with_nested = NULL, ...) {
   resource <- "taxon-importances"
   vb_key <- get_vb_key(resource)
   is_collection <- is.null(vb_code) || substr(vb_code, 1, 2) != vb_key
   if (missing(parquet)) parquet <- if (is_collection) TRUE else FALSE
+  if (missing(detail)) detail <- if (is_collection) "minimal" else "full"
   if (missing(with_nested)) with_nested <- if (is_collection) FALSE else TRUE
-  vb_get(resource, vb_code, parquet = parquet, with_nested = with_nested,
-         limit = limit, offset = offset, ...)
+  vb_get(resource, vb_code, parquet = parquet, detail = detail,
+         with_nested = with_nested, limit = limit, offset = offset, ...)
 }
 
 #' @rdname vb_get
 #' @export
 vb_get_stem_counts <- function(vb_code = NULL, limit = 100, offset = 0,
-                               parquet = NULL, ...) {
+                               parquet = NULL, detail = NULL, ...) {
   resource <- "stem-counts"
   vb_key <- get_vb_key(resource)
   is_collection <- is.null(vb_code) || substr(vb_code, 1, 2) != vb_key
+  if (missing(detail)) detail <- if (is_collection) "minimal" else "full"
   if (missing(parquet)) parquet <- if (is_collection) TRUE else FALSE
   vb_get(resource, vb_code, parquet = parquet, limit = limit,
-         offset = offset, ...)
+         offset = offset, detail = detail, ...)
 }
 
 #' @rdname vb_get
 #' @export
 vb_get_strata <- function(vb_code = NULL, limit = 100, offset = 0,
-                          parquet = NULL, ...) {
+                          parquet = NULL, detail = NULL,...) {
   resource <- "strata"
   vb_key <- get_vb_key(resource)
   is_collection <- is.null(vb_code) || substr(vb_code, 1, 2) != vb_key
+  if (missing(detail)) detail <- if (is_collection) "minimal" else "full"
   if (missing(parquet)) parquet <- if (is_collection) TRUE else FALSE
   vb_get(resource, vb_code, parquet = parquet, limit = limit,
-         offset = offset, ...)
+         offset = offset, detail = detail, ...)
 }
 
 #' @rdname vb_get
@@ -338,14 +353,14 @@ vb_get_taxon_interpretations <- function(vb_code = NULL, limit = 100,
 #' @rdname vb_get
 #' @export
 vb_get_community_concepts <- function(vb_code = NULL, limit = 100, offset = 0,
-                                      parquet = NULL, search = NULL,
+                                      parquet = NULL, search = NULL, status = NULL,
                                       with_nested = NULL, ...) {
   resource <- "community-concepts"
   vb_key <- get_vb_key(resource)
   is_collection <- is.null(vb_code) || substr(vb_code, 1, 2) != vb_key
   if (missing(parquet)) parquet <- if (is_collection) TRUE else FALSE
   if (missing(with_nested)) with_nested <- if (is_collection) FALSE else TRUE
-  vb_get(resource, vb_code, parquet = parquet, search = search,
+  vb_get(resource, vb_code, parquet = parquet, search = search, status = status,
          with_nested = with_nested, limit = limit, offset = offset, ...)
 }
 
@@ -384,7 +399,7 @@ vb_get_community_interpretations <- function(vb_code = NULL, limit = 100,
 #' @rdname vb_get
 #' @export
 vb_get_plot_observations <- function(vb_code = NULL, limit = 100, offset = 0,
-                                     parquet = NULL, search = NULL,
+                                     parquet = NULL, search = NULL, status = NULL,
                                      detail = NULL, with_nested = NULL,
                                      num_taxa = NULL, num_comms = NULL, ...) {
   resource <- "plot-observations"
@@ -395,7 +410,7 @@ vb_get_plot_observations <- function(vb_code = NULL, limit = 100, offset = 0,
   if (missing(with_nested)) with_nested <- if (is_collection) FALSE else TRUE
   if (missing(num_taxa)) num_taxa <- if (is_collection) 5 else 5000
   if (missing(num_comms)) num_comms <- if (is_collection) 5 else 5000
-  vb_get(resource, vb_code, parquet = parquet, search = search,
+  vb_get(resource, vb_code, parquet = parquet, search = search, status = status,
          detail = detail, with_nested = with_nested, num_taxa = num_taxa,
          num_comms = num_comms, limit = limit, offset = offset, ...)
 }