> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Google Calendar

> Test calendars, events, attendees, recurring meetings and free/busy queries with Google Calendar API v3.

The Google Calendar tool covers calendar lists, calendars, events, attendees, recurrence and free/busy queries. Its key is `google-calendar`. Coverage lists 20 routes, including `quickAdd` and `import`, which always return a coverage gap.

## Connect

| Variable | Value |
| - | - |
| `GOOGLE_CALENDAR_API_URL` | Base URL. API paths start with `/calendar/v3/`. |
| `GOOGLE_CALENDAR_ACCESS_TOKEN` | Fake OAuth access token. Send `Authorization: Bearer <token>`. |

```js Node theme={null}
import { auth, calendar } from '@googleapis/calendar';
const oauth = new auth.OAuth2();
oauth.setCredentials({ access_token: process.env.GOOGLE_CALENDAR_ACCESS_TOKEN });
const cal = calendar({ version: 'v3', auth: oauth });
const options = { rootUrl: process.env.GOOGLE_CALENDAR_API_URL + '/' };
const { data } = await cal.events.list({ calendarId: 'primary', timeMin: '2026-11-02T00:00:00Z', singleEvents: true, orderBy: 'startTime', maxResults: 10 }, options);
```

This is what `ancha connect google-calendar --lang ts` prints. Pass `rootUrl` on each request, with a trailing `/`. A global `rootUrl` keeps only the origin and drops the path. Use `primary` for the owner's calendar.

## Endpoints

| Method | Path | Support |
| - | - | - |
| `GET` | `/calendar/v3/users/me/calendarList` | supported: minAccessRole; syncToken is a gap |
| `GET` | `/calendar/v3/users/me/calendarList/:calendarId` | supported |
| `GET` | `/calendar/v3/calendars/:calendarId` | supported |
| `POST` | `/calendar/v3/calendars` | supported: a secondary calendar the owner owns |
| `PATCH` | `/calendar/v3/calendars/:calendarId` | supported |
| `DELETE` | `/calendar/v3/calendars/:calendarId` | supported |
| `GET` | `/calendar/v3/calendars/:calendarId/events` | partial: time window, q, singleEvents, orderBy, showDeleted, updatedMin, eventTypes, iCalUID, extended properties; syncToken is a gap |
| `POST` | `/calendar/v3/calendars/:calendarId/events` | partial: attachments, working location and attaching existing conferences are gaps |
| `POST` | `/calendar/v3/calendars/:calendarId/events/quickAdd` | partial: always a gap: natural-language parsing |
| `POST` | `/calendar/v3/calendars/:calendarId/events/import` | partial: always a gap |
| `GET` | `/calendar/v3/calendars/:calendarId/events/:eventId` | supported: occurrences of recurring events by instance id |
| `PATCH` | `/calendar/v3/calendars/:calendarId/events/:eventId` | partial: whole series or single events; changing one occurrence is a gap; an invitee can only answer |
| `PUT` | `/calendar/v3/calendars/:calendarId/events/:eventId` | partial: as PATCH, replacing the event |
| `DELETE` | `/calendar/v3/calendars/:calendarId/events/:eventId` | partial: cancels the event or series; one occurrence is a gap |
| `GET` | `/calendar/v3/calendars/:calendarId/events/:eventId/instances` | supported |
| `POST` | `/calendar/v3/calendars/:calendarId/events/:eventId/move` | supported |
| `POST` | `/calendar/v3/freeBusy` | supported: calendars on the list; group expansion is a gap |
| `GET` | `/calendar/v3/users/me/settings` | supported |
| `GET` | `/calendar/v3/users/me/settings/:setting` | supported |
| `GET` | `/calendar/v3/colors` | supported |

Unsupported features on listed routes return HTTP 400 in Google's error shape. Unknown routes return HTTP 404. Both carry `x-ancha-gap: 1`. The client retries 5xx responses, so these errors use 4xx responses.

## Starter data

The starter data belongs to Ben Carter, `ben@acme.example`, in `America/Los_Angeles`.

| Record | Detail |
| - | - |
| Calendars | Ben's primary calendar; Acme team, with writer access; Rachel Moore's calendar, with free/busy access; and Holidays in United States, with reader access. |
| Customer meetings | Ridgeway Robotics pilot check-in, Pinecrest Health kickoff and Summit Freight admin training. |
| Team meetings | Orders API incident review, a data platform walkthrough with Victor, the company all-hands, a recurring roadmap review and a recurring Ben/Rachel one-on-one. |
| Other events | Focus time, Tom's day out at the Ridgeway offsite, two busy periods on Rachel's calendar, Veterans Day and Thanksgiving Day. |

The events include attendee responses and Google Meet links. Run `ancha twins seed google-calendar --full` to print every event, its date and its scene seed fields.

## Checks

Google Calendar has no state checks. Use [trace checks](https://docs.ancha.io/concepts/checks.md#trace-patterns), for example `{ called: "POST /calendar/v3/calendars/*/events" }` or `{ not_called: "DELETE /calendar/v3/calendars/*/events/*" }`.

## Limits

* You can read recurring occurrences and change or cancel a whole series. Changing or deleting one occurrence is a gap.
* An invitee can answer an invitation, but cannot edit its other fields.
* `quickAdd`, `import`, ACLs, watch channels and sync tokens are gaps.
* Attachments, working locations, attaching existing conferences and group expansion in free/busy queries are gaps.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [ancha init](https://docs.ancha.io/cli/init.md)
- [Introduction](https://docs.ancha.io/index.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.