API conventions
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
| Interface | URL |
|---|---|
| REST API | https:// |
| CDP connection to a session | wss:// |
| MCP server | https:// |
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
| Request | Content type |
|---|---|
| A request with a JSON body | application/ |
| A file, extension or profile upload | multipart/ |
| Response | Content type |
|---|---|
| Most responses, and every error | application/ |
| A file download | application/ |
| A session's files as one archive, and an extension download | application/ |
| The HLS playlist of a recording | application/ |
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:
| Endpoint | Request parameters | How to get the next page |
|---|---|---|
GET / | cursorId, and limit (default 50, at most 100) | Pass nextCursor of the response as cursorId. nextCursor is null on the last page. |
GET /, GET / and GET / | offset (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 / | pointer, 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);
}for session in client.sessions.list(status="live"):
print(session.id)iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
Status: steel.F(steel.SessionListParamsStatusLive),
})
for iter.Next() {
session := iter.Current()
fmt.Println(session.ID)
}
if err := iter.Err(); err != nil {
return err
}let sessions = client
.sessions()
.list_auto_paging(steel_rs::SessionListParams {
status: Some(steel_rs::SessionListParamsStatus::Live),
..Default::default()
});
let mut sessions = std::pin::pin!(sessions);
while let Some(session) = futures_util::StreamExt::next(&mut sessions).await {
let session = session?;
println!("{}", 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:
| Code | Cause |
|---|---|
concurrency_limit_reached | Your organization runs as many sessions as its plan allows. |
rate_limited | You 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:
| Endpoint | TypeScript | Python | Go | Rust |
|---|---|---|---|---|
POST / | client. | client. | client. | client. |
GET / | client. | client. | client. | client. |
GET / | client. | client. | client. | client. |
POST / | client. | client. | client. | client. |
GET / | client. | client. | client. | client. |
POST / | client. | client. | client. | client. |
- 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 asdownload("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
useProxyisuse_proxy. The body fieldtimeoutofPOST /v1/sessionsisapi_timeout, becausetimeoutis 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.SessionNewParamsorsteel_rs::SessionCreateParams.useProxyisUseProxyin Go anduse_proxyin 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.