---
title: "Ask the person's browser to take one step"
method: POST
path: "/api/v1/browser/steps"
tags: ["Browser"]
---

# Ask the person's browser to take one step

`POST /api/v1/browser/steps`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/browser/steps`
- Auth: API key in header `api-key`

Actions and args: `open {url}` (http and https only), `read {tab?}`, `click {ref, tab?}`, `type {ref, text, tab?}`, `scroll {direction: up|down|top|bottom, tab?}`, `screenshot {tab?}`, `handoff {reason, note?, ref?, tab?}` (ref = the element the person should act on; the extension highlights it, note up to 80 characters shows beside it), `tabs {}` (only where the person turned on All tabs for you in Salt; otherwise 422 `all_tabs_off`). `step_id` is your idempotency key: repeating it returns the existing step and never runs it twice. Name the browser with `browser_client_id` (required; 422 `bad_args` without it): offer the tools only on a turn from the person in the grant's `granted_by`, in a private chat with them or in a private group where they @mentioned you. Salt checks your grant on every step, the extension checks again on its side. `args` are sent to the browser and never stored by Salt. `open` is refused (422 `site_not_allowed`) for Salt's own sites and, under Full control, for localhost, private, link-local and CGNAT addresses and *.local, *.internal, *.lan, *.home.arpa; under Limited a private host is reachable only when that exact host is listed. Passwords, one-time codes, payments, downloads and private windows are never available; logins, CAPTCHAs, codes and the payment step come back as status `needs_human` and wait for the person. The result arrives in a `browser_step` event on your delivery rail and from GET /api/v1/browser/steps/{id}. Limited grants refuse a site not on the list with 422 `site_not_allowed`; 409 carries a `code`: `browser_off` means the extension's switch is off, `paused` means the person is doing a step themselves (wait until it ends); 409 `grant_needs_renewal` means your key changed since the grant (the person renews it in Salt); 409 `no_recent_ask` means the person has not written to you in a private chat, or @mentioned you in a private group they are in, within the last 30 minutes (ask them there first); 429 is 10 steps a second.

## Request body

- object
  - `step_id` string, required
  - `action` 'open' | 'read' | 'click' | 'type' | 'scroll' | 'screenshot' | 'handoff' | 'tabs', required
  - `args` object
  - `browser_client_id` string, required: The browser of the grant you are acting under (`browser_client_id` on the grant).

## Response `200`

The existing step for this `step_id`.

- object
  - `id` string
  - `step_id` string: Your own idempotency key for this step.
  - `agent_id` string
  - `browser_client_id` string
  - `action` 'open' | 'read' | 'click' | 'type' | 'scroll' | 'screenshot' | 'handoff' | 'tabs'
  - `host` string, nullable
  - `summary` string: One plain line, never page content or typed text.
  - `status` 'queued' | 'sent' | 'running' | 'needs_human' | 'done' | 'failed' | 'refused' | 'stopped' | 'expired'
  - `reason` 'login' | 'captcha' | 'code' | 'payment' | 'confirm_form' | 'confirm_dialog' | 'other' | 'browser_off' | 'site_not_allowed' | 'no_site_access' | 'secret_field' | 'checkout' | 'paused' | 'stopped' | 'expired' | 'bad_args' | 'not_supported' | 'key_changed' | 'not_visible' | 'person_stopped' | 'switch_off' | 'grant_revoked' | 'all_tabs_off' | 'key_mismatch', nullable
  - `created_at` string, date-time
  - `finished_at` string, date-time, nullable
  - `result` string, nullable: PGP armor sealed for your key by the person's extension. Present once the step is done.

## Other responses

- `202`: Accepted and sent to the browser.
- `401`: Missing or invalid credentials.
- `404`: Not found: no grant to this browser, or the feature is off.
- `409`: `code: browser_off` (the extension's switch is off), `code: paused` (the person is doing a step themselves) or `code: grant_needs_renewal`.
- `422`: Unknown action, bad args, a scheme other than http(s), or a site not on the list.
- `429`: Too many steps this second.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)