{ "opencollection": "1.0.0", "info": { "name": "Runloop agents Devbox API", "version": "0.1" }, "request": { "auth": { "type": "bearer", "token": "{{bearerToken}}" } }, "items": [ { "info": { "name": "Devbox", "type": "folder" }, "items": [ { "info": { "name": "Create or reconnect to a PTY session.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/pty/:session_name", "params": [ { "name": "session_name", "value": "", "type": "path", "description": "The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. Reusing the same name reconnects to the same logical PTY session when it is still available." }, { "name": "cols", "value": "", "type": "query", "description": "Optional initial terminal width in character cells (1..=1000). Defaults to 80 when omitted. Applied only if both cols and rows are provided; otherwise ignored." }, { "name": "rows", "value": "", "type": "query", "description": "Optional initial terminal height in character cells (1..=1000). Defaults to 24 when omitted. Applied only if both cols and rows are provided; otherwise ignored." } ] }, "docs": "Looks up the PTY session identified by the path session_name and either reconnects to the existing session or creates it if it does not yet exist. The session_name is a client-chosen session identifier, not an opaque server-issued ID. It must be non-empty (1..=256 chars) and use only ASCII letters, digits, '-' and '_'. A newly created PTY session starts an interactive bash shell on the Devbox. Optional cols and rows query parameters apply an initial terminal size before any I/O; they must both b" }, { "info": { "name": "Send a control command to a PTY session.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/pty/:session_name/control", "params": [ { "name": "session_name", "value": "", "type": "path", "description": "The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Applies a PTY control operation to an existing session. The action field selects the operation; the other fields in PtyControlParameters are interpreted only when they are relevant to the chosen action.\n\nresize: cols and rows are required and must each be in 1..=1000. A 0 or out-of-range value returns 400. The new winsize is applied to the PTY master and the kernel delivers SIGWINCH to the foreground process group.\n\nsignal: signal is the POSIX signal name (for example 'SIGTERM', 'SIGHUP', 'SIGIN" }, { "info": { "name": "List Devboxes.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes", "params": [ { "name": "status", "value": "", "type": "query", "description": "Filter by status" }, { "name": "limit", "value": "", "type": "query", "description": "The limit of items to return. Default is 20. Max is 5000." }, { "name": "starting_after", "value": "", "type": "query", "description": "Load the next page of data starting after the item with the given ID." }, { "name": "include_total_count", "value": "", "type": "query", "description": "If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets." } ] }, "docs": "List all Devboxes while optionally filtering by status." }, { "info": { "name": "Create a Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes", "body": { "type": "json", "data": "{}" } }, "docs": "Create a Devbox and begin the boot process. The Devbox will initially launch in the 'provisioning' state while Runloop allocates the necessary infrastructure. It will transition to the 'initializing' state while the booted Devbox runs any Runloop or user defined set up scripts. Finally, the Devbox will transition to the 'running' state when it is ready for use." }, { "info": { "name": "List disk snapshots of a Devbox.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots", "params": [ { "name": "devbox_id", "value": "", "type": "query", "description": "Devbox ID to filter by." }, { "name": "source_blueprint_id", "value": "", "type": "query", "description": "Source Blueprint ID to filter snapshots by." }, { "name": "metadata[key]", "value": "", "type": "query", "description": "Filter snapshots by metadata key-value pair. Can be used multiple times for different keys." }, { "name": "metadata[key][in]", "value": "", "type": "query", "description": "Filter snapshots by metadata key with multiple possible values (OR condition)." }, { "name": "limit", "value": "", "type": "query", "description": "The limit of items to return. Default is 20. Max is 5000." }, { "name": "starting_after", "value": "", "type": "query", "description": "Load the next page of data starting after the item with the given ID." }, { "name": "include_total_count", "value": "", "type": "query", "description": "If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets." } ] }, "docs": "List all snapshots of a Devbox while optionally filtering by Devbox ID, source Blueprint ID, and metadata." }, { "info": { "name": "List public disk snapshots.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/list_public", "params": [ { "name": "devbox_id", "value": "", "type": "query", "description": "Devbox ID to filter by." }, { "name": "source_blueprint_id", "value": "", "type": "query", "description": "Source Blueprint ID to filter snapshots by." }, { "name": "metadata[key]", "value": "", "type": "query", "description": "Filter snapshots by metadata key-value pair. Can be used multiple times for different keys." }, { "name": "metadata[key][in]", "value": "", "type": "query", "description": "Filter snapshots by metadata key with multiple possible values (OR condition)." }, { "name": "limit", "value": "", "type": "query", "description": "The limit of items to return. Default is 20. Max is 5000." }, { "name": "starting_after", "value": "", "type": "query", "description": "Load the next page of data starting after the item with the given ID." }, { "name": "include_total_count", "value": "", "type": "query", "description": "If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets." } ] }, "docs": "List all public disk snapshots that are available to all users." }, { "info": { "name": "List available snapshot metadata keys.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/metadata/keys" }, "docs": "Returns a list of all available metadata keys that can be used for filtering snapshots." }, { "info": { "name": "List values for a specific snapshot metadata key.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/metadata/keys/:key/values", "params": [ { "name": "key", "value": "", "type": "path", "description": "The metadata key to get values for." } ] }, "docs": "Returns a list of all values that exist for a specific metadata key across all snapshots." }, { "info": { "name": "List available public snapshot metadata keys.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/public/metadata/keys" }, "docs": "Returns a list of all available metadata keys from public snapshots only that can be used for filtering." }, { "info": { "name": "List values for a specific public snapshot metadata key.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/public/metadata/keys/:key/values", "params": [ { "name": "key", "value": "", "type": "path", "description": "The metadata key to get values for from public snapshots." } ] }, "docs": "Returns a list of all values that exist for a specific metadata key across all public snapshots only." }, { "info": { "name": "Update metadata of Disk Snapshot.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Snapshot ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates disk snapshot metadata via update vs patch. The entire metadata will be replaced." }, { "info": { "name": "Delete a disk snapshot of a Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/:id/delete", "params": [ { "name": "id", "value": "", "type": "path", "description": "The ID of the snapshot." } ] }, "docs": "Delete a previously taken disk snapshot of a Devbox." }, { "info": { "name": "Query the status of an asynchronous disk snapshot.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/disk_snapshots/:id/status", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Snapshot ID." } ] }, "docs": "Get the current status of an asynchronous disk snapshot operation, including whether it is still in progress and any error messages if it failed." }, { "info": { "name": "List available devbox metadata keys.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/metadata/keys" }, "docs": "Returns a list of all available metadata keys that can be used for filtering devboxes." }, { "info": { "name": "List values for a specific devbox metadata key.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/metadata/keys/:key/values", "params": [ { "name": "key", "value": "", "type": "path", "description": "The metadata key to get values for." } ] }, "docs": "Returns a list of all values that exist for a specific metadata key across all devboxes." }, { "info": { "name": "Get status of an asynchronous execution on a Devbox.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/:devbox_id/executions/:execution_id", "params": [ { "name": "devbox_id", "value": "", "type": "path", "description": "The Devbox ID" }, { "name": "execution_id", "value": "", "type": "path", "description": "The Execution ID" }, { "name": "last_n", "value": "", "type": "query", "description": "Last n lines of standard error / standard out to return (default: 100)" } ] }, "docs": "Get the latest status of a previously launched asynchronous execuction including stdout/error and the exit code if complete." }, { "info": { "name": "Kill an asynchronous execution currently running on a devbox", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:devbox_id/executions/:execution_id/kill", "params": [ { "name": "devbox_id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "execution_id", "value": "", "type": "path", "description": "The Async Execution ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Kill a previously launched asynchronous execution if it is still running by killing the launched process. Optionally kill the entire process group." }, { "info": { "name": "Send Content to Std In for a running execution.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:devbox_id/executions/:execution_id/send_std_in", "params": [ { "name": "devbox_id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "execution_id", "value": "", "type": "path", "description": "The Async Execution ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Send content to the Std In of a running execution." }, { "info": { "name": "Wait for an asynchronous execution to reach a specific status.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:devbox_id/executions/:execution_id/wait_for_status", "params": [ { "name": "devbox_id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "execution_id", "value": "", "type": "path", "description": "The Async Execution ID." }, { "name": "last_n", "value": "", "type": "query", "description": "Last n lines of standard error / standard out to return (default: 100)" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Polls the asynchronous execution's status until it reaches one of the desired statuses or times out. Max is 25 seconds." }, { "info": { "name": "Get Devbox details.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Get the latest details and status of a Devbox." }, { "info": { "name": "Update a Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates a devbox by doing a complete update the existing name,metadata fields. It does not patch partial values." }, { "info": { "name": "Create an ephemeral PTY tunnel for a running Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/create_pty_tunnel", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Create an ephemeral authenticated tunnel for terminal access to a running Devbox. This tunnel is not persisted on the Devbox and is generated fresh on each request. The returned auth_token must be passed as a Bearer token in the Authorization header." }, { "info": { "name": "Create an SSH key for a Devbox", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/create_ssh_key", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Create an SSH key for a Devbox to enable remote access." }, { "info": { "name": "Download binary file contents from Devbox filesystem.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/download_file", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Download file contents of any type (binary, text, etc) from a specified path on the Devbox." }, { "info": { "name": "Enable a tunnel for a running Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/enable_tunnel", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Enable a V2 tunnel for an existing running Devbox. Tunnels provide encrypted URL-based access to the Devbox without exposing internal IDs. The tunnel URL format is: https://{port}-{tunnel_key}.tunnel.runloop.ai\n\nEach Devbox can have one tunnel." }, { "info": { "name": "Execute a command with a known ID, optimistically waiting for completion", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/execute", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "last_n", "value": "", "type": "query", "description": "Last n lines of standard error / standard out to return (default: 100)" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Execute a command with a known command ID on a devbox, optimistically waiting for it to complete within the specified timeout. If it completes in time, return the result. If not, return a status indicating the command is still running. Note: attach_stdin parameter is not supported; use execute_async for stdin support." }, { "info": { "name": "Asynchronously execute a command via the Devbox shell", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/execute_async", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Execute the given command in the Devbox shell asynchronously and returns the execution that can be used to track the command's progress." }, { "info": { "name": "(Deprecated, please use /execute_async) Synchronously execute a shell command on a Devbox", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/execute_sync", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Execute a bash command in the Devbox shell, await the command completion and return the output. Note: attach_stdin parameter is not supported for synchronous execution." }, { "info": { "name": "Reset the idle timer of a running Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/keep_alive", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Send a 'Keep Alive' signal to a running Devbox that is configured to shutdown on idle so the idle time resets." }, { "info": { "name": "Get Devbox logs.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/:id/logs", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "execution_id", "value": "", "type": "query", "description": "ID of execution to filter logs by." }, { "name": "shell_name", "value": "", "type": "query", "description": "Shell Name to filter logs by." } ] }, "docs": "Get all logs from a running or completed Devbox." }, { "info": { "name": "Live Tail Devbox Logs.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/:id/logs/tail", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "execution_id", "value": "", "type": "query", "description": "ID of execution to filter logs by." }, { "name": "shell_name", "value": "", "type": "query", "description": "Shell Name to filter logs by." } ] }, "docs": "Tail the logs for the given devbox. This will return past log entries and continue streaming from there. The stream will then continue to stream logs until the connection is closed." }, { "info": { "name": "Read text file contents from Devbox filesystem.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/read_file_contents", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Read file contents from a file on a Devbox as a UTF-8. Note 'downloadFile' should be used for large files (greater than 100MB). Returns the file contents as a UTF-8 string." }, { "info": { "name": "Remove a tunnel from the Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/remove_tunnel", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Remove an existing V2 tunnel from the Devbox." }, { "info": { "name": "Resume a suspended Devbox", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/resume", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Resume a suspended Devbox with the disk state captured as suspend time. Note that any previously running processes or daemons will need to be restarted using the Devbox shell tools." }, { "info": { "name": "Shutdown a running Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/shutdown", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." }, { "name": "force", "value": "", "type": "query", "description": "If true, force shutdown even if snapshots are in progress. Defaults to false." } ] }, "docs": "Shutdown a running Devbox. This will permanently stop the Devbox. If you want to save the state of the Devbox, you should take a snapshot before shutting down or should suspend the Devbox instead of shutting down. If the Devbox has any in-progress snapshots, the shutdown will be rejected with a 409 Conflict unless force=true is specified." }, { "info": { "name": "Synchronously create a disk snapshot of a running Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/snapshot_disk", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Create a disk snapshot of a devbox with the specified name and metadata to enable launching future Devboxes with the same disk state." }, { "info": { "name": "Start an asynchronous disk snapshot of a running Devbox.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/snapshot_disk_async", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Start an asynchronous disk snapshot of a devbox with the specified name and metadata. The snapshot operation will continue in the background and can be monitored using the query endpoint." }, { "info": { "name": "Suspend a running Devbox", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/suspend", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Suspend a running Devbox and create a disk snapshot to enable resuming the Devbox later with the same disk. Note this will not snapshot memory state such as running processes." }, { "info": { "name": "Upload binary file contents to Devbox filesystem.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/upload_file", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Upload file contents of any type (binary, text, etc) to a Devbox. Note this API is suitable for large files (larger than 100MB) and efficiently uploads files via multipart form data." }, { "info": { "name": "Get resource usage for a Devbox.", "type": "http" }, "http": { "method": "GET", "url": "https://api.runloop.ai/v1/devboxes/:id/usage", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ] }, "docs": "Get resource usage metrics for a specific Devbox. Returns CPU, memory, and disk consumption calculated from the Devbox's lifecycle, excluding any suspended periods for CPU and memory. Disk usage includes the full elapsed time since storage is consumed even when suspended." }, { "info": { "name": "Wait for a Devbox to reach one of the specified statuses.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/wait_for_status", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Polls the Devbox's status until it reaches one of the desired statuses or times out." }, { "info": { "name": "Write text file contents to Devbox filesystem.", "type": "http" }, "http": { "method": "POST", "url": "https://api.runloop.ai/v1/devboxes/:id/write_file_contents", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Devbox ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Write UTF-8 string contents to a file at path on the Devbox. Note for large files (larger than 100MB), the upload_file endpoint must be used." } ] } ], "bundled": true }