API Overview

This page groups the HTTP surface by feature instead of trying to duplicate the OpenAPI output.

Most user-facing JSON / REST endpoints live under:

/api/v1

Primary vs. Follower

The repository exposes two HTTP node modes:

• primary
  • ordinary user REST API
  • public sharing API
  • remote-node reverse-tunnel internal entry /api/v1/internal/remote-tunnel/*
  • WebDAV
  • frontend pages
  • health checks
• follower
  • health checks
  • internal object storage protocol /api/v1/internal/storage/*

So anything used by a browser, a frontend SDK, or a public share page is usually in this directory. The two internal paths above are between primary and follower nodes only.

Endpoints outside /api/v1

The following capabilities are intentionally mounted elsewhere:

• health checks: /health*
• direct download links: /d/{token}/{filename}
• preview links: /pv/{token}/{filename}
• WebDAV: default /webdav
• frontend pages, public share pages, and static fallback routes: registered last on the primary node

Unified response shape

Most JSON APIs use the same wrapper:

{
  "code": "success",
  "msg": "",
  "data": {}
}

Field meaning:

• code: stable string ApiErrorCode; success means success
• msg: human-readable fallback message
• data: payload, omitted by some successful endpoints

Error responses also include an error object:

{
  "code": "auth.credentials_failed",
  "msg": "Invalid Credentials",
  "error": {
    "retryable": false,
    "diagnostic": {
      "kind": "auth",
      "message": "Invalid Credentials"
    }
  }
}

The public error contract has one stable code source: the top-level code. The nested error object carries behavior hints such as retryable and optional redacted diagnostics under diagnostic.kind / diagnostic.message.

Storage connection tests, storage actions, and remote-node probes return administrator-facing failure context through error.diagnostic. Successful connection tests still return an empty success payload; probe details are no longer returned as a success response body.

Error-code rules

• Backend responses must write top-level code: ApiErrorCode.
• ApiErrorInfo may expose only retryable and redacted diagnostic; do not reintroduce code, subcode, internal_code, or api_code under error.
• New user-visible errors should add or reuse a stable ApiErrorCode instead of relying on message text.
• Client copy and branching should use code, while msg remains a human-readable fallback.

Non-JSON endpoints

The following responses are raw content instead of ApiResponse:

• file downloads
• direct download links
• preview links
• share stream sessions
• thumbnails
• image previews
• archive-download ZIP streams
• share file downloads
• share thumbnails
• share image previews
• uploaded avatars
• storage event streams
• WOPI CheckFileInfo and content callbacks
• WebDAV responses
• Prometheus metrics
• follower object streams /api/v1/internal/storage/objects/{tail:.*}
• primary reverse-tunnel WebSocket /api/v1/internal/remote-tunnel/connect

Public frontend bootstrap config (including branding fields), preview-app configuration, thumbnail support, media-data support, and remote enrollment are unauthenticated, but they are still ordinary /api/v1/public/* JSON endpoints. There is no separate /public/branding route.

Supported authentication modes

REST / frontend

• HttpOnly cookie
• Authorization: Bearer <jwt>

WebDAV

• Authorization: Basic ...

Follower internal storage protocol

• primary-signed headers:
  • x-aster-access-key
  • x-aster-timestamp
  • x-aster-nonce
  • x-aster-signature
• some object GET / PUT operations also accept presigned query parameters

Remote-tunnel internal entry

• the follower connects to the primary’s /api/v1/internal/remote-tunnel/* with remote-node signatures
• this entry is for reverse-tunnel polling, completion callbacks, and WebSocket streaming only

Workspace scopes

There are two protected workspace types:

• personal space: /files, /folders, /batch, /search, /shares, /tags, /trash
• team space: the same semantics, but prefixed with /teams/{team_id}

Typical team paths:

/api/v1/teams/{team_id}/folders
/api/v1/teams/{team_id}/files/{id}
/api/v1/teams/{team_id}/batch/move
/api/v1/teams/{team_id}/search
/api/v1/teams/{team_id}/shares
/api/v1/teams/{team_id}/tags
/api/v1/teams/{team_id}/trash
/api/v1/teams/{team_id}/tasks
/api/v1/teams/{team_id}/tasks/offline-download
/api/v1/teams/{team_id}/webdav-accounts

In other words, team spaces reuse the same file / folder / search / tag / trash / task / WebDAV-account semantics under a team scope instead of using a separate business model.

Module index

• Authentication
• Files
• Folders
• Teams and team spaces
• Batch operations
• Sharing
• Tags
• Trash
• Search
• Background tasks
• WOPI
• WebDAV
• Properties
• Public API
• Admin API
• Health checks
• Internal storage protocol (follower)

Useful clusters to read first:

• upload and versioning: Files
• MFA, passkeys, external auth, and login sessions: Authentication
• archive-only preview: Files, Sharing, and Background tasks
• batch delete / move / copy / package download: Batch operations
• trash restore and purge: Trash
• tags, entity bindings, and tag-filtered search: Tags and Search
• search, file categories, extension filters, and tag filters: Search
• task retry and storage migration tasks: Background tasks
• team management and team workspaces: Teams
• public shares, preview links, and stream sessions: Sharing
• Office / WOPI preview and callbacks: WOPI
• WebDAV, accounts, and DeltaV: WebDAV
• login page, anonymous page, thumbnail / media-data support, and remote enrollment: Public API
• internal object protocol and reverse-tunnel control plane: Internal storage protocol
• admin policies, remote nodes, storage migration, file / blob observability, external auth providers, locks, runtime config, and audit: Admin API

OpenAPI and Swagger

For machine-readable and generated endpoint-level documentation, use any of these paths:

• Browse the online OpenAPI Reference for operations grouped by tag, parameters, responses, authentication requirements, and request snippets.
• In a debug_assertions + openapi feature build, open /swagger-ui or /api-docs/openapi.json.
• In any checkout, run cargo test --features openapi --test generate_openapi to export the static specification to frontend-panel/generated/openapi.json. The file is a build artifact and is not committed to Git.

OpenAPI registration lives in src/api/openapi.rs, but the actual runtime route registration still comes from src/api/primary.rs, src/api/follower.rs, and src/api/routes/**. If the OpenAPI spec and the route code disagree, trust the route code first and then repair the spec.