---
title: "Create a browser profile"
method: POST
path: "/contexts"
tags: ["Browser"]
---

# Create a browser profile

`POST /contexts`

## Request

- Base URL: `https://request.usestring.ai/v1`
- URL: `https://request.usestring.ai/v1/contexts`
- Auth: HTTP bearer

Create a reusable browser profile (context) that saves logins, cookies and site storage between remote browser sessions. Pass the returned `id` as `contextId` when connecting to GET /wss; closing that session saves the profile.

## Headers

- `Idempotency-Key` string

## Request body

- CreateContextRequest: Request body for POST /contexts. Unknown fields return 400.
  - `name` string: Optional label, 1-200 characters after trimming, unique among your live profiles. A duplicate returns 409.

## Response `201`

Profile created, or an idempotent create replayed.

- Context: A saved browser profile. See https://portal.usestring.ai/docs/browser/contexts#the-profile-object
  - `id` string, uuid, required: Opaque UUID used to reconnect (`/wss?contextId=`), inspect, or delete.
  - `name` string, nullable, required: Optional label.
  - `status` 'EMPTY' | 'IN_USE' | 'UPLOADING' | 'READY' | 'FAILED' | 'DELETING', required: `EMPTY`: no saved data. `IN_USE`: a saving session is using the profile. `UPLOADING`: a save is finishing. `READY`: saved data is available. `FAILED`: a save failed; earlier saved data remains. `DELETING`: returned only by DELETE.
  - `sizeBytes` integer, nullable, required: Compressed size of the saved profile. Null before the first successful save.
  - `failureReason` string, nullable, required: Most recent save failure, cleared by a successful save.
  - `latestSaveOperation` ContextSaveOperation, required: The most recent save.
    - `id` string
    - `status` 'PENDING' | 'COMMITTED' | 'FAILED' | 'EXPIRED' | 'SUPERSEDED': `PENDING`: not finished. `COMMITTED`: succeeded. `FAILED`: failed; read `failureReason`. `EXPIRED`: the session ended before anything was saved. `SUPERSEDED`: another session saved first; not a success.
    - `failureReason` string, nullable
    - `completedAt` string, nullable
  - `lastSavedAt` string, date-time, nullable, required: Time of the last successful save.
  - `lastUsedAt` string, date-time, nullable, required: Last connection, saving or read-only. Reading status does not update it.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: Validation error: invalid input or an unrecognized field. `issues` lists per-field problems.
- `401`: Missing or invalid Authorization header.
- `402`: Insufficient balance for creation.
- `409`: Duplicate name, or a create with the same Idempotency-Key is still in progress (retry with backoff).
- `429`: Profile limit (25 per organization), storage limit (1 GiB per organization), or request-rate limit reached.
- `500`: Internal server error.

---

[API](https://skmtc.dev/usestring/apis/string-web-access-api.md) · [All operations](https://skmtc.dev/usestring/apis/string-web-access-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usestring/apis/string-web-access-api/revisions/fd336960036e?raw)