Interface

Workbench

Workbench API

Method launch_session

Launches a Posit Workbench Session on behalf of the username provided in the parameters or the auth cookie.

POST /api/launch_session
   {"method": "launch_session",
   "kwparams": { "workbench": "RStudio", "name": "My RStudio Session", ...}}

Parameters

Name Type Summary
workbench (required) string The IDE name to use: one of: ‘RStudio’, ‘JupyterLab’, ‘Jupyter Notebook’, ‘VS Code’.
username string Start the session on behalf of this user. If not provided, the auth-token’s username is used.
name string The new session’s name, as it appears in the homepage.
open_file string For Jupyter Notebook sessions, the path to the notebook file. (FUTURE: a file to open by default in any IDE).
working_directory string The current directory for the new session.
launch_parameters LaunchParameters Provides additional launch config when launcher sessions are enabled.

Result

Returns a result object with ID, URL, project_id properties identifying the session

Property name Type Summary
id string The ID of the new session, used in stop_session or get_session to filter the result.
url string The URL starting with a / to use to join the session. If the server context has changed, prepend the appropriate https://server-name part to the returned value before opening the URL in the browser, or using it in further api requests.
project_id string A unique identifier for the project used by the session.

Example results:

{
  "result": {
    "url": "/s/0da29cfc78a31acdd5861/",
    "id": "acdd5861",
    "project_id": "cfc78a31"
  }
}

Method get_session

Returns session and job information for a given user.

POST /api/get_session
    {"method": "get_session",
   "kwparams": { "session_id": "id1,id2",  "user": "username",
   "fields" : ["id", "url,", "activity_state"], "include_jobs" : true}}

Parameters

Name Type Summary
session_id string Return info for a specific session identified by the ID provided.
user string Return sessions for the given user, defaulting to the api token’s username. The token must have at least read-only admin or super-admin permissions to get the session info for a different user.
fields array of string Array of field names returned by the session to filter whats returned.
include_jobs boolean Set to true to include job information in the response.

Result

Returns a result object with an array of sessions and optionally jobs

On error, either a 40x, 50x http status code, or a JSON RPC error will be returned with code, and message properties. Any problems associated with the user’s account, or configuration problems on the server node will generate a JSON RPC error with an appropriate message.

Property name Type Summary
sessions array of WorkbenchSession
jobs array of WorkbenchJob

Example results:

{
  "result": {
    "sessions": [
      {
        "url": "/s/0da29cfc78a316124d41f/",
        "id": "6124d41f",
        "launch_parameters": {
          "name": "RStudio Pro Session",
          "cluster": "Local",
          "placement_constraints": [],
          "resource_limits": [],
          "queues": [],
          "container_image": "",
          "default_image": "",
          "container_images": [
            ""
          ]
        },
        "created": 1721684073175,
        "activity_state": "suspended",
        "last_state_updated": 1721695376181,
        "label": "RStudio Pro Session",
        "display_name": "RStudio Pro Session",
        "status_detail": "",
        "project": null,
        "project_id": "none",
        "running": false,
        "working_dir": "~",
        "executing": false,
        "save_prompt_required": false,
        "last_used": 1721694685914,
        "r_version": "4.3.0",
        "r_version_label": "",
        "r_version_home": "/usr/lib/R",
        "suspend_size": 20324197,
        "workbench": "RStudio"
      }
    ]
  }
}

Method get_compute_envs

Returns metadata about the environments the server supports for launching new sessions.

GET /api/get_compute_envs

POST /api/get_compute_envs
   {"method": "get_compute_envs"}

Result

Returns a result object with ComputeEnv and a list of supported IDEs

Property name Type Summary
clusters array of ComputeEnv
workbenches object An object whose properties are the names of the supported IDEs: ‘RStudio’, ‘VS Code’, ‘JupyterLab’, ‘Jupyter Notebook’

Example results:

