Register a ship

Adds a ship to the harbor's register.

POST /ships

Warning

A ship's type cannot be changed once it is registered.

Authorization

bearerAuth Authorization: Bearer <token>

Any token will do here. Without one the answer is a 401.

Header parameters

Idempotency-Key? string

Repeat a request safely.

Format uuid

Request body

application/json Required

name* string

Range 2 ≤ value ≤ 80

type* string

What the ship carries.

Value in cargo tanker ferry tug

id? integer

Format int64

tonnage? number

Gross tonnage.

Format float Range 0 ≤ value ≤ 500000

captain? object

Whoever is in command right now.

Properties

name* string

licence? string

Pattern ^[A-Z]{2}\d{6}$

crew? array<object>

Properties

name? string

role? string

Value in deck engine galley

escort? Ship

Repeats Ship

registeredAt? string

Format date-time

Responses

201 The ship as registered. application/json

name* string

Range 2 ≤ value ≤ 80

type* string

What the ship carries.

Value in cargo tanker ferry tug

id? integer

Format int64

tonnage? number

Gross tonnage.

Format float Range 0 ≤ value ≤ 500000

captain? object

Whoever is in command right now.

Properties

name* string

licence? string

Pattern ^[A-Z]{2}\d{6}$

crew? array<object>

Properties

name? string

role? string

Value in deck engine galley

escort? Ship

Repeats Ship

registeredAt? string

Format date-time

422 The ship did not pass validation. application/json

message* string

errors? object

Request

curl -X POST 'https://vellum.jimmyverburgt.com/harbor/v2/ships' \
  -H 'Authorization: Bearer <token>' \
  -H 'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "name": "Aurora",
    "type": "cargo",
    "tonnage": 48200,
    "captain": {
        "name": "Ada Vos",
        "licence": "NL204518"
    },
    "crew": [
        {
            "name": "Tomas Lind",
            "role": "deck"
        }
    ],
    "registeredAt": "2026-01-31T09:00:00Z"
}'

$response = Http::withToken('<token>')
    ->withHeaders([
        'Idempotency-Key' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    ])
    ->post('https://vellum.jimmyverburgt.com/harbor/v2/ships', [
        'id' => 1,
        'name' => 'Aurora',
        'type' => 'cargo',
        'tonnage' => 48200,
        'captain' => [
            'name' => 'Ada Vos',
            'licence' => 'NL204518',
        ],
        'crew' => [
            [
                'name' => 'Tomas Lind',
                'role' => 'deck',
            ],
        ],
        'registeredAt' => '2026-01-31T09:00:00Z',
    ]);

const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/ships', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Idempotency-Key': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": 1,
      "name": "Aurora",
      "type": "cargo",
      "tonnage": 48200,
      "captain": {
          "name": "Ada Vos",
          "licence": "NL204518"
      },
      "crew": [
          {
              "name": "Tomas Lind",
              "role": "deck"
          }
      ],
      "registeredAt": "2026-01-31T09:00:00Z"
  })
})

Response

{
    "id": 1,
    "name": "Aurora",
    "type": "cargo",
    "tonnage": 48200,
    "captain": {
        "name": "Ada Vos",
        "licence": "NL204518"
    },
    "crew": [
        {
            "name": "Tomas Lind",
            "role": "deck"
        }
    ],
    "registeredAt": "2026-01-31T09:00:00Z"
}

{
    "message": "The name field is required.",
    "errors": []
}