Skip to content

Sessions 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 session is one cloud browser that Steel runs for you. These endpoints create, list, get and release sessions, and work with a session's logs, recordings, metadata, commands, files and more. For the base URL, authentication and pagination, 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 session in SESSION_ID (cURL), sessionId (TypeScript), session_id (Python and Rust) or sessionID (Go).

Sessions

List sessions

GET/v1/sessions

Lists the sessions of your organization, one page at a time.

Parameters

NameTypeRequiredDescription
cursorIdstring · queryNoThe cursor of the page to return. Pass nextCursor from the previous page.
limitinteger · queryNoNumber of sessions to return, from 1 to 100.Default 50.
statusstring · queryNoFilter by status: live, released or failed.
releaseReasonstring · queryNoFilter released sessions by why they ended: user_requested, timeout, inactivity_timeout, creation_timeout, startup_failed, browser_closed or browser_crashed. Live sessions are excluded. Without status, failed sessions that match are included.
projectIdstring (uuid) · queryNoFilter by project.
createdAfterstring (date-time) · queryNoOnly sessions created at or after this ISO 8601 time, such as 2026-10-01T00:00:00Z.
createdBeforestring (date-time) · queryNoOnly sessions created before this ISO 8601 time.
signalstring[] · queryNoSignals that the session must have. Repeat the parameter to require several; all must match. See Signals reference.
metadataobject · queryNoExact-match metadata filters, such as metadata[environment]=production. All entries must match. Numbers and booleans are stored as strings, so metadata[attempt]=3 matches 3 and "3".

Response

FieldTypeDescription
sessionsobject[]The sessions on this page. Each one is a session object, as in Create a session.
nextCursorstring or nullThe cursor of the next page. null when there are no more pages.
totalCountintegerThe number of live sessions. Present only for status=live with no metadata, signal, releaseReason, createdAfter or createdBefore filter.

The SDKs fetch the next page for you while you iterate. The method that does this is ListAutoPaging in Go and list_auto_paging in Rust. In Rust, the program also needs cargo add futures-util. See Create a session.

curl "https://api.steel.dev/v1/sessions?status=live&limit=10" \
  -H "steel-api-key: $STEEL_API_KEY"

Create a session

POST/v1/sessions

Starts a new session and returns it. With a project key, every field of the body is optional, and a request with no body creates a session with the defaults. With an organization key, the body must have projectId.

The body has these top-level fields. Session configuration explains each one, with its default, nested fields and limits.

Parameters

NameTypeRequired
blockAdsboolean · bodyNo
caCertificatesstring[] · bodyNo
concurrencyinteger · bodyNo
credentialsobject · bodyNo
debugConfigobject · bodyNo
deviceConfigobject · bodyNo
dimensionsobject · bodyNo
experimentalFeaturesstring[] · bodyNo
extensionIdsstring[] · bodyNo
fullscreenboolean · bodyNo
headlessboolean · bodyNo
inactivityTimeoutinteger · bodyNo
metadataobject · bodyNo
namespacestring · bodyNo
optimizeBandwidthboolean or object · bodyNo
persistProfileboolean · bodyNo
profileIdstring (uuid) · bodyNo
projectIdstring (uuid) · bodyNo
proxyUrlstring (uri) · bodyNo
recordingboolean · bodyNo
sessionContextobject · bodyNo
solveCaptchaboolean · bodyNo
stealthConfigobject · bodyNo
timeoutinteger · bodyNo
useProxyboolean or object · bodyNo
userAgentstring · bodyNo

The response is 201 with the session object. Its main fields:

Response

FieldTypeDescription
idstring (uuid)The ID of the session.
statusstringlive, released or failed.
websocketUrlstringThe CDP URL of the session's browser. Connect Playwright or Puppeteer to it as it is: it holds a token for this session, until the session ends. A session in the list of sessions has it without the token.
debugUrlstringThe URL of the live view, which you can open in a browser or embed in your app. See Live view.
sessionViewerUrlstringThe session's page in the Steel dashboard.
createdAtstring (date-time)When the session started.
durationintegerHow long the session ran, in milliseconds.
timeoutintegerThe session timeout, in milliseconds.
inactivityTimeoutintegerThe inactivity timeout, in milliseconds, if one was set.
dimensionsobjectThe width and height of the browser window, in pixels.
profileIdstring (uuid)The profile that the session started from, or that it saves to.
projectIdstring (uuid) or nullThe project that the session runs in.
metadataobjectYour metadata. Every value comes back as a string.
browserModestringstealth, standard or unknown.
proxySourcestring or nullsteel, external, or null with no proxy.
proxyBytesUsedintegerBytes sent and received through a proxy, whether a Steel proxy or your own.
creditsUsedintegerCredits that the session used.
eventCountintegerNumber of events recorded in the session.
signalsstring[]Signals observed in the session. Filled in a few seconds after the session ends.
releaseReasonstring or nullWhy the session ended, such as user_requested or timeout. null while it is live, and when Steel has no record of why it ended.

