Skip to content

REST API

The Herd REST API gives your own tools read access to one network. Version 1 is read-only.

  • Base path: /api/public/v1
  • Auth: Authorization: Bearer <key>
  • Format: JSON
  1. In the console, open Settings and find API keys.
  2. Give the key a label and choose its scopes.
  3. Copy the key. It starts with hk_live_ and is shown once; Herd stores only a hash of it.

Creating and revoking keys needs the Admin role. A key belongs to the network it was created in and sees only that network. Revoke a key from the same screen; it stops working at once.

Scope Grants
fleet:read Vehicles and hubs
rides:read Completed rides, without rider identity
mds:read The MDS feeds, for a city or regulator
Request Scope Returns
GET /me any The key’s label, scopes and network
GET /vehicles fleet:read Vehicles, paged. Add ?available=true for rentable bikes only
GET /vehicles/{vehicle_id} fleet:read One vehicle
GET /hubs fleet:read Every hub. Not paged
GET /rides rides:read Completed rides, newest first, paged. Add ?since= for rides after a time

A vehicle carries its plate, type, state, battery level, estimated range, position and current hub. A hub carries its name, position, rack count and whether it is disabled.

Terminal window
curl -H "Authorization: Bearer hk_live_…" \
"https://<your-api-host>/api/public/v1/vehicles?available=true&limit=100"

Paged endpoints take limit (1 to 500, default 50) and offset (default 0) and return:

{ "items": [], "total": 0, "limit": 50, "offset": 0 }

Errors are JSON with a detail field.

Status Meaning
401 The key is missing, wrong or revoked
403 The key lacks the scope. detail.code is insufficient_scope
404 No such vehicle
422 A query parameter is invalid. detail lists each problem

Settings also has Service keys. Those are for your own scripts to act as a staff account against the console’s internal API, with permissions you pick. That API is not versioned and can change without notice. For anything a third party will depend on, use the API keys described here.