Cloud API

Mindwtr Cloud exposes a small bearer-token API for sync, task automation, and attachment transfer. It is designed for self-hosted deployments and uses the same token namespace as the self-hosted cloud backend.

Authentication

Send a bearer token on every /v1/* request:

Authorization: Bearer <token>

Use MINDWTR_CLOUD_AUTH_TOKENS or MINDWTR_CLOUD_AUTH_TOKENS_FILE in production. MINDWTR_CLOUD_ALLOW_ANY_TOKEN=true is only for controlled automation and caps new namespaces with MINDWTR_CLOUD_ANY_TOKEN_MAX_NAMESPACES.

Health

GET /health

Returns server health without authentication.

Snapshot Sync

GET /v1/data
PUT /v1/data

GET /v1/data returns the authenticated namespace snapshot. If the namespace does not exist and writes are allowed, the server creates an empty snapshot.

PUT /v1/data validates the uploaded AppData, merges it with the existing namespace using the core sync algorithm, validates the merged result, and writes it back. It is not a forced overwrite. A successful response returns { ok: true, stats, clockSkewWarning }, where stats is the same merge-stats shape used by local sync diagnostics.

Tasks

GET /v1/tasks
POST /v1/tasks
GET /v1/tasks/:id
PATCH /v1/tasks/:id
DELETE /v1/tasks/:id
POST /v1/tasks/:id/complete
POST /v1/tasks/:id/archive

List query parameters:

Parameter	Purpose
query	Case-insensitive text search across task title and metadata.
status	One task status: inbox, next, waiting, someday, reference, done, or archived.
all=1	Include completed tasks.
deleted=1	Include soft-deleted tasks.
isFocusedToday	true/1 returns only tasks starred for today's focus; false/0 returns only the rest. Omit for no filter.
limit, offset	Page size and start offset.

Create accepts either title or quick-add input, plus optional props. Patch accepts task fields supported by the cloud validation layer and bumps sync revision metadata.

Projects, Areas, and Sections

GET /v1/projects
POST /v1/projects
GET /v1/projects/:id
PATCH /v1/projects/:id
DELETE /v1/projects/:id

GET /v1/areas
POST /v1/areas
GET /v1/areas/:id
PATCH /v1/areas/:id
DELETE /v1/areas/:id

GET /v1/sections
POST /v1/sections
GET /v1/sections/:id
PATCH /v1/sections/:id
DELETE /v1/sections/:id

All list endpoints accept limit, offset, and deleted=1. Sections also accept projectId.

Reference fields must point to live records. A project areaId must reference a live area. Use areaId: null to clear a project area; areaId: "" is invalid. A section projectId must reference a live project.

Deleting areas, projects, and sections uses tombstones and server-side repair to keep the snapshot valid for sync.

Search

GET /v1/search?query=<text>

Search returns live tasks and projects in separate arrays. It supports the shared limit and offset parameters, plus independent cursors:

Parameter	Purpose
taskLimit, taskOffset	Page the task result set.
projectLimit, projectOffset	Page the project result set.

The response includes taskTotal, projectTotal, and the effective cursor values.

Attachments

GET /v1/attachments/:path
PUT /v1/attachments/:path
DELETE /v1/attachments/:path

POST /v1/attachments/orphans
DELETE /v1/attachments/orphans

Attachment paths are resolved inside the authenticated token namespace. Uploads enforce the configured byte limit and the core attachment validation rules.

The orphan cleanup endpoint scans the namespace for files no longer referenced by data.json. It skips files modified in the last five minutes so an upload racing with a later snapshot write is not removed.

Calendar Feed

GET /v1/calendar/feed
POST /v1/calendar/feed
DELETE /v1/calendar/feed

GET /v1/calendar/:token.ics

The first three require the bearer token and read, rotate, and revoke the namespace's feed token. They return { "feed": { "token", "path", "createdAt" } }, or { "feed": null } when nothing is published. POST returns 404 for a namespace that has never synced data.

GET /v1/calendar/:token.ics takes no Authorization header — the token in the URL is the credential — and returns text/calendar for that namespace. An unknown token is a 404.

The feed carries one event per scheduled task (startTime) and one per deadline (dueDate), matching what the app's Calendar view shows: completed, archived, reference, deleted, and non-active-project tasks are excluded, and a task scheduled and due on the same day appears once. Events carry a stable UID and the task title only — no description, checklist, attachments, tags, or project metadata.

MCP Adapter

The published mindwtr-mcp helper can use a self-hosted Cloud endpoint as a backend. Configure it with --cloud-url and --cloud-token or the MINDWTR_MCP_CLOUD_URL / MINDWTR_MCP_CLOUD_TOKEN environment variables.

Cloud-backed MCP mode reads /v1/data and exposes read tools for tasks, projects, sections, areas, and people. With --write, it routes task, project, section, and area mutations through the per-resource REST endpoints above; it stays read-only by default and does not turn Mindwtr Cloud itself into a hosted MCP service.

Related Pages

• MCP Server
• Cloud Deployment
• Sync Algorithm