Create a profile
Empty: start a session with profile:{id, persist:true} to fill it. With fromSession: holds that working session's cookies and the site storage of its open tabs right now; with attach: true the session also saves to it from now on (at its checkpoints and when it stops; 409 conflict when it already has a profile). 400 for a session without a browser, 404 for another project's session, 409 session_not_running once it has stopped, 413 profile_too_large over 16 MB; 30 saves from sessions per minute per project. 402 plan_limit past the plan's maxProfiles (profiles per project) or maxProfileBytes (what they hold together).
POST
/v1/profilesRequest
| Method and path | POST/v1/profiles |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
| Safe retries | Send an Idempotency-Key header to retry without creating anything twice. See Idempotency keys. |
| Rate limit | Yes. See Rate limits for the numbers and headers. |
Headers
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
Idempotency-Key | string | – | – | Makes a retry safe: the same key and body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of creating something twice. 1 to 255 printable ASCII characters without spaces, e.g. a UUID. Keys belong to the project (a new API key is replayed only to its caller). At most 300 new keys per minute per project (429). 1 to 255 characters. |
Body
JSON with content-type: application/json. Optional: you can leave the body out.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
name | string | – | – | Default "Profile …", or "Saved from session …" with fromSession. Up to 100 characters. |
fromSession | string | – | – | A running session of this project whose current sign-ins to save. |
attach | boolean | false | – | With fromSession: the session saves to the new profile from now on (its profileId, persist). |
curl -X POST "https://api.boxline.dev/v1/profiles" \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "content-type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"name": "Work account"}'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst profile = await bx.profiles.create({ name: "Work account" });console.log(profile.id);from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLprofile = bx.profiles.create(name="Work account")print(profile["id"])Responses
201 Created
The new profile.
Headers
Idempotent-Replayed:truewhen this is the kept response of an earlier request with the same Idempotency-Key. (Idempotency keys)
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
id | string | – | – | |
name | string | – | – | |
sizeBytes | integer | – | – | |
createdAt | string | – | – | Format: date-time. |
updatedAt | string | – | – | Format: date-time. |
inUseBy | string | null | – | – | The running session using it. |
credential | string | null | – | – | The password credential it signs in with (PATCH /v1/profiles/:id {credential}); null without one. |
{ "id": "prof_Hk3VxP9mQ2sLw7Tn", "name": "Work account", "sizeBytes": 0, "createdAt": "2026-09-29T10:00:00.000Z", "updatedAt": "2026-09-29T10:00:00.000Z", "inUseBy": "…", "credential": "SHOP"}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 402 Payment Required | feature_not_in_plan, spend_limit, out_of_credit, plan_limit, spend_limit, out_of_credit, organization, project, plan, credit | The plan does not include this, a monthly allowance or spending limit is used up, the organization has no credit left, or the plan allows no more of this. spend_limit and out_of_credit carry error.details.limit: organization, project, plan or credit. |
| 404 Not Found | not_found, invite_not_found, provider_unavailable | No such thing in this project (or organization), or no such route. |
| 409 Conflict | session_not_running, shell_disabled, browser_disabled, nothing_saved, not_resumable, invalid_state, conflict, email_taken, identity_in_use, provider_already_linked, last_sign_in_method, not_impersonating, machine_too_old, too_many_credential_values, limit_reached, terms_version_mismatch, no_project, last_owner, organization_not_empty, project_has_sessions, already_member, invite_pending, idempotency_in_progress | The current state does not allow it, or a request with this Idempotency-Key is still being answered. |
| 413 | payload_too_large | The request body is larger than the route allows. |
| 422 Unprocessable Content | idempotency_mismatch | This Idempotency-Key was already used for a different request. |
| 429 Too Many Requests | rate_limited, concurrency_limit | Too many requests, or the organization's concurrent sessions (its plan's) or the project's concurrencyCap are in use. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.