Use https://api.tooluse.net/v1/browsers with Authorization: Bearer $TOOLUSE_API_KEY, where the variable contains an application Agent key. All examples use the native HTTP API.
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}}}'
Session creation requires an application-scoped Idempotency-Key. Keep the same key and body when reconciling one operation; use a new key for a new session.
| Method | Path | Result |
|---|---|---|
| POST | /sessions |
Create a session |
| GET | /sessions?page=1&size=20 |
Paged sessions and total |
| GET | /sessions/{id} |
Session state and usage |
| POST | /sessions/{id} |
Release, metadata or allowed-domain update |
| GET | /sessions/{id}/debug |
CDP and live-view URLs |
| GET | /sessions/{id}/logs |
Paged redacted CDP logs |
| POST | /sessions/{id}/actions |
Bounded browser action; idempotency key required |
| POST | /sessions/{id}/uploads |
Multipart upload to a running session |
| GET | /downloads |
Paged download metadata |
| GET, DELETE | /downloads/{id} |
Read or remove a download |
| GET | /sessions/{id}/replays |
Retained page summaries |
| GET | /sessions/{id}/replays/{pageId} |
Paged JPEG frames |
| POST, GET | /sessions/{id}/recording/downloads |
Create or list MP4 jobs |
| GET | /sessions/{id}/recording/downloads/{recordingId} |
MP4 metadata or authenticated bytes |
Contexts require the deployment’s encrypted storage configuration and may return 503 context_storage_unavailable. 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 generated API schema for exact input and response definitions.