Zum Inhalt springen

Für Entwickler

Alles, was du brauchst, um auf Sunshine aufzubauen.

REST-API

Eine JSON-API über HTTPS. Erstelle in deinen Kontoeinstellungen ein persönliches API-Token und sende es mit jeder Anfrage.

Basis-URL

https://sunshine.rescoot.org/api/v1

Authentifizierung

Sende dein Token im Authorization-Header. Ein persönliches API-Token hat vollen Zugriff auf dein Konto, halte es also geheim.

curl -H "Authorization: Bearer $SUNSHINE_TOKEN" \
  https://sunshine.rescoot.org/api/v1/scooters

API-Token erstellen

Was du erreichen kannst

  • Roller, ihr Status und ihre Telemetrie
  • Befehle: Verriegeln, Entriegeln, Blinker, Hupe, Töne, Sitzfach, Alarm, Ping, Hibernate
  • Navigationsziel und aktueller Standort
  • Fahrten, Ereignisse und Log-Bundles
  • Gespeicherte Ziele

Vollständige Referenz

Die komplette Endpunkt-Referenz mit Parametern und Antwortformaten liegt im Repository.

API-Referenz öffnen

OAuth

Baue eine App, die für andere Sunshine-Nutzer*innen handelt. Registriere eine OAuth-Anwendung und nutze dann den Authorization-Code-Flow mit PKCE.

Anwendung registrieren

Berechtigungsbereiche

read Kontodaten und Rollerdaten der Nutzer*innen lesen.
write Kontodaten der Nutzer*innen ändern.
scooter_control Befehle an den Roller der Nutzer*innen senden.

Ablauf

Authorization Code mit PKCE (S256). Öffentliche Clients brauchen nur eine Client-ID; vertrauliche Clients erhalten zusätzlich ein Secret. Refresh-Tokens werden ausgegeben.

Endpunkte

GET  /oauth/authorize
POST /oauth/token

Deine Nutzer*innen sehen einen Zustimmungsdialog mit dem Namen deiner App und den angefragten Berechtigungen.

MCP-Server

Sunshine spricht das Model Context Protocol, damit Assistenten wie Claude den Rollerstatus lesen und dieselben Befehle wie die Web-App ausführen können.

Endpunkt

POST https://sunshine.rescoot.org/mcp

Streamable HTTP. Anfragen und Antworten sind JSON-RPC über einen einzelnen POST.

Authentifizierung

Melde dich mit demselben Bearer-Token an wie bei der REST-API. Lesende Tools brauchen den Bereich read; Tools, die einen Befehl senden, brauchen scooter_control.

Tools

alarm clear_destination get_destination get_scooter get_state hibernate honk list_scooters list_trips locate_scooter lock_scooter open_seatbox ping_scooter play_sound set_blinkers set_destination unlock_scooter

Beispiel

curl -X POST https://sunshine.rescoot.org/mcp \
  -H "Authorization: Bearer $SUNSHINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Befehle gehen an den Roller. Eine erfolgreiche Antwort heißt also, dass der Befehl angenommen wurde, nicht dass er schon wirkt.