Skip to content

API.md

Latest commit

 

History

History
207 lines (154 loc) · 3.93 KB

API.md

File metadata and controls

207 lines (154 loc) · 3.93 KB

HFDesk API

HFDesk exposes a local JSON API under /api. The web UI uses this API directly.

Error Format

Errors return JSON with a legacy flat error string and a structured error_detail object:

{
  "ok": false,
  "error": "Invalid request body",
  "details": "unexpected EOF",
  "error_detail": {
    "code": "bad_request",
    "message": "Invalid request body",
    "details": "unexpected EOF"
  }
}

Health

GET /api/health

Returns server status, version, and timestamp.

Search

GET /api/search?q=Qwen%20GGUF&sort=downloads&limit=40&filter=gguf
GET /api/search?datasets=true&q=fineweb

Searches Hugging Face models or datasets through the configured endpoint/proxy.

Analyze

GET /api/analyze/{owner}/{repo}?revision=main&dataset=false

Returns repository metadata, files, type-specific analysis, selectable download items, and recommended download defaults.

Important response fields:

{
  "repo": "owner/name",
  "is_dataset": false,
  "type": "gguf",
  "files": [],
  "selectable_items": [
    {
      "id": "q4_k_m",
      "label": "Q4_K_M",
      "filter_value": "q4_k_m",
      "recommended": true,
      "files": ["model-Q4_K_M.gguf"]
    }
  ],
  "recommended_filters": ["q4_k_m"],
  "recommended_download": {
    "repo": "owner/name",
    "filters": ["q4_k_m"]
  }
}

recommended_download is a ready-to-send request body for POST /api/download. It replaces the old CLI-command string contract.

Plan

POST /api/plan

Request:

{
  "repo": "owner/name",
  "revision": "main",
  "dataset": false,
  "filters": ["q4_k_m"],
  "excludes": [],
  "exactMatch": false
}

Returns the files that would be downloaded without starting a job.

Download

POST /api/download

Uses the same request shape as /api/plan. Starts or reuses a download job.

Notes:

  • repo is required and must be owner/name.
  • revision defaults to main.
  • cacheDir and global localDir are server-controlled.
  • Per-request localDir is accepted only where explicitly supported by server configuration.
  • Duplicate active downloads return the existing job.

Jobs

GET    /api/jobs
GET    /api/jobs/{id}
DELETE /api/jobs/{id}
POST   /api/jobs/{id}/pause
POST   /api/jobs/{id}/resume
POST   /api/jobs/{id}/dismiss

dismiss removes terminal jobs from the UI/state. Running or queued jobs must be cancelled first.

Settings

GET  /api/settings
POST /api/settings

Settings include runtime paths, concurrency, verification, endpoint, proxy settings, the HF cache directory, and extra local scan folders.

Storage fields:

{
  "cacheDir": "I:\\huggingface",
  "localDir": "D:\\Models",
  "localScanDirs": ["D:\\Models", "I:\\LM Studio\\models"]
}

cacheDir controls where HF cache-layout downloads are written. When localDir is set, downloads use real files under <localDir>/<owner>/<model>, which matches LM Studio-style model roots. localScanDirs are read-only model roots scanned as <owner>/<model> folders for the Cache browser and local badges in Hub search results.

Cache

GET    /api/cache
GET    /api/cache/{owner}/{repo}
POST   /api/cache/rebuild
DELETE /api/cache/{owner}/{repo}?type=model

Cache entries may come from:

  • HF cache
  • Friendly view
  • Local

downloadStatus is one of:

  • complete
  • filtered
  • unknown

Mirror

GET    /api/mirror/targets
POST   /api/mirror/targets
DELETE /api/mirror/targets/{name}
POST   /api/mirror/diff
POST   /api/mirror/push
POST   /api/mirror/pull

Mirror operations compare and synchronize cache roots to configured targets.

History and Disk

GET /api/history
GET /api/diskfree?path=/path/to/cache

/api/diskfree defaults to the resolved HF cache directory when no path is provided.

WebSocket

GET /api/ws

Messages use:

{
  "type": "job_update",
  "data": {}
}

Known message types:

  • job_update
  • event
  • status