plumber v1.0.0


Monthly downloads



An API Generator for R

Gives the ability to automatically generate and serve an HTTP API from R functions using the annotations in the R documentation around your functions.



R build status CRAN RStudio mirror downloads codecov RStudio community

Plumber allows you to create a web API by merely decorating your existing R source code with special comments. Take a look at an example.

# plumber.R

#* Echo back the input
#* @param msg The message to echo
#* @get /echo
function(msg="") {
  list(msg = paste0("The message is: '", msg, "'"))

#* Plot a histogram
#* @png
#* @get /plot
function() {
  rand <- rnorm(100)

#* Return the sum of two numbers
#* @param a The first number to add
#* @param b The second number to add
#* @post /sum
function(a, b) {
  as.numeric(a) + as.numeric(b)

These comments allow plumber to make your R functions available as API endpoints. You can use either #* as the prefix or #', but we recommend the former since #' will collide with Roxygen.

# 'plumber.R' is the location of the file shown above
pr("plumber.R") %>%

You can visit this URL using a browser or a terminal to run your R function and get the results. For instance http://localhost:8000/plot will show you a histogram, and http://localhost:8000/echo?msg=hello will echo back the 'hello' message you provided.

Here we're using curl via a Mac/Linux terminal.

$ curl "http://localhost:8000/echo"
 {"msg":["The message is: ''"]}
$ curl "http://localhost:8000/echo?msg=hello"
 {"msg":["The message is: 'hello'"]}

As you might have guessed, the request's query string parameters are forwarded to the R function as arguments (as character strings).

$ curl --data "a=4&b=3" "http://localhost:8000/sum"

You can also send your data as JSON:

$ curl --data '{"a":4, "b":5}' http://localhost:8000/sum


You can install the latest stable version from CRAN using the following command:


If you want to try out the latest development version, you can install it from GitHub.



If you're just getting started with hosting cloud servers, the DigitalOcean integration included in plumber will be the best way to get started. You'll be able to get a server hosting your custom API in just two R commands. To deploy to DigitalOcean, check out the plumber companion package plumberDeploy.

RStudio Connect is a commercial publishing platform that enables R developers to easily publish a variety of R content types, including Plumber APIs. Additional documentation is available at

A couple of other approaches to hosting plumber are also made available:

  • OpenCPU - A server designed for hosting R APIs with an eye towards scientific research.
  • jug - (development discontinued) an R package similar to Plumber but uses a more programmatic approach to constructing the API.

Functions in plumber

Name Description
endpoint_serializer Endpoint Serializer with Hooks
PlumberStep plumber step R6 class
hookable Deprecated R6 functions
PlumberEndpoint Plumber Endpoint
as_attachment Return an attachment response
PlumberStatic Static file router
do_provision DigitalOcean Plumber server
addSerializer Deprecated functions
Hookable Hookable
%>% Pipe operator
plumb_api Process a Package's Plumber API
include_file Send File Contents as Response
Plumber Package Plumber Router
is_plumber Determine if Plumber object
pr_set_docs Set the API visual documentation
serializer_headers Plumber Serializers
register_serializer Register a Serializer
pr_set_debug Set debug value to include error messages of routes cause an error
parser_form Plumber Parsers
options_plumber Plumber options
plumb Process a Plumber API
pr_mount Mount a Plumber router
pr_hook Register a hook
pr_handle Add handler to Plumber router
pr Create a new Plumber router
pr_static Add a static route to the plumber object
pr_cookie Store session data in encrypted cookies.
pr_filter Add a filter to Plumber router
pr_set_404 Set the handler that is called when the incoming request can't be served
forward Forward Request to The Next Handler
get_character_set Request character set
random_cookie_key Random cookie key generator
pr_set_parsers Set the default endpoint parsers for the router
pr_set_api_spec Set the OpenAPI Specification information
register_docs Add visual documentation for plumber to use
pr_set_serializer Set the default serializer of the router
pr_set_docs_callback Set the callback to tell where the API visual documentation is located
pr_run Start a server using plumber object
pr_set_error Set the error handler that is invoked if any filter or endpoint generates an error
session_cookie Store session data in encrypted cookies.
validate_api_spec Validate OpenAPI Spec
register_parser Manage parsers
No Results!

Last month downloads


Encoding UTF-8
Type Package
License MIT + file LICENSE
LazyData TRUE
ByteCompile TRUE
RoxygenNote 7.1.1
Collate 'async.R' 'content-types.R' 'default-handlers.R' 'hookable.R' 'shared-secret-filter.R' 'parser-cookie.R' 'parse-body.R' 'parse-query.R' 'plumber.R' 'deprecated-R6.R' 'deprecated.R' 'digital-ocean.R' 'find-port.R' 'globals.R' 'includes.R' 'json.R' 'new-rstudio-project.R' 'openapi-spec.R' 'openapi-types.R' 'paths.R' 'plumb-block.R' 'plumb-globals.R' 'plumb.R' 'plumber-options.R' 'plumber-response.R' 'plumber-static.R' 'plumber-step.R' 'pr.R' 'pr_set.R' 'serializer.R' 'session-cookie.R' 'ui.R' 'utf8.R' 'utils-pipe.R' 'utils.R' 'validate_api_spec.R' 'zzz.R'
RdMacros lifecycle
NeedsCompilation no
Packaged 2020-09-14 16:36:27 UTC; barret
Repository CRAN
Date/Publication 2020-09-14 21:40:02 UTC

Include our badge in your README