> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rustybrowser.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Rusty Browser REST API

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}
```