Dock record API

Yard ledger token

Send the yard ledger token on every call in the Authorization header as a Bearer token. The yard desk issues a token when it opens a planner account. A token is scoped to one yard's records. This site does not mint tokens.

Authorization: Bearer YARD_LEDGER_TOKEN

Open a dock record

POST /dock-records opens one ship's stay in one berth. The undock in this example is the hour first asked, before any dispute.

curl https://api.commonsilo.com/v1/dock-records \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vessel":"M/V Harting","berth":"2","dock_in":"2026-10-06T06:40:00Z","undock":"2026-10-20T16:00:00Z"}'

{
  "record_id": "DS-184",
  "vessel": "M/V Harting",
  "berth": "2",
  "dock_in": "2026-10-06T06:40:00Z",
  "undock": "2026-10-20T16:00:00Z",
  "open_items": [],
  "dispute_count": 0,
  "counted_this_month": true
}

Revise the window

PATCH /dock-records/{record_id}/window changes the undock on the same record. The earlier hour remains available on the dispute timeline. The reason is stored with the change.

curl -X PATCH https://api.commonsilo.com/v1/dock-records/DS-184/window \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"undock":"2026-10-24T16:00:00Z","reason":"Boot-top coating and rudder stock survey are still open on this ship."}'

{
  "record_id": "DS-184",
  "undock": "2026-10-24T16:00:00Z",
  "previous_undock": "2026-10-20T16:00:00Z",
  "reason": "Boot-top coating and rudder stock survey are still open on this ship.",
  "counted_this_month": true
}

Write an open item back onto the ship

POST /dock-records/{record_id}/open-items is how the workshop puts unfinished work on the vessel. wrote_back must be true. A call that tries to park the item on a yard-wide list is rejected.

curl https://api.commonsilo.com/v1/dock-records/DS-184/open-items \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"item":"Rudder stock survey","remains_on_vessel":true,"wrote_back":true}'

{
  "record_id": "DS-184",
  "item_id": "OI-17",
  "item": "Rudder stock survey",
  "remains_on_vessel": true,
  "wrote_back": true,
  "separate_master_list": false
}

Read the dispute timeline

GET /dock-records/{record_id}/disputes returns the asked hours in order, including hours the planner did not accept.

curl https://api.commonsilo.com/v1/dock-records/DS-184/disputes \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN"

{
  "record_id": "DS-184",
  "disputes": [
    {
      "at": "2026-10-15T09:10:00Z",
      "by_role": "superintendent",
      "name": "M. Leclerc",
      "asked_undock": "2026-10-20T16:00:00Z",
      "accepted": false
    },
    {
      "at": "2026-10-16T15:40:00Z",
      "by_role": "planner",
      "name": "A. Pell",
      "asked_undock": "2026-10-24T16:00:00Z",
      "accepted": true
    }
  ]
}

Sign a row

POST /dock-records/{record_id}/signatures adds one signature row. The value of signed is window, open_items, dock_in, flood_up, or dispute_only.

curl https://api.commonsilo.com/v1/dock-records/DS-184/signatures \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"workshop_lead","name":"R. Okonkwo","signed":"open_items"}'

{
  "record_id": "DS-184",
  "name": "R. Okonkwo",
  "role": "workshop_lead",
  "signed": "open_items",
  "at": "2026-10-11T18:05:00Z"
}

Export the record

POST /dock-records/{record_id}/export returns one copy of the slip. pack is berth_copy, undock_packet, or ledger_line. An open dispute and an unsigned flood-up are included. They are not stripped.

curl -X POST https://api.commonsilo.com/v1/dock-records/DS-184/export \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pack":"undock_packet"}'

{
  "record_id": "DS-184",
  "pack": "undock_packet",
  "vessel": "M/V Harting",
  "berth": "2",
  "dock_in": "2026-10-06T06:40:00Z",
  "undock": "2026-10-24T16:00:00Z",
  "open_items": [
    "Port sea chest grids",
    "Rudder stock survey",
    "Boot-top coating, frames 42-58"
  ],
  "flood_up_signed": false,
  "dispute_open": true
}

Monthly record count

GET /ledger/record-count returns the qualifying dock records for a month, the floor, the rate, and the amount. A record edited several times in the month appears once. The records array in this example shows DS-184 only. A live payload lists every qualifying record.

curl "https://api.commonsilo.com/v1/ledger/record-count?month=2026-10" \
  -H "Authorization: Bearer YARD_LEDGER_TOKEN"

{
  "month": "2026-10",
  "rate_dollars": 48,
  "floor": 8,
  "qualifying_records": 22,
  "billed_records": 22,
  "amount_dollars": 1056,
  "records": ["DS-184"]
}

Wrong role on a signature

A workshop lead can write an open item back onto the ship. Flood-up is signed by the dockmaster. The API refuses the crossed signature and leaves the row unsigned.

{
  "error": "role_cannot_sign",
  "record_id": "DS-184",
  "detail": "A workshop lead can write an open item back onto the ship. Flood-up is signed by the dockmaster."
}