Skip to main content
POST/api/public/v1/sessions/{id}/stop

sessions.stop

Stop a session; closed only after the machine proves no browser process remains.

Capability: session.stopCommand (idempotent)DestructiveMCP tool: sessions_stop
View as Markdown

Parameters

NameTypeRequiredDescription
idpathstring (uuid)YesSession id
command_idbodystring (uuid)YesClient-generated UUID for this command. Send the same id (and body) again to get the stored receipt instead of a second change; a different body under the same id is CONFLICT.

Examples

curl -X POST "https://browlix.com/api/public/v1/sessions/<id>/stop" \
  -H "Authorization: Bearer $BROWLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command_id":"<uuid>"}'

Response

201 with { data, replayed: false, correlation_id } the first time; 200 with replayed: true when the same command_id and body come again.

FieldTypeAlways presentDescription
dataobjectYes
data.idstring (uuid)Yes
data.lifecycle"queued" | "preflight" | "starting" | "ready" | "quiescing" | "stopping" | "closed" | "failed" | …Yes
data.control"free" | "reserved" | "controlled" | "handoff_pending" | "revoked" | "uncertain"Yes
data.connectivity"connected" | "reconnecting" | "offline" | "unknown"Yes
data.network"unchecked" | "checking" | "healthy" | "unhealthy" | "unknown"Yes
data.sync"clean" | "dirty" | "snapshotting" | "upload_pending" | "committing" | "committed" | "conflict" | "failed"Yes
data.fenceintegerYesIncrements every time the profile is opened; stale reports carry an older fence (min -9007199254740991, max 9007199254740991)
data.revisionintegerYes(min -9007199254740991, max 9007199254740991)
data.headlessbooleanYes
data.profileobjectYes
data.profile.idstring (uuid)Yes
data.profile.os"windows" | "linux"Yes
data.profile.namestringYes
data.profile.numberintegerYes(min -9007199254740991, max 9007199254740991)
data.profile.group_idstring (uuid) | nullYes
data.profile.revisionintegerYes(min -9007199254740991, max 9007199254740991)
data.deviceobjectYes
data.device.idstring (uuid)Yes
data.device.os"windows" | "linux"Yes
data.device.namestringYes
data.device.statestringYes
data.device.freshnessstringYes
data.leaseobject | nullYesThe machine's hold on the profile while the session runs (not an app hold — see sessions.acquire)
data.lease.expires_atstring (date-time)Yes
data.lease.expiredbooleanYes
data.egressobject | nullYes
data.egress.ipstringYes
data.egress.checked_atstring (date-time)Yes
data.processobject | nullYes
data.process.pidintegerYes(min -9007199254740991, max 9007199254740991)
data.runtimeobject | nullYes
data.runtime.channelstringYes
data.runtime.versionstringYes
data.identityobject | nullYesWhat the browser actually reported (user agent, languages, timezone, …)
data.mismatchesarray<object>Yes
data.remoteobject | nullYes
data.proxy_idstring (uuid) | nullYes
data.run_idstring (uuid) | nullYes
data.run_target_idstring (uuid) | nullYes
data.started_bystring | nullYes
data.stopped_bystring | nullYes
data.stop_reasonstring | nullYes
data.reason_codestring | nullYes
data.network_reasonstring | nullYes
data.ready_msinteger | nullYes
data.ready_atstring (date-time) | nullYes
data.closed_atstring (date-time) | nullYes
data.created_atstring (date-time)Yes
data.updated_atstring (date-time)Yes
data.attach_openintegerYes(min -9007199254740991, max 9007199254740991)
data.pending_changesbooleanYes
data.profile_revisionintegerYes(min -9007199254740991, max 9007199254740991)
correlation_idstring (uuid)Yes
replayedbooleanNotrue when this command_id was already applied and the stored receipt came back

New fields can appear at any time; ignore the ones you do not know.

Errors

CodeHTTPRetryable
UNAUTHENTICATED401No
FORBIDDEN403No
RATE_LIMITED429Yes
VALIDATION_FAILED422No
NOT_FOUND404No
CONFLICT409No
OUTCOME_UNKNOWN202Yes
DEPENDENCY_UNAVAILABLE503Yes
UNKNOWN500No

Every error code and when to retry

All operations