> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aegi.run/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aegi.run/_mcp/server.

# Tools

## Screenshots

```
GET /v1/tools/screenshot?url={url}
```

Renders a webpage in a headless browser and queues the capture as a
[job](/jobs):

```ts
const shot = await aegis.tools.screenshot({ url: 'https://aegi.run' })

const { status, result } = await aegis.jobs.wait(shot.jobId, { timeout: 60 })
```

| Parameter  | Values              | Default   |
| ---------- | ------------------- | --------- |
| `url`      | Any http(s) URL     | required  |
| `device`   | `desktop`, `mobile` | `desktop` |
| `fullpage` | boolean             | `false`   |

The response confirms the request rather than the capture:

```json
{
  "success": true,
  "data": {
    "jobId": "3f8a1c8e-5b7d-2049-af31-c6e8d5b90742",
    "status": "pending",
    "url": "https://aegi.run"
  },
  "requestId": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
```

> **Warning**
>
> Screenshots are in the `puppeteer` rate class and are **not available on the
> `free` plan** — asking for one there answers `403` with
> `"puppeteer is not part of the free plan. Upgrade to use it."` See
> [rate limits](/rate-limits).

## Binary encoding

Converts UTF-8 text to a binary digit string and back.

```ts
const { text } = await aegis.tools.encode({ text: 'hello' })
// text: '0110100001101001...'  (0s and 1s, 8 bits per character)

const decoded = await aegis.tools.decode({ text })
// decoded.text: 'hello'
```

Decoding ignores whitespace and requires the input to be `0` and `1` only, in
groups of exactly 8.

### Checking the result

These two endpoints answer with a flag named `error` rather than `success`, and
a decode failure comes back inside the body:

```json
{ "error": true, "data": { "error": "Invalid binary sequence. Must be valid 8-bit groups." } }
```

Read `data.error` rather than relying on the status code alone — this is the one
area where a `200` does not mean success.

> **Note**
>
> The SDK's `aegis.binary` namespace is a deprecated alias for these two
> methods. Use `aegis.tools` instead.

> **Warning**
>
> Omitting `?text` entirely is a `422` validation error, not the `400` the
> handler would return for an empty value. See [errors](/errors).