> ## Documentation Index
> Fetch the complete documentation index at: https://docs.earthity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an actuation command (open/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. Name approved and reserved 2026-08-03 (see contracts/README.md decision #1); a full reference implementation exists in the sandbox server (see x-sandbox at the document root) — the production route (viam task 3.6) is not yet built.

> **Reserved** — this name is approved and frozen, but the production route is not yet built. A full reference implementation exists in the sandbox — see the `servers` entry and `x-sandbox` extension in the spec.

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

* **Gate:** `session`
* **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. The server replays the first response for a duplicate key within a 24h window. The same key with a different request body is rejected with 409 idempotency\_key\_reused. |

## Request body

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

### Example

```json theme={null}
{
  "command": "open"
}
```

## Responses

### `202` — Command queued.

| Property    | Type     | Required | Constraints  | Description |
| ----------- | -------- | -------- | ------------ | ----------- |
| `commandId` | `string` | no       | —            |             |
| `status`    | `string` | no       | enum: queued |             |

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

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `401` — Not signed in.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `403` — Demo mode is read-only, or the caller lacks entitlement on this dock.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `404` — No such dock.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `409` — The dock already has a command in flight, or Idempotency-Key was reused with a different request body.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `429` — Too many requests from this IP.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

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

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

## Errors

* [validation\_failed](/errors/validation_failed)
* [unauthorized](/errors/unauthorized)
* [forbidden](/errors/forbidden)
* [demo\_read\_only](/errors/demo_read_only)
* [not\_found](/errors/not_found)
* [dock\_busy](/errors/dock_busy)
* [idempotency\_key\_reused](/errors/idempotency_key_reused)
* [rate\_limited](/errors/rate_limited)
* [command\_unavailable](/errors/command_unavailable)