Scheduling API-first: il tuo calendario è un database, non un'app

La maggior parte degli strumenti di scheduling tratta la UI come il prodotto. Il calendario vive dentro l'app, e l'unico modo per arrivarci è accedere e cliccare. Se vuoi fare qualcosa che il designer non aveva immaginato — tirarti le riunioni della settimana prossima nella revisione settimanale, creare automaticamente orari di ricevimento da un CSV, far prenotare qualcosa dall'estensione Raycast di un collega al posto tuo — sei bloccato.

WhenToMeet prende la visione opposta. Il calendario è un database. La UI è una sua vista. Se ne vuoi un'altra, scrivila.

È a questo che serve la REST API v1.

Cosa c'è nell'API

La superficie v1 su /api/v1/ è piccola di proposito. Copre le cose che la gente automatizza davvero:

• Events — elencare, leggere e creare scheduling poll e direct event. /api/v1/polls
• Bookings — leggere gli appuntamenti arrivati tramite le tue booking page. /api/v1/bookings
• Calendar events — una vista unificata su tutti i calendari che hai collegato, più i tuoi scheduling event e booking. /api/v1/calendar/events
• Conflict check — chiedere se un intervallo proposto collide con qualcosa che hai già
• Profile — leggere il tuo profilo utente, fuso, tier e impostazioni

L'autenticazione è un Bearer token. Generi una chiave sk_… dalle impostazioni account, la mandi come Authorization: Bearer sk_…, e sei dentro. Ogni endpoint è in scope, così una chiave vede solo ciò per cui ha permesso.

C'è uno spec OpenAPI. I docs su docs.whentomeet.io elencano ogni endpoint con le forme di richiesta e risposta, quindi puoi puntarci un generatore di codice e ottenere un client tipizzato nel linguaggio che già usi.

Perché è gated per Pro

L'accesso all'API è una feature Pro. Il motivo onesto è che un'API è una superficie di supporto — le chiavi si disperdono, gli script vanno in loop, i rate limit si toccano — e preferiamo dare supporto con cura a chi ne ha davvero bisogno invece di spargerlo tra tutti gli account gratuiti. I rate limit sono per chiave e deliberatamente generosi per automazioni normali. Con un digest settimanale non li toccherai.

Cosa cambia

Una volta che il calendario è un endpoint vero, il lavoro che prima generava sparisce dentro agli script:

• Lo stagista non copia più le riunioni della settimana prossima nella wiki del team. Lo fa un cron job.
• Non inoltri più le notifiche di booking al CRM. Un poll in stile webhook le scrive.
• L'engineering lead non è più il PM dello scheduling. Uno script condiviso crea lo standup settimanale con un comando.

Nulla di tutto questo è nuovo nello spirito — gli sviluppatori incollano SaaS con le API da quindici anni. La parte nuova è che gli strumenti di scheduling storicamente si rifiutavano di far parte di quel mucchio. Avevi Calendly il prodotto e nient'altro. Con un'API vera, il prodotto diventa un client fra tanti.

Se stai costruendo qualcosa

Parti da docs.whentomeet.io, genera una chiave, chiama GET /api/v1/polls, e vedrai i tuoi scheduling poll tornare in JSON. Tutto il resto è composizione da lì.

Se preferisci consegnare le chiavi a un agente invece di scrivere lo script — Claude, ChatGPT, Cursor — il server MCP su /api/mcp impacchetta gli stessi endpoint in un protocollo che quei client già parlano. Stessa auth, stessi rate limit. Ne parliamo nel prossimo post.