{
  "result": {
    "clusters": [
      {
        "supportsContainers": false,
        "queues": [],
        "config": [],
        "resourceLimits": [],
        "placementConstraints": [],
        "resourceProfiles": [],
        "name": "Local",
        "type": "Local",
        "workbenches": {
          "RStudio": {
            "supports_interactive_sessions": true,
            "supports_adhoc_jobs": true
          },
          "JupyterLab": {
            "supports_interactive_sessions": true,
            "supports_adhoc_jobs": true
          },
          "Jupyter Notebook": {
            "supports_interactive_sessions": true,
            "supports_adhoc_jobs": true
          },
          "VS Code": {
            "supports_interactive_sessions": true,
            "supports_adhoc_jobs": true
          }
        },
        "images": []
      }
    ],
    "workbenches": {
      "RStudio": {
        "default_cluster": "Localhost",
        "default_image": "",
        "lang": {
          "name": "R",
          "available": true
        }
      },
      "JupyterLab": {
        "default_cluster": "Local",
        "default_image": "",
        "lang": {
          "name": "Jupyter",
          "available": true
        }
      },
      "Jupyter Notebook": {
        "default_cluster": "Local",
        "default_image": "",
        "lang": {
          "name": "Jupyter",
          "available": true
        }
      },
      "VS Code": {
        "default_cluster": "Localhost",
        "default_image": "",
        "lang": {
          "name": "code-server",
          "available": false
        }
      }
    }
  }
}

Method stop_session

Stops one or more session given a list of session_ids. Optionally force quit, or suspend the sessions.

POST /api/stop_session
   {"method": "stop_session", "kwparams": {
      "session_ids": "id1,id2,..."
      "force_quit" : false
      "suspend_session": false}

Parameters

Name Type Summary
session_ids (required) string A comma separated list of session IDs to stop, suspend or force quit
force_quit boolean Sends the kill signal to forcefully quit the session process.
suspend_session boolean For sessions that support suspension, e.g. RStudio, tells the session to save its state before exiting.

Result

On success, returns with an HTTP 200 return code and an empty result message.

Method version

Returns a Json object with version information including a list of enabled features.

GET /api/version

Result

Returns an HTTP 401 code for permission denied, 50x for server problems, or 200 with a JSON result indicating success or error.

On success, the result is a Json object with version and feature info.

Property name Type Summary
version object An object containing major, minor, patch, build_number, release_name, and build_type string properties
features array of string List of the names of features enabled in this server

Resources

PlacementConstraint

Name/values that choose launch options defined in the server configuration

Required Properties: name, value

Properties
Property name Type Summary
name string Constraint name
value string Constraint value

ResourceLimit

Properties
Property name Type Summary
name string
value string
valueType string

LaunchParameters

Used to define parameters for Job launcher sessions.

Required Properties: name, cluster

Properties
Property name Type Summary
name string
cluster string The compute environment to launch the session
container_image string
placement_constraints array of PlacementConstraint
resource_limits array of ResourceLimit
queues array of string
default_image string
resource_profile string
aws_role_arn string
databricks_instance string
snowflake_account string
snowflake_role string

WorkbenchSession

The metadata workbench manages for a given session.

Properties
Property name Type Summary
name string
id string
url string
launch_parameters
created number
activity_state string
last_state_updated number
label string
display_name string
project string
project_id string
working_dir string
running boolean
executing boolean
save_prompt_required boolean
last_used number
r_version string
r_version_label string
r_version_home string
suspend_size number
workbench string

WorkbenchJob

The metadata workbench manages for a given session.

Properties
Property name Type Summary
id string
cluster string
name string
group string
user string
queues array of string
tags array of string
working_directory string
container string
host string
status string
statusMessage string
statusCode string
pid number
exitCode number
command string
stdoutFile string
stderrFile string
stdin string
submissionTime string
lastUpdateTime string

JobConfig

Properties
Property name Type Summary
name string
value string
valueType string

ComputeEnv

An environment for running sessions.

Properties
Property name Type Summary
supportsContainers boolean
queues array of string
config array of JobConfig
resourceLimits array of ResourceLimit

WorkbenchIDEInfo

Stores default info for a supported IDE

Required Properties: default_cluster, default_image, lang

Properties
Property name Type Summary
default_cluster string
default_image string
lang

WorkbenchLanguage

Required Properties: name, available

Properties
Property name Type Summary
name string
available boolean
Back to top