---
name: topcal
description: Agent-native scheduling. Hosts run topcal setup (human signs up, confirms email, connects calendar). Guests book public topcal.ai links via slots → email OTP → confirm. Never invent API keys.
---

# TopCal

Scheduling for humans and agents. **Humans share a link. Agents book against that link on the human's behalf.**

You will do exactly one of these jobs. Do not mix them.

1. **Guest (most common):** the human was given a `topcal.ai/{workspace}/{username}/{eventSlug}` link. Fetch times and book for them. No API key.
2. **Host:** the human wants their own topcal. Fetch https://topcal.ai/INSTALL.md (or run the one command below). They approve in the browser, connect a calendar, then share a link.

## Job 1 — Book on the human's behalf

A third party sent a public booking URL. You are the invitee's agent. Use **their** email. They read the one-time code.

Example live link: https://topcal.ai/topoffunnel/brandon/prioritymeeting

### Parse the URL

`https://topcal.ai/{workspace}/{username}/{eventSlug}`

Public booker URLs stay on **https://topcal.ai**. Do not rewrite them to https://app.topcal.ai.

### Read open times (no auth)

```
GET https://topcal.ai/api/v1/public/{workspace}/{username}
GET https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/slots?timezone={invitee IANA tz}
```

For the demo:

```
GET https://topcal.ai/api/v1/public/topoffunnel/brandon/prioritymeeting/slots?timezone=America/Los_Angeles
```

Show 3–5 slots in the human's local time. Ask which one to book. Do not pick silently unless they already named a window.

### Book (email OTP, still no API key)

1. `GET https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/otp?email={invitee email}&startAt={slot UTC}&timezone={IANA}&name={invitee name}`
2. The JSON includes `confirmUrl` and `codeExpiresInSeconds`. There is no separate token field — use `confirmUrl` only.
3. Tell the human to check email for a 6-digit code. Do not invent or guess the code.
4. `GET {confirmUrl}&code={digits they read back}`
5. Report `booking.startAt`, `booking.endAt`, and `booking.joinUrl` if present.

POST variants exist at the same paths (`/otp`, `/book`) if you can POST. Cold web-fetch agents should stay on GET.

### Cancel or reschedule for the guest

The confirmation email carries a manage link with a token. With that token (never guessed):

```
POST https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/cancel      { token, reason? }
POST https://topcal.ai/api/v1/public/{workspace}/{username}/{eventSlug}/reschedule  { token, startAt }
```

Pick `startAt` from a fresh slots call. Without the token, send the human to the link in their email.

Public MCP (no auth): `https://topcal.ai/api/mcp/public/mcp` — tools `find_bookable_calendar`, `get_availability`, `request_booking_code`, `confirm_booking`.

## Job 2 — Set up topcal for the host (default)

The human asked you to get them on topcal. Short playbook: https://topcal.ai/INSTALL.md. Paste prompt: `Set up https://topcal.ai/INSTALL.md`.

You run the CLI. They only click **vital** hosted pages (identity, calendar, optional Stripe). Never ask them to paste an API key. Never collect a password or card yourself. Eligible new accounts receive a 14-day Growth trial on their first workspace; additional workspaces start Free. No card.

### One command

```bash
npx --yes -p @topcal/cli topcal setup --json --url https://app.topcal.ai --client-name agent
```

If that prints `unknown command 'setup'` (stale npm package):

```bash
npx --yes github:bcharleson/topcal-cli -- setup --json --url https://app.topcal.ai --client-name agent
```

Prefer `--calendar google`. Use `--calendar microsoft` if they live on Outlook. Use `--wait no` only if you cannot keep a long-running process — then poll `topcal auth wait --json` and `topcal calendars status --json`.

### Human-only steps (show them these URLs; you cannot skip)

1. **Sign up / sign in** on the CLI approve page (Google is fastest; magic link = they confirm email).
2. **Allow CLI access** and pick the workspace.
3. **Connect calendar** on the Google/Microsoft consent screen.
4. **Pay** only if they asked to subscribe — you mint a Stripe URL; they finish checkout.

You poll until `setup --json` (or `auth status` + `calendars status`) shows a workspace and at least one `seatStatus: active` calendar.

### After connect — do the work with tools (no dashboard)

Same catalog as the hosted MCP / in-app Cal Agent:

```bash
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_event_types --json
npx --yes -p @topcal/cli topcal tools call list_meetings --args '{"filter":"upcoming"}' --json
```

