Skip to content

API conventions

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

Every request to the Steel API follows the same rules for the base URL, authentication, content types, errors, pagination, idempotency and rate limits. Each endpoint's page, such as Sessions API, has its parameters and response.

Base URL

InterfaceURL
REST APIhttps://api.steel.dev
CDP connection to a sessionwss://connect.steel.dev
MCP serverhttps://mcp.steel.dev/mcp

The version of the API is in the path. Every endpoint is under /v1, such as https://api.steel.dev/v1/sessions.

The SDKs use https://api.steel.dev by default. To send their requests to another server, such as a self-hosted Steel Browser, set the STEEL_BASE_URL environment variable, or the client option baseURL in TypeScript, base_url in Python and Rust, and option.WithBaseURL in Go.

OpenAPI spec

Steel's API is also published as an OpenAPI 3.0 spec. Load it into an API client such as Postman, or use it to generate a client in a language that has no Steel SDK.

Authentication

Send your API key in the steel-api-key header of every request:

curl https://api.steel.dev/v1/sessions \
  -H "steel-api-key: $STEEL_API_KEY"

The SDKs, the Steel CLI and the MCP server take the key in other places, as Send the key shows.

The REST API also accepts the key as Authorization: Bearer KEY, for compatibility. The response then has an X-Steel-Warning header that asks you to use steel-api-key.

A project key reaches one project, and an organization key reaches every project of your organization. With an organization key, a request that creates a session, runs a Quick action, or works with profiles or credentials must name its project in projectId. Choose a scope compares the two.

Keep your key on your server, and do not put it in code that runs in a browser or in an app. A request with no key fails with missing_api_key, and a request with a wrong key fails with invalid_api_key. To create and revoke keys, see API keys.

Content types

RequestContent type
A request with a JSON bodyapplication/json
A file, extension or profile uploadmultipart/form-data
ResponseContent type
Most responses, and every errorapplication/json
A file downloadapplication/octet-stream
A session's files as one archive, and an extension downloadapplication/zip
The HLS playlist of a recordingapplication/vnd.apple.mpegurl

Errors

A failed request returns a 4xx or 5xx status and a JSON body with a message and, for most errors, a code and retryable. Errors describes the body and the x-should-retry header, and lists every code with its fix.

Pagination

These endpoints return their items in pages:

EndpointRequest parametersHow to get the next page
GET /v1/sessionscursorId, and limit (default 50, at most 100)Pass nextCursor of the response as cursorId. nextCursor is null on the last page.
GET /v1/sessions/{id}/logs, GET /v1/sessions/{id}/agent-logs and GET /v1/sessions/{id}/agent-tracesoffset (default 0), and limit (at most 1000; default 100 for logs and agent logs)Add the number of items to offset. hasMore is false on the last page, and total is the number of items.
GET /v1/sessions/{id}/eventspointer, and limit (default 1000, at most 1000)Pass the value of the Next-Cursor response header as pointer. The last page has no Next-Cursor header.

The other list endpoints return every item in one response.

The SDKs fetch the next pages of the session list for you:

for await (const session of client.sessions.list({ status: "live" })) {
  console.log(session.id);
}

In Go and Rust, the method that does this is ListAutoPaging or list_auto_paging. In Rust, this code needs cargo add futures-util.

Idempotency

Only POST /v1/sessions/{sessionId}/commands reads an Idempotency-Key header. A request that you send again with the same key returns the stored result and does not run the commands a second time. The Commands reference has the rules.

From version 0.23.0, the SDKs send an Idempotency-Key header with every request that is not a GET, and keep the same key when they retry. A key that you pass with a request replaces the SDK's key. The other endpoints ignore the key, so a retried request that creates a session can start a second session.

To find out whether a request that creates a session started one, put your own job ID in the session's metadata. Before you send the request again, list the sessions with that metadata. If the first request started a session, use it, or release it. For other requests, check whether the first one succeeded before you send it again.

Rate limits and retries

Your plan limits how many sessions run at the same time and how many sessions you can create in a minute. Scrape, Screenshot and PDF have their own limit. Limits has the numbers for each plan.

A request over a limit fails with status 429 and one of these codes:

CodeCause
concurrency_limit_reachedYour organization runs as many sessions as its plan allows.
rate_limitedYou created too many sessions in a minute, or sent too many Quick action requests.

A rate_limited response has retryAfterSeconds in the body and a retry-after header. Wait that many seconds before you send the request again.

The response of POST /v1/sessions also has headers that show how many sessions you run and how many you can still start. Know your limits lists them.

The SDKs retry some failed requests automatically, and they follow x-should-retry. Each SDK's page has the details.

SDKs

Each endpoint has one method in the SDKs, except Get agent logs, which has none. The reference shows the method on each endpoint's page, except for the Commands endpoints, which it shows in cURL only. The method is on the endpoint's resource, such as client.sessions for /v1/sessions. Its name depends on the SDK and the resource, so check the endpoint's page for it. To create, Go uses New, and the other SDKs use create. To get one item, Go uses Get, and the other SDKs use retrieve for a session and get for a profile. Some examples:

EndpointTypeScriptPythonGoRust
POST /v1/sessionsclient.sessions.create()client.sessions.create()client.Sessions.New(ctx, params)client.sessions().create(params)
GET /v1/sessions/{id}client.sessions.retrieve(id)client.sessions.retrieve(id)client.Sessions.Get(ctx, id)client.sessions().retrieve(&id)
GET /v1/profiles/{id}client.profiles.get(id)client.profiles.get(id)client.Profiles.Get(ctx, id, params)client.profiles().get(&id, params)
POST /v1/sessions/{id}/releaseclient.sessions.release(id)client.sessions.release(id)client.Sessions.Release(ctx, id)client.sessions().release(&id)
GET /v1/sessions/signals/catalogclient.sessions.signalCatalog()client.sessions.signal_catalog()client.Sessions.SignalCatalog(ctx)client.sessions().signal_catalog()
POST /v1/scrapeclient.scrape()client.scrape()client.Scrape(ctx, params)client.scrape(params)
  • Path parameters are the first arguments, in the order of the path. In Go, they come after ctx. In Python, the last path parameter comes first, and the others are keyword arguments, such as download("report.csv", session_id=session_id).
  • In TypeScript, the query and body fields are one object, with the names of the API.
  • In Python, the query and body fields are keyword arguments in snake_case, so useProxy is use_proxy. The body field timeout of POST /v1/sessions is api_timeout, because timeout is the timeout of the HTTP request in the Python SDK.
  • In Go and Rust, the query and body fields are the fields of one params struct, such as steel.SessionNewParams or steel_rs::SessionCreateParams. useProxy is UseProxy in Go and use_proxy in Rust.

The page of each endpoint shows its call in cURL, TypeScript, Python, Go and Rust. Get agent logs and the Commands endpoints show only cURL.