HCFS REST API Reference

The authoritative description of every HCFS HTTP endpoint. Each endpoint has its own page with request shape, response shape, status codes, and a working curl example.

Before reading an endpoint page, skim auth.md and errors.md — every endpoint assumes that model.

• Base URL: https://<server>/
• Transport: HTTPS (TLS terminated upstream)
• Content types: application/json for request/response bodies, multipart/form-data for uploads, application/octet-stream for ciphertext downloads

---

Prerequisites

Page	What it covers
auth.md	Bearer-token model, identity resolution, 401 / 403 behaviour
errors.md	NetworkResponse<T> envelope, error-code catalog, optimistic concurrency

---

Endpoint index

File lifecycle — HCFS native (end-to-end encrypted)

Endpoint	Method	Purpose
/upload	POST	Upload a signed manifest + ciphertext for one file
/download/{ss58}/{folder_hash}/{file_id}	GET	Stream the ciphertext back, with metadata headers
/delete/{ss58}/{folder_hash}/{file_id}	DELETE	Remove ciphertext + metadata for one file

File lifecycle — S3-compatible gateway (server-side only)

Endpoint	Method	Purpose
/upload	POST	Upload a plain file with account_ss58 + file fields (no manifest, no client-side encryption)
/download/{ss58}/{file_id}	GET	Stream file by ID without folder scope
/delete/{ss58}/{file_id}	DELETE	Remove file by ID without folder scope

State and discovery

Endpoint	Method	Purpose
/get_state/{ss58}/{folder_hash}	GET	Paginated listing of every file in a folder
/browse/{ss58}/{folder_hash}	GET	Directory-scoped tree listing with subfolder aggregates
/search_files/{ss58}	GET	Cross-folder file search with filters, sort, pagination
/register_relative_paths/{ss58}/{folder_hash}	POST	Backfill plaintext relative paths for legacy rows

Folder lifecycle

Endpoint	Method	Purpose
/register_folder	POST	Declare a new sync folder under an SS58 address
/list_folders/{base_address}	GET	Enumerate every folder a user has registered
/unregister_folder	DELETE	Remove a folder and every file record it owns

Rename

Endpoint	Method	Purpose
/rename_files	POST	Atomic batch rename — re-keys file records without touching storage

Resumable / chunked upload

Endpoint	Method	Purpose
/upload/session	POST	Open a chunked upload session
/upload/session/{id}/chunk/{index}	PUT	Upload one chunk (≤ 16 MiB)
/upload/session/{id}/status	GET	Inspect session progress and resume point
/upload/session/{id}/finalize	POST	Assemble chunks and commit the file
/upload/session/{id}	DELETE	Abort and clean up a session

---

Response envelope

Every endpoint's JSON body is shaped as one of:

{ "Success": { ... endpoint-specific payload ... } }
{ "Conflict": { "error": "...", "message": "...", "current_revision_id": [...], "current_revision_seq": 0 } }
{ "Error":    { "error": "<code>", "message": "<human-readable>" } }

See errors.md for the code catalog and the optimistic-concurrency rules that produce Conflict.

---

Authentication in one line

Send Authorization: Bearer <token>. The server resolves the token to an SS58 address and refuses requests whose URL {ss58_address} segment does not match. See auth.md.