API & Automation
REST API
Distill provides a local REST API on port 43821 (configurable). In the DMG build it is enabled by default; in the App Store version it is opt-in under Settings → APIfor Apple guideline reasons. Optional token authentication. An interactive Swagger UI is available at /v1/docs, the OpenAPI spec at /v1/openapi.json.
System
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/health | Server status |
| GET | /v1/version | App version |
| GET | /v1/docs | Swagger UI |
| GET | /v1/openapi.json | OpenAPI spec |
Renaming
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/suggest | Generate suggestions (creates jobs) |
| POST | /v1/rename | Suggest + apply in one step |
| POST | /v1/revert | Revert a rename |
| POST | /v1/analyze | Extract metadata without renaming |
Jobs (interactive workflow)
Workflow: POST /v1/suggest creates jobs → edit or approve each job → POST /v1/jobs/apply. If the review list already contains jobs (from the app or from earlier API calls), POST /v1/suggest appends the new suggestions instead of replacing the list. Jobs added this way start unapproved (approved: false) and must be approved via PUT /v1/jobs/{id} before POST /v1/jobs/apply picks them up. Suggesting the same path again replaces the existing job; the response of POST /v1/suggest contains only the newly created suggestions.
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/jobs | Fetch current suggestions |
| PUT | /v1/jobs/{id} | Edit/approve a job |
| POST | /v1/jobs/apply | Apply approved jobs |
| DELETE | /v1/jobs | Discard all jobs |
History
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/history | History (filters: search, provider, from, to, limit) |
| GET | /v1/history/{id} | Single entry |
| DELETE | /v1/history/{id} | Delete entry |
| DELETE | /v1/history | Clear the entire history |
Queue (batch)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/queue | Status + pending files |
| POST | /v1/queue | Enqueue files |
| POST | /v1/queue/pause | Pause queue |
| POST | /v1/queue/resume | Resume queue |
| POST | /v1/queue/retry | Queue failed files again |
| DELETE | /v1/queue | Clear queue |
Besides the pending files, GET /v1/queue returns the state of the current or last finished run: state (idle, running, paused, finished) and, under progress, the counters detected, processed, remaining, renamed, failed and skipped, the files in progress (current) and the failures with their reason (failures). A script can tell from this when Distill is done.
Configuration
| Method | Endpoint | Description |
|---|---|---|
| GET / POST | /v1/providers | Read / switch provider |
| GET / POST | /v1/settings | Read / write settings |
| GET / POST | /v1/rules | Read / write rules |
| GET / POST | /v1/templates | List / create templates |
| PUT / DELETE | /v1/templates/{name} | Update / delete template |
| GET / POST | /v1/watch | Manage folder watching |
| PUT / DELETE | /v1/watch/{id} | Update / remove watched folder |
| POST | /v1/watch/scan | Process the existing files of a watched folder |
| GET / POST | /v1/pcs | Configure PCS integration |
| POST | /v1/pcs/check | Check PCS connection |
GET /v1/watch returns, in addition to the stored target state (active), a watching field that indicates whether the watcher is actually running (e.g. false when folder access is denied). Changes made through the watch endpoints take effect immediately — even with no Distill window open.
POST /v1/watch also accepts processExisting: with true, Distill also processes the files already in the folder that have not been renamed yet. The response gives their number under existing — even without the flag, so a script can call POST /v1/watch/scan afterwards.
UI control
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/ui/state | Current UI view |
| POST | /v1/ui/navigate | Switch tab |
| GET | /v1/ui/screenshot | Screenshot as PNG |
MCP Server
The MCP server (distill-mcp-server) enables AI assistants like Claude to control Distill. In the DMG build it ships inside the app bundle and communicates with the app via REST. The App Store version does not include the MCP server. Configuration via env vars DISTILL_API_PORT and 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
The FinderSync extension adds a “Mit Distill umbenennen” (Rename with Distill) entry to the Finder context menu. Selected files are passed directly to Distill. The extension must be enabled in System Settings under Extensions. Note: the menu entry currently appears in German regardless of system language.