BRbrumby
device launch intents

Create Intent

Place an intent. The action-worker publishes it retained.

The idempotency key is REQUIRED, and it is not ceremony. A retried POST without one would place a second intent with a second id, and the dock dedupes by id -- so two rows are two launches, however carefully the dock behaves.

post/api/v1/devices/{device_id}/launch-intents

Request

  • Base URL
    https://api.brumby.com (the document declares no server; this is the origin it was published from)
  • URL
    https://api.brumby.com/api/v1/devices/{device_id}/launch-intents
  • Auth
    HTTP bearer

Path parameters

device_idstring required

Headers

Idempotency-Keystring nullable

Request body

intent_type'launch' | 'open' | 'close' | 'hold' | 'recall' | 'clear_fault' required

Doc 04 §1.1's intent vocabulary. launch and recall have dock seams.

The rest are declared because the dock's own contract declares them, and a type it does not handle is logged and ignored rather than mistaken for a launch.

parametersobject nullable
valid_fromstring date-time nullable
valid_untilstring date-time nullable

Response

Successful Response

intent_idstring uuid required
device_idstring required
intent_type'launch' | 'open' | 'close' | 'hold' | 'recall' | 'clear_fault' required

Doc 04 §1.1's intent vocabulary. launch and recall have dock seams.

The rest are declared because the dock's own contract declares them, and a type it does not handle is logged and ignored rather than mistaken for a launch.

state'pending' | 'published' | 'acknowledged' | 'refused' | 'withdrawn' | 'failed' required

FleetOps-side lifecycle of one intent.

Shorter than a diagnostic action's, and the difference is the point: an intent is RETAINED, so the broker owns redelivery. There is no publishing/accepted dance to track, because the dock may collect it minutes later on reconnect and that is correct rather than late.

WITHDRAWN is a real state and not a deletion: clearing a standing intent means publishing an empty retained payload, which is an act that has to be recorded.

parametersobject nullable required
requested_by_actorstring required
valid_fromstring date-time required
valid_untilstring date-time required
published_atstring date-time nullable required
withdrawn_atstring date-time nullable required
acknowledged_atstring date-time nullable
disposition'accepted' | 'refused' | 'ignored'

What the dock reported doing with a collected intent, verbatim.

ignored is a type with no supervisor seam (open/close/hold today) — recorded as REFUSED state-wise, but the word is kept because "the dock cannot do this yet" and "preflight said no" are different answers.

disposition_detailobject nullable
last_errorstring nullable required
created_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.