> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiles and extensions

> Save a browser session's cookies and logins under a name to reuse them later, and load your own Chrome extensions into sessions.

A profile keeps cookies and local storage under a name, so a later session starts signed in. It saves when the session closes. A scrape and a batch take the same `profile` field, so a login saved here also works there.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 300, "profile": {"name": "shop-login"}}'
```

A name that does not exist is created. Sign in with [Execute](https://docs.stophy.dev/browser/execute.md) or your own CDP client, then [close the session](https://docs.stophy.dev/browser/overview#close-read-and-list) to save. Open the next session with the same name to load it. A profile also keeps the country it first used. A different `location.country` opens in the profile's country and returns a `warning`.

| Field | Default | Meaning |
| - | - | - |
| `profile.name` | none | The profile to load and save, 1 to 200 characters |
| `profile.saveChanges` | `true` | `false` loads the profile and saves nothing. Chosen per session, not stored on the profile. |

## Manage profiles

All profile calls are free.

| Action | Call |
| - | - |
| Create empty | `POST /v1/browser/profiles` with `{"name": "shop-login"}` |
| List | `GET /v1/browser/profiles`, most recently used first. `data.profiles` has each `name` and `lastUsedAt`. |
| Read | `GET /v1/browser/profiles/{name}` returns `cookies` and `origins`, the count of sites with saved local storage |
| Rename | `PATCH /v1/browser/profiles/{name}` with `{"name": "shop-login-2026"}`. Cookies stay. |
| Delete | `DELETE /v1/browser/profiles/{name}`. The cookies go with it. |

## Extensions

Upload a Chrome extension once, then load it into any session. Uploads, lists, reads and deletes are free. Send a Manifest V3 zip of up to 50 MiB, with `manifest.json` at its root, in a multipart field named `file`.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser/extensions \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -F "file=@mark-page.zip;type=application/zip"
```

The answer is `201` with `id`, `name` and `version`, read from `manifest.json`. Keep `id`. There is no update: upload again for a new `id`.

Open a session with `"extensionIds": ["<id>"]`, up to 3, each once. They load before the first page opens and cannot change while the session runs. The answer lists each `id`, `runtimeId` and `version` in the order you sent them. Use `runtimeId` in `chrome-extension://{runtimeId}/` addresses. An extension runs only in sessions that load it, and changes what sites can see.

| Action | Call |
| - | - |
| List | `GET /v1/browser/extensions`, newest first. `pageSize` 1 to 100, default 10. `pageNumber` from 1. `items` is empty with none. |
| Read | `GET /v1/browser/extensions/{extension_id}` |
| Delete | `DELETE /v1/browser/extensions/{extension_id}`. Open sessions keep it until they close. |

You can keep 100 extensions.

## Errors

* A second session saving to the same profile: `409 profileBusy`, retryable. Wait for the first to close, or send `saveChanges: false`.
* A profile too large to save: `413 profileTooLarge`.
* A taken name on create or rename, or a rename while a session saves: `409 invalidRequest`. An unknown name: `404 notFound`.
* `profile` with `zeroDataRetention`: `400 invalidRequest`.
* A manifest with a `key` field, or the `debugger`, `proxy`, `processes`, `dns`, `experimental` or `enterprise.*` permission: `400 prohibitedPermission`.
* An unknown or deleted extension id: `404 notFound`. More than 3 ids, or the same id twice: `400 invalidRequest`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.