Vehicles.md

 # Vehicles
 
-Vehicles and their attached data will work pretty much as documented in the IronAPI documentation.
\ No newline at end of file
+[[TOC]]
+
+Vehicles and their attached data will work pretty much as documented in the [IronAPI documentation](https://bitbucket.org/ironapigenesis/ironapi-gw/wiki/Home).
+
+According to the client which is logged in, their universe will list the available options to [list](https://bitbucket.org/ironapigenesis/ironapi-gw/wiki/Queries) and [change](https://bitbucket.org/ironapigenesis/ironapi-gw/wiki/Transitions) the data.
+
+Many entites have "created" and "owning_vehicle" as attributes - these are always optional and will be set automatically, so best to never show them in forms and never send them. Exception: when creating or changing a vehicle, owning_client is required and needs to be set by the user.
+
+Some entities are only available to certain client agendas (e.g. vehicle_note). Sending a query joining this entity will result in an error, so do not do this.
+
+## Example
+
+List all vehicles, filter by band "Renault", join internal notes, attached files and their type definitions:
+
+```
+#!json
+
+# POST {{url}}/data/core/vehicle/query
+{
+  "conds" : {"me.brand" : "Renault"},
+  "attrs" : {
+    "prefetch" : ["core__vehicle_note__vehicle", {"core__vehicle_file__vehicle" : "vehicle_document_type"}]
+  }
+}
+```
+
+Note that this query will fail for clients without "admin" or "employee" agendas, as they have no access to "vehicle_note".
+
+core__vehicle_file__vehicle.id can be used to show a [download](https://bitbucket.org/ironapigenesis/ironapi-gw/wiki/Storing-Files) button for the file. The Link will looks something like this
+
+```
+#!
+
+{{url}}/data/core/file/3/download/file
+```
\ No newline at end of file