Skip to content

TypeScript SDK

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 →

The Steel SDK for TypeScript and JavaScript is the steel-sdk package on npm. It gives your code typed methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The API reference shows the call for each endpoint.

Install

npm install steel-sdk

The SDK supports TypeScript 4.5 or later and these runtimes:

  • Node.js 18 LTS or later
  • Deno 1.28.0 or later
  • Bun 1.0 or later
  • Cloudflare Workers and the Vercel Edge Runtime
  • Up-to-date web browsers

React Native is not supported. In a web browser, do not give the SDK your API key, because anyone who opens the page can read it. See Authentication.

Create a client

new Steel() reads your API key from the STEEL_API_KEY environment variable. To change the key or another setting, pass options to the constructor.

import Steel from "steel-sdk";

const client = new Steel();
OptionDefaultMeaning
steelAPIKeyprocess.env.STEEL_API_KEYThe API key. The SDK sends it in the steel-api-key header.
baseURLprocess.env.STEEL_BASE_URL, then https://api.steel.devThe URL of the API. Change it to use a self-hosted Steel Browser.
timeout60000How long one HTTP request can take, in milliseconds.
maxRetries2How many times the SDK retries a request that failed.
defaultHeadersnoneHeaders to send with every request.
defaultQuerynoneQuery parameters to send with every request.
fetchnode-fetch in Node.js, the global fetch elsewhereA custom fetch function, for example to log each request.
httpAgentan agent that reuses connectionsThe HTTP agent for all requests, for example to send them through a proxy.

The STEEL_CUSTOM_HEADERS environment variable adds headers to every request. Write one Name: value pair on each line.

Create a session

This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it in finally.

session.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create();

try {
  console.log(session.id);
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx session.mts

The program prints the session's ID.

de987dce-13d0-4e2b-b70c-6d2fa9a189d0

To drive the session's browser, connect Playwright or Puppeteer over CDP (Chrome DevTools Protocol). See Playwright and Puppeteer.

A method's options are camelCase, such as useProxy and blockAds. In sessions.create, timeout is the session timeout. Session configuration lists every option of a new session.

Retries and timeouts

The SDK retries a request twice, with a short exponential backoff, after one of these failures:

  • a connection error
  • 408 Request Timeout
  • 409 Conflict
  • 429 Too Many Requests
  • a status of 500 or higher

When the response has the x-should-retry header, the SDK follows the header instead of this list. true retries and false does not. When the response has a Retry-After header, the SDK waits that long before it retries.

A request times out after one minute and then throws APIConnectionTimeoutError. The SDK retries a request that timed out, so a call can take longer than its timeout.

Set maxRetries and timeout on the client for all requests:

const client = new Steel({
  maxRetries: 0,
  timeout: 20 * 1000,
});

To change them for one call, pass them in the method's last argument. This argument holds the request options, not the API's parameters:

await client.sessions.retrieve(session.id, {
  maxRetries: 5,
  timeout: 5 * 1000,
});

Handle errors

When the SDK cannot reach the API, or when the API returns a 4xx or 5xx status, the call throws a subclass of Steel.APIError. The error has status, headers and error, which is the response's JSON body.

try {
  await client.sessions.retrieve(sessionId);
} catch (err) {
  if (err instanceof Steel.APIError) {
    console.log(err.status);
    console.log(err.name);
    console.log(err.error);
  } else {
    throw err;
  }
}
StatusError class
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
409ConflictError
422UnprocessableEntityError
429RateLimitError
500 or higherInternalServerError
No responseAPIConnectionError

Errors lists the error codes and messages of the API.

Pagination

client.sessions.list returns its results in pages. Iterate with for await to read every item. The SDK fetches the next page when it needs it.

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

To read one page at a time, use hasNextPage() and getNextPage():

let page = await client.sessions.list({ status: "live" });
while (true) {
  for (const session of page.sessions) {
    console.log(session.id);
  }
  if (!page.hasNextPage()) {
    break;
  }
  page = await page.getNextPage();
}

Methods

Each group of methods matches a page of the API reference. The methods take the same parameters as the endpoints, in camelCase.

MethodsAPI reference
client.sessions, client.sessions.files, client.sessions.captchasSessions API
client.scrape, client.screenshot, client.pdfQuick actions API
client.profilesProfiles API
client.credentialsCredentials API
client.filesFiles API
client.extensionsExtensions API
client.projectsProjects API
client.apiKeysAPI keys API

The SDK's own list of methods and types is api.md. Your editor also shows the type of each parameter and field, because the package includes TypeScript definitions.