Interface
Workbench | Preview
Workbench API
Method launch_session
Launches a Posit Workbench Session on behalf of the username provided in the parameters or the auth cookie. A super-admin API token is required to launch a session on behalf of a different user than the API token owner.
POST /api/launch_session {
"method": "launch_session",
"kwparams": {
"workbench": "RStudio",
"name": "My RStudio Session",
"launch_parameters": {
"name": "Job name", "cluster": "Local",
"placement_constraints":[], "resource_limits":[], "queues":[]
}
}
}
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 | A file to open by default in the launched IDE session. This is supported for RStudio and Jupyter Notebook sessions. |
working_directory | string | The current directory for the new session. |
launch_parameters | LaunchParameters | Provides additional launch config, required when launcher sessions are enabled. |
start_hooks | SessionHook | Provides hooks that should be run when the session is started. |
stop_hooks | SessionHook | Provides hooks that should be run when the session is stopped. |
environment | Environment | Provides environment variables that should be added to the session. |
Result
Returns a result object with ID, URL, and 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 launch_job
Launches a Posit Workbench Job on behalf of the username provided in the parameters or the auth cookie. A super-admin API token is required to launch a job on behalf of a different user than the API token owner.
POST /api/launch_job {
"method": "launch_job",
"kwparams": {
"job": {
"cluster": "Local",
"name": "Job Test",
"exe": "/bin/bash",
"args": ["-c", "R -f JobTest.R"]
}
}
}
Parameters
Name | Type | Summary |
---|---|---|
job (required) | object | An object that provides the initial properties for the job: name, exe, args, cluster, and working_directory. Optional initial properties include environment, tags, container_image, resource_limits, queues, and placement_constraints. The user property in the job can be used with a super-admin API token to impersonate another user. If the user property is not set, the user from the API token is used. |
apply_config_settings | boolean | Set this to false to bypass launcher mounts and other global settings normally applied to all jobs |
Result
Returns a result object with a job
property containing the WorkbenchJob. The returned job has all fields populated, both the initial values provided and those that reflect the state of the running job (e.g., status, process id, the host for the job, and timestamps).
Property name | Type | Summary |
---|---|---|
job | object | The WorkbenchJob with job_id and status fields populated |
Example results:
{
"result": {
"result": {
"job": {
"id": "...",
"cluster": "Local",
"name": "JobTest.R",
"user": "jvroom",
"queues": [],
"workingDirectory": "",
"host": "localhost",
"status": "Pending",
"pid": 729383,
"command": "",
"exe": "/bin/bash",
"stdoutFile": "",
"stderrFile": "",
"stdin": "",
"args": [
"-c",
"R -f /tmp/JobTest.R"
],
"environment": [],
"placementConstraints": [],
"lastUpdateTime": "2024-10-01T20:49:32.294130Z",
"submissionTime": "2024-10-01T20:49:32.294014Z",
"exposedPorts": [],
"mounts": [],
"config": [],
"resourceLimits": [],
"tags": [],
"metadata": {},
"resourceProfile": "custom"
}
}
}
}
Method get_session
Returns session and job information for a given user. An admin or super-admin API token is required to retrieve a session for a user other the API token’s owner.
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 with read access 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 resume_session
Resumes a suspended Posit Workbench Session (RStudio Pro sessions only). Provide the username of the session owner and the session id. If a username
parameter is not provided, the owner of the API token or auth cookie used instead. A super-admin API token is required to resume a session on behalf of a different user than the API token owner.
POST /api/resume_session {
"method": "resume_session",
"kwparams": {
"username": "optional-session-username",
"session_id": "<the-session-id-returned>",
"launch_parameters": {
"name": "Job name", "cluster": "Local",
"placement_constraints":[], "resource_limits":[], "queues":[]
}
}
}
Parameters
Name | Type | Summary |
---|---|---|
session_id (required) | string | The session id of the suspended session to resume. Use get_session to get the session_id, or store the value returned from launch_session. |
username | string | The owner of the session. If not provided the API token’s owner is used. |
launch_parameters | LaunchParameters | Provides additional launch config, required when launcher sessions are enabled. |
Result
Returns a result object with ID, URL, and project_id properties identifying the session
Property name | Type | Summary |
---|---|---|
url | string | The URL starting with a / to use to join the session, that was returned in launch_session. |
project_id | string | The unique identifier for the project used by the session, that was returned in launch_session. |
Example results:
{
"result": {
"url": "/s/0da29cfc78a31acdd5861/",
"id": "acdd5861",
"project_id": "cfc78a31"
}
}
Method get_compute_envs
Returns metadata about the environments the server supports for launching new sessions, including resource limits for a given user. When using an admin or super-admin token with read access, it’s possible to retrieve the environment for a supplied user. Use the POST
method and provide the username as a named parameter.
GET /api/get_compute_envs
POST /api/get_compute_envs {"method": "get_compute_envs", "kwparams":{ "user": "session-username"}}
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 get_job_output
Returns a specific job’s output for either a live running job, or a job that finished but hasn’t been removed from the system yet. The output is returned in a stream of JSON objects that are parsed one after another. For a live job, the chunks are returned as they are produced and the connection will not be closed by the server until the job exits, or it times out on the server or in a proxy layer. An admin or super-admin API token with read access is required to retrieve the job output for a user other than the API token’s owner.
POST /api/get_job_output {
"method": "get_job_output",
"kwparams": {
"job_id": "job_id",
"user": "job-user"
}
}
Parameters
Name | Type | Summary |
---|---|---|
job_id (required) | string | The id of the job. |
user | string | The user that owns the job, required if using a super-admin token for impersonation. |
Result
Returns a stream of JSON objects, each one containing a chunk of either the stdout or stderr streams of the job. Each chunk has jobId
, outputType
of stdout
or stderr
and output
with the chunk. If the process is still running, the server will stream chunks as they arrive. If not, the stream is closed.
{"jobId":"....", "outputType":"stdout", "output":"A chunk of the job's standard output"}
{"jobId":"...", "outputType":"stderr", "output":"A chunk of the job's error output"}
Method stop_session
Stops one or more session given a list of session_ids. Optionally force quit, or suspend the sessions. Use an admin or super-admin API token with write access to stop a session on behalf of another user.
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 stop_job
Stops a workbench job given the job_id. Use an admin or super-admin API token with write access to stop a job on behalf of another user.
POST /api/stop_job {
"method": "stop_job",
"kwparams": {
"job_id": "id1"
"force_quit" : false
}
}
Parameters
Name | Type | Summary |
---|---|---|
job_id (required) | string | The individual job id of the job to stop. |
force_quit | boolean | With force_quit is true, the kill signal is used instead of terminate (i.e. kill -9 <pid> instead of kill <pid> ). |
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 |
Method get_users
Returns a JSON array containing the users registered in Posit Workbench. Requires read
access with an admin or super-admin API token.
GET /api/get_users
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.
Example results:
{
"result": [
{
"username": "user1",
"status": "Active",
"isAdmin": false,
"uid": 1037,
"lastSignIn": "2024-07-30T23:45:28.351868Z",
"created": "2024-07-30T23:41:28.109218Z"
},
{
"username": "user2",
"status": "Inactive",
"isAdmin": false,
"uid": 1038,
"lastSignIn": "2024-07-25T13:43:25.231845Z",
"created": "2024-07-30T23:41:28.109218Z"
}
]
}
Data types
These types are used in the Workbench API.
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, resource_limits, placement_constraints, queues
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 | Overall state of the session at a given moment, for the launch process: launching/resuming, pending, starting, and finally running. Also represents exit states: finished, suspended, failed, killed, and suspending for sessions that support suspension (i.e. RStudio) |
last_state_updated | number | Timestamp for last state change |
label | string | |
display_name | string | |
project | string | |
project_id | string | |
working_dir | string | |
running | boolean | |
executing | boolean | The session is active and busy. |
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 |
---|---|---|
name | string | Required job’s name. |
cluster | string | The name of the compute environment to run the job - e.g. Local, Slurm, Kubernetes |
exe | string | The executable on the session node to run |
args | array of string | List of string arguments to provide to the exe. |
command | string | An alternative to exe for providing a shell command to run (i.e. the job is run as: /bin/sh -c command arg1 arg2... ). |
working_directory | string | Provides the initial working directory for the job. |
user | string | The username of the job’s owner |
queues | array of string | |
tags | array of string | |
id | string | The job’s id, returned from the launch_job API. |
container | string | |
host | string | |
group | string | |
status | string | |
statusMessage | string | |
statusCode | string | |
pid | number | |
exitCode | number | |
stdoutFile | string | |
stderrFile | 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 |
EnvironmentVariable
Stores an environment variable.
Required Properties: name, value
Properties
Property name | Type | Summary |
---|---|---|
name | string | |
value | string |
SessionHook
Stores information about a session hook.
Required Properties: exe
Properties
Property name | Type | Summary |
---|---|---|
exe | string |
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 |
WorkbenchUser
Properties
Property name | Type | Summary |
---|---|---|
username | string | Contains the username of the user. |
status | string | Contains the user’s status: Active or Inactive . |
isAdmin | boolean | This value is true if the user has the ability to access the /admin UI. |
isSuperAdmin | boolean | This value is true if the user has the super-admin role that can also start sessions/jobs on behalf of other users. |
uid | int | Contains the posix user’s uid used as an attribute on files for permissions. |
lastSignIn | string | |
created | string |