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
Create a key
Section titled “Create a key”- In the console, open Settings and find API keys.
- Give the key a label and choose its scopes.
- 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.
Scopes
Section titled “Scopes”| Scope | Grants |
|---|---|
fleet:read |
Vehicles and hubs |
rides:read |
Completed rides, without rider identity |
mds:read |
The MDS feeds, for a city or regulator |
Endpoints
Section titled “Endpoints”| 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.
curl -H "Authorization: Bearer hk_live_…" \ "https://<your-api-host>/api/public/v1/vehicles?available=true&limit=100"Paging
Section titled “Paging”Paged endpoints take limit (1 to 500, default 50) and offset (default 0) and return:
{ "items": [], "total": 0, "limit": 50, "offset": 0 }Errors
Section titled “Errors”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 |
Service keys
Section titled “Service keys”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.