The object also holds the options that the session was created with, such as headless, solveCaptcha, stealthConfig, debugConfig, deviceConfig, optimizeBandwidth, persistProfile, fullscreen and userAgent.

Release the session when you are done with it. See Create a session.

curl -X POST https://api.steel.dev/v1/sessions \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blockAds": true}'

Get a session

GET/v1/sessions/{id}

Returns one session.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.

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

See Create a session.

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

Release a session

POST/v1/sessions/{id}/release

Ends one session.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.

Response

FieldTypeDescription
successbooleanWhether the session was released.
messagestringDetails about the result.

See Session lifecycle.

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

Release all sessions

POST/v1/sessions/release

Releases the live sessions of one project, or of your whole organization. With an organization key and no projectId, it releases every live session in all of your organization's projects. With a project key, it releases only the sessions of the key's project. The examples read the project's ID from STEEL_PROJECT_ID, so that they never release the sessions of other projects.

Parameters

NameTypeRequiredDescription
projectIdstring (uuid) · queryNoRelease only the sessions of this project.

Response

FieldTypeDescription
successbooleanWhether the sessions were released.
messagestringDetails about the result.

See Session lifecycle.

curl -X POST "https://api.steel.dev/v1/sessions/release?projectId=$STEEL_PROJECT_ID" \
  -H "steel-api-key: $STEEL_API_KEY"

Signals

List signal definitions

GET/v1/sessions/signals/catalog

Returns the label and meaning of each signal that a session can have. It holds no session data.

This endpoint takes no parameters.

Response

FieldTypeDescription
signalsobject[]One entry for each signal, with value, label, description, severity (info, warning, danger or success) and source (manual or derived).
semanticsstringHow to read signals, and the limits of their coverage.

See Signals.

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

Logs and agent traces

Get agent logs

GET/v1/sessions/{id}/agent-logs

Returns the raw input and navigation events that an agent sent to the browser over CDP, such as Input.dispatchMouseEvent and Page.navigate.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.
namespacestring · queryNoThe namespace to read. Steel uses the session's namespace when you leave it out.
startTimestring (date-time) · queryNoOnly events at or after this time.
endTimestring (date-time) · queryNoOnly events at or before this time.
eventTypesstring[] · queryNoIgnored. This endpoint sets its own list of event types.
limitinteger · queryNoNumber of events to return, from 1 to 1000.Default 100.
offsetinteger · queryNoNumber of events to skip.Default 0.

Response

FieldTypeDescription
eventsobject[]The input and navigation events on this page.
totalnumberThe number of events that match.
hasMorebooleanWhether more events follow this page.

The SDKs have no method for this endpoint.

For a timeline of clicks and typing, use Get agent traces. See Agent traces.

curl "https://api.steel.dev/v1/sessions/$SESSION_ID/agent-logs?limit=100" \
  -H "steel-api-key: $STEEL_API_KEY"

Get agent traces

GET/v1/sessions/{id}/agent-traces

Returns the agent trace of a session: one entry for each click, typed text, scroll, drag and navigation, with the element's role, accessible name and selectors.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.
namespacestring · queryNoThe namespace to read. Steel uses the session's namespace when you leave it out.
startTimestring (date-time) · queryNoOnly entries at or after this time.
endTimestring (date-time) · queryNoOnly entries at or before this time.
eventTypesstring[] · queryNoIgnored. This endpoint sets its own list of event types.
limitinteger · queryNoNumber of entries to return, from 1 to 1000. Without it, the response has the whole trace.
offsetinteger · queryNoNumber of entries to skip.Default 0.

Response

FieldTypeDescription
eventsobject[]The entries of the trace.
totalnumberThe number of entries that match.
hasMorebooleanWhether more entries follow this page.

When Steel captured no browser actions in the session, as in older sessions, it builds the trace from the session's raw CDP commands. A session with neither returns an empty list.

See Agent traces.

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

Get session logs

GET/v1/sessions/{id}/logs

Returns the browser logs of a session: console messages, page errors, network requests and page loads.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.
namespacestring · queryNoThe namespace to read. Steel uses the session's namespace when you leave it out.
startTimestring (date-time) · queryNoOnly events at or after this time.
endTimestring (date-time) · queryNoOnly events at or before this time.
eventTypesstring[] · queryNoOnly events of these types.
limitinteger · queryNoNumber of events to return, from 1 to 1000.Default 100.
offsetinteger · queryNoNumber of events to skip.Default 0.

