# TopCal developers

> Three 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.

### Cancel or reschedule (manage token)

The confirmation email carries a manage link with a token. Use that token — never a guessed one.

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

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

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: Set up https://topcal.ai/INSTALL.md
2. Agent runs: npx --yes -p @topcal/cli topcal setup --json
3. Human only: sign up (14-day Growth trial, no card), Allow CLI, connect Google/Microsoft.

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

## Job 3 — Operate the workspace (after approve)

Same tool catalog as Cal Agent — event types, availability, meetings, teams, members, API keys, billing — through whichever door fits.

### CLI (after `topcal setup`)

```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_meetings --args '{"filter":"upcoming"}' --json
```

### Remote MCP connector — ChatGPT, Claude, custom connectors (no terminal)

URL: `https://mcp.topcal.ai/mcp` · auth: oauth2.1-pkce · authorization server: https://app.topcal.ai

1. Add the MCP URL https://mcp.topcal.ai/mcp as a connector.
2. The human signs in and clicks Allow — same Google, Microsoft, or magic-link login.
3. Call get_workspace, then the same tools as the CLI. Do not ask for an API key; connectors reject keys.

### In-app MCP shim — API key

URL: `https://app.topcal.ai/api/mcp/mcp` · auth: Bearer API key from CLI device auth. In-app MCP on app.topcal.ai. Bearer API key after CLI device auth.

### REST — workspace tools

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

- When to use TopCal: https://topcal.ai/.well-known/agent-instructions.md
- Install: https://topcal.ai/INSTALL.md
- Skill: https://topcal.ai/skill/SKILL.md
- OpenAPI: https://app.topcal.ai/api/v1/openapi
- Scalar: https://app.topcal.ai/docs
- Remote MCP (ChatGPT / Claude connector): https://mcp.topcal.ai/mcp
- Host MCP shim (API key): 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
- Remote MCP connector: https://mcp.topcal.ai/mcp

## Workspaces (multi-workspace)

- One account spans multiple workspaces: personal, department, agency client books.
- Membership: A user can own one workspace, admin another, and be a member of a third. Each membership has its own username slug.
- Addressing: Every book is addressed by path: topcal.ai/{workspace}/{username}/{eventSlug}. Team round-robin: topcal.ai/{workspace}/team/{teamSlug}/{eventSlug}. Short revocable link: topcal.ai/b/{token}.
- Agent scoping: API keys, MCP sessions, and CLI device approvals bind to exactly one workspace. An agent operates only where its key is bound; cross-workspace access requires a separate assignment.
- Public plane: Guest booking needs no key and is workspace-addressed: GET /api/v1/public/{workspace}/{username} …

## 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 setup.
- 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.
- Guests cancel or reschedule from the manage link in their confirmation email. Agents use that token on the public cancel and reschedule endpoints. Never guess a token.