---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/api
markdown_url: https://steel.dev/docs/reference/api.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: API conventions
description: Learn the rules that every Steel API request follows, from the base URL and authentication to errors, pagination and rate limits.
summary: Learn the rules that every Steel API request follows, from the base URL and authentication to errors, pagination and rate limits.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/api/sessions.md
  - https://steel.dev/docs/reference/api/quick-actions.md
  - https://steel.dev/docs/reference/api/profiles.md
  - https://steel.dev/docs/reference/api/credentials.md
  - https://steel.dev/docs/reference/api/files.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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](https://steel.dev/docs/reference/api/sessions), has its parameters and response.

## Base URL

| Interface | URL |
| - | - |
| REST API | `https://api.steel.dev` |
| CDP connection to a session | `wss://connect.steel.dev` |
| MCP server | `https://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](https://steel.dev/docs/self-hosting/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](https://api.steel.dev/sdk-openapi.json). 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:

```sh
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](https://steel.dev/docs/account/api-keys#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](https://steel.dev/docs/account/api-keys#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`](https://steel.dev/docs/reference/errors#missing-api-key), and a request with a wrong key fails with [`invalid_api_key`](https://steel.dev/docs/reference/errors#invalid-api-key). To create and revoke keys, see [API keys](https://steel.dev/docs/account/api-keys).

## Content types

| Request | Content type |
| - | - |
| A request with a JSON body | `application/json` |
| A file, extension or profile upload | `multipart/form-data` |

| Response | Content type |
| - | - |
| Most responses, and every error | `application/json` |
| A file download | `application/octet-stream` |
| A session's files as one archive, and an extension download | `application/zip` |
| The HLS playlist of a recording | `application/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](https://steel.dev/docs/reference/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 /v1/sessions` | `cursorId`, 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-traces` | `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 /v1/sessions/{id}/events` | `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:

**TypeScript**

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

**Python**

```python
for session in client.sessions.list(status="live"):
    print(session.id)
```

**Go**

```go
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
}
```

**Rust**

```rust
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](https://steel.dev/docs/reference/commands#retries) 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](https://steel.dev/docs/sessions/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](https://steel.dev/docs/platform/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`](https://steel.dev/docs/reference/errors#concurrency-limit-reached) | Your organization runs as many sessions as its plan allows. |
| [`rate_limited`](https://steel.dev/docs/reference/errors#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](https://steel.dev/docs/production/run-sessions-at-scale#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](https://steel.dev/docs/reference/api/sessions#get-agent-logs), which has none. The reference shows the method on each endpoint's page, except for the [Commands](https://steel.dev/docs/reference/api/sessions#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 /v1/sessions` | `client.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}/release` | `client.sessions.release(id)` | `client.sessions.release(id)` | `client.Sessions.Release(ctx, id)` | `client.sessions().release(&id)` |
| `GET /v1/sessions/signals/catalog` | `client.sessions.signalCatalog()` | `client.sessions.signal_catalog()` | `client.Sessions.SignalCatalog(ctx)` | `client.sessions().signal_catalog()` |
| `POST /v1/scrape` | `client.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](https://steel.dev/docs/reference/api/sessions#get-agent-logs) and the [Commands](https://steel.dev/docs/reference/api/sessions#commands) endpoints show only cURL.