Response

FieldTypeDescription
eventsobject[]The events, each with id, timestamp, type and log.
totalnumberThe number of events that match.
hasMorebooleanWhether more events follow this page.

See Logs.

curl "https://api.steel.dev/v1/sessions/$SESSION_ID/logs?limit=100" \
  -H "steel-api-key: $STEEL_API_KEY"

Session context

Get the session context

GET/v1/sessions/{id}/context

Returns a session's cookies and storage, in the form that sessionContext accepts when you create a session.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.

Response

FieldTypeDescription
cookiesobject[]The cookies, with the fields in sessionContext.
localStorageobjectlocalStorage items, by domain.
sessionStorageobjectsessionStorage items, by domain.
indexedDBobjectIndexedDB items, by domain.

See Session context.

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

Cost

Get the session cost

GET/v1/sessions/{id}/cost

Returns the final cost of a released session in US dollars, to six decimal places. For a few seconds after the release, until Steel writes the final usage, it returns a totalCost of 0, so wait about 5 seconds after the release before you call it.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.

Response

FieldTypeDescription
idstring (uuid)The ID of the session.
totalCostnumberThe total cost in US dollars, such as 0.031905.
currencystringAlways usd.
unitstringAlways dollar.
usageobjectThe billable usage: browser (value and unit, minute or second), proxy (bytes) and captcha (solves).

See Session cost.

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

Recordings

Get recorded events

GET/v1/sessions/{id}/events

Returns a session's recorded events, in the rrweb format.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.
compressedboolean · queryNotrue returns the events as Steel stores them, packed with @rrweb/packer, which makes the response smaller. Unpack them with the package's unpack function.Default false.
limitinteger · queryNoNumber of events to return, from 1 to 1000.Default 1000.
pointerstring · queryNoThe page to return. Pass the value of the Next-Cursor response header.

The response is one page of rrweb events. When more events are left, it has a Next-Cursor header. The SDK methods return only the events, so in TypeScript, Python and Go, read the header from the raw response, as Fetch the recording shows. The Rust SDK does not return headers, so a Rust call reads one page.

See Recordings.

curl "https://api.steel.dev/v1/sessions/$SESSION_ID/events?limit=1000" \
  -H "steel-api-key: $STEEL_API_KEY"

Get the HLS playlist

GET/v1/sessions/{id}/hls

Returns the HLS playlist of a session's recording, as application/vnd.apple.mpegurl.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.

The response is an M3U8 playlist that a video player can play. The playlist is ready a few seconds after the session ends. Until then, the endpoint returns 404, so ask again every 2 seconds, as the examples in Recordings do.

See Recordings.

curl https://api.steel.dev/v1/sessions/$SESSION_ID/hls \
  -H "steel-api-key: $STEEL_API_KEY" \
  -o recording.m3u8

Live details

Get live details

GET/v1/sessions/{id}/live-details

Returns a session's live state: its open pages and the URLs to view them.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.

Response

FieldTypeDescription
pagesobject[]The open pages, each with id, url, title, favicon, and the sessionViewerUrl and sessionViewerFullscreenUrl of the live view of that page. In a headless session, these two URLs show only that page. See Embed the live view in your app.
sessionViewerUrlstringThe URL of the live view, the same URL as the session's debugUrl. It is not the dashboard page in the session's own sessionViewerUrl, which has the same name.
sessionViewerFullscreenUrlstringThe URL of the live view without its navigation controls. It hides them only in a headless session.
wsUrlstringThe CDP URL of the session's browser, with a token for this session in it. The token expires when the session ends.

See Live view.

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

Metadata

Update metadata

PATCH/v1/sessions/{id}/metadata

Merges keys into a session's metadata and returns the result.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.
metadataobject · bodyYesUp to 100 keys to change. A string, a number or a boolean sets a key. null removes it. Keys that you leave out keep their values.

The merged metadata must stay within 50 keys and 8192 bytes of UTF-8 JSON. Updates to different keys at the same time are all kept.

Response

FieldTypeDescription
metadataobjectThe merged metadata. Every value is a string.

In Rust, this code needs cargo add serde_json. See Add metadata.

curl -X PATCH https://api.steel.dev/v1/sessions/$SESSION_ID/metadata \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"outcome": "success", "attempt": null}}'

Replace metadata

PUT/v1/sessions/{id}/metadata

Replaces all of a session's metadata. Send an empty object to clear it.

Parameters

