⇧ Back to top

RStudio Connect API Reference 1.0.0

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 client which invoked the API did not provide appropriate credentials to call the API. The result will have a code of `24` and an error of "The requested operation requires authentication."
403 APIError
The client which invoked the API did not provide appropriate credentials to call the API. The result will have a code of `22` and an error of "You don't have permission to perform this operation."
default APIError
An error occurred invoking the API.

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 client which invoked the API did not provide appropriate credentials to call the API. The result will have a code of `24` and an error of "The requested operation requires authentication."
403 APIError
The client which invoked the API did not provide appropriate credentials to call the API. The result will have a code of `22` and an error of "You don't have permission to perform this operation."
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 client which invoked the API did not provide appropriate credentials to call the API. The result will have a code of `24` and an error of "The requested operation requires authentication."
403 APIError
The client which invoked the API did not provide appropriate credentials to call the API. The result will have a code of `22` and an error of "You don't have permission to perform this operation."
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
The specific code for the type of error returned.
error* string
Some text which describes the problem that was encountered.
payload nullable object

Example

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

User

active_time* nullable string (date-time)
The timestamp (in RFC3339 format) when the user was last active on the Connect server
confirmed* boolean
Whether or not the user is confirmed
created_time* string (date-time)
The timestamp (in RFC3339 format) when the user was created in the Connect server
email* string (email)
The user's email
first_name* string
The user's first name
guid* string
The user's GUID, or unique identifer
last_name* string
The user's last name
locked* boolean
Whether or not the user is locked
updated_time* string (date-time)
The timestamp (in RFC3339 format) when the user was last updated in the Connect server
user_role* string
The user's role
username* string
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 User
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
Audit action taken
event_description* string
Description of action
id* string
ID of the audit action
time* string (date-time)
Timestamp in RFC3339 format when action was taken
user_description* string
Description of the actor
user_id* string
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
Cursors that can be used for navigation
next* nullable string
A cursor ID that can be used with the `next` query param to get the next page of results.
previous* nullable string
A cursor ID that can be used with the `previous` query param to get the previous page of results.

first* nullable string
A full URL of the first page of results. It will always return the current first page.
last* nullable string
A full URL of the last page of results. It will always return the current last page.
next* nullable string
A full URL of the next page of results when the original request was made.
previous* nullable string
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" } ] } ```