Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/docs/cookbook/topics/mcp.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: MCP
description: 1 recipe tagged MCP.
description: Recipes that build your own MCP server on Steel. For the hosted Steel MCP server, connect a client to mcp.steel.dev instead.
---

<RecipeGrid>
Expand Down
10 changes: 5 additions & 5 deletions content/docs/overview/agent-traces/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ Use the Agent Traces API when you want the same activity timeline shown in the d

Returns the trace timeline for a finished or in-progress session.

```bash !! curl -wcn
```bash curl -wcn
curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \
-H "steel-api-key: $STEEL_API_KEY"
```

```javascript !! fetch -wcn
```javascript fetch -wcn
const response = await fetch(
`https://api.steel.dev/v1/sessions/${sessionId}/agent-traces`,
{ headers: { "steel-api-key": process.env.STEEL_API_KEY } },
Expand All @@ -28,7 +28,7 @@ const trace = await response.json();

### Response

```json !! JSON -wcn
```json JSON -wcn
{
"events": [
{
Expand Down Expand Up @@ -70,7 +70,7 @@ Activity-specific details appear when relevant. For example, click activities ca

When Steel can identify the element involved in an activity, `target` can include readable labels and useful selectors:

```json !! target -wcn
```json target -wcn
{
"role": "button",
"accessibleName": "Sign in",
Expand All @@ -91,7 +91,7 @@ Use target details as hints for review or replay. Some activities, such as navig

You can limit results to a time range:

```bash !! curl -wcn
```bash curl -wcn
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces?startTime=2026-05-22T18:00:00.000Z&endTime=2026-05-22T18:10:00.000Z" \
-H "steel-api-key: $STEEL_API_KEY"
```
Expand Down
4 changes: 2 additions & 2 deletions content/docs/overview/agent-traces/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ Agent Traces are based on what happened in the browser session, not on what the

Fetch the trace timeline for a session as JSON:

```bash !! curl -wcn
```bash curl -wcn
curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \
-H "steel-api-key: $STEEL_API_KEY"
```

```json !! Response -wcn
```json Response -wcn
{
"events": [
{
Expand Down
2 changes: 1 addition & 1 deletion content/docs/overview/agent-traces/timeline.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ The format includes:

A trimmed example:

```markdown !! agent-traces.md -wcn
```markdown -wcn agent-traces.md
# Browser session

Recording of a real browser session, structured for review and replay by an automation agent.
Expand Down
9 changes: 9 additions & 0 deletions content/docs/overview/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,15 @@ steel login

This walks you through signing in and stores a key locally. Alternatively, set `STEEL_API_KEY` in your environment and the CLI will use it directly: useful for CI and non-interactive environments.

#### MCP Server

The [Steel MCP server](/overview/mcp) can sign you in with OAuth, so a client can connect without a key. To use a key instead, send it as a bearer token:

```bash Terminal -wcn
claude mcp add --transport http steel https://mcp.steel.dev/mcp \
--header "Authorization: Bearer $STEEL_API_KEY"
```

### Managing Your API Keys

All key management happens in the [API Keys dashboard](https://app.steel.dev/settings/api-keys). From there you can:
Expand Down
4 changes: 2 additions & 2 deletions content/docs/overview/browser-tools/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ The supported formats map to fields on `content`:

`metadata` carries the usual SEO fields (`title`, `description`, `canonical`, Open Graph tags, JSON-LD, `statusCode`, etc.) and `links` is a flat array of every anchor on the page.

```json !! JSON -wcn
```json JSON -wcn
{
"content": {
"markdown": "# Steel Docs\n\n..."
Expand Down Expand Up @@ -142,7 +142,7 @@ print(result.url)

The hosted URL is public and durable. Download it like any other PNG:

```typescript !! Typescript -wcn
```typescript Typescript -wcn
import fs from "node:fs";

const response = await fetch(result.url);
Expand Down
33 changes: 17 additions & 16 deletions content/docs/overview/commands-api/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ type: info
The Commands API is in beta. Commands, fields, and limits may change. Share feedback on [Discord](https://discord.gg/steel-dev).
:::

```bash !! curl -wcn
```bash curl -wcn
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
Expand All @@ -28,7 +28,7 @@ curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \

The response has one result per command. The snapshot lists the elements on the page, each with a ref.

```json !! Response -wcn
```json Response -wcn
{
"next": "op_4f8k2m9q1x",
"epoch": 1,
Expand All @@ -43,7 +43,7 @@ The response has one result per command. The snapshot lists the elements on the

Send a ref back to act on its element. Pass `next` as `after`, so Steel knows which page state you saw.

```json !! Request -wcn
```json Request -wcn
{ "after": "op_4f8k2m9q1x", "commands": [{ "command": "click", "target": "e1" }] }
```

Expand All @@ -52,6 +52,7 @@ Send a ref back to act on its element. Pass `next` as `after`, so Steel knows wh
| Approach | Use it for |
| --- | --- |
| Commands API | Agents that read the page and act step by step. Plain HTTP, no browser library. |
| [MCP Server](/overview/mcp) | Agents in an MCP client, such as Claude or Cursor. The same commands as tools, with nothing to host. |
| [Playwright](/cookbook/playwright) or [Puppeteer](/cookbook/puppeteer) | Scripts that need full CDP control, such as network interception. |
| [Browser Tools](/overview/browser-tools/overview) | One-shot scrapes, screenshots, and PDFs without a session. |

Expand Down Expand Up @@ -154,7 +155,7 @@ The click uses a locator, so the example does not depend on a ref number. An age

A snapshot is the page's accessibility tree as text. Each line has the role, the name, the states, and a ref. A value follows the colon.

```text !! Snapshot -wcn
```text Snapshot -wcn
- heading "Account" [level=1, ref=e1]
- textbox "Name" [ref=e2]: Ada
- checkbox "Remember me" [checked=false, ref=e3]
Expand All @@ -174,7 +175,7 @@ A ref points at one element and stays the same across snapshots of the same page

Commands that act on an element take a `target`. It can be a ref, a CSS selector, or a locator object.

```json !! Request -wcn
```json Request -wcn
{
"commands": [
{ "command": "fill", "target": "e2", "value": "Ada Lovelace" },
Expand All @@ -200,7 +201,7 @@ A locator sets exactly one of these fields:

Text matches a case-insensitive substring unless you set `exact: true`. When a locator finds several elements, it uses the only visible one or fails with `ambiguous`, so set `nth` to pick one. For an element inside an iframe, add `frame`:

```json !! Request -wcn
```json Request -wcn
{
"commands": [
{
Expand All @@ -217,7 +218,7 @@ Text matches a case-insensitive substring unless you set `exact: true`. When a l

`commands` takes up to 50 commands. They run in order and stop at the first failure. Commands that already ran are not undone. Add `observe` to see the page after the commands.

```json !! Request -wcn
```json Request -wcn
{
"commands": [
{ "command": "fill", "target": "e2", "value": "ada@example.com" },
Expand All @@ -235,7 +236,7 @@ Text matches a case-insensitive substring unless you set `exact: true`. When a l

A failed command still returns `200`. Its error is in `results`, and the execution state is `failed`. Here a cookie banner covers the button:

```json !! Response -wcn
```json Response -wcn
{
"execution": { "id": "x-4", "state": "failed", "effect": "none", "replayed": false, "ran": 1 },
"results": [
Expand All @@ -256,7 +257,7 @@ A failed command still returns `200`. Its error is in `results`, and the executi

Every response has a `next` value. Send it as `after` in your next request. A retried request with the same `after` and commands then runs only once. If another Commands API client changed the session in between, the response sets `epochChanged: true`.

```typescript !! Typescript -wcn
```typescript Typescript -wcn
let after: string | undefined;

async function step(commands: object[]) {
Expand All @@ -273,7 +274,7 @@ async function step(commands: object[]) {

Send a random `Idempotency-Key` header with each request, and reuse it when you retry that request. A retry with the same key returns the stored result with `replayed: true` instead of running the commands again.

```bash !! curl -wcn
```bash curl -wcn
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
Expand All @@ -294,7 +295,7 @@ Steel keeps results for at least an hour. Large parts, such as snapshot text and

Executions run one at a time per session. The response waits up to 20 seconds. If the execution is still going, the response shows `state: "running"`. Wait for it with `status`, or stop it with `cancel`.

```json !! Request -wcn
```json Request -wcn
{ "commands": [{ "command": "status", "execution": "x-1" }] }
```

Expand All @@ -304,29 +305,29 @@ Executions run one at a time per session. The response waits up to 20 seconds. I

Steel never answers a dialog on its own. An open dialog shows up in `dialog`, and commands on its tab fail with `dialog_pending` until you answer it.

```json !! Response -wcn
```json Response -wcn
{
"dialog": { "id": "d-1", "tab": "t1", "type": "confirm", "message": "Delete this item?" }
}
```

Answer it with the `dialog` command. Pass `text` to answer a prompt.

```json !! Request -wcn
```json Request -wcn
{ "commands": [{ "command": "dialog", "dialog": "d-1", "action": "accept" }] }
```

### Files

`upload` takes files from the session's files, so upload them first with the [Files API](/overview/files-api/overview). Then pass their names.

```json !! Request -wcn
```json Request -wcn
{ "commands": [{ "command": "upload", "target": { "label": "Resume" }, "files": "resume.pdf" }] }
```

`wait` with `download: true` waits for the next download to finish. Its result has the file name and size.

```json !! Request -wcn
```json Request -wcn
{
"commands": [
{ "command": "click", "target": { "role": "button", "name": "Export CSV" } },
Expand All @@ -337,7 +338,7 @@ Answer it with the `dialog` command. Pass `text` to answer a prompt.

Then download the file from the session's files:

```bash !! curl -wcn
```bash curl -wcn
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
-H "steel-api-key: $STEEL_API_KEY" \
-o report.csv
Expand Down
8 changes: 4 additions & 4 deletions content/docs/overview/commands-api/reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ publishedAt: "2026-11-04"

`POST /v1/sessions/{sessionId}/commands` runs commands in a live session. The full schema is also in the [API reference](/api-reference).

```bash !! curl -wcn
```bash curl -wcn
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
Expand All @@ -35,7 +35,7 @@ Fields that are not listed, or that a command does not take, fail with `400 inva

### Response

```json !! Response -wcn
```json Response -wcn
{
"next": "op_4f8k2m9q1x",
"epoch": 3,
Expand Down Expand Up @@ -122,7 +122,7 @@ Input commands that start a navigation wait up to 15 seconds for the new page's

`wait` takes one of the conditions below, and an optional `timeout` in milliseconds. The default timeout is 10 seconds and the most is 50 seconds.

```json !! Request -wcn
```json Request -wcn
{ "commands": [{ "command": "wait", "target": { "text": "Order placed" }, "timeout": 20000 }] }
```

Expand Down Expand Up @@ -156,7 +156,7 @@ Input commands that start a navigation wait up to 15 seconds for the new page's

Element commands take `target`: a ref such as `e12`, a CSS selector, or a locator object. A locator sets exactly one of `role`, `text`, `label`, `placeholder`, `alt`, `title`, `testid`, or `css`.

```json !! Request -wcn
```json Request -wcn
{
"commands": [
{
Expand Down
4 changes: 4 additions & 0 deletions content/docs/overview/intro-to-steel.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,10 @@ Under the hood, Steel’s cloud-native platform handles all the headaches of bro
- [Connect with Playwright](/cookbook/playwright)
- [Connect with Selenium](/cookbook/selenium)

### Use Steel from an AI client

- [Steel MCP Server](/overview/mcp)

### Reference

- [API Reference](/api-reference)
Expand Down
Loading
Loading