NameTypeRequiredDescription
idstring (uuid) · pathYesThe ID of the session.
metadataobject · bodyYesThe new metadata: up to 50 keys and 8192 bytes of UTF-8 JSON. Values are strings, numbers or booleans.

When two replacements arrive at the same time, the last one wins. To change single keys, use Update metadata.

Response

FieldTypeDescription
metadataobjectThe new metadata. Every value is a string.

See Add metadata.

curl -X PUT https://api.steel.dev/v1/sessions/$SESSION_ID/metadata \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"job_id": "job-1042"}}'

CAPTCHAs

Solve CAPTCHAs

POST/v1/sessions/{sessionId}/captchas/solve

Starts solving CAPTCHAs in a session. With pageId, url or taskId, Steel solves that CAPTCHA. With none of them, it solves every CAPTCHA that it detected.

Use it when stealthConfig.autoCaptchaSolving is false.

Parameters

NameTypeRequiredDescription
sessionIdstring (uuid) · pathYesThe ID of the session.
pageIdstring · bodyNoThe ID of the page that has the CAPTCHA, from Get the CAPTCHA status.
urlstring · bodyNoThe URL of the page that has the CAPTCHA.
taskIdstring · bodyNoThe ID of one CAPTCHA task, from Get the CAPTCHA status.

Response

FieldTypeDescription
successbooleanWhether the action succeeded.
messagestringA message about the result.

See CAPTCHA solving.

curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/captchas/solve \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Solve an image CAPTCHA

POST/v1/sessions/{sessionId}/captchas/solve-image

Solves an image CAPTCHA. Steel reads the image and types the answer into the input.

Parameters

NameTypeRequiredDescription
sessionIdstring (uuid) · pathYesThe ID of the session.
imageXPathstring · bodyYesThe XPath of the CAPTCHA image.
inputXPathstring · bodyYesThe XPath of the input for the answer.
urlstring · bodyNoThe URL of the page that has the CAPTCHA.Default The current page.

Response

FieldTypeDescription
successbooleanWhether the action succeeded.
messagestringA message about the result.

See CAPTCHA solving.

curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/captchas/solve-image \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imageXPath": "//img[@id=\"captcha-image\"]", "inputXPath": "//input[@name=\"captcha\"]"}'

Get the CAPTCHA status

GET/v1/sessions/{sessionId}/captchas/status

Returns the CAPTCHA state of each page in a session.

Parameters

NameTypeRequiredDescription
sessionIdstring (uuid) · pathYesThe ID of the session.

The response is an array with one object for each page:

Response

FieldTypeDescription
pageIdstringThe ID of the page.
urlstringThe URL of the page.
isSolvingCaptchabooleanWhether Steel is solving a CAPTCHA on the page now.
tasksarrayThe page's CAPTCHA tasks.
creatednumberWhen the state was created, in milliseconds since the Unix epoch.
lastUpdatednumberWhen the state last changed, in milliseconds since the Unix epoch.

See CAPTCHA solving.

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

Commands

Call these endpoints over HTTP. The Steel CLI and the MCP server call them for you. To call them from your own agent, see Build your own agent harness.

Run commands

POST/v1/sessions/{sessionId}/commands

Drives a session's browser with commands such as snapshot, click and fill. The commands run in order and stop at the first failure.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
Idempotency-Keystring · headerNoA random value. A retry with the same key returns the stored result and does not run the commands again.
commandsobject or object[] · bodyYesOne command, or an array of up to 50. Commands reference lists each command and its fields.
afterstring · bodyNoThe next value of your last response. A retry with the same after and commands runs only once.
observeobject · bodyNoReturn a snapshot (mode: "snapshot") or a diff (mode: "diff") of the page after the commands.

The request returns 200 even when a command fails, and the command's error is in results. Commands that ran before it are not undone.

Response

FieldTypeDescription
idstringThe ID of the execution, such as x-1. Use it to get or cancel the execution.
executionobjectid, state (running, completed, failed, cancelled or timeout), effect (none, applied or unknown), ran and replayed.
resultsobject[]One result for each command that has finished.
pageobject or nullThe tab that the execution used: tab, url and title.
nextstringSend it as after in the next request.
observeobjectThe snapshot or the diff that observe asked for.
dialogobjectA dialog that is open on the tab and blocks it. A press of Enter or Escape answers it. See Dialogs.
epochChangedbooleanPresent with after. true when something else changed the session after the response whose next value you sent.
bodyExpiredbooleanWhether the large parts of a stored result have expired.

See Commands.

curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commands": [{"command": "navigate", "url": "https://example.com"}, {"command": "snapshot", "interactive": true}]}'

