Zum Hauptinhalt springen

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

MethodEndpointDescription
GET/v1/healthServer status
GET/v1/versionApp version
GET/v1/docsSwagger UI
GET/v1/openapi.jsonOpenAPI spec

Renaming

MethodEndpointDescription
POST/v1/suggestGenerate suggestions (creates jobs)
POST/v1/renameSuggest + apply in one step
POST/v1/revertRevert a rename
POST/v1/analyzeExtract metadata without renaming

Jobs (interactive workflow)

Workflow: POST /v1/suggest creates jobs → edit or approve each job → POST /v1/jobs/apply.

MethodEndpointDescription
GET/v1/jobsFetch current suggestions
PUT/v1/jobs/{id}Edit/approve a job
POST/v1/jobs/applyApply approved jobs
DELETE/v1/jobsDiscard all jobs

History

MethodEndpointDescription
GET/v1/historyHistory (filters: search, provider, from, to, limit)
GET/v1/history/{id}Single entry
DELETE/v1/history/{id}Delete entry
DELETE/v1/historyClear the entire history

Queue (batch)

MethodEndpointDescription
GET/v1/queueStatus + pending files
POST/v1/queueEnqueue files
POST/v1/queue/pausePause queue
POST/v1/queue/resumeResume queue
DELETE/v1/queueClear queue

Configuration

MethodEndpointDescription
GET / POST/v1/providersRead / switch provider
GET / POST/v1/settingsRead / write settings
GET / POST/v1/rulesRead / write rules
GET / POST/v1/templatesList / create templates
PUT / DELETE/v1/templates/{name}Update / delete template
GET / POST/v1/watchManage folder watching
PUT / DELETE/v1/watch/{id}Update / remove watched folder
GET / POST/v1/pcsConfigure PCS integration
POST/v1/pcs/checkCheck PCS connection

UI control

MethodEndpointDescription
GET/v1/ui/stateCurrent UI view
POST/v1/ui/navigateSwitch tab
GET/v1/ui/screenshotScreenshot 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. Configuration via env vars DISTILL_API_PORT and DISTILL_API_TOKEN.

9 MCP tools: rename_files, suggest_names, revert_rename, get_rename_history, watch_folder, app_status, set_provider, get_rules, set_rules.

Finder Extension

The FinderSync extension adds a “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.