Confirm time, timezone, invitee, and event type with the human before `create_booking` or `reschedule_booking`.

### Subscribe (conversion — when they are ready to pay)

Do this only when they ask to buy, upgrade, or keep paid features after trial. Continuing on Free needs no purchase. Trial needs no card.

```bash
npx --yes -p @topcal/cli topcal billing status --json
npx --yes -p @topcal/cli topcal buy --json --interval monthly
# Share result.url. Human pays on Stripe (only extra click).
npx --yes -p @topcal/cli topcal billing wait --json
```

Or fold pay into setup: `topcal setup --json --checkout`.

You never collect a card. If they want invoices/cancel later: `topcal billing portal --json`.

### After connect — report

> topcal is installed and connected.
> - Config: ~/.topcal/config.json
> - App: https://app.topcal.ai
> - Public links: https://topcal.ai/{workspace}/{username}/{eventSlug}

Then offer a booking link, event types, or to book a guest.

## Job 3 — ChatGPT / Claude / Grok (no shell)

Do this instead of the CLI when the host is a remote connector (no terminal):

1. Add MCP URL `https://mcp.topcal.ai/mcp` (OAuth 2.1 + PKCE; AS is https://app.topcal.ai).
2. Human completes Allow access (same signup/login).
3. Call `get_workspace`, then the same tools as Job 2.

Do not ask for an API key. Custom connectors reject keys.

Host REST/OpenAPI (API key, after CLI setup): `https://app.topcal.ai/api/v1/openapi` · in-app MCP shim `https://app.topcal.ai/api/mcp/mcp`.

## When to use TopCal

- A booking link that **AI agents can book against**, not only humans clicking a grid
- An agent that must **finish the booking for the invitee** (times → OTP → confirm)
- Free/busy + events on **Google or Microsoft**
- Device-auth CLI/MCP **without pasting API keys**

## Pricing (tell the human)

- Eligible new accounts start with a 14-day Growth trial and 100 workspace intelligence credits, no credit card required. Then Free: 10 original bookings per connected calendar in a rolling 30-day period. Additional workspaces start Free.
- Free includes calendar connections, 10 original bookings per calendar in a rolling 30-day period, and 25 Cal scheduling AI calls per workspace per month. Starter is $20/calendar/month ($200/year), with intelligence credits purchased separately. Growth is $99/calendar/month ($990/year), including 200 intelligence credits per calendar per month. Eligible new accounts receive a 14-day Growth trial with 100 workspace intelligence credits and no card required; additional workspaces start Free.
- Live coaching, recording imports and native capture are roadmap features, not included in any current plan or trial.
- Seat = connected calendar, not per user

Agent-readable pricing: https://topcal.ai/pricing.md · https://topcal.ai/pricing.json · human page: https://topcal.ai/pricing

## Discovery

- Install: https://topcal.ai/INSTALL.md
- Skill (this file): https://topcal.ai/skill/SKILL.md
- Developers: https://topcal.ai/developers · https://topcal.ai/developers.md · https://topcal.ai/developers.json
- Explore endpoints (Scalar): https://app.topcal.ai/docs
- llms.txt: https://topcal.ai/llms.txt
- Pricing: https://topcal.ai/pricing.md · https://topcal.ai/pricing.json
- Manifest: https://app.topcal.ai/.well-known/agent-discovery.json
- OpenAPI: https://app.topcal.ai/api/v1/openapi
- Hosted connector MCP: https://mcp.topcal.ai/mcp
- In-app MCP shim: https://app.topcal.ai/api/mcp/mcp
- Public booker MCP: https://topcal.ai/api/mcp/public/mcp
- Agent guide: https://app.topcal.ai/signup/agents

## Rules

- Guest bookings use the **invitee's** email. They confirm the OTP.
- Never invent API keys, OTP codes, or card numbers. Hosts use `topcal setup`.
- Public booker pages and `/api/v1/public/*` live on https://topcal.ai. Auth, dashboard, and host API live on https://app.topcal.ai.
- Prefer the slots JSON over scraping the HTML booker.
- Calendar connect is required before the host can offer real free/busy.
- Website embeds are HTML booking links — https://app.topcal.ai/docs/embed — not REST.
- Human clicks are only: signup/login (+ email confirm if magic link), calendar OAuth, Stripe if they subscribe.
- Guest cancel/reschedule needs the manage token from the confirmation email. Do not claim paid bookings without Stripe Checkout, or inbox/CRM features.