Get a command execution

GET/v1/sessions/{sessionId}/commands/executions/{executionId}

Waits up to 20 seconds for an execution to finish, then returns it. Use it when Run commands returned the state running.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
executionIdstring · pathYesThe ID of the execution, such as x-1.

The response has the same fields as Run commands.

See Commands.

curl https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-1 \
  -H "steel-api-key: $STEEL_API_KEY"

Cancel a command execution

POST/v1/sessions/{sessionId}/commands/executions/{executionId}/cancel

Stops an execution. The running command stops before its next input. Commands that already ran are not undone.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
executionIdstring · pathYesThe ID of the execution, such as x-1.

The response has the same fields as Run commands.

See Commands.

curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-1/cancel \
  -H "steel-api-key: $STEEL_API_KEY"

Computer actions

Run a computer action

POST/v1/sessions/{sessionId}/computer

Runs one mouse, keyboard or screenshot action in a session. The body is one action, and action decides which other fields it takes.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
actionstring · bodyYesmove_mouse, click_mouse, drag_mouse, scroll, press_key, type_text, wait, take_screenshot or get_cursor_position.
coordinatesnumber[] · bodyfor move_mouse[x, y]. Used by move_mouse, click_mouse and scroll.
buttonstring · bodyNoclick_mouse: left, right, middle, back or forward. back and forward click the left button.Default left.
click_typestring · bodyNoclick_mouse: down, up or click. Ignored. Steel always clicks.Default click.
num_clicksnumber · bodyNoclick_mouse: number of clicks. 2 double-clicks; any other value clicks once.Default 1.
pathnumber[][] · bodyfor drag_mousedrag_mouse: an array of [x, y] pairs.
delta_xnumber · bodyNoscroll: horizontal amount. Steel scrolls one wheel step in the direction of the larger delta.Default 0.
delta_ynumber · bodyNoscroll: vertical amount. Steel scrolls one wheel step in the direction of the larger delta.Default 0.
keysstring[] · bodyfor press_keypress_key: the keys to press.
textstring · bodyfor type_texttype_text: the text to type.
durationnumber · bodyfor waitwait: how long to wait, in seconds. Ignored for press_key.
hold_keysstring[] · bodyNoKeys to hold during the action. Ignored. Not for press_key, wait, take_screenshot or get_cursor_position.
screenshotboolean · bodyNoTake a screenshot after the action. Not for take_screenshot or get_cursor_position.

Response

FieldTypeDescription
base64_imagestringThe screenshot, in base64, when one was taken.
outputstringWhat the action did, as text, such as Mouse left clicked at (100, 200).
errorstringThe error, if the action failed.
systemstringAlways steel-browser.

See Computer actions.

curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/computer \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "take_screenshot"}'

Session files

Upload a file to a session

POST/v1/sessions/{sessionId}/files

Adds a file to a session. The request is multipart/form-data.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
filefile or string · bodyYesThe file content, an http:// or https:// URL to download, or the path of a global file.
pathstring · bodyNoThe path of the file in the session, such as downloads/report.pdf.

Response

FieldTypeDescription
pathstringThe path of the file in the session.
sizeintegerThe size in bytes.
lastModifiedstring (date-time)When the file was created.

See Files.

curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/files \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "file=@resume.pdf" \
  -F "path=resume.pdf"

List session files

GET/v1/sessions/{sessionId}/files

Lists a session's files. While the session runs, the newest file comes first. After the session ends, the files come in no set order.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.

Response

FieldTypeDescription
dataobject[]The files, each with path, size in bytes and lastModified.

See Files.

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

Download a session file

GET/v1/sessions/{sessionId}/files/{path}

Downloads one file from a session.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
pathstring · pathYesThe path of the file. It can contain /.

The response is the file, as application/octet-stream.

See Files.

curl https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
  -H "steel-api-key: $STEEL_API_KEY" \
  -o report.csv

Download all session files

GET/v1/sessions/{sessionId}/files.zip

Downloads all of a session's files in one ZIP archive.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.

The response is the archive, as application/zip.

See Files.

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

Delete a session file

DELETE/v1/sessions/{sessionId}/files/{path}

Deletes one file from a session.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.
pathstring · pathYesThe path of the file. It can contain /.

The response is 204 with no body.

See Files.

curl -X DELETE https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
  -H "steel-api-key: $STEEL_API_KEY"

Delete all session files

DELETE/v1/sessions/{sessionId}/files

Deletes all of a session's files.

Parameters

NameTypeRequiredDescription
sessionIdstring · pathYesThe ID of the session.

The response is 204 with no body.

See Files.

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