# topcal developers

> Two jobs. Do not mix them. Human page: https://topcal.ai/developers · JSON: https://topcal.ai/developers.json

## Explore endpoints

Agents: fetch the OpenAPI spec, do not scrape HTML docs.

- Explore (Scalar): https://app.topcal.ai/docs
- OpenAPI 3.1: https://app.topcal.ai/api/v1/openapi
- Discovery manifest: https://app.topcal.ai/.well-known/agent-discovery.json

## Job 1 — Book a public link (no API key)

Someone sent `topcal.ai/{workspace}/{username}/{eventSlug}`. Fetch times and book for the guest. They confirm a 6-digit email code.

```
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
```

GET-only agents (no POST):

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

Form fields: the first GET includes `form.definition` and `requiredFieldKeys`. Send answers as `customFields` on book.

Public MCP (no auth): `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.

## Job 2 — Share your own link (device auth)

1. Paste the skill into Cursor, Claude, or ChatGPT.
2. Approve in the browser at app.topcal.ai/cli/approve. No key to copy.
3. Connect Google or Microsoft. Share topcal.ai/{workspace}/{you}/{event}.

```bash
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
```

- Skill: https://topcal.ai/skill/SKILL.md
- OpenAPI: https://app.topcal.ai/api/v1/openapi
- Scalar: https://app.topcal.ai/docs
- Host MCP: https://app.topcal.ai/api/mcp/mcp
- Manifest: https://app.topcal.ai/.well-known/agent-discovery.json
- Agent guide: https://app.topcal.ai/signup/agents

## Origins

- Public booker + marketing: https://topcal.ai
- Auth, dashboard, host API: https://app.topcal.ai

## Rules

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