Skip to content

Profiles API

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 →

A profile is a saved browser state that a new session can start from. These endpoints create, list, get and update profiles. For the base URL and authentication, see API conventions. For the error codes, see Errors.

The first example is a complete program. The later examples use its client, and the ID of a profile in PROFILE_ID (cURL), profileId (TypeScript), profile_id (Python and Rust) or profileID (Go).

Endpoints

List profiles

GET/v1/profiles

Lists the profiles of a project, the most recently updated first.

Parameters

NameTypeRequiredDescription
projectIdstring (uuid) · queryNoThe project whose profiles to list. Required with an organization key.

Response

FieldTypeDescription
profilesobject[]The profiles. Each one is a profile object, as in Create a profile.
countnumberThe total number of profiles.

See Profiles.

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

Create a profile

POST/v1/profiles

Creates a profile from a ZIP archive of a browser user data directory. The request is multipart/form-data.

Parameters

NameTypeRequiredDescription
userDataDirfile · bodyYesThe user data directory, as a ZIP archive.
userAgentstring · bodyNoThe user agent that sessions from the profile use.
dimensionsobject · bodyNoThe window width and height that sessions from the profile use, as JSON.
proxyUrlstring (uri) · bodyNoIgnored. Steel does not save proxyUrl in a profile, so pass it when you create each session.
useProxystring · bodyNoThe Steel proxy settings for sessions from the profile, as JSON. For a dedicated IP, send {"type":"fixed","id":"fixed:ID"}.
projectIdstring (uuid) · bodyNoThe project to create the profile in. Required with an organization key.

The response is 201 with the profile object:

Response

FieldTypeDescription
idstring (uuid)The ID of the profile.
statusstringUPLOADING, READY or FAILED.
projectIdstring (uuid) or nullThe project of the profile.
sourceSessionIdstring (uuid) or nullThe last session that saved the profile, or the session that is creating it. A session that only loads the profile does not change this field. null for a profile created from a ZIP archive, until a session saves it.
userAgentstring or nullThe user agent that sessions from the profile use.
dimensionsobject or nullThe window width and height that sessions from the profile use.
fingerprintobject or nullThe browser fingerprint that the profile keeps.
extensionIdsstring[] or nullThe IDs of the extensions that the profile keeps.
credentialsConfigobject or nullThe credentials settings that the profile keeps.
useProxyConfigobject or nullThe proxy settings that the profile keeps.
createdAtstring (date-time)When the profile was created.
updatedAtstring (date-time)When the profile last changed.

To create a profile from a session instead of an archive, create the session with persistProfile. See Profiles.

curl -X POST https://api.steel.dev/v1/profiles \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "userDataDir=@profile.zip" \
  -F 'dimensions={"width":1280,"height":800}'

Get a profile

GET/v1/profiles/{id}

Returns one profile.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the profile.
projectIdstring (uuid) · queryNoThe profile's project. Required with an organization key.

The response is the profile object, with the fields in Create a profile.

See Profiles.

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

Update a profile

PATCH/v1/profiles/{id}

Replaces a profile's user data directory, and changes its settings. The request is multipart/form-data.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the profile.
projectIdstring (uuid) · queryNoThe profile's project. Required with an organization key, in the query or in the body.
userDataDirfile · bodyYesThe new user data directory, as a ZIP archive.
userAgentstring · bodyNoThe user agent that sessions from the profile use.
dimensionsobject · bodyNoThe window width and height that sessions from the profile use, as JSON.
proxyUrlstring (uri) · bodyNoIgnored. Steel does not save proxyUrl in a profile, so pass it when you create each session.
useProxystring · bodyNoThe Steel proxy settings for sessions from the profile, as JSON. For a dedicated IP, send {"type":"fixed","id":"fixed:ID"}.
projectIdstring (uuid) · bodyNoThe profile's project, as in the query.

The response is the profile object, with the fields in Create a profile.

See Profiles.

curl -X PATCH https://api.steel.dev/v1/profiles/$PROFILE_ID \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "userDataDir=@profile.zip"