Technical documentation

The API reference

REST routes, authentication, concurrency, reports and desktop synchronisation.

Version 0.1.0 · English documentationMarkdown documentation ↓

REST uses /api/v1; MCP uses /mcp and Streamable HTTP. REST objects use camelCase. The separate portability JSON document uses schema_version: 2 and historical snake_case fields.

Authentication

The browser receives a minutrel cookie with HttpOnly, SameSite=Strict and Secure when APP_SECURE_COOKIES=true. Authenticated writes use X-CSRF-Token, returned at sign-in and by GET /me. Foreign-origin writes are rejected. Setup and sign-in routes are rate-limited.

Native sign-in uses native: true. The Bearer session is returned to Rust once, stored in the keychain and removed from the response passed to the JavaScript renderer. Personal MCP tokens are different: they open scoped MCP tools and, with work.draft_own, the note webhook. They grant no REST access.

MethodREST pathPurpose and permissions
GET/instance, /health/live, /health/readyPublic instance version and health
GET/setupWhether the first workspace needs creation
POST/setupFirst administrator with setupToken, workspace name/time zone, identity and password
POST/auth/login, /auth/logoutSign in and revoke the current session
GET/meAccount, workspace, CSRF and server time
POST/me/passwordCurrent/new password; revokes sessions and personal tokens
PATCH/workspaceAdministrator: workspace name/time zone; time zone fixed after the first entry
GET/membersMember list; manager or administrator
POST/membersCreate account and role; administrator
PATCH/members/{id}Identity, role and enabled state; administrator
POST/members/{id}/passwordReset password and revoke access; administrator
GET, POST/members/{id}/timer, /members/{id}/timer/stopView/resolve active timer with version and reason; administrator
GET, POST/projectsAuthorised projects; manager/administrator creation
PATCH/projects/{id}Edit, archive and assign members with version; manager/administrator
POST/projects/{id}/tasksAdd a task; manager/administrator
PATCH/tasks/{id}Rename/archive task; manager/administrator
GET/timerOwn timer and server time
POST/timer/start, /timer/pause, /timer/resume, /timer/stopPersonal, idempotent writes with version checks
GET, POST/time-entriesPaginated list and personal manual entries
PATCH, DELETE/time-entries/{id}Correct/remove completed entry; version and reason required
PATCH/time-entries/{id}/descriptionEdit description without replacing segments
GET, POST/notesOwn notes; human-created private/shared notes
PATCH, DELETE/notes/{id}Review/share or delete own note
GET, POST/summariesOwn summaries; create a manual draft
PATCH/summaries/{id}Author edits text and draft/approved status
POST/summaries/generatePersonal AI draft; configured provider and consent: true
GET/reports/monthly?month=YYYY-MMPersonal report; administrator may select members
POST/exportsCreate CSV/PDF/ZIP snapshot; administrator
GET/exports/{id}Download own valid snapshot; administrator permission rechecked
GET/workspace/exportShared, completed-work JSON export; administrator
GET/auditRecent administration events; administrator
GET, POST/mcp-tokensList/create own assistant tokens; secrets not redisplayed
DELETE/mcp-tokens/{id}Revoke own token
GET/providersProvider profiles without secrets; signed-in account
POST, PATCH, DELETE/providers, /providers/{id}Provider management; administrator
GET/eventsAuthenticated SSE: connected, change, heartbeat; no business data in events
POST/sync/time-entryPersonal timer snapshot with mutationId, baseVersion and segments; rights/history rechecked
POST/sync/importPersonal manual entry with stable localId and input; durable receipt avoids duplicates

Timer and concurrency

Timer writes and manual entry creation require an Idempotency-Key: 8–128 alphanumeric characters, hyphens or _, unique to the request. The original result is kept for 30 days. Reusing a key for different content returns 409.

http
POST /api/v1/timer/start
Idempotency-Key: 6c508152-4964-4d50-82a1-30f7c4545d90
Content-Type: application/json

{"projectId":"PROJECT_UUID","taskId":null,"description":"Prepare mockups"}

pause, resume and stop receive {"version":1} with the current version. The response contains the entry and its new version. GET /timer returns {"timer":...,"serverNow":...}. Reread after a conflict; do not blindly resubmit with a newer version.

Entries and lists

A manual duration has projectId, optional taskId, description, kind: "duration", workDate: "2026-11-05" and duration: "1h30". An interval uses kind: "interval", startedAt, endedAt in ISO format with explicit UTC offsets, and optionally allowOverlap: true after confirmation.

Lists accept memberId=me or an authorised UUID, month, offset and limit (1–100, default 50). They return items, total and serverNow. Contributors cannot select another member.

A full correction uses the manual-entry form with version and reason. A description-only correction preserves segments and takes the new description, version and reason.

Reports

memberIds is comma-separated UUIDs for report GET requests or an array for export creation. Without a selection, administrators see the whole team; other roles see themselves.

Reports contain totalSeconds, entryCount, member/project aggregates, up to 100 preview entries, shared notes and approved summaries. Each preview row has reportSeconds for its portion of that month.

POST /exports receives month, format (csv, pdf, zip), language (fr, en, de; default French) and optional memberIds. It returns id, url, filename and expiresAt. The private snapshot keeps its original content and language after later entry changes.

Desktop synchronisation

Standalone mode exposes no API. For connected accounts, /sync/time-entry accepts a UUID mutationId, expected baseVersion or null, and entry: id, projectId, taskId, description, state, and segments with second-based startedAt/endedAt. The server calculates durations, rejects incoherent states and never rewrites already finalised segments. Response: {entry, serverNow}.

/sync/import accepts localId and input in the manual-entry format. Repeating it returns the same record; changed content for an existing identifier returns 409. Sync receipts are separate from ordinary 30-day idempotency records. See synchronisation.

Errors

Errors use {"error":"...","message":"..."}. Common codes are 400 (input), 401 (session), 403 (permissions/CSRF/origin), 404 (object or expired export), 409 (concurrency/state), 429 (limit) and 502 (AI provider). Client-facing errors must not expose database internals, passwords or keys.

Ctrl/Cmd + K to open · Escape to close · Search stays on this site.