API Reference

Profiles

A profile is a saved browser sign-in: the cookie jar of a signed-in website session. Create a profile, upload its cookie jar, and confirm it, then name it in a job so the job's browser starts signed in.

Endpoints

A profile holds the cookie jar of one signed-in website session, so a job's browser can start signed in. Export the jar from a browser that is signed in to the website, including HttpOnly cookies, as a JSON array of cookie objects with name, value, domain, and optionally path, expires in Unix seconds, httpOnly, secure, and sameSite. Upload it to the signed URL, confirm it, then send the profileId with start job. The API never returns the jar, and the scraper cannot export or change the browser's cookies. When a job ends Done, its browser's cookies replace the stored jar, so a session that the website renews stays signed in; a job that ends Error keeps the stored jar. To use one account from one address, pin every job of the profile to the same static IP. A website that binds a session to the address it signed in from needs a jar signed in from that static IP.

POSThttps://api.browserfleet.dev/rest/public/profiles

Create Profile

Creates an unconfirmed profile and returns a signed URL for its cookie jar upload.

Create Profile request fields
Field	Location	Type	Required	Description
name	JSON Body	string	Yes	Your label for the sign-in, up to 200 characters, for example the website and account.

Example Request

curl -X POST "https://api.browserfleet.dev/rest/public/profiles" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example portal, research account" }'

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/json" \
  --data-binary @cookies.json

201 Created

{
  "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35",
  "name": "Example portal, research account",
  "uploaded": false,
  "upload": {
    "method": "PUT",
    "url": "https://.../browser_profiles/5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35/cookies.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=...",
    "contentType": "application/json",
    "expiresInSeconds": 900
  },
  "createdAt": "2026-06-17T10:00:00.000Z"
}

Create Profile response fields
Field	Type	Description
profileId	string	Profile id used by the profile endpoints and start job.
name	string	Stored label.
uploaded	boolean	false until confirm profile accepts an uploaded jar.
upload	{ method, url, contentType, expiresInSeconds }	Signed upload of the cookie jar. Send the jar as the body of a PUT to url with the Content-Type header set to contentType, before expiresInSeconds pass.
createdAt	string	Creation timestamp as an ISO string.

Create Profile error responses
Status	Body	Meaning
400	{ "error": "Invalid or missing JSON body" }	The request body is missing or is not valid JSON.
400	{ "error": "Invalid request body", "issues": { ... } }	The name is missing, empty, or longer than 200 characters.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.

POSThttps://api.browserfleet.dev/rest/public/profiles/upload-url

Sign Upload

Returns a new signed URL for a profile's cookie jar, to replace an expired upload URL or to replace the stored jar, for example after the website signed the session out. Confirm the profile again after the upload.

Sign Upload request fields
Field	Location	Type	Required	Description
profileId	JSON Body	string	Yes	Profile id returned by create profile.

Example Request

curl -X POST "https://api.browserfleet.dev/rest/public/profiles/upload-url" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35" }'

200 OK

{
  "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35",
  "upload": {
    "method": "PUT",
    "url": "https://.../browser_profiles/5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35/cookies.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=...",
    "contentType": "application/json",
    "expiresInSeconds": 900
  }
}

Sign Upload response fields
Field	Type	Description
profileId	string	Profile id.
upload	{ method, url, contentType, expiresInSeconds }	Signed upload of the cookie jar, used as in create profile.

Sign Upload error responses
Status	Body	Meaning
400	{ "error": "Invalid request body", "issues": { ... } }	The profileId is missing or is not a profile id.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Profile not found" }	The profile id could not be found.

POSThttps://api.browserfleet.dev/rest/public/profiles/confirm

Confirm Profile

Reads the uploaded cookie jar, checks that it is a non-empty JSON array of cookies that each have a name, a value, and a domain, and marks the profile uploaded so jobs can use it.

Confirm Profile request fields
Field	Location	Type	Required	Description
profileId	JSON Body	string	Yes	Profile id whose jar was uploaded.

Example Request

curl -X POST "https://api.browserfleet.dev/rest/public/profiles/confirm" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35" }'

200 OK

{
  "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35",
  "name": "Example portal, research account",
  "uploaded": true,
  "cookieCount": 18,
  "uploadedAt": "2026-06-17T10:02:00.000Z",
  "createdAt": "2026-06-17T10:00:00.000Z",
  "updatedAt": "2026-06-17T10:02:00.000Z"
}

Confirm Profile response fields
Field	Type	Description
profileId	string	Profile id.
name	string	Stored label.
uploaded	boolean	Always true when the confirmation succeeds.
cookieCount	number	Number of cookies in the confirmed jar.
uploadedAt, createdAt, updatedAt	string	Confirmation, creation, and last update timestamps as ISO strings.

Confirm Profile error responses
Status	Body	Meaning
400	{ "error": "Invalid request body", "issues": { ... } }	The profileId is missing or is not a profile id.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Profile not found" }	The profile id could not be found.
422	{ "error": "No cookie jar was uploaded for this profile" }	Nothing was uploaded to the signed URL.
422	{ "error": "The cookie jar must be a non-empty JSON array of cookies, each with a name, a value and a domain" }	The uploaded file is not a cookie jar. Upload a valid jar with sign upload, then confirm again.

GEThttps://api.browserfleet.dev/rest/public/profiles?profileId={profileId}

Retrieve Profiles

Returns one profile when profileId is sent, or every profile of the organization, newest first, when it is omitted. The cookie jar is never returned.

Retrieve Profiles request fields
Field	Location	Type	Required	Description
profileId	Query String	string	No	Profile id to read. Omit it to list every profile.

Example Request

curl "https://api.browserfleet.dev/rest/public/profiles?profileId=5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK

{
  "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35",
  "name": "Example portal, research account",
  "uploaded": true,
  "uploadedAt": "2026-06-17T10:02:00.000Z",
  "createdAt": "2026-06-17T10:00:00.000Z",
  "updatedAt": "2026-06-17T10:02:00.000Z"
}

Retrieve Profiles response fields
Field	Type	Description
profileId	string	Profile id.
name	string	Stored label.
uploaded	boolean	true when a confirmed jar is stored and jobs can use the profile.
uploadedAt	string or null	Last confirmation timestamp as an ISO string, or null before the first confirmation.
createdAt, updatedAt	string	Creation and last update timestamps as ISO strings.

Retrieve Profiles error responses
Status	Body	Meaning
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Profile not found" }	The profile id could not be found.

DELETEhttps://api.browserfleet.dev/rest/public/profiles?profileId={profileId}

Delete Profile

Deletes a profile and its stored cookie jar. A profile that a Pending or In Progress job names cannot be deleted until that job ends.

Delete Profile request fields
Field	Location	Type	Required	Description
profileId	Query String	string	Yes	Profile id to delete.

Example Request

curl -X DELETE "https://api.browserfleet.dev/rest/public/profiles?profileId=5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK

{
  "deleted": true,
  "profileId": "5d1e8c3a-7b2f-4e9d-a6c4-1f0b9e2d7a35"
}

Delete Profile response fields
Field	Type	Description
deleted	boolean	Always true when the deletion succeeds.
profileId	string	Deleted profile id.

Delete Profile error responses
Status	Body	Meaning
400	{ "error": "Missing profileId" }	The profileId query parameter is empty or absent.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Profile not found" }	The profile id could not be found.
409	{ "error": "Profile is named by a Pending or In Progress job" }	A queued or running job still uses the profile. Delete it after that job ends.