Documentazione

Riferimento API

Ogni endpoint è limitato all’account autenticato, e l’API REST si autentica con il cookie di sessione impostato dall’app web. Script e agenti usano invece l’endpoint MCP.

Tutte le richieste e le risposte sono in JSON. Ogni route /api/* si autentica con il cookie di sessione impostato da POST /api/auth/login:

curl -X POST https://trydone.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"..."}' \
  -c cookies.txt

curl -X GET https://trydone.app/api/tasks -b cookies.txt

Un token MCP non autentica l’API REST. Un’intestazione Authorization: Bearer <mcp-token> viene accettata su una sola route, GET /api/events, così un agente può iscriversi alle modifiche con la credenziale che ha già. Ogni altra route /api/* risponde a un bearer token con un 401.

È una scelta voluta, non una dimenticanza: impedisce che un token MCP trapelato possa pilotare l’intera superficie REST dell’account. Script e agenti devono parlare con POST /mcp, che è ciò a cui serve il token.

curl -X GET https://trydone.app/api/events \
  -H "Authorization: Bearer <your-generated-mcp-token>"

Autenticazione e account

POST/api/auth/signup
Crea un account (email + password, più un codice di invito `ref` facoltativo).
GET/api/referrals
Il tuo link di invito, chi si è iscritto usandolo e l’avanzamento verso il prossimo premio.
POST/api/auth/login
Avvia una sessione; imposta un cookie. Con la 2FA attiva restituisce invece una challenge: completa su /api/auth/2fa/verify.
POST/api/auth/magic-link
Invia per email a un indirizzo un link di accesso monouso.
POST/api/auth/magic-link/verify
Scambia il token di un magic link con una sessione vera. Non serve la password.
POST/api/auth/2fa/verify
Passo 2 di un accesso con 2FA: scambia la challenge e un codice con una sessione vera. Non serve una sessione.
POST/api/auth/logout
Termina la sessione corrente.
GET/api/auth/me
L’utente corrente (compreso se l’email è confermata) e se esiste un token MCP.
GET/api/bootstrap
L’utente corrente più tutte le liste (attività, progetti, obiettivi, dipendenze, tag, attività↔tag) in una sola richiesta: il polling del client web.
PATCH/api/auth/profile
Aggiorna il profilo: nome, fuso orario, avatar.
POST/api/auth/password/verify
Verifica la password attuale (passo 1 per cambiarla).
POST/api/auth/password
Imposta una nuova password: richiede un /password/verify recente in questa sessione (passo 2).
POST/api/auth/forgot-password
Richiede un’email per reimpostare la password.
POST/api/auth/reset-password
Completa la reimpostazione con il token ricevuto per email.
POST/api/auth/verify-email
Conferma un indirizzo con il token ricevuto per email. Non serve una sessione.
POST/api/auth/resend-verification
Invia di nuovo l’email di conferma all’account che ha effettuato l’accesso.
POST/api/auth/mcp-token
Genera (o rigenera) il token MCP con accesso completo dell’account.
DELETE/api/auth/mcp-token
Revoca il token MCP con accesso completo.
GET/api/mcp-tokens
Elenca i token MCP dell’account (completo, sola lettura, singolo progetto).
POST/api/mcp-tokens
Crea un token MCP con ambito limitato (sola lettura o un solo progetto).
DELETE/api/mcp-tokens/:id
Revoca un token MCP con ambito limitato.
GET/api/auth/2fa
Indica se l’autenticazione a due fattori è attiva e quanti codici di recupero restano.
POST/api/auth/2fa/setup
Avvia la registrazione TOTP: restituisce il segreto e l’URI otpauth:// codificato dal QR. Non attiva la 2FA.
POST/api/auth/2fa/enable
Conferma la registrazione con un codice valido. Restituisce i codici di recupero: l’unico momento in cui esistono in chiaro.
DELETE/api/auth/2fa
Disattiva l’autenticazione a due fattori.
POST/api/auth/2fa/recovery-codes
Emette una nuova serie di codici di recupero, invalidando quelli vecchi.
GET/api/auth/connections
Elenca i client OAuth a cui hai concesso l’accesso.
DELETE/api/auth/connections/:clientId
Revoca l’accesso di un client OAuth.
DELETE/api/auth/account
Elimina l’account e tutto ciò che contiene. Richiede la password attuale.

Attività

GET/api/tasks
Elenca le attività: filtra per stato, priorità, progetto, attività principale; cerca in titolo e note.
POST/api/tasks
Crea un’attività.
POST/api/tasks/quick
Crea un’attività da una stringa grezza di acquisizione rapida.
POST/api/tasks/import
Importa un’esportazione CSV da Todoist, TickTick, Asana, Trello o Notion (o un CSV generico).
GET/api/tasks/:id
Recupera un’attività.
PATCH/api/tasks/:id
Aggiorna un’attività.
DELETE/api/tasks/:id
Elimina un’attività (a cascata sulle sottoattività): la sposta nel Cestino, non è un’eliminazione definitiva.
POST/api/tasks/bulk-assign
Assegna un insieme di id di attività (fino a 200) a un utente o a un agente IA.
POST/api/tasks/bulk-delete
Sposta nel Cestino un insieme di id di attività in una sola chiamata.
POST/api/tasks/bulk-move
Sposta un insieme di id di attività in un progetto (o fuori da uno) in una sola chiamata.
POST/api/tasks/:id/decompose
Divide un’attività in sottoattività a partire da un elenco di titoli.
POST/api/tasks/:id/approve
Approva un completamento proposto da un agente (pending_approval → done).
POST/api/tasks/:id/reject
Rifiuta un’attività in pending_approval, con un commento facoltativo (→ in_progress).
POST/api/tasks/:id/approve-plan
Approva un piano proposto (plan_proposed → in_progress).
POST/api/tasks/:id/reject-plan
Rifiuta un piano proposto, con un commento facoltativo.
GET/api/tasks/:id/evidence
Ciò di cui un’approvazione chiede di fidarsi: avanzamento dei criteri, spesa rispetto al budget, ricevute, risultati consegnati e link alle tracce.
GET/api/tasks/:id/runs
Le esecuzioni degli agenti registrate per un’attività.
GET/api/tasks/:id/decisions
Le domande che un agente ha lasciato in sospeso su questa attività.
POST/api/tasks/:id/pause
Ferma ogni agente che lavora su questa attività finché non viene ripresa.
POST/api/tasks/:id/resume
Riavvia un’attività in pausa. Solo per le persone: non esiste un equivalente MCP.
POST/api/resurface
Toglie dall’attesa le attività la cui data di ricomparsa è arrivata.

Cestino

GET/api/trash
Elenca le attività eliminate, dalla più recente.
POST/api/tasks/:id/restore
Ripristina un’attività eliminata (e le sottoattività eliminate insieme a lei).
DELETE/api/trash/:id
Elimina definitivamente un’attività dal cestino.
DELETE/api/trash
Svuota il cestino.

Tag

GET/api/tags
Elenca i tag.
POST/api/tags
Crea un tag.
DELETE/api/tags/:id
Elimina un tag (viene rimosso da ogni attività che lo aveva).
GET/api/task-tags
Elenca tutti gli abbinamenti attività↔tag dell’account.
POST/api/tasks/:id/tags
Applica un tag a un’attività.
DELETE/api/tasks/:id/tags/:tagId
Rimuove un tag da un’attività.

Dipendenze

GET/api/dependencies
Elenca tutte le relazioni blocked-by dell’account.
GET/api/tasks/:id/dependencies
Elenca ciò che blocca un’attività.
POST/api/tasks/:id/dependencies
Aggiunge un blocco (con controllo dei cicli).
DELETE/api/tasks/:id/dependencies/:blockerId
Rimuove un blocco.

Cronologia

GET/api/tasks/:id/comments
Elenca la cronologia di un’attività (commenti + storico degli stati).
POST/api/tasks/:id/comments
Aggiunge un commento, scritto da te o da un agente IA.
GET/api/activity
Il pannello della cronologia di tutta la bacheca: ciò che è successo in ogni attività che puoi vedere, dal più recente. ?limit= imposta il massimo.
GET/api/claude-shipped
Il feed del lavoro degli agenti: ciò che Claude ha effettivamente consegnato. ?days=1|7|30 imposta il periodo.

Riepilogo e revisione

GET/api/digest
Attività in ritardo, in scadenza oggi, ferme e completate di recente.
GET/api/review
Il resoconto della revisione settimanale.
GET/api/stats
Andamento dei completamenti, serie di giorni e ripartizione delle attività aperte per priorità e progetto.

Obiettivi

GET/api/goals
Elenca gli obiettivi.
POST/api/goals
Crea un obiettivo.
PATCH/api/goals/:id
Aggiorna un obiettivo.
DELETE/api/goals/:id
Elimina un obiettivo.
POST/api/goals/:id/breakdown
Inserisce sotto l’obiettivo un’attività di scomposizione assegnata a Claude: l’azione “Proponi i passaggi”.

Posta in arrivo delle acquisizioni

GET/api/capture
Attività proposte dagli agenti in attesa di smistamento, più i numeri di salute su accettate e ignorate. ?state=pending|accepted|dismissed|all.
POST/api/capture/sweep
Esamina il calendario alla ricerca di cose che vale la pena suggerire e le registra come suggerimenti.
POST/api/capture/:id/accept
Trasforma un suggerimento in un’attività vera. L’attività parte sempre con l’approvazione obbligatoria (agent_ok: false).
POST/api/capture/:id/dismiss
Ignora un suggerimento senza creare nulla.

Riordino

GET/api/grooming
La passata sul lavoro fermo: lavoro aperto su cui è calato il silenzio, con le evidenze per decidere. ?days= imposta la soglia, ?limit= il massimo.
GET/api/grooming/proposals
Proposte di riordino raggruppate. ?state=open|resolved|all.
POST/api/grooming/items/:id/approve
Applica l’esito proposto per un elemento.
POST/api/grooming/items/:id/dismiss
Rifiuta un elemento, lasciando l’attività com’è.

Autonomia e agenti

GET/api/autonomy
Il registro dell’autonomia: dove agent_ok è stato guadagnato, per progetto e classe di tag. È una lettura; non concede nulla.
POST/api/autonomy/revoke
Ritira la concessione di una classe, riportando le sue attività dietro il controllo di approvazione.
GET/api/agents
La squadra di agenti: cosa ha fatto ogni agente con un nome. ?days= imposta il periodo. Solo conteggi e date.
GET/api/fleet
Stato della flotta in tempo reale: chi sta lavorando su cosa in questo momento.
GET/api/projects/:id/rejections
I rifiuti recenti in un progetto: lo storico da cui legge il decadimento dell’autonomia.
GET/api/decisions
Tutte le decisioni aperte che un agente sta aspettando, in tutta la bacheca.
POST/api/decisions/:id/answer
Risponde a una decisione in sospeso e sblocca la sua attività.

Avvii

GET/api/triggers
Tutte le richieste aperte perché un agente parta subito (da un clic su Esegui ora o da una menzione @claude) ancora in attesa di un collegamento.
DELETE/api/triggers/:id
Ritira un avvio finché nessuno lo ha ancora preso in carico.
GET/api/trigger-webhook
Indica se è impostato un webhook in uscita per trigger.created, i risultati delle consegne recenti e needs_rotation: true per un webhook registrato prima che le consegne venissero firmate con il segreto stesso, che va sostituito per ottenere un nuovo segreto.
PUT/api/trigger-webhook
Imposta o sostituisce l’URL del webhook. Restituisce il segreto di firma una sola volta, alla creazione. Ogni consegna porta X-Done-Signature: l’HMAC-SHA256 esadecimale, con quel segreto come chiave, del valore di X-Done-Timestamp, un punto e il corpo grezzo.
DELETE/api/trigger-webhook
Rimuove il webhook.

Routine e budget

GET/api/routine
I limiti a cui si ferma una routine programmata.
PATCH/api/routine
Aggiorna quei limiti.
GET/api/routine/night
La spesa rispetto al budget di stanotte. ?since= sostituisce la finestra predefinita di 12 ore.

Progetti

GET/api/projects
Elenca i progetti.
POST/api/projects
Crea un progetto.
PATCH/api/projects/:id
Aggiorna un progetto.
DELETE/api/projects/:id
Elimina un progetto.

Spazi di lavoro e condivisione

GET/api/workspaces
Elenca gli spazi di lavoro di cui fai parte.
POST/api/workspaces/:id/pause
Ferma una bacheca: nessun agente riceve lavoro da lì finché non viene ripresa.
POST/api/workspaces/:id/resume
Riavvia una bacheca ferma. Solo per le persone: non esiste un equivalente MCP.
GET/api/workspaces/:id/members
Elenca i membri di uno spazio di lavoro.
DELETE/api/workspaces/:id/members/:memberId
Rimuove un membro da uno spazio di lavoro.
POST/api/invites
Invita qualcuno in uno spazio di lavoro o in un singolo progetto: gli invia il link per email. Richiede il suo indirizzo.
POST/api/invites/accept
Riscatta il token di un invito per unirsi.

Esecuzioni degli agenti

GET/api/runs
Le esecuzioni recenti degli agenti, più le statistiche aggregate su stato, chiamate agli strumenti e token.

Calendario e sincronizzazione con Google

GET/api/calendar
Le impostazioni di calendario e pianificazione e il token del feed ICS.
PUT/api/calendar
Aggiorna le impostazioni del calendario e delle fasce di pianificazione.
POST/api/calendar/token
Genera il token del feed ICS a cui abbonarsi.
DELETE/api/calendar/token
Revoca il token del feed ICS.
POST/api/calendar/oauth/start
Avvia il collegamento di un Google Calendar: restituisce l’URL di consenso a cui mandare il browser.
GET/api/calendar/writeback
Indica se Pianifica la giornata scrive i blocchi di concentrazione in un calendario di proprietà di Done, e in quale.
POST/api/calendar/writeback/sync
Riallinea subito il calendario di scrittura, senza aspettare la passata notturna.
DELETE/api/calendar/writeback
Disattiva la scrittura e smette di toccare quel calendario.
GET/api/google/accounts
Elenca gli account Google Calendar collegati.
POST/api/google/sync
Sincronizza gli orari occupati da Google Calendar.
DELETE/api/google/accounts/:id
Scollega un account Google.
GET/api/calendar/events
Elenca gli eventi del calendario in cache (titoli, persone) in un intervallo di date.
GET/api/calendar/matches
Abbinamenti attività↔evento suggeriti, per attività, per evento o per intervallo di date.
GET/api/tasks/:id/calendar-links
Elenca gli eventi del calendario collegati a un’attività.
POST/api/tasks/:id/calendar-links
Collega un’attività all’evento del calendario di cui tratta.
DELETE/api/tasks/:id/calendar-links/:eventId
Scollega un’attività da un evento del calendario.

Notifiche e tempo reale

GET/api/notifications
Recupera le preferenze di notifica (riepilogo per email).
PUT/api/notifications
Aggiorna le preferenze di notifica.
GET/api/events
Flusso server-sent delle modifiche ad attività e cronologia. Riconnettiti con l’id dell’ultimo frame (Last-Event-ID, oppure ?cursor=) per riprodurre le modifiche alle attività e gli eventi che hai perso.
GET/api/export
Esporta le attività in CSV o Markdown.
PUT/api/view-prefs
Salva le preferenze di visualizzazione (ordinamento, raggruppamento, pannelli aperti).
PUT/api/saved-views
Sostituisce le viste salvate dell’account.
GET/api/widget
Un’istantanea compatta della bacheca per il widget della schermata Home. ?limit=, ?days= e un’intestazione X-Client-Date per l’oggi del dispositivo.

MCP

POST/mcp
L’endpoint MCP remoto: JSON-RPC su Streamable HTTP. Vedi la configurazione di MCP.