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

# TinyAgent Reference — Browser Context Profiles

> Create, manage, and set up Browser Context Profiles

Create, manage, and set up Browser Context Profiles — reusable saved browser sessions. Full
setup flow and SDK connection examples: [Browser Context Profiles API](https://docs.tinyfish.ai/agent/api/profiles/browser-context-profiles.md).
All requests require the `X-API-Key` header unless noted otherwise. See
[Authentication](https://docs.tinyfish.ai/authentication.md).

## Quick Setup

**1. Create a profile**

`POST /v1/profiles` with a name. Start a setup session, sign in through it, then save it — full
request and response schemas: [Browser Context Profiles
API](https://docs.tinyfish.ai/agent-api/browser-context-profiles.md).

**2. Run with the saved session**

Pass `use_profile: true` (and optionally `profile_id`) on an automation request to start the
run already signed in.

The sections below are the exact request/response schema for every Browser Context Profiles
endpoint.

## Endpoints

| Endpoint | Method | Purpose |
| - | - | - |
| `/v1/profiles` | `GET` | List profiles |
| `/v1/profiles` | `POST` | Create a profile |
| `/v1/profiles/{profileId}` | `GET` | Get profile details and saved domains |
| `/v1/profiles/{profileId}` | `PATCH` | Rename a profile, set default, or update proxy location |
| `/v1/profiles/{profileId}` | `DELETE` | Delete a profile |
| `/v1/profiles/{profileId}/setup-session` | `POST` | Start an interactive setup browser |
| `/v1/profiles/{profileId}/setup-session/cancel` | `POST` | Cancel a setup browser session without saving |
| `/v1/profiles/{profileId}/save` | `POST` | Save a setup browser session |
| `/v1/profiles/{profileId}/upload` | `POST` | Upload cookies and storage manually |
| `/v1/profiles/{profileId}/domains/{domain}` | `DELETE` | Delete stored state for one domain |

## List Profiles

`GET /v1/profiles`

List every Browser Context Profile on the account.

```json theme={null}
{ "profiles": [ { "id": "prof_abc123", "name": "Salesforce", "is_default": true } ] }
```

## Create a Profile

`POST /v1/profiles`

Create a named profile.

**name** `string` *required*

Profile display name.

**set\_as\_default** `boolean`

Makes this the default profile for `use_profile: true`.

**proxy\_country\_code** `string | null`

Supported country code, or `null` for no profile proxy.

Response (`201`):

**id** `string`

Browser Context Profile ID.

**name** `string`

Profile display name.

**proxy\_country\_code** `string | null`

**is\_default** `boolean`

**fingerprint\_seed** `string`

**domain\_count** `integer`

**created\_at** `string`

**updated\_at** `string`

## Get Profile Details

`GET /v1/profiles/{profileId}`

**profileId** `string` *required*

Browser Context Profile ID.

Same response fields as create, plus:

**domains** `array`

Saved domains and their capture state.

## Update a Profile

`PATCH /v1/profiles/{profileId}`

**profileId** `string` *required*

Browser Context Profile ID.

**name** `string`

New display name.

**set\_as\_default** `boolean`

**proxy\_country\_code** `string | null`

Returns the same shape as `GET /v1/profiles/{profileId}`.

## Delete a Profile

`DELETE /v1/profiles/{profileId}`

**profileId** `string` *required*

Browser Context Profile ID.

**deleted** `boolean`

## Start a Setup Session

`POST /v1/profiles/{profileId}/setup-session`

**profileId** `string` *required*

Browser Context Profile ID.

**url** `string`

Target URL the browser session will navigate to on startup. Bare domains (e.g. `tinyfish.ai`) are automatically prefixed with `https://`.

**timeout\_seconds** `integer`

Inactivity timeout in seconds (5–86400). Defaults to your plan maximum.

**session\_id** `string`

Unique identifier for this browser session.

**cdp\_url** `string`

WebSocket URL for browser connection. Pass this to Playwright's `connect_over_cdp` or any CDP client.

**base\_url** `string`

HTTPS base URL for the session. Use to access session endpoints such as `/pages` — don't pass this to Playwright.

**timeout\_seconds** `integer`

**expires\_at** `string`

## Cancel a Setup Session

`POST /v1/profiles/{profileId}/setup-session/cancel`

**profileId** `string` *required*

Browser Context Profile ID.

**session\_id** `string` *required*

From the `setup-session` response.

**cancelled** `boolean`

## Save a Setup Session

`POST /v1/profiles/{profileId}/save`

**profileId** `string` *required*

Browser Context Profile ID.

**session\_id** `string` *required*

From the `setup-session` response.

**signed\_in\_sites** `array`

Sites the caller believes were signed into during setup, as hosts or URLs.

**domains\_updated** `array`

**domains\_failed** `array`

**cookie\_count** `integer`

**domains\_skipped** `object`

**pages\_captured** `integer`

**target\_reads\_skipped** `integer`

**signed\_in\_sites** `array`

Sites this save recorded as signed in. Present only when sign-in tracking is enabled for the account.

## Upload Cookies and Storage

`POST /v1/profiles/{profileId}/upload`

Upload exported browser state directly, without opening a setup browser.

**profileId** `string` *required*

Browser Context Profile ID.

**cookies** `array` *required*

**localStorage** `array`

**sessionStorage** `array`

**domains\_updated** `array`

**domains\_failed** `array`

**cookie\_count** `integer`

**domains\_skipped** `object`

| Limit | Value |
| - | - |
| Upload payload | 5 MB |
| Cookies per upload | 3,000 |
| Domains per profile | 100 |

## Delete a Domain

`DELETE /v1/profiles/{profileId}/domains/{domain}`

Delete one stored domain's saved state from a profile, without deleting the profile itself.

**profileId** `string` *required*

Browser Context Profile ID.

**domain** `string` *required*

Domain to remove from the profile.

**deleted** `boolean`


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