---
title: "Browsers API"
description: "Native browser HTTP endpoints."
---

> Documentation Index
> Fetch the complete documentation index at: https://help.tooluse.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Browsers API

<p>Use <code>https://api.tooluse.net/v1/browsers</code> with <code>Authorization: Bearer $TOOLUSE_API_KEY</code>, where the variable contains an application Agent key. All examples use the native HTTP API.</p>
<pre><code class="language-bash">curl -X POST "https://api.tooluse.net/v1/browsers/sessions" \
  -H "Authorization: Bearer $TOOLUSE_API_KEY" \
  -H "Idempotency-Key: tooluse-example-001" \
  -H "Content-Type: application/json" \
  -d '{"timeout":300,"browserSettings":{"viewport":{"width":1280,"height":720}}}'
</code></pre>
<p>Session creation requires an application-scoped <code>Idempotency-Key</code>. Keep the same key and body when reconciling one operation; use a new key for a new session.</p>
<div class="nb-table-scroll"><table>
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Result</th>
</tr>
</thead>
<tbody><tr>
<td>POST</td>
<td><code>/sessions</code></td>
<td>Create a session</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions?page=1&amp;size=20</code></td>
<td>Paged sessions and total</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions/{id}</code></td>
<td>Session state and usage</td>
</tr>
<tr>
<td>POST</td>
<td><code>/sessions/{id}</code></td>
<td>Release, metadata or allowed-domain update</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions/{id}/debug</code></td>
<td>CDP and live-view URLs</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions/{id}/logs</code></td>
<td>Paged redacted CDP logs</td>
</tr>
<tr>
<td>POST</td>
<td><code>/sessions/{id}/actions</code></td>
<td>Bounded browser action; idempotency key required</td>
</tr>
<tr>
<td>POST</td>
<td><code>/sessions/{id}/uploads</code></td>
<td>Multipart upload to a running session</td>
</tr>
<tr>
<td>GET</td>
<td><code>/downloads</code></td>
<td>Paged download metadata</td>
</tr>
<tr>
<td>GET, DELETE</td>
<td><code>/downloads/{id}</code></td>
<td>Read or remove a download</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions/{id}/replays</code></td>
<td>Retained page summaries</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions/{id}/replays/{pageId}</code></td>
<td>Paged JPEG frames</td>
</tr>
<tr>
<td>POST, GET</td>
<td><code>/sessions/{id}/recording/downloads</code></td>
<td>Create or list MP4 jobs</td>
</tr>
<tr>
<td>GET</td>
<td><code>/sessions/{id}/recording/downloads/{recordingId}</code></td>
<td>MP4 metadata or authenticated bytes</td>
</tr>
</tbody></table>
</div><p>Contexts require the deployment’s encrypted storage configuration and may return <code>503 context_storage_unavailable</code>. Extension and certificate uploads are not available. Native download streams require authentication; they are not signed public URLs. Native replay retention is 24 hours, and recording must be enabled at creation. See the <a href="/openapi.yaml">generated API schema</a> for exact input and response definitions.</p>

Source: https://help.tooluse.net/browsers/api/index.mdx