Caravans

The static caravan stock: owned inventory units with make, model, year, purchase details and dimensions. Caravans can be assigned to pitches and owners (assignment happens through the dashboard's pitch-owner flows) and removed from stock. Numbers from your stock list belong in metadata.stock_number.

The caravan object

{
  "id": "cR4v4nX",
  "object": "caravan",
  "make": "Willerby",
  "model": "Herald",
  "year": "2010",
  "status": "available",
  "purchase_price": "",
  "length_m": "",
  "width_m": "",
  "max_sleeping_capacity": "",
  "assigned_to": { "owner_id": null, "pitch_number": null },
  "removed_date": null,
  "notes": null,
  "created": 1793061121,
  "metadata": { "stock_number": "3" }
}

status: available | assigned | removed. year is a string (matching the dashboard's model).

Endpoints

Method	Path	Description
GET	/v1/caravans	List (filter: status)
POST	/v1/caravans	Create one
POST	/v1/caravans/bulk	Paste endpoint — ingest a whole stock list
GET	/v1/caravans/{id}	Retrieve
PATCH	/v1/caravans/{id}	Update details (never status)
DELETE	/v1/caravans/{id}	Remove from stock (soft)

Bulk ingest (the paste endpoint)

Send an entire stock list in one request. Every field is optional per row — stock lists often have gaps — and per-row outcomes are reported so an agent can retry only the failures:

curl -s $API/v1/caravans/bulk -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: stock-import-1" -H "Content-Type: application/json" \
  -d '{
        "caravans": [
          {"make": "Willerby", "model": "Herald", "year": 2010,
           "metadata": {"stock_number": "3", "type": "Static"}},
          {"make": "Atlas", "model": "Moonstone", "year": 2006,
           "metadata": {"stock_number": "2", "type": "Static"}},
          {"metadata": {"stock_number": "13", "type": "Static"}}
        ]
      }'

Rows with unknown fields land in errors with their index. Status codes: 200 when at least one row committed (check errors for the rest), 400 when every row failed.

Updates and removal

PATCH updates details and merges metadata; it never changes status — assignment flows own assigned, and DELETE marks the caravan removed with a removed_date. Removing an already-removed caravan returns validation_failed.