API Reference - Rusty Browser

Overview

The Rusty Browser API gives you full programmatic control over browsers. Create a browser, issue commands, inspect state, and close it when done, all over HTTP.

Base URL

For a local self-hosted server:

http://localhost:8080

Use the hostname and port for your own deployment in production examples.

Authentication

Open-source deployments do not require authentication by default. If your rusty-server config enables X-API-Key, include it with each request:

X-API-Key: your-local-key

Capacity

Concurrency and throughput depend on your server, Redis, Flux setup, browser agents, and the compute capacity you provide.

Endpoints

Sessions

Method	Endpoint	Description
`PUT`	`/browsers/`	Create a browser
`GET`	`/browsers/:id/`	Get browser info
`GET`	`/browsers/`	List active browsers
`DELETE`	`/browsers/:id/`	Close a browser
`DELETE`	`/browsers/`	Close all browsers

Commands

All commands operate on an existing browser via its id.

Method	Endpoint	Description
`POST`	`/browsers/:id/navigate/`	Navigate to a URL
`POST`	`/browsers/:id/click/`	Click at coordinates
`POST`	`/browsers/:id/node-click/`	Click by node reference
`POST`	`/browsers/:id/type/`	Type text into a field
`POST`	`/browsers/:id/scroll-by/`	Scroll by a relative amount
`POST`	`/browsers/:id/scroll-to/`	Scroll to an element or position
`POST`	`/browsers/:id/screenshot/`	Capture a screenshot
`POST`	`/browsers/:id/fetch-html/`	Fetch the current page HTML
`POST`	`/browsers/:id/fetch-text/`	Fetch the current page text
`POST`	`/browsers/:id/eval/`	Evaluate a JavaScript expression
`POST`	`/browsers/:id/instruct/`	Issue a natural language instruction

UI Map

Method	Endpoint	Description
`GET`	`/browsers/:id/ui-map/`	Fetch the current accessibility tree
`GET`	`/browsers/:id/ui-map-diff/`	Fetch accessibility tree changes since the previous snapshot

Contexts

Method	Endpoint	Description
`PUT`	`/browsers/:id/contexts/`	Create an isolated browser context
`DELETE`	`/browsers/:id/contexts/:ctx_id/`	Close a browser context

Lifecycle

Method	Endpoint	Description
`POST`	`/initialize/`	Initialize the server and agent registration
`DELETE`	`/teardown/`	Close browsers and terminate browser nodes

Response Format

Response shapes are documented on each endpoint page. Most command endpoints return a small JSON object with the result of the command, while session endpoints return browser or execution metadata.

Error Handling

Code	Description
`400`	Bad Request: missing or invalid parameters
`401`	Unauthorized: `X-API-Key` is enabled and the key is missing or invalid
`404`	Not Found: browser ID or resource does not exist
`500`	Internal Server Error

Error response format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}

​Overview

​Base URL

​Authentication

​Capacity

​Endpoints

​Sessions

​Commands

​UI Map

​Contexts

​Lifecycle

​Response Format

​Error Handling