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
directly — assignment flows own assigned, and DELETE marks the caravan
removed with a removed_date. Removing an already-removed caravan
returns validation_failed.
Assigning a caravan to an owner and pitch
Static caravans are linked to customers (pitch owners) and pitches with
one PATCH call. The relation mirrors the Pitch Owners dashboard page:
assigning sets the caravan to status: "assigned" with
assigned_to.owner_id (a pitchOwners document id) and
assigned_to.pitch_number, and writes a caravanId back-link onto the
owner document so both sides always agree:
curl -s $API/v1/caravans/car_abc123 -H "Authorization: Bearer $KEY" \
-X PATCH -H "Content-Type: application/json" \
-d '{"assigned_to": {"owner_id": "ownerDocId", "pitch_number": "S04"}}'
The response returns the caravan with status: "assigned" and the
resolved assigned_to. The pitch number must match the owner's own
pitch — a mismatch returns invalid_request_error naming the offending
parameter. Assigning an owner who already holds another caravan frees
that unit back to available, and reassigning a caravan clears the
previous owner's back-link; the relation is one-to-one by construction.
Unassign (owner departs, caravan returns to the resale pool):
curl -s $API/v1/caravans/car_abc123 -H "Authorization: Bearer $KEY" \
-X PATCH -H "Content-Type: application/json" \
-d '{"assigned_to": null}'
The caravan returns to status: "available", both link fields are
cleared and the owner's caravanId back-link is removed.
Removed caravans cannot be assigned — reinstate them first.