API & Automatisierung
REST-API
Distill bietet eine lokale REST-API auf Port 43821 (konfigurierbar). Im DMG-Build ist sie standardmäßig aktiv, in der App-Store-Version ist sie aus Apple-Richtliniengründen opt-in unter Einstellungen → API. Optionale Token-Authentifizierung. Eine interaktive Swagger-UI ist unter /v1/docs verfügbar, die OpenAPI-Spec unter /v1/openapi.json.
System
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET | /v1/health | Server-Status |
| GET | /v1/version | App-Version |
| GET | /v1/docs | Swagger-UI |
| GET | /v1/openapi.json | OpenAPI-Spec |
Umbenennung
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| POST | /v1/suggest | Vorschläge generieren (legt Jobs an) |
| POST | /v1/rename | Suggest + Apply in einem Schritt |
| POST | /v1/revert | Umbenennung rückgängig machen |
| POST | /v1/analyze | Metadaten extrahieren ohne Rename |
Jobs (interaktiver Workflow)
Workflow: POST /v1/suggest erzeugt Jobs → Jobs einzeln editieren oder genehmigen → POST /v1/jobs/apply. Enthält die Prüfliste bereits Jobs (aus der App oder aus früheren API-Aufrufen), hängt POST /v1/suggest die neuen Vorschläge an, statt die Liste zu ersetzen. Nachträglich hinzugefügte Jobs sind zunächst nicht genehmigt (approved: false) und müssen per PUT /v1/jobs/{id} genehmigt werden, bevor POST /v1/jobs/apply sie anwendet. Ein erneuter Suggest für denselben Pfad ersetzt den vorhandenen Job; die Antwort von POST /v1/suggestenthält nur die neu erzeugten Vorschläge.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET | /v1/jobs | Aktuelle Vorschläge abrufen |
| PUT | /v1/jobs/{id} | Job editieren/genehmigen |
| POST | /v1/jobs/apply | Genehmigte Jobs anwenden |
| DELETE | /v1/jobs | Alle Jobs verwerfen |
Verlauf
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET | /v1/history | Verlauf (Filter: search, provider, from, to, limit) |
| GET | /v1/history/{id} | Einzelner Eintrag |
| DELETE | /v1/history/{id} | Eintrag löschen |
| DELETE | /v1/history | Gesamten Verlauf löschen |
Warteschlange (Batch)
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET | /v1/queue | Status + wartende Dateien |
| POST | /v1/queue | Dateien einreihen |
| POST | /v1/queue/pause | Queue pausieren |
| POST | /v1/queue/resume | Queue fortsetzen |
| POST | /v1/queue/retry | Fehlgeschlagene Dateien erneut einreihen |
| DELETE | /v1/queue | Queue leeren |
GET /v1/queue liefert neben den wartenden Dateien den Stand des laufenden oder zuletzt abgeschlossenen Durchlaufs: state (idle, running, paused, finished) und unter progress die Zähler detected, processed, remaining, renamed, failed und skipped, die Dateien in Arbeit (current) sowie die Fehlschläge mit Grund (failures). Ein Skript erkennt daran, wann Distill fertig ist.
Konfiguration
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET / POST | /v1/providers | Provider lesen / wechseln |
| GET / POST | /v1/settings | Einstellungen lesen / setzen |
| GET / POST | /v1/rules | Regeln lesen / setzen |
| GET / POST | /v1/templates | Templates auflisten / anlegen |
| PUT / DELETE | /v1/templates/{name} | Template aktualisieren / löschen |
| GET / POST | /v1/watch | Ordnerüberwachung verwalten |
| PUT / DELETE | /v1/watch/{id} | Ordnerüberwachung aktualisieren / entfernen |
| POST | /v1/watch/scan | Vorhandene Dateien eines überwachten Ordners verarbeiten |
| GET / POST | /v1/pcs | PCS-Integration konfigurieren |
| POST | /v1/pcs/check | PCS-Verbindung prüfen |
GET /v1/watch liefert pro Ordner neben dem gespeicherten Soll-Zustand (active) auch das Feld watching, das anzeigt, ob die Überwachung tatsächlich läuft (z. B. false bei fehlendem Ordnerzugriff). Änderungen über die Watch-Endpoints wirken sofort — auch wenn kein Distill-Fenster geöffnet ist.
POST /v1/watch nimmt zusätzlich processExisting an: Mit true verarbeitet Distill auch die Dateien, die schon im Ordner liegen und noch nicht umbenannt sind. Die Antwort nennt ihre Zahl unter existing — auch ohne den Schalter, sodass ein Skript anschließend POST /v1/watch/scan aufrufen kann.
UI-Steuerung
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET | /v1/ui/state | Aktuelle UI-Ansicht |
| POST | /v1/ui/navigate | Tab wechseln |
| GET | /v1/ui/screenshot | Screenshot als PNG |
MCP-Server
Der MCP-Server (distill-mcp-server) ermöglicht KI-Assistenten wie Claude die Steuerung von Distill. Er wird im DMG-Build automatisch im App-Bundle mitgeliefert und kommuniziert via REST mit der App. In der App-Store-Version ist der MCP-Server nicht enthalten. Konfiguration via Env-Vars DISTILL_API_PORT und DISTILL_API_TOKEN.
13 MCP-Tools: rename_files, suggest_names, revert_rename, get_rename_history, watch_folder, process_existing_files, queue_status, app_status, set_provider, get_rules, set_rules, search_manual, get_manual_section.
Finder-Extension
Die FinderSync-Extension fügt einen Eintrag „Mit Distill umbenennen“ ins Kontextmenü des Finders ein. Ausgewählte Dateien werden direkt an Distill übergeben. Die Extension muss in den Systemeinstellungen unter Erweiterungen aktiviert sein.