Skip to content

API Reference

This document is the authoritative V1 API contract. The mobile client is the source of truth: the Go server must match it exactly (method + path + response envelope).

Reference file: docs/api-v1.md in the repository.

  • Base URL: http://<host>:8080/api/v1
  • Format: JSON everywhere, except POST /files/upload (multipart).
  • Success envelope: { "data": T, "meta"?: { "page", "pageSize", "total" } } (meta is present on paginated lists).
  • Error envelope: { "error": { "code", "message" } } + proper HTTP status.
  • The device registers first: POST /devices with a client-generated identifier (32-hex). The response contains { "deviceId" } only — no token.
  • Then POST /auth/login (username, password, device_id) returns a PASETO v4-local token.
  • Subsequent requests use Authorization: Bearer <token>.
  • Token TTL is 7 days, no refresh. Signing secret: AUTH_SECRET. The official client re-logs in silently (persisted encrypted credentials) without replaying the in-flight request.
  • Identifiers are opaque 32-hex lowercase strings (^[0-9a-f]{32}$).
MethodPathAuthDescription
GET/health—Status probe, { "status": "healthy" }.
POST/devices—Register a device (client-generated deviceId).
POST/auth/login—Login, returns { token, expires_at, user }.
GET/shares/links/:token—Public share-link resolution.
GET/users/resolve?username=✓Resolve a username (exact match only).
PATCH/users/me/password✓Change own password.
GET/files✓List files (folderId?, page?, pageSize?, sort?).
GET/files/:id✓Get one file (hasContent: bytes seen server-side).
GET/files/:id/content✓Raw bytes (binary, Range supported, never enveloped).
GET/files/:id/shares✓Active grants (owner only).
GET/files/:id/links✓Active public links (owner only).
GET/files/:id/placements✓Byte presence, server + devices (owner only).
POST/groups✓Create a group ({ "name" }).
GET/groups✓Owned + joined groups.
POST/groups/:id/members✓Add a member ({ "userId" }, group owner).
GET/groups/:id/members✓List members (group owner).
DELETE/groups/:id/members/:userId✓Remove a member.
DELETE/groups/:id✓Delete an owned group.
DELETE/files/:id✓Delete a file (owner-only for shared resources).
GET/files/search?q=✓Search files.
GET/files/folders✓List root folders.
POST/files/upload✓Upload (multipart file, optional folderId).
POST/ocr/jobs✓Create an OCR job ({ "fileId" }).
GET/ocr/jobs/:id✓Poll an OCR job.
GET/files/:id/ocr✓Read a file’s extracted OCR text.
POST/sync/ops✓Apply client outbox operations (sequential).
GET/sync/permissions?after=✓Permission snapshot / delta.

The client sends a batch of operations. Each operation:

{
"operations": [
{
"operation_id": "…32-hex",
"ref_type": "resource",
"ref_id": null,
"resource_id": "…32-hex",
"resource_type": "folder",
"operation": "create_resource",
"payload": {}
}
]
}

Supported operations: create_resource, update_metadata, delete_resource, move_resource, share, revoke_share, update_share, create_link, revoke_link, report_bytes.

Key rules:

  • Operations are applied sequentially; the server stops at the first non-idempotent error and returns the index reached.
  • Idempotence is scoped per device: UNIQUE(device_id, operation_id). Replayed operations are no-ops.
  • delete_resource is idempotent (deleting a missing resource succeeds).
  • Sharing requires the resource to be owned by the caller; the target is exactly one principal (granteeUserId XOR granteeGroupId, V2-6 groups, one level, no nesting).
  • report_bytes ({ "hasBytes" }, multi-device presence, file only): fresh operation_id per state change, failure = dead-letter without blocking the queue.

Response:

{ "applied": 3, "failed": { "operation_id": "…", "code": "NAME_CONFLICT", "message": "…" } }

Snapshot — GET /sync/permissions?after=<cached_at_ms>

Section titled “Snapshot — GET /sync/permissions?after=<cached_at_ms>”

Returns the effective permissions for the current user. The server is the source of truth for effective_access resolution (viewer < commenter < editor < owner). Ancestors propagate only when inherit = true; expired relations are ignored. A after delta filters on resource.updated_at and the winning relation’s updated_at. After 24h without reseed, the client downgrades its cache to read-only (viewer).

CodeHTTPMeaning
UNAUTHORIZED401Missing/invalid/expired token, or bad login credentials (indistinguishable by design).
INVALID_DEVICE_ID400Device not registered.
NOT_FOUND404Resource, user or link not found.
NAME_CONFLICT409Same name in the same parent (or root).
FILE_TOO_LARGE413Upload exceeds MAX_FILE_SIZE_MB.
GRANTEE_NOT_FOUND404Share target user does not exist.
GROUP_NOT_FOUND404Target group does not exist.
INVALID_PASSWORD403Wrong current password on password change.
NETWORK_ERROR / INVALID_RESPONSE / HTTP_<status>—Client-only errors.
  • POST /ocr/jobs { "fileId" } → { "id", "status": "queued" }, processed asynchronously in a goroutine.
  • Poll GET /ocr/jobs/:id every 3s until done/failed (queued → processing → done | failed).
  • Engine: Tesseract system call (OCR_LANG). PDFs get their text layer extracted; scanned PDFs yield empty text (out of V1 scope).