---
title: HTTP API
description: Control a screen-relay session over HTTP.
url: "https://screen-relay.dev/docs/protocol"
docs_index: /llms.txt
lastUpdated: 2026-11-18
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Call screen-relay over HTTP from any language. For most tasks, use the [CLI](/docs/cli) or [Node SDK](/docs/sdk).

## Read the screen

Start a session, then run these commands on the VM or through an [SSH tunnel](/docs/remote-access#ssh-tunnel):

```sh
curl -fsS http://127.0.0.1:8080/capabilities
curl -fsS http://127.0.0.1:8080/screenshot.png -o screen.png
```

These commands assume the default address and a session bound to `127.0.0.1` without `--public`. That session has no token.

For a session with a token:

1. Run `screen-relay status --json` on the VM to find its `tokenFile` path. Add `--name NAME` for a named session.
2. Replace `/path/to/token` with that path, and add `-H "Authorization: Bearer $(cat /path/to/token)"` to each request.
3. Use the HTTPS origin if the session uses TLS.

## Send input

<span id="text-events" />

<span id="input-events" />

<span id="input-records" />

Close a control session, or a viewer that owns input, before sending HTTP input. A view-only viewer does not block input. Then send input from any machine with the [CLI](/docs/cli), passing `--url` and `--token-file`, or with the [Node SDK](/docs/sdk).

```sh
screen-relay click 0.5 0.5 --url https://desktop.example.com --token-file ./token
```

Replace the URL and securely copy the session token into `./token`. For a local session, omit `--url` and `--token-file`. Text input uses the desktop's keyboard layout and can type characters absent from it.

`POST /input` takes binary records. To write your own client, see the [wire protocol](https://github.com/vercel-labs/screen-relay/blob/main/PROTOCOL.md).

## Endpoints

| Method    | Path                                          | What it does                                                                                                              |
| --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `GET`     | <span id="get-capabilities" />`/capabilities` | Returns the desktop size, backend, features, and input limits as JSON.                                                    |
| `GET`     | `/screenshot.png`                             | Returns a PNG without the cursor, even when another client owns input; maximum 8 MiB and a 5-second timeout.              |
| `POST`    | <span id="post-input" />`/input`              | Sends a batch of binary input records.                                                                                    |
| `GET`     | <span id="get-metrics" />`/metrics`           | Returns stream and resource metrics as JSON.                                                                              |
| `GET`     | `/`, `/index.html`, `/viewer.js`              | Serves the viewer.                                                                                                        |
| WebSocket | `/stream`                                     | Streams video, sends cursor images when supported, and accepts viewer input. Add `?view=1` to watch without owning input. |
| WebSocket | `/control`                                    | Sends input and receives a response for each event, without video.                                                        |

The viewer HTML is served with `Content-Security-Policy: frame-ancestors 'none'` and `X-Frame-Options: DENY`, so another site cannot embed it and forward clicks to the desktop.

## Authentication

- When the session has a token, send `Authorization: Bearer TOKEN`. Do not put the token in a request URL. See [Tokens](/docs/remote-access#tokens).
- The `Host` must be `localhost`, `127.0.0.1`, or the authority configured with `--public`, with its port if specified.
- `Origin` is optional. When the session has a token, any `Origin` is accepted. Without a token, a sent `Origin` must be a loopback origin with a loopback `Host`.

## Errors

<span id="limits" />

| Status                       | What to do                                                                                                                                     |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 `invalid_input`          | Send a nonempty batch of valid records with the correct `Content-Length`.                                                                      |
| 401 `unauthorized`           | Send the correct session token.                                                                                                                |
| 403 `forbidden`              | Check the `Host` and `Origin` rules.                                                                                                           |
| 404 `not_found`              | Check the endpoint path.                                                                                                                       |
| 405 `method_not_allowed`     | Use the method listed for the endpoint.                                                                                                        |
| 409 `busy`                   | Close the input owner or wait, then check for partial input before retrying. A viewer that owns input is one owner; a view-only viewer is not. |
| 411 `length_required`        | Include `Content-Length` on `POST /input`.                                                                                                     |
| 413 `too_large`              | Send no more than 256 input records per request.                                                                                               |
| 422 `unsupported_input`      | Change the input or keyboard layout.                                                                                                           |
| 503 `busy`                   | Wait for the other screenshot to finish.                                                                                                       |
| 503 `screenshot_unavailable` | Check `screen-relay logs engine` and try again.                                                                                                |

Errors are JSON with an `error` field.

- A rejected input record returns its zero-based `index`. The records before it were applied, and that record and the ones after it were not.
- A `busy` input reply returns an `applied` count. Text-only input can resume from it. For other input it is not a retry offset, because the engine drops queued text, pointer moves, and scrolls but still applies key and button events. Check the desktop before retrying.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)