customer launch intents

Create Farm Recall

Recall the aircraft of this farm. The phone's ABORT button ends here.

THE DEVICE IS RESOLVED, NEVER SUPPLIED. Same rule as the customer mission route: a phone naming its own target could recall somebody else's aircraft by typing a different id. The farm's one active N100 is looked up here; two of them is a 409 and none is a 404, because guessing which to recall is not a thing software should do.

WHAT HAPPENS NEXT, so the shape of this handler makes sense: the row is published retained to the dock, whose supervisor holds it as STATE -- not gated on preflight, not gated on the aircraft being airborne -- and dock-mav then sends BRUMBY_DOCK_ABORT at 1 Hz for as long as it stands, deliberately even into a link that reads stale. The Cube changes its own flight mode on receipt and flies the recovery itself. So this endpoint's job is only to make the standing instruction exist; nothing downstream is waiting on this response.

THE IDEMPOTENCY KEY IS REQUIRED, for the reason the admin route gives: a retried POST without one places a second intent with a second id, and two rows are two recalls. Here it also matters in the other direction -- a panicking operator pressing ABORT four times should place ONE recall, not four.

post/api/v1/customer/farms/{farm_id}/recall

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/customer/farms/{farm_id}/recall
  • Auth
    none declared

Path parameters

farm_idstring required

Headers

Idempotency-Keystring nullable
X-Brumby-Customer-User-Idstring nullable
X-Request-Idstring nullable

Request body

action'rth' | 'recover' | 'cancel_launch'
reasonstring

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.