⇧ Back to top

RStudio Connect API Reference 1.0.0

Build 1.6.8.2-12

This is a reference document explaining the RStudio Connect API. Please note that paths are relative to the base API URL (i.e., http:/localhost:3939/__api__/v1)

The Connect Server API can be used to perform certain user actions remotely. You will need to install a tool or library that can make HTTP requests, such as: - [httr](http://httr.r-lib.org/) (R HTTP library) - [cURL](https://curl.haxx.se/) (Linux tool for making HTTP calls) - [requests](http://docs.python-requests.org/en/master/) (Python HTTP library) ## Authentication Most endpoints require you to identify yourself as a valid RStudio Connect user. You do this by specifying an API key when you make a call to the server. See the RStudio Connect User Guide if you need help creating one. You can find a link to it on the **Documentation** tab of the Connect dashboard. ### API Keys API Keys are managed by each user in the Connect dashboard. If you ever lose an API key or otherwise feel it has been compromised, use the dashboard to revoke the key and create another one. Once you have an API key, you can authenticate by passing the key with a prefix of `"Key "` (the space is important) in the Authorization header. Below are examples of invoking the "Get R Information" endpoint. **cURL** ```bash curl -H "Authorization: Key XXXXXXXXXXX" \ https://rstudioconnect.example.com/__api__/v1/server_settings/r ``` **R** ```r library(httr) apiKey <- "XXXXXXXXXXX" result <- GET("https://rstudioconnect.example.com/__api__/v1/server_settings/r", add_headers(Authorization = paste("Key", apiKey)) ``` **Python** ```python import requests r = requests.get( 'https://rstudioconnect.example.com/__api__/v1/server_settings/r', headers = { 'Authorization': 'Key XXXXXXXXXXX' } ) ```

Endpoints

The URIs for all endpoints below must be prefixed with /__api__/v1 to function properly. Unless otherwise noted, all endpoints which accept a request body will require the body to be in application/json format. Similarly, all response bodies will be returned in application/json format.

Users

These endpoints allow you to discover what the Connect server knows about users.
get   /users Get all users
Operation ID: getUsers

This endpoint returns a list of all users.
Administrator access is required for filtering by `account_status`.
This endpoint uses offset pagination (using page numbers). For examples, please see the RStudio Connect User Guide. You can find a link to it on the **Documentation** tab of the Connect dashboard.
Parameters
user_role string (query)
Filter by user role. "|" represents logical OR. For example, `user_role=viewer|publisher` means users who are either a viewer or a publisher will be included in the result. Note that for `user_role`, logical AND is also supported but always returns no results. For example, `user_role=viewer&user_role=publisher` tries to return users who are both viewers and publishers.
account_status string (query)
Filter by account status. "|" represents logical OR. For example, `account_status=locked|licensed` means users who are either locked or licensed. - `locked` - Users with a locked account. - `licensed` - Users regarded as licensed (unlocked and recently active). - `inactive` - Users not locked and not recently active. Note that for `account_status`, logical AND is also supported but always returns no results. For example, `account_status=locked&account_status=licensed` tries to return users who are both locked and licensed.
page_number integer (int32) (query)
The page to return relative to the given `page_size`. If `page_number` is 0 or negative, an error will be returned.
It has a default value of `1`.
page_size integer (int32) (query)
The number of items to include in each page. This parameter is "best effort" since there may not be enough users to honor the request. If `page_size` is less than 1 or greater than 500, an error will be returned.
It has a default value of `20`.
asc_order boolean (query)
Whether or not to return the users in ascending order, sorted by first name, last name, username, and email.
It has a default value of `true`.

200 Users
The user list results and paging information.
401 APIError
The requested operation requires authentication. The result will have a code of `24`.
403 APIError
You don't have permission to perform this operation. The result will have a code of `22`.
default APIError
An error occurred invoking the API.
post   /users Create a user for password, PAM, and proxy providers.
Operation ID: createPushUser

This endpoint creates the given user on the Connect server. For a `password` provider, all but the first created user will receive a login email.
This endpoint is used only for `password`, `PAM`, and `proxy` providers.
Parameters
user (see below) (body) (required)
The new user values.

Body Schema

The body for this request must be specified as follows:

email string
The user's email.
first_name string
The user's first name
last_name string
The user's last name
password string
Applies only to `password` providers. Must be at least 6 characters long. Cannot be set when `user_must_set_password` is true.
user_must_set_password boolean
Applies only to `password` providers. - When `true`, the created user will be asked to set their password on first login. The `password` request parameter cannot be set when this parameter is `true`. - When `false`, you must specify the `password`.
user_role nullable string
The user's role. If `null` it will default to default user role specified by the config setting `Authorization.DefaultUserRole`.
username string (required)
The user's desired username

Here is an example of what it may look like:

```json { "username": "john_doe", "first_name": "John", "last_name": "Doe", "user_role": "viewer", "user_must_set_password": false, "password": "", "email": "john_doe@rstudio.com" } ```
200 User
The user object
400
The requested operation is inavlid.
401 APIError
The requested operation requires authentication. The result will have a code of `24`.
403 APIError
You don't have permission to perform this operation. The result will have a code of `22`.
404 APIError
The requested object does not exist. The result will have a code of `4`.
409 APIError
The requested username is already in use. The result will have a code of `8`.
500
A server error occurred.
put   /users/{guid} Update a user
Operation ID: updateUser

This endpoint updates a given user and returns the updated user properties. Note that it returns only the properties that can be modified by this endpoint. Changing an unconfirmed user's email will cause the confirmation email to be resent to the new email. Password providers may be configured to only allow admins to edit user properties. See the `Password.UserInfoEditableBy` configuration setting.
If the provider allows it: - a user can change their own user properties. - another user's properties can be changed with administrator access.
Parameters
guid string (path) (required)
The user's GUID, or unique identifier
user (see below) (body) (required)
The new user values.

Body Schema

The body for this request must be specified as follows:

email string
The user's new email. Note that changing an unconfirmed user's email will cause the confirmation email to be resent to the new email.
first_name string
The user's new first name
last_name string
The user's new last name
user_role string
The user's new role. Note that you can only downgrade yourself. Administrators can change other users' roles to any valid role.
username string
The user's new username

Here is an example of what it may look like:

```json { "username": "john_doe", "first_name": "John", "last_name": "Doe", "email": "john_doe@rstudio.com", "user_role": "viewer" } ```
200 EditableUser
The latest user properties that can be modified by this endpoint.
400
The requested operation is inavlid.
401 APIError
The requested operation requires authentication. The result will have a code of `24`.
403 APIError
You don't have permission to perform this operation. The result will have a code of `22`.
404 APIError
The requested object does not exist. The result will have a code of `4`.
409 APIError
The requested username is already in use. The result will have a code of `8`.
500
A server error occurred.

Audit Logs

These endpoints allow you to discover what the Connect server knows about the audit logs.
get   /audit_logs Get audit logs
Operation ID: getAuditLogs

This endpoint returns a portion of the audit logs, as well as paging information that can be used to navigate the audit log results.
This endpoint requires administrator access.
This endpoint uses keyset pagination. For examples, please see the RStudio Connect User Guide. You can find a link to it on the **Documentation** tab of the Connect dashboard.
Parameters
limit integer (int32) (query)
Number of logs to return. The minimum supported value is 1 and maximum supported value is 500. Note that `limit` is a "best effort" request since there may not be enough logs to satisfy the limit.
It has a default value of `20`.
previous string (query)
Gets the previous page of audit logs relative to the given id.
next string (query)
Gets the next page of audit logs relative to the given id.
ascOrder boolean (query)
Whether the audit logs should be listed in ascending order
It has a default value of `true`.

200 AuditLogs
The audit logs results and paging information
401 APIError
The requested operation requires authentication. The result will have a code of `24`.
403 APIError
You don't have permission to perform this operation. The result will have a code of `22`.
default APIError
An error occurred invoking the API.

R Information

These endpoints allow you to discover what the Connect server knows about its R installations.
get   /server_settings/r Get R Information
Operation ID: getRInformation

This endpoint returns a list of metadata objects for each installed version of R that RStudio Connect can run.
This endpoint requires authentication and is only available to `publisher` and `administrator` roles.
For examples, please see the RStudio Connect User Guide. You can find a link to it on the **Documentation** tab of the Connect dashboard.
200 RInstallations
An object describing all the metadata information Connect has about each installation of R.
401 APIError
The requested operation requires authentication. The result will have a code of `24`.
403 APIError
You don't have permission to perform this operation. The result will have a code of `22`.
default APIError
An error occurred invoking the API.

Models

APIError

This object defines data that the Connect server in the case of an error.
code integer (required)
The specific code for the type of error returned.
error string (required)
Some text which describes the problem that was encountered.
payload nullable object

Example

```json { "code": 24, "payload": {}, "error": "The requested operation requires authentication." } ```

EditableUser

email string (required)
The user's email
first_name string (required)
The user's first name
last_name string (required)
The user's last name
updated_time string (date-time) (required)
The timestamp (in RFC3339 format) when the user was last updated in the Connect server
user_role string (required)
The user's role
username string (required)
The user's username

Example

```json { "username": "jondoe", "first_name": "Jon", "last_name": "Doe", "user_role": "administrator", "updated_time": "2006-01-02T15:04:05Z07:00", "email": "jon.doe@localhost.com" } ```

User

active_time nullable string (date-time) (required)
The timestamp (in RFC3339 format) when the user was last active on the Connect server
confirmed boolean (required)
Whether or not the user is confirmed
created_time string (date-time) (required)
The timestamp (in RFC3339 format) when the user was created in the Connect server
email string (required)
The user's email
first_name string (required)
The user's first name
guid string (required)
The user's GUID, or unique identifer
last_name string (required)
The user's last name
locked boolean (required)
Whether or not the user is locked
updated_time string (date-time) (required)
The timestamp (in RFC3339 format) when the user was last updated in the Connect server
user_role string (required)
The user's role
username string (required)
The user's username

Example

```json { "username": "jondoe", "active_time": "2006-01-02T15:04:05Z07:00", "first_name": "Jon", "last_name": "Doe", "locked": false, "user_role": "administrator", "updated_time": "2006-01-02T15:04:05Z07:00", "confirmed": true, "created_time": "2006-01-02T15:04:05Z07:00", "guid": "6f300623-1e0c-48e6-a473-ddf630c0c0c3", "email": "jon.doe@localhost.com" } ```

UserWithTicket

active_time nullable string (date-time) (required)
The timestamp (in RFC3339 format) when the user was last active on the Connect server
confirmed boolean (required)
Whether or not the user is confirmed
created_time string (date-time) (required)
The timestamp (in RFC3339 format) when the user was created in the Connect server
email string (required)
The user's email
first_name string (required)
The user's first name
guid string (required)
The user's GUID, or unique identifer
last_name string (required)
The user's last name
locked boolean (required)
Whether or not the user is locked
updated_time string (date-time) (required)
The timestamp (in RFC3339 format) when the user was last updated in the Connect server
user_role string (required)
The user's role
username string (required)
The user's username

Example

```json { "username": "jondoe", "active_time": "2006-01-02T15:04:05Z07:00", "first_name": "Jon", "last_name": "Doe", "locked": false, "user_role": "administrator", "updated_time": "2006-01-02T15:04:05Z07:00", "confirmed": true, "created_time": "2006-01-02T15:04:05Z07:00", "guid": "6f300623-1e0c-48e6-a473-ddf630c0c0c3", "email": "jon.doe@localhost.com" } ```

Users

current_page integer:int32 (0 <= n)
The current page of results
results array of UserWithTicket
The users list
total integer
The number of users that match the given filters

Example

```json { "total": 0, "results": [ { "username": "jondoe", "active_time": "2006-01-02T15:04:05Z07:00", "first_name": "Jon", "last_name": "Doe", "locked": false, "user_role": "administrator", "updated_time": "2006-01-02T15:04:05Z07:00", "confirmed": true, "created_time": "2006-01-02T15:04:05Z07:00", "guid": "6f300623-1e0c-48e6-a473-ddf630c0c0c3", "email": "jon.doe@localhost.com" } ], "current_page": 0 } ```

AuditEntry

action string (required)
Audit action taken
event_description string (required)
Description of action
id string (required)
ID of the audit action
time string (date-time) (required)
Timestamp in RFC3339 format when action was taken
user_description string (required)
Description of the actor
user_id string (required)
User ID of the actor who made the audit action

Example

```json { "event_description": "Added user Full Name (username)", "user_id": "string", "user_description": "Full name (username)", "time": "2006-01-02T15:04:05Z07:00", "action": "add_user", "id": "string" } ```

AuditLogs

paging AuditPager
results array of AuditEntry
The audit logs

Example

```json { "paging": { "next": "http://localhost:3443/__api__/audit_logs?next=23948901087", "previous": "http://localhost:3443/__api__/audit_logs?previous=23948901087", "last": "http://localhost:3443/__api__/audit_logs?last=true", "cursors": { "next": "23948901087", "previous": "23948901087" }, "first": "http://localhost:3443/__api__/audit_logs" }, "results": [ { "event_description": "Added user Full Name (username)", "user_id": "string", "user_description": "Full name (username)", "time": "2006-01-02T15:04:05Z07:00", "action": "add_user", "id": "string" } ] } ```

AuditPager

Paging object that can be used for navigation
cursors object (required)
Cursors that can be used for navigation
next nullable string (required)
A cursor ID that can be used with the `next` query param to get the next page of results.
previous nullable string (required)
A cursor ID that can be used with the `previous` query param to get the previous page of results.

first nullable string (required)
A full URL of the first page of results. It will always return the current first page.
last nullable string (required)
A full URL of the last page of results. It will always return the current last page.
next nullable string (required)
A full URL of the next page of results when the original request was made.
previous nullable string (required)
A full URL of the previous page of results when the original request was made.

Example

```json { "next": "http://localhost:3443/__api__/audit_logs?next=23948901087", "previous": "http://localhost:3443/__api__/audit_logs?previous=23948901087", "last": "http://localhost:3443/__api__/audit_logs?last=true", "cursors": { "next": "23948901087", "previous": "23948901087" }, "first": "http://localhost:3443/__api__/audit_logs" } ```

RInstallation

This defines the information provided by the server about a single installation of R.
version string
The version number of this R installation.

Example

```json { "version": "3.4.4" } ```

RInstallations

This defines the top-level object that describes the data returned by the server. It contains information about each installation of R that is known.
installations array of RInstallation
The array of information about Connect's R installations.

Example

```json { "installations": [ { "version": "3.4.4" } ] } ```