Scheduling API-first: teu calendário é uma base de dados, não uma app

A maioria das ferramentas de scheduling trata a UI como o produto. O calendário vive dentro da app e a única forma de chegar nele é fazer login e clicar. Se queres fazer algo que o designer não imaginou — puxar as reuniões da próxima semana para a tua revisão semanal, criar horários de atendimento automaticamente a partir de um CSV, deixar a extensão Raycast de um colega marcar algo por ti — ficas preso.

O WhenToMeet adota a visão contrária. O calendário é uma base de dados. A UI é uma vista dele. Se queres outra vista, escreve-a.

É para isso que existe a REST API v1.

O que há na API

A superfície v1 em /api/v1/ é pequena de propósito. Cobre as coisas que as pessoas realmente automatizam:

• Events — listar, ler e criar scheduling polls e direct events. /api/v1/polls
• Bookings — ler os agendamentos que entraram pelas tuas booking pages. /api/v1/bookings
• Calendar events — uma vista unificada de todos os calendários que ligaste, mais os teus scheduling events e bookings. /api/v1/calendar/events
• Conflict checks — perguntar se um intervalo proposto colide com algo que já tens
• Profile — buscar o teu perfil, fuso horário, tier e preferências

A autenticação é um Bearer token. Geras uma chave sk_… nas tuas definições, envias como Authorization: Bearer sk_…, e estás dentro. Cada endpoint é scoped — uma chave só vê o que tem permissão para ver.

Há um OpenAPI spec. Os docs em docs.whentomeet.io listam todos os endpoints com as formas de request e response, portanto podes apontar-lhe um gerador de código e obter um cliente tipado na linguagem que já usas.

Porquê gated para Pro

O acesso à API é uma feature Pro. A razão honesta é que uma API é uma superfície de suporte — as chaves vazam, os scripts fazem loop, os rate limits batem — e preferimos dar suporte cuidadoso a quem realmente precisa, em vez de espalhar por todas as contas gratuitas. Os rate limits são por chave e intencionalmente folgados para automação normal. Com um digest semanal não lá chegas.

O que isto muda

Quando o calendário é um endpoint real, o trabalho que ele gerava desaparece em scripts:

• O estagiário já não copia as reuniões da próxima semana para a wiki da equipa. Um cron job faz isso.
• Já não reencaminhas as notificações de booking para o teu CRM. Um poll estilo webhook escreve-as.
• O engineering lead já não é o PM de scheduling. Um script partilhado cria o standup semanal com um comando.

Nada disto é novo em espírito — programadores colam SaaS com APIs há quinze anos. O que é novo é que ferramentas de scheduling historicamente recusaram estar nessa pilha. Tinhas o Calendly produto e mais nada. Com uma API a sério, o produto passa a ser um cliente entre muitos.

Se estás a construir algo

Começa em docs.whentomeet.io, gera uma chave, chama GET /api/v1/polls com ela, e vais ver os teus próprios scheduling polls a voltar em JSON. Tudo o resto é composição a partir daí.

Se preferes entregar as chaves a um agente em vez de escrever o script — Claude, ChatGPT, Cursor — o servidor MCP em /api/mcp embrulha os mesmos endpoints num protocolo que esses clientes já falam. Mesma auth, mesmos rate limits. Cobrimos isso no próximo post.