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

sessions.detach

Release your app hold without stopping the browser: it stays warm for keep_warm_seconds (0–1800) and stops then unless a person, a run or an app takes it again.

Capability: session.startCommand (idempotent)MCP tool: sessions_detach
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.
generationbodyintegerYeslease.generation from acquire (min 1, max 9007199254740991)
holder_refbodystringYesYour stable name for this holder (worker, job); renew and detach must send the same value (min length 1, max length 120)
keep_warm_secondsbodyintegerNoOverride the keep-warm time given at acquire (min 0, max 1800)

Examples

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

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.leaseobjectYesYour app's hold after letting go
data.lease.session_idstring (uuid)Yes
data.lease.app_idstringYes
data.lease.binding_idstring (uuid) | nullNo
data.lease.holder_refstringYes
data.lease.generationintegerYesSend with renew and detach; an older generation is FENCED (min -9007199254740991, max 9007199254740991)
data.lease.state"active" | "detached" | "lapsed" | "ended"Yes
data.lease.ttl_secondsintegerYes(min -9007199254740991, max 9007199254740991)
data.lease.keep_warm_secondsintegerYes(min -9007199254740991, max 9007199254740991)
data.lease.acquired_atstring (date-time)Yes
data.lease.expires_atstring (date-time)Yes
data.lease.keep_warm_untilstring (date-time)No
data.lease.ended_reasonstringNo
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