Thanks to visit codestin.com
Credit goes to github.com

Skip to content

API_REFERENCE.md

Latest commit

 

History

History
188 lines (137 loc) · 5.34 KB

API_REFERENCE.md

File metadata and controls

188 lines (137 loc) · 5.34 KB

API Reference

ADM exposes a local Axum gateway for the desktop UI, CLI, browser extension, native host, and local automation. It is not a public LAN API.

Binding

Default base URL:

http://127.0.0.1:57423

Allowed REST bind addresses are loopback only: 127.0.0.1 and ::1.

Response Styles

Internal API routes generally use:

{
  "success": true,
  "data": {}
}

Browser-extension routes use:

{
  "ok": true
}

Extension errors include stable code values so clients do not need to branch on localized messages.

Discovery

GET /v1/ping

Public local discovery endpoint used by the browser extension and support checks.

{
  "ok": true,
  "app": "APEX Download Manager",
  "status": "healthy",
  "appVersion": "<tag-version>",
  "protocolVersion": 4,
  "minimumSupportedProtocolVersion": 2,
  "browserIntegrationEnabled": true
}

Pairing And Auth

POST /v1/pair/auto

Loopback-only, rate-limited zero-click pairing endpoint. It returns an opaque bearer token with a 30 day TTL when local trust requirements pass.

Native Messaging Pairing

The native host bridges JSON-RPC methods for browser startup pairing:

Method Purpose
browser.pair.auto / extension.pair.auto Silent trusted-local pairing
browser.pair.request / extension.pair.request One-click manual fallback

POST /v1/auth/check

Requires:

Authorization: Bearer <pairToken>

Returns compatibility and scopes:

{
  "ok": true,
  "protocolVersion": 4,
  "minimumSupportedProtocolVersion": 2,
  "scopes": ["downloads:add", "captures:report", "settings:read"]
}

Protected Extension Routes

These routes require a bearer pair token:

Method Path Purpose
GET /v1/extension-settings Extension runtime settings
POST /v1/add Add a download from the extension
POST /v1/task/add Add-task alias
POST /v1/tasks Add-task alias
POST /captures Report browser media captures
POST /v1/extract-page Authenticated extraction surface
POST /v1/site/mirror Authenticated site mirror surface
GET /v1/events Extension event stream

Tokens in query strings are rejected.

Task API

Method Path Purpose
GET /api/v1/tasks List tasks
POST /api/v1/tasks Create task
GET /api/v1/tasks/{id} Read task
PATCH /api/v1/tasks/{id} Update task metadata
DELETE /api/v1/tasks/{id} Delete task
POST /api/v1/tasks/{id}/pause Pause task
POST /api/v1/tasks/{id}/resume Resume task
POST /api/v1/tasks/{id}/retry Retry task
POST /api/v1/tasks/{id}/cancel Cancel task
POST /api/v1/tasks/{id}/verify Verify task
POST /api/v1/tasks/{id}/extract Extract archive

/api/v1/downloads mirrors the main task surface for compatibility and supports pagination/sorting.

Queues And Automation

Method Path Purpose
GET/POST /api/v1/queues List or create queues
GET/PATCH/DELETE /api/v1/queues/{id} Manage queue
POST /api/v1/queues/{id}/start Start queue
POST /api/v1/queues/{id}/pause Pause queue
POST /api/v1/queues/{id}/move-up Move queue up
POST /api/v1/queues/{id}/move-down Move queue down
GET/POST /api/v1/automation/rules List or create automation rules

System And Observability

Method Path Purpose
GET /api/v1/system/health Health
GET /api/v1/system/stats Runtime stats
GET /api/v1/system/capabilities Protocol and feature capabilities
POST /api/v1/system/shutdown Linked UI/daemon graceful shutdown
GET /api/v1/observability/live Live observability snapshot
GET /api/v1/observability/prometheus Prometheus metrics
GET /api/v1/production/readiness Production readiness diagnostics

Notifications

Method Path Purpose
POST /api/v1/notifications/test Send a test notification
POST /api/v1/notifications/send Send a runtime notification
GET /api/v1/notifications/spool List spooled notifications
POST /api/v1/notifications/spool/replay Replay spooled notifications

Error Codes

Extension auth and pairing can return:

  • TOKEN_MISSING
  • TOKEN_INVALID
  • TOKEN_EXPIRED
  • CLIENT_REVOKED
  • AUTO_PAIR_DISABLED
  • LOCALHOST_REQUIRED
  • RATE_LIMITED

Downloads listing pagination and sorting

GET /api/v1/downloads?page=2&per_page=50&sort=filename&order=asc

Valid sort fields include stable task metadata such as filename, state, created time, progress, and queue. The HTTP HEAD metadata cache keeps repeated metadata probes bounded.

WebDAV download-folder API

WebDAV access is constrained to the configured ADM download directory:

PROPFIND /api/v1/webdav/

The resolver rejects path traversal, absolute paths, and internal ADM directories. CLI parity is provided by adm-cli webdav list|stat|get|put; the CLI uploads put bodies as application/octet-stream.

CLI API Parity

Plugin registry administration is available through adm-cli plugins list|get|enable|disable|unload. WebDAV administration is available through adm-cli webdav list|stat|get|put.