> ## 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.

# Create a dock

> Creates a new Dock owned by the caller's org, finding-or-creating a Site for the given address. Use this to onboard a new physical dock into a host's fleet; only an admin of the owning org may call it (viewers are read-only) and demo sessions are rejected. `accessMode` defaults to `open` and determines which network the dock is placed in (its own private net, or the shared open net); changing it later is a PATCH, not a re-create.

## `POST /api/docks`

* **Gate:** `session`
* **Read-only:** `false`
* **Destructive:** `false`
* **Idempotent:** `false`

## Request body

| Property         | Type     | Required | Constraints                                  | Description                                                                            |
| ---------------- | -------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
| `name`           | `string` | yes      | maxLength: 200                               |                                                                                        |
| `address`        | `string` | yes      | maxLength: 300                               |                                                                                        |
| `latitude`       | `number` | yes      | minimum: -90; maximum: 90                    |                                                                                        |
| `longitude`      | `number` | yes      | minimum: -180; maximum: 180                  |                                                                                        |
| `pricePerMinute` | `number` | yes      | minimum: 0; maximum: 100000                  |                                                                                        |
| `accessMode`     | `string` | no       | enum: private, shared, open; default: "open" | Closed set; unrecognized values are rejected. Governs which network the dock lands on. |

### Example

```json theme={null}
{
  "name": "Rooftop Alpha",
  "address": "123 Main St",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "pricePerMinute": 2.5,
  "accessMode": "open"
}
```

## Responses

### `201` — The created dock.

| Property         | Type     | Required | Constraints       | Description                                                                                |
| ---------------- | -------- | -------- | ----------------- | ------------------------------------------------------------------------------------------ |
| `id`             | `string` | no       | —                 |                                                                                            |
| `callsign`       | `string` | no       | —                 | Two-word callsign: the stored slug for real docks, derived from the id for synthetic rows. |
| `name`           | `string` | no       | —                 |                                                                                            |
| `rooftop`        | `object` | no       | —                 | The dock's Site (legacy name retained).                                                    |
| `latitude`       | `number` | no       | —                 |                                                                                            |
| `longitude`      | `number` | no       | —                 |                                                                                            |
| `status`         | `string` | no       | —                 | Open set; stored status only, not derived from live occupancy.                             |
| `pricePerMinute` | `number` | no       | —                 |                                                                                            |
| `createdAt`      | `string` | no       | format: date-time |                                                                                            |
| `earningsToDate` | `number` | no       | —                 | Always 0 until the v2 booking backend lands.                                               |

#### `rooftop`

| Property  | Type     | Required | Constraints | Description |
| --------- | -------- | -------- | ----------- | ----------- |
| `id`      | `string` | no       | —           |             |
| `address` | `string` | no       | —           |             |

### `400` — name/address/latitude/longitude/pricePerMinute/accessMode failed validation.

| 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 is not an admin of any org.

| 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 |
| -------- | -------- | -------- | ----------- | ----------- |
| `error`  | `string` | no       | —           |             |

## Errors

* [validation\_failed](/errors/validation_failed)
* [unauthorized](/errors/unauthorized)
* [demo\_read\_only](/errors/demo_read_only)
* [forbidden](/errors/forbidden)
* [rate\_limited](/errors/rate_limited)