Interface
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 |