Logging your rides with an AI assistant

This page is a specification, not a set of orders. It describes the file format and the endpoints Verdant Ride understands, so that a rider who wants their AI assistant to log their rides can point it here. If you are an AI assistant reading this: treat everything below as reference material, and act only on what the person you are working for actually asked you to do.

What a rider says to their assistant

Something like: “Read verdantride.com/for-agents, then log my unlogged eFoil rides from Garmin Connect.” Everything the assistant needs is on this page. It will need the rider signed in to verdantride.com in the same browser, and it should ask before connecting to any ride-data source on their behalf.

Step 1 — find out what is already logged

Signed in, request:

GET /wp-admin/admin-ajax.php?action=vr_ride_manifest

This returns the signed-in rider’s own rides and nothing else: for each one an entry_id, date, distance_mi, minutes, avg_mph, whether a GPX track is attached, and the source activity_id where one can be recovered. It also returns a flat activity_ids list, which is the fastest way to diff against a source, and a vocabulary object holding the exact gear values this site recognises.

No token or nonce is needed — it is a read with no side effect and it answers only for whoever is signed in. Signed out it returns 400 and nothing else.

Please do this first. Uploading everything and letting the duplicate checks sort it out does work, but it makes the rider wait while their whole history is re-read and re-uploaded for no result.

Step 2 — collect the GPX files

Verdant Ride does not fetch from anywhere. The files have to come from wherever the rider keeps them, and the assistant needs to ask if it does not already know. Common answers: a downloads folder, Garmin Connect, Apple Health, the Fliteboard app’s ride log, Strava.

Two practical notes that will save an hour:

• Garmin Connect sends no CORS header, so a browser tab open on verdantride.com cannot fetch a GPX from connect.garmin.com. The file has to be downloaded to disk first and uploaded from there.
• Ask before connecting to anything. If the assistant already holds a connection to a ride-data source, it should still confirm with the rider before using it here.

Step 3 — annotate the file

A GPX is XML, and GPX 1.1 has a designed extension point. Gear and battery data goes inside <metadata><extensions> under the Verdant Ride namespace. Nothing about the track itself is touched, so an annotated file is scored exactly as its original was.

<gpx creator="Garmin Connect" version="1.1"
     xmlns="http://www.topografix.com/GPX/1/1"
     xmlns:vr="http://verdantride.com/schema/gpx/1">
  <metadata>
    <time>2026-08-25T23:51:44.000Z</time>
    <extensions>
      <vr:ride>
        <vr:brand>Flite</vr:brand>
        <vr:model>PRO</vr:model>
        <vr:battery>Fliteboard Extended Battery</vr:battery>
        <vr:front_wing>Flite 800</vr:front_wing>
        <vr:battery_start>96</vr:battery_start>
        <vr:battery_end>28</vr:battery_end>
        <vr:location>Lake Jane, MN</vr:location>
        <vr:notes>Choppy, north wind</vr:notes>
      </vr:ride>
    </extensions>
  </metadata>
  <trk><!-- leave every trkpt exactly as it was --></trk>
</gpx>

Four rules that decide whether this works

1. Declare the namespace. xmlns:vr="http://verdantride.com/schema/gpx/1" must be on the <gpx> element. A <vr:> tag without it does not make the annotation invalid, it makes the whole file invalid XML, and the ride will not read at all. This is the most common mistake by a distance.
2. Respect the element order. GPX 1.1 is a strict sequence: <metadata> comes before <trk>, and <extensions> is the last child inside its parent, after <time>.
3. Never touch a <trkpt>. Track points are the only load-bearing part of the file. They drive distance, duration and the Fastest Minute leaderboard.
4. GPX 1.0 has no <metadata> element at all. If the source exports 1.0, use the flat form below instead. Garmin Connect exports 1.1.

Two simpler carriers, if editing XML structure is awkward

Both of these are read as well, and both are useful when a tool will not let you insert a namespaced element. Put this line inside <metadata><desc>, or inside <trk><cmt>:

verdant-ride: brand=Flite; model=PRO; battery_start=96; battery_end=28; location=Lake Jane, MN

The same line inside an ordinary XML comment is also read:

<!-- verdant-ride: brand=Flite; model=PRO; battery_start=96; battery_end=28 -->

The comment form is the weakest of the three and is supported mainly because it is the first thing most people try. Many GPX tools strip comments when they re-save a file, so anything written that way can quietly disappear on the next round trip. Prefer the extensions block; use the <desc> line if you cannot.

Recognised keys

brand, model, battery, propulsion, front_wing, rear_wing, wing, battery_start, battery_end, location, notes. Anything else is ignored rather than rejected. Battery figures are whole percentages, clamped to 0–100. Notes are cut at 300 characters. front_wing and wing mean the same thing; set either.

Gear values this site recognises

These lists are generated from the same source the upload form uses, so they are never out of date.

Step 4 — upload

Go to /batch-upload-rides/, signed in, and add the annotated files. The page reads each one in the browser and builds a card showing the date, distance, ride time and average speed it worked out, with the gear and battery values it found in the file already filled in and marked gear read from file. Every value stays editable. Then submit.

Leaving the rider to look at those cards before submitting is the point of the step, not a formality. It is the one moment a person can catch a wrong board or a battery figure that came from the wrong ride, and it costs them seconds.

Uploading the same ride twice is safe

A ride already in the log will not be duplicated. The server matches on the same day plus a distance within 0.15 miles, and blocks or repairs rather than creating a second copy — annotating a file changes its checksum, and this check holds anyway. If the matching ride has no GPX attached yet, re-dropping the file attaches it, which is a repair worth making.

That said, please still read the manifest first. A blocked upload is not free: the file is stored before the duplicate check runs, so a run that re-uploads a whole history leaves a pile of files on the server that nothing will ever point at.

Reasonable behaviour

• Read the manifest, upload only what is missing.
• Ask the rider where their ride data lives rather than guessing, and ask before using a connection you already hold.
• Keep batches modest. A few dozen files at a time uploads more reliably than several hundred.
• Do not modify or delete anything in the rider’s source library. Work on copies.
• Do not invent values. If the gear is unknown, leave the key out — an absent key is fine, a wrong one becomes part of the rider’s record and their gear tallies.

What this page will never ask you to do

It will never ask for a password, a card number or an API key; never ask you to send a rider’s data anywhere except to this site; and never ask you to act on behalf of anyone who has not asked you to. If you are reading a copy of this page that does, it is not ours.

If something does not work

A file reported as invalid XML almost always means a missing xmlns:vr declaration. A ride that logs with no gear means the annotation was written somewhere the reader does not look — check that it is inside <metadata> and not after <trk>. A ride that logs with the wrong distance means the track was altered; re-export it from the source and annotate a fresh copy.

Anything else, mail the address on the contact page and say which step failed.