API Reference

Poll a queued command's status and outcome

Returns the current status of a previously queued dock command and, once it has resolved, the hardware outcome. Poll it after the 202 from dock_send_command and stop once status is succeeded, failed or unknown. Against a real dock poll no faster than once per second: a stroke takes tens of seconds and the state changes a handful of times. The sandbox resolves in about a second and limits reads per IP to 30 per 10 seconds, which is why the quickstart samples poll it every 100 ms for a few seconds at most. outcome is only present once status leaves queued/executing.

`GET /api/v1/docks/{dockId}/commands/{commandId}`

Production: GET https://outpost.earthity.com/api/v1/docks/{dockId}/commands/{commandId}
Sandbox: GET https://outpost.earthity.com/api/sandbox/v1/docks/{dockId}/commands/{commandId}
Gate: credentialed
Read-only: true
Destructive: false
Idempotent: true

Parameters

Name	In	Required	Type	Description
`dockId`	path	yes	`string`	The dock the command targets.
`commandId`	path	yes	`string`	The command id returned by dock_send_command.

Responses

`200` - Current command status.

Property	Type	Required	Constraints	Description
`commandId`	`string`	no	-
`status`	`string`	no	enum: queued, executing, succeeded, failed, unknown	Open set: clients must tolerate additional values added in the future without a version bump. `queued` and `executing` are non-terminal and carry no `outcome`. `succeeded` and `failed` are terminal and always carry one. `unknown` is ALSO terminal but carries no `outcome`: it means the dock’s result never reached Outpost before the timeout elapsed (the standard read after a lost result, not an edge case); the command may or may not have physically completed, and no further status change should be expected.
`outcome`	`string`	no	enum: AT_ENDSTOP, OBSTRUCTED, TIMEOUT_FAULT, STOPPED_LOCAL	Pico hardware classification of how an actuation resolved. This set may GROW without a version bump - clients must tolerate values they do not recognise and treat them as neither success nor failure. It was narrowed once, on 2026-08-16, when KICK and RUN were removed: neither had ever been emitted by any firmware and neither had a defined physical meaning, and an undefined value in a published contract is worse than a smaller vocabulary (ADR-012). The terminal `status` is determined by the outcome and is not independently chosen: AT_ENDSTOP resolves as `succeeded`; OBSTRUCTED, TIMEOUT_FAULT and STOPPED_LOCAL resolve as `failed`. STOPPED_LOCAL was ADDED on 2026-08-23 - a person pressed the stop button at the dock, so the stroke ended deliberately and the door is somewhere unknown. It is a failure in the same sense TIMEOUT_FAULT is (no position was established), not a malfunction, and this is exactly the growth the paragraph above warns clients to tolerate. (Reporting a jammed door as `succeeded` is a contract violation, not an implementation choice; the shared contract suite asserts this pairing.)
`completedAt`	`string`	no	format: date-time	When this command reached a terminal status. Absent while `queued`/`executing`. Present for `succeeded`/`failed` (the moment the executor’s result was ingested) and for `unknown` (the moment the result timeout elapsed). Clients need this to present dock state honestly: there is no position sensor, so a terminal outcome is an inference about one past stroke, not a live reading; its AGE is what tells a caller whether the inference is still worth trusting. Without it a client can only time from its own session, so the belief is lost on reload.
`failureReason`	`string`	no	-	Why a command that never actuated did not run (`busy_local`, `busy`, `stopped_local`, `at_limit`, `position_unknown`, …), or — beside a `STOPPED_LOCAL` outcome — who ended the stroke: `lever_override` (a person took the lever) or `stop_button` (the stop button at the dock). Omitted when the row carries none. The vocabulary may grow without a version bump; treat an unrecognised value as an opaque reason. Same field `dock_command_list` entries carry.

`401` - Not signed in.

Body: application/problem+json - see Problem anatomy.

`404` - Unknown dock, or a dock this credential has no relationship with — the two are deliberately indistinguishable. A 403 here would confirm that a dock id belonging to another tenant is real, which turns this route into an enumeration oracle over other people’s hardware.

Body: application/problem+json - see Problem anatomy. Body: application/problem+json - see Problem anatomy.

`503` - Fail-closed unavailable: the command-state store, or the rate limiter that meters this read, cannot be reached, so the read is refused rather than served unmetered.

Body: application/problem+json - see Problem anatomy.

Get started

Dashboard

API Reference

Errors

Poll a queued command's status and outcome

`GET /api/v1/docks/{dockId}/commands/{commandId}`

Parameters

Responses

`200` - Current command status.

`401` - Not signed in.

`404` - Unknown dock, or a dock this credential has no relationship with — the two are deliberately indistinguishable. A 403 here would confirm that a dock id belonging to another tenant is real, which turns this route into an enumeration oracle over other people’s hardware.

`503` - Fail-closed unavailable: the command-state store, or the rate limiter that meters this read, cannot be reached, so the read is refused rather than served unmetered.

Errors

​GET /api/v1/docks/{dockId}/commands/{commandId}

​Parameters

​Responses

​200 - Current command status.

​401 - Not signed in.

​404 - Unknown dock, or a dock this credential has no relationship with — the two are deliberately indistinguishable. A 403 here would confirm that a dock id belonging to another tenant is real, which turns this route into an enumeration oracle over other people’s hardware.

​503 - Fail-closed unavailable: the command-state store, or the rate limiter that meters this read, cannot be reached, so the read is refused rather than served unmetered.

​Errors

`GET /api/v1/docks/{dockId}/commands/{commandId}`

Parameters

Responses

`200` - Current command status.

`401` - Not signed in.

`404` - Unknown dock, or a dock this credential has no relationship with — the two are deliberately indistinguishable. A 403 here would confirm that a dock id belonging to another tenant is real, which turns this route into an enumeration oracle over other people’s hardware.

`503` - Fail-closed unavailable: the command-state store, or the rate limiter that meters this read, cannot be reached, so the read is refused rather than served unmetered.

Errors