Devices

Ask to open a control session on a device

Needs an active mandate carrying a device.* capability that names this device. Creates the device lane (the person is a silent observer) and asks the DEVICE, which approves or declines locally. Nothing is sent to the lane until the session is active. A device has ONE controller: when another agent holds it (or the device is being asked), this answers 202 with {session} in status queued and a 1-based position; the session is promoted when the controller ends and the agent is told by a device_session delivery (event: promoted, queue_moved). At most 5 wait per device (422); a queued session expires after 30 minutes (queue_expired). Cancel with DELETE /device_sessions/{id}.

post/api/v1/devices/{device_id}/sessions

Request

  • Base URL: https://saltapp.ai
  • URL: https://saltapp.ai/api/v1/devices/{device_id}/sessions
  • Auth: API key in header api-key

Path parameters

device_idstring required

Request body

intentstring

What you are about to do, in one line. Plain text, shown to the person at the machine as what the agent says. Control and bidi characters are stripped and whitespace collapsed; over 140 characters after that is a 422 intent_too_long.

Response

Requested.

idstring
agent_idstring
device_idstring
mandate_idstring
chat_idstring

The device lane the encrypted commands ride.

status'queued' | 'requested' | 'active' | 'paused' | 'ended'
requested_atstring date-time
started_atstring date-time nullable
ended_atstring date-time nullable
end_reason'declined' | 'stopped_by_person' | 'stopped_by_agent' | 'stopped_by_device' | 'mandate_revoked' | 'mandate_paused' | 'mandate_expired' | 'mandate_changed' | 'agent_blocked' | 'lost_contact' | 'request_expired' | 'budget_exhausted' | 'duration_limit' | 'device_removed' | 'device_reenrolled' | 'queue_expired' | 'agent_idle' | 'agent_removed' nullable
last_beat_atstring date-time nullable
positioninteger nullable

1-based place in the device's queue while status is queued.

pause_reason'person_active' | 'secure_field' | 'person' | 'other' | 'phone' nullable
lease_expires_atstring date-time nullable

Idle lease; each accepted command (reported by the device) pushes it out. Null while paused.

last_seqinteger

Last command sequence the device reported.

capabilitiesobject
action_countsobject
intentstring nullable

What the agent says it is doing. Agent-authored, untrusted plain text: shown, never interpreted. At most 140 characters after cleaning.

Changes

No recorded changes to this operation across all 2 revisions of this API.