HOST
Setup
- 01Paste: Set up https://topcal.ai/INSTALL.md
- 02Agent runs: npx --yes -p @topcal/cli topcal setup --json
- 03Human only: sign up (14-day Growth trial, no card), Allow CLI, connect Google/Microsoft.
Explore endpoints: fetch the OpenAPI spec, or open Scalar. Guide is on the developers page.
Developers: https://topcal.ai/developers
Explore endpoints: https://app.topcal.ai/docs
OpenAPI: https://app.topcal.ai/api/v1/openapi
Discovery manifest: https://app.topcal.ai/.well-known/agent-discovery.json
Remote MCP connector (ChatGPT, Claude — OAuth, no API key): https://mcp.topcal.ai/mcp
Public booker MCP (no auth): https://topcal.ai/api/mcp/public/mcp
Paste into your agent:
Set up https://topcal.ai/INSTALL.mdInstall playbook: https://topcal.ai/INSTALL.md
Run this in your terminal:
curl -sL "https://app.topcal.ai/api/agent/install" | bashDEVELOPERS
Two jobs. Same calendars. Book a link someone sent you, or stand up your own. REST, MCP, and the CLI all hit the same free/busy.
Explore endpointsExplore endpoints · openapi · developers.md · developers.json · INSTALL.md · SKILL.md · when to use
PICK THE JOB
NO API KEY
Someone sent a topcal.ai URL. Fetch open times, email a 6-digit code to the guest, confirm. Same calendars as the hosted page.
BROWSER APPROVE
Install the CLI. The human approves in the browser. Connect Google or Microsoft. You never pick a time.
AFTER APPROVE
One tool catalog, three doors: the CLI, the in-app MCP with an API key, or the remote connector in ChatGPT and Claude with no terminal at all.
JOB 1
Parse topcal.ai/{workspace}/{username}/{event}. Ask the guest which time works. Email goes to their address. They read the code back.
GET https://topcal.ai/api/v1/public/{workspace}/{username}
GET https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/slots?timezone={IANA}
POST https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/otp
POST https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/bookGET /api/v1/public/{workspace}/{username}
List their event types and any form fields you must collect.
GET /api/v1/public/{workspace}/{username}/{eventSlug}/slots?timezone={IANA}
Read open times. Each slot has UTC and a local display string.
GET /api/v1/public/{workspace}/{username}/{eventSlug}/otp?email=&startAt=&timezone=&name=
Email the code. Response has confirmUrl — use that, not a token field.
GET {confirmUrl}&code={6 digits}
Confirm with the digits the guest read from email. Never guess.
POST /api/v1/public/{workspace}/{username}/{eventSlug}/otp
Same code email. Body: { email, name? }.
POST /api/v1/public/{workspace}/{username}/{eventSlug}/book
Finish the booking. Body: { startAt, code, invitee, customFields? }.
The confirmation email carries a manage link with a token. Use that token — never a guessed one. Pick a new startAt from a fresh slots call.
POST /api/v1/public/{workspace}/{username}/{eventSlug}/cancel
Cancel with the manage token. Body: { token, reason? }.
POST /api/v1/public/{workspace}/{username}/{eventSlug}/reschedule
Move to a new slot. Body: { token, startAt }. Pick startAt from a fresh slots call.
POST /api/v1/public/manage/cancel
Same cancel when you only have the token. Body: { token, reason? }.
POST /api/v1/public/manage/reschedule
Same reschedule by token alone. Body: { token, startAt }.
The first GET includes the form and requiredFieldKeys. Collect them in your UI. Send them as customFields on book. A homepage button is still just an HTML link — see embeds.
MCP
One tool catalog — event types, availability, meetings, teams, members, API keys, billing — behind three doors. Pick the one your runtime can open.
Public — no login
https://topcal.ai/api/mcp/public/mcp
Remote connector — ChatGPT, Claude, no terminal
https://mcp.topcal.ai/mcp
OAuth 2.1 with PKCE. The human signs in and clicks Allow. No API key — connectors reject keys.
In-app shim — API key
https://app.topcal.ai/api/mcp/mcp
Bearer key from CLI device auth. Same tools as the connector. /api/mcp without the last segment 404s.
CLI and REST — same catalog
npx --yes -p @topcal/cli topcal tools list --json
npx --yes -p @topcal/cli topcal tools call get_workspace --json
npx --yes -p @topcal/cli topcal tools call list_meetings --args '{"filter":"upcoming"}' --jsonGET /api/v1/workspace/tools
List the workspace tools your API key owner can run — same catalog as Cal Agent.
POST /api/v1/workspace/tools/execute
Run one tool. Body: { name, arguments? }.
JOB 2
HOST
Paste into your agent
Set up https://topcal.ai/INSTALL.mdnpx --yes -p @topcal/cli topcal setup --json --url https://app.topcal.ai --client-name agent # Human: sign up / confirm email if asked → Allow CLI → connect calendar npx --yes -p @topcal/cli topcal tools list --json
curl -sL "https://app.topcal.ai/api/agent/install" | bashRULES