---
title: "Browsers API"
description: "Session, context, download, replay, and upload endpoints for cloud browser sessions."
image: "https://help.agent.mq/og.svg"
---

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

# Browsers API

All endpoints live under `https://api.agent.mq/v1/browsers` and carry an application Agent key:

```bash
-H "Authorization: Bearer $AGENTMQ_TOKEN"
```

Answers are JSON. A create, upload, or recording request is a write, and an uncertain answer is reconciled by reading the session back rather than by sending the write again.

## Sessions

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/sessions` | Create a session and return its id and connection URL. |
| `GET` | `/sessions` | List sessions, filterable by status and metadata. |
| `GET` | `/sessions/{id}` | Read one session, including status, region, and timings. |
| `POST` | `/sessions/{id}` | Update a running session; `REQUEST_RELEASE` ends it. |
| `GET` | `/sessions/{id}/logs` | Read the session's console and network logs. |
| `POST` | `/sessions/{id}/uploads` | Upload a local file into a running session. |
| `GET` | `/sessions/{id}/debug` | Return the live view and debug URLs for a running session. |

### Create a session

```bash
curl -X POST https://api.agent.mq/v1/browsers/sessions \
  -H "Authorization: Bearer $AGENTMQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
"browserSettings": {
  "viewport": { "width": 1920, "height": 1080 }
}
  }'
```

The create body accepts the session's viewport, timeout, keep alive, recording and logging flags, extension and context references, proxy settings, allowed domains, and `userMetadata`. See [Create a browser session](/browsers/getting-started/create-browser-session) for the options and their defaults.

### Update a session

```bash
curl -X POST https://api.agent.mq/v1/browsers/sessions/{sessionId} \
  -H "Authorization: Bearer $AGENTMQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "REQUEST_RELEASE"}'
```

`REQUEST_RELEASE` closes the session; omitted fields are left unchanged.

## Contexts

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/contexts` | Create a Context and return its id. |
| `GET` | `/contexts/{id}` | Read a Context. |
| `DELETE` | `/contexts/{id}` | Delete a Context and its stored user data. |

Pass the Context id into a session to persist cookies and storage across sessions. See [Contexts](/browsers/core-features/contexts).

## Files

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/downloads` | List the downloads of a session, filterable and paginated. |
| `GET` | `/downloads/{id}` | Read download metadata, or the bytes with `Accept: application/octet-stream`. |
| `DELETE` | `/downloads/{id}` | Delete a stored download. |

Download URLs are signed and expire six hours after they are issued; list the downloads again to mint a fresh URL. See [Downloads](/browsers/files/downloads) and [Uploads](/browsers/files/uploads).

## Replays and recordings

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/sessions/{id}/replays` | List the recorded pages of a session. |
| `GET` | `/sessions/{id}/replays/{pageId}` | Return the HLS playlist for one recorded page. |
| `POST` | `/sessions/{id}/recording/downloads` | Assemble one downloadable MP4 per recorded page. |
| `GET` | `/sessions/{id}/recording/downloads` | Read the per-page assembly status and download URLs. |

Replay and recording source is retained for 31 days after a session ends. See [Session replay](/browsers/observability/session-replay) and [Recording downloads](/browsers/observability/recording-downloads).

## Extensions and certificates

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/extensions` | Upload a Chrome extension for sessions to load. |
| `GET` | `/extensions/{id}` | Read an uploaded extension. |
| `DELETE` | `/extensions/{id}` | Delete an uploaded extension. |
| `POST` | `/certificates` | Upload a certificate authority a session should trust. |
| `GET` | `/certificates` | List uploaded certificate authorities. |
| `GET` | `/certificates/{id}` | Read one certificate authority. |
| `DELETE` | `/certificates/{id}` | Delete a certificate authority. |

See [Browser extensions](/browsers/core-features/browser-extensions) and [Certificate validation](/browsers/security/certificate-validation).

## OpenAPI

The platform's OpenAPI description is published at [https://help.agent.mq/openapi.yaml](https://help.agent.mq/openapi.yaml).

Source: https://help.agent.mq/browsers/api/index.mdx