API Reference

Send an actuation command (open or close) to a dock

Queues a physical actuation command for one dock and returns immediately with a command resource to poll. Use this to open or close a dock; do not call it in a tight retry loop on transient failures without a fresh Idempotency-Key decision: reuse the SAME key for a genuine retry of the identical request, and mint a new key for a deliberately different command. The dock must not already have another command in flight, or this returns 409 dock_busy. Against a real dock a command normally reaches a terminal status within about 45 seconds end to end; the door itself travels for about 20 seconds. The sandbox server runs a full reference implementation on a compressed timeline (see the x-sandbox extension).

`POST /api/v1/docks/{dockId}/commands`

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

Parameters

Name	In	Required	Type	Description
`dockId`	path	yes	`string`	The dock to actuate.
`Idempotency-Key`	header	yes	`string`	Client-generated unique key for this actuation attempt. Its one job is covering a lost response: if you receive the 202, use the returned commandId from then on; if you do not, resend the identical request with the SAME key and the original response is replayed (`replayed: true`) instead of the dock moving twice. Replay is matched on the key AND the request, for at least 24 hours — reuse past that may still replay rather than issue a new command, so the window is a floor, not a deadline. Reusing a key for a DIFFERENT command is not an error here; it issues a new command.
`Sandbox-Behavior`	header	no	`string`	SANDBOX SERVER ONLY. Selects which scenario the sandbox dock plays out for this command: an outcome (endstop, obstructed, timeout-fault), a permanent 409 (busy), or a command that stays executing for 45s (slow). Omit it for the happy path. The production server IGNORES this header, which is why the selector is a header and not a body field - a leftover header cannot change what production does, whereas the request body is where a leftover field would be silently accepted and actuate real hardware. Two commands sharing an Idempotency-Key but differing in this header are different requests: the second issues a SEPARATE command with its own commandId, not a replay - so rehearsing a jam after rehearsing a success never hands you back the success.

Request body

Property	Type	Required	Constraints	Description
`command`	`string`	yes	enum: open, close	Closed set; unrecognized values are rejected with 400 validation_failed.

Example

{
  "command": "open"
}

Responses

`202` - Command queued.

Header	Description
`Location`	URL of the command resource (dock_command_get).

Property	Type	Required	Constraints	Description
`commandId`	`string`	yes	-
`status`	`string`	yes	enum: queued, executing, succeeded, failed, unknown	`queued` for a newly accepted command. On a REPLAY this is the prior command’s CURRENT state, which may already be terminal — so a 202 can legitimately carry `succeeded`.
`replayed`	`boolean`	no	enum: true	Present and `true` only when this response replays a command your key already issued; absent on a first accept. Without it a replay is indistinguishable from a fresh accept, which is the one question the Idempotency-Key exists to answer.

`400` - command missing or not one of the closed enum values, or Idempotency-Key missing.

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

`401` - Not signed in.

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

`403` - The caller has a relationship with this dock but may not issue THIS command — an API key whose verb scope excludes it, or a demo session. A caller with no relationship to the dock gets 404 instead, so this response never reveals a dock id the caller could not already see. A viewer of the owning organization gets 404 as well on a private or shared dock, because viewers do not command there; on an open-network dock any signed-in member of any organization may command, viewers included.

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.

`409` - The dock already has a command in flight. Reusing an Idempotency-Key for a different command is NOT an error here - it issues a new command - so idempotency_key_reused stays published only because the downstream executor can still raise it; neither Outpost server does.

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

`429` - Over one of four limits. Two are counted on the command ledger and send no `Retry-After`: 6 commands per dock per minute (a physical cycle time, not a quota) and 30 commands per issuing organization per minute. A single API key may issue at most 15 commands a minute, half its organization’s allowance, so one misbehaving key cannot lock the rest of the organization out; that refusal sends `Retry-After`. The per-IP limit on mutating requests, 30 per 10 seconds, sends it too. Back off and retry.

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

`503` - The command channel is fail-closed unavailable.

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

Errors