REST-API

Die REST-API unter https://app.miovea.com/api/v1 bietet dieselben Operationen wie der MCP-Server, für Integrationen ohne KI-Agent. Die vollständige Referenz steht unter /api/v1/openapi.json (OpenAPI 3.1) und /api/v1/docs.

Zugang

• API-Key der Organisation: Authorization: Bearer mio_live_… für Produktion, mio_test_… für die Dev-Umgebung. Ein Admin erzeugt den Key in der App unter Einstellungen, Reiter KI-Zugriff, Abschnitt API-Keys; der Klartext erscheint genau einmal. Der Key gehört der Organisation, nicht der Person, die ihn erzeugt hat.
• Scopes: <domain>:read, <domain>:write (schließt read ein) und <domain>:destroy für endgültige Operationen. Spezialrechte stehen ausdrücklich als Scope: dispatch:send, settings:manage, members:manage, billing:manage, agents:manage, api_keys:manage. Die Domäne einer Operation nennt ihr Vertrag (domain); jobs.get und changes.list liegen in system.
• Schreibzugriffe über API-Keys unterliegen der Agenten-Richtlinie der Organisation; Versand läuft im Namen des Standardabsenders.
• Agenten können statt eines Keys ihr OAuth-Access-Token mit Scope user:org:read senden.

Routen

• Ressourcen-Routen leiten sich aus dem Key ab: customers.list ist GET /customers, customers.create ist POST /customers, preinquiries.get ist GET /preinquiries/{preinquiry_id}, send_packages.send ist POST /send-packages/{send_package_id}/send. Jede Route nennt ihre Operation in x-operation-key. Die Antwort ist die Ausgabe der Operation; schreibende Aufrufe liefern zusätzlich den Header X-Change-Set-Id.
• Generischer Aufruf: POST /api/v1/operations/{key}/invoke mit dem Input der Operation als JSON-Body. Antwort { data, change_set_id?, replayed? }.
• Katalog: GET /api/v1/operations?q=<stichwort> sucht Operationen, GET /api/v1/operations/{key} und GET /api/v1/operations/describe?keys=a,b liefern Verträge; diese drei und die OpenAPI-Datei sind ohne Anmeldung lesbar. liefert Organisation, Rolle, Richtlinie und die wichtigsten Verträge, die Guides.