Agent onboarding

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

Run this in your terminal:

curl -sL "https://app.topcal.ai/api/agent/install" | bash

DEVELOPERS

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 endpoints

Explore endpoints · openapi · developers.md · developers.json · SKILL.md

PICK THE JOB

You are doing one of these.

NO API KEY

Book a public link

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

Share your own link

Install the CLI. The human approves in the browser. Connect Google or Microsoft. You never pick a time.

JOB 1

Book a public link

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}/book

If you can only GET

  • GET /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.

If you can POST

  • 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? }.

Your own questions

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

Same two jobs, as tools

Public — no login

https://topcal.ai/api/mcp/public/mcp

  • find_bookable_calendar — Start here. Workspace + username → events and form fields.
  • get_availability — Open slots for one event. Pass the guest's IANA timezone.
  • request_booking_code — Email a 6-digit code to the guest.
  • confirm_booking — Book with startAt, the code, invitee, and optional customFields.

Host — after approve

https://app.topcal.ai/api/mcp/mcp

Propose slots and book as the host. /api/mcp without the last segment 404s.

JOB 2

Share your own link

HOST

Setup

  1. 01Paste the skill into Cursor, Claude, or ChatGPT.
  2. 02Approve in the browser at app.topcal.ai/cli/approve. No key to copy.
  3. 03Connect Google or Microsoft. Share topcal.ai/{workspace}/{you}/{event}.
Paste into your agent
Set up topcal from https://topcal.ai/skill/SKILL.md
npm install -g @topcal/cli

topcal auth register --wait auto --url https://app.topcal.ai --client-name cursor --agent-name topcal
topcal auth status --json
topcal calendars connect --provider google
topcal calendars status --json
Install script
$curl -sL "https://app.topcal.ai/api/agent/install" | bash

RULES

Do not invent a third path

  1. 01Guest bookings use the guest's email. They confirm the code. You book on their behalf.
  2. 02Never invent API keys or codes. Hosts run topcal auth register.
  3. 03Public booking lives on topcal.ai. Sign-in and host API live on app.topcal.ai.
  4. 04Read slots JSON. Do not scrape the HTML booking page.
  5. 05A website button is an HTML link (app.topcal.ai/docs/embed), not a REST integration.
  6. 06Cancel and reschedule need the manage token from the confirmation email.