# Pyas API

> One API for Google Calendar, Outlook and Zoom: connect your users' calendars, read and write their events, find times they are free, and get webhooks for every change. Every request requires an `x-api-key` header. Test keys (`pyas_sk_test_...`) work only in the sandbox.

Base URL: https://api.pyas.io. OpenAPI document: https://api.pyas.io/v2/openapi.json. All error codes as JSON: https://api.pyas.io/v2/errors. The full documentation in one file: https://developer.pyas.io/llms-full.txt.

## Guides

- [Pyas API](https://developer.pyas.io/): One API for Google Calendar, Microsoft Outlook, and Zoom. Connect your users' calendars, read and write their events, find times when they're free, and get notified about every change.
- [Quickstart](https://developer.pyas.io/quickstart): Go from a test key to an event on a calendar in 5 minutes, using your app's sandbox.
- [SDKs and tools](https://developer.pyas.io/sdks): The Node.js SDK, the CLI, the Postman collection, the MCP server and AI tools, and PyasConnect for your frontend.
- [Authentication](https://developer.pyas.io/authentication): How to authenticate with live and test API keys, what each key has access to, how scopes work, and how to rotate a key without a failed request.
- [The sandbox](https://developer.pyas.io/sandbox): Sample people with a week of events, simulated Google, Outlook and Zoom accounts, and changes, meetings and failures that you trigger on demand.
- [Connecting accounts](https://developer.pyas.io/connect): Let your users connect their Google Calendar, Microsoft Outlook and Zoom accounts, with PyasConnect or with your own screens.
- [Events](https://developer.pyas.io/events): A single event format for Google, Outlook and Pyas calendars, covering times and time zones, recurrence, meeting links, your own metadata, and keeping a copy in sync.
- [Webhooks](https://developer.pyas.io/webhooks): Receive a signed notification for every change as it happens. Deliveries are retried for 41 hours and can be replayed, and you can test them before you write your handler.
- [Pagination](https://developer.pyas.io/pagination): List endpoints return results one page at a time with a cursor, and the SDK can iterate through every page for you.
- [Retries and idempotency](https://developer.pyas.io/idempotency): Retry any request safely with an Idempotency-Key, learn which errors are worth retrying, and avoid creating an event twice.
- [Rate limits](https://developer.pyas.io/rate-limits): Request limits per 5-minute window for each plan, the response headers that show your current usage, and how to handle the limit.
- [Errors](https://developer.pyas.io/errors): Every error uses the same format, with a stable code, a hint, a link to the fix and the request's trace id.
- [Migrating from v1](https://developer.pyas.io/migrating-from-v1): What changes when you move from v1 to v2 (the endpoint paths and the response format), and everything that stays the same, endpoint by endpoint.
- [AI in your app](https://developer.pyas.io/ai-in-your-app): Give the AI assistant in your app calendar tools for your users' Google, Outlook and Zoom calendars. Each person's assistant has access to their calendars only, and asks them before it changes anything.
- [AI tools](https://developer.pyas.io/ai-tools): Add the Pyas MCP server to ChatGPT, Claude, Cursor, VS Code, Claude Code, or Codex by its address, sign in, and let the tool set up your app and work in its sandbox or on live calendars.
- [Build with Base44](https://developer.pyas.io/base44): Add Google Calendar and Microsoft Outlook to a Base44 app. Connect the Pyas MCP server to Base44, and its AI adds the backend functions, the secret and the connect button.
- [Build with Bolt](https://developer.pyas.io/bolt): Add Google Calendar and Microsoft Outlook to a Bolt app. Connect the Pyas MCP server to Bolt, and its agent adds the server code, the secret and the connect button.
- [ChatGPT](https://developer.pyas.io/chatgpt): Add Pyas to ChatGPT as a custom MCP plugin, sign in to Pyas, and ask about your app's calendars in a chat. Find a time everyone is free, see someone's week, or book a meeting.
- [Claude](https://developer.pyas.io/claude): Add Pyas to Claude as a custom connector, sign in to Pyas, and ask about your app's calendars in a chat. Find a time everyone is free, see someone's week, or book a meeting.
- [Claude API](https://developer.pyas.io/claude-api): Add a calendar assistant to your app with the Claude API and Pyas. It reads each user's Google and Outlook calendars, and asks them before it books, moves or deletes anything.
- [Claude Code](https://developer.pyas.io/claude-code): Add the Pyas MCP server to Claude Code with one command, sign in to Pyas, and let Claude set up your app, write the integration and check your sandbox while you code.
- [Codex](https://developer.pyas.io/codex): Add the Pyas MCP server to OpenAI's Codex, in the CLI, the IDE extension or the ChatGPT desktop app, sign in to Pyas, and let Codex set up your app and write the integration while you code.
- [Cursor](https://developer.pyas.io/cursor): Add the Pyas MCP server to Cursor, sign in to Pyas, and let Cursor's agent set up your app, write the integration and check your sandbox while you code.
- [LangChain](https://developer.pyas.io/langchain): Add a calendar assistant to your app with a LangChain agent and Pyas. It reads each user's Google and Outlook calendars, and pauses for their approval before it books, moves or deletes anything.
- [Build with Lovable](https://developer.pyas.io/lovable): Add Google Calendar and Microsoft Outlook to a Lovable app. Connect the Pyas MCP server to Lovable, and its agent adds the server code, the secret and the connect button.
- [OpenAI](https://developer.pyas.io/openai): Add a calendar assistant to your app with OpenAI and Pyas, with Chat Completions or the Responses API. It reads each user's Google and Outlook calendars, and asks them before it books, moves or deletes anything.
- [Build with Replit](https://developer.pyas.io/replit): Add Google Calendar and Microsoft Outlook to a Replit app. Connect the Pyas MCP server to Replit, and Replit Agent adds the server routes, the secret and the connect button.
- [Build with v0](https://developer.pyas.io/v0): Add Google Calendar and Microsoft Outlook to a v0 app. Connect the Pyas MCP server to v0, and it adds the route handlers, the environment variable and the connect button.
- [Vercel AI SDK](https://developer.pyas.io/vercel-ai-sdk): Add a calendar assistant to a Next.js app with the Vercel AI SDK and Pyas. It reads each user's Google and Outlook calendars, and asks them before it books, moves or deletes anything.
- [VS Code](https://developer.pyas.io/vs-code): Add the Pyas MCP server to GitHub Copilot in VS Code, sign in to Pyas, and let the agent set up your app, write the integration and check your sandbox while you code.

## API reference

- [Accounts](https://developer.pyas.io/reference/accounts): List connected calendar accounts and manage their status, settings and imports, including virtual accounts.
- [Connect](https://developer.pyas.io/reference/connect): Connect and reconnect calendar accounts with connect sessions, including the steps that run in the user's browser.
- [Calendars](https://developer.pyas.io/reference/calendars): Manage calendars, calendar sharing, categories, feeds and calendar groups.
- [Events](https://developer.pyas.io/reference/events): Manage events across Google Calendar, Microsoft Outlook and virtual calendars, including metadata, attachments and conferencing.
- [Availability](https://developer.pyas.io/reference/availability): Check free/busy information, find meeting times and find rooms.
- [Meetings](https://developer.pyas.io/reference/meetings): Meetings on their own, with no calendar event: Zoom meetings (list, get, create, change, delete), Microsoft Teams meetings (get, create, change, delete) and Google Meet links (get, create, change settings). To add a meeting to an event, use conferencing on the event.
- [Invitations](https://developer.pyas.io/reference/invitations): Invitations sent for virtual calendars.
- [Webhooks](https://developer.pyas.io/reference/webhooks): Receive events at your own endpoints through signed, retried and recorded deliveries. Includes replays, test deliveries and a relay for sandbox events.
- [Metadata](https://developer.pyas.io/reference/metadata): Import the extended properties stored at the provider into Pyas metadata.
- [Keys](https://developer.pyas.io/reference/keys): List API keys, and rotate a key with a grace period during which both the old and new keys work.
- [Sandbox](https://developer.pyas.io/reference/sandbox): The sandbox environment that test keys work in.
- [Usage](https://developer.pyas.io/reference/usage): Retrieve API usage by day.
- [Logs](https://developer.pyas.io/reference/logs): Look up any v2 request by its trace ID to see what was requested, what the API responded and why, and what happened while the request was processed.

## Tools

- [@pyas/sdk](https://www.npmjs.com/package/@pyas/sdk): the Node.js and TypeScript SDK
- [@pyas/cli](https://www.npmjs.com/package/@pyas/cli): the CLI, for developers and coding agents
- [@pyas/mcp](https://www.npmjs.com/package/@pyas/mcp): the MCP server

## Optional

- [AUTH_EXPIRED_KEY](https://developer.pyas.io/errors/AUTH_EXPIRED_KEY): The API key has expired.
- [AUTH_EXPIRED_SESSION](https://developer.pyas.io/errors/AUTH_EXPIRED_SESSION): The session has expired.
- [AUTH_INSUFFICIENT_SCOPE](https://developer.pyas.io/errors/AUTH_INSUFFICIENT_SCOPE): The API key or session does not have permission to make this request.
- [AUTH_INVALID_CONNECT_SESSION](https://developer.pyas.io/errors/AUTH_INVALID_CONNECT_SESSION): The connect session is missing, invalid, expired or already used.
- [AUTH_INVALID_KEY](https://developer.pyas.io/errors/AUTH_INVALID_KEY): The API key is missing, unknown or revoked.
- [AUTH_INVALID_SESSION](https://developer.pyas.io/errors/AUTH_INVALID_SESSION): The session is missing, invalid or revoked.
- [AUTH_KEY_IN_BROWSER](https://developer.pyas.io/errors/AUTH_KEY_IN_BROWSER): A live API key was sent from a web page. Live keys only work from a server.
- [AUTH_ORIGIN_NOT_ALLOWED](https://developer.pyas.io/errors/AUTH_ORIGIN_NOT_ALLOWED): The request's origin is not in the app's allowed origins.
- [AUTH_SANDBOX_MISMATCH](https://developer.pyas.io/errors/AUTH_SANDBOX_MISMATCH): A test key was used with live data, or a live key was used with sandbox data.
- [BILLING_CONNECTION_LIMIT](https://developer.pyas.io/errors/BILLING_CONNECTION_LIMIT): The plan's connected account limit has been reached.
- [BILLING_FEATURE_UNAVAILABLE](https://developer.pyas.io/errors/BILLING_FEATURE_UNAVAILABLE): This feature is not included in the current plan.
- [BILLING_OVERDUE](https://developer.pyas.io/errors/BILLING_OVERDUE): The account has an overdue payment.
- [BILLING_SUBSCRIPTION_REQUIRED](https://developer.pyas.io/errors/BILLING_SUBSCRIPTION_REQUIRED): The organization has no active subscription.
- [CONNECTION_CONSENT_FAILED](https://developer.pyas.io/errors/CONNECTION_CONSENT_FAILED): The provider did not complete the connection.
- [CONNECTION_NOT_FOUND](https://developer.pyas.io/errors/CONNECTION_NOT_FOUND): No connected account was found for this request.
- [CONNECTION_PROVIDER_NOT_CONFIGURED](https://developer.pyas.io/errors/CONNECTION_PROVIDER_NOT_CONFIGURED): The app is not configured to connect accounts from this provider.
- [CONNECTION_REVOKED](https://developer.pyas.io/errors/CONNECTION_REVOKED): The user revoked access, or the provider no longer accepts the stored credentials.
- [CONNECTION_SCOPE_INSUFFICIENT](https://developer.pyas.io/errors/CONNECTION_SCOPE_INSUFFICIENT): The connected account did not grant a permission that this operation requires.
- [CONNECTION_TOKEN_EXPIRED](https://developer.pyas.io/errors/CONNECTION_TOKEN_EXPIRED): The provider's access token expired and could not be refreshed.
- [CONNECT_CANCELLED](https://developer.pyas.io/errors/CONNECT_CANCELLED): The user closed the widget before connecting.
- [CONNECT_CONSENT_DENIED](https://developer.pyas.io/errors/CONNECT_CONSENT_DENIED): The user did not grant access at the provider.
- [CONNECT_INVALID_CONFIG](https://developer.pyas.io/errors/CONNECT_INVALID_CONFIG): The connect widget is not configured correctly.
- [CONNECT_NETWORK_ERROR](https://developer.pyas.io/errors/CONNECT_NETWORK_ERROR): The browser could not connect to the Pyas API.
- [CONNECT_POPUP_BLOCKED](https://developer.pyas.io/errors/CONNECT_POPUP_BLOCKED): The browser blocked the sign-in window.
- [CONNECT_PROVIDER_ERROR](https://developer.pyas.io/errors/CONNECT_PROVIDER_ERROR): The calendar provider could not finish the sign-in.
- [CONNECT_SESSION_FAILED](https://developer.pyas.io/errors/CONNECT_SESSION_FAILED): Your server could not create a connect session.
- [CONNECT_TIMEOUT](https://developer.pyas.io/errors/CONNECT_TIMEOUT): The sign-in timed out.
- [INTERNAL_ERROR](https://developer.pyas.io/errors/INTERNAL_ERROR): Something went wrong on our end.
- [PROVIDER_PARTIAL_SUCCESS](https://developer.pyas.io/errors/PROVIDER_PARTIAL_SUCCESS): Some operations succeeded and some failed.
- [PROVIDER_RATE_LIMITED](https://developer.pyas.io/errors/PROVIDER_RATE_LIMITED): The calendar provider is rate limiting requests for this account.
- [PROVIDER_TIMEOUT](https://developer.pyas.io/errors/PROVIDER_TIMEOUT): The calendar provider did not respond in time.
- [PROVIDER_UNAVAILABLE](https://developer.pyas.io/errors/PROVIDER_UNAVAILABLE): The calendar provider is not responding normally.
- [PROVIDER_UNKNOWN_ERROR](https://developer.pyas.io/errors/PROVIDER_UNKNOWN_ERROR): The calendar provider returned an error that Pyas could not classify.
- [RATE_LIMIT_BURST](https://developer.pyas.io/errors/RATE_LIMIT_BURST): Too many requests were sent in a short period.
- [RATE_LIMIT_EXCEEDED](https://developer.pyas.io/errors/RATE_LIMIT_EXCEEDED): The request rate exceeds this plan's rate limit.
- [RATE_MONTHLY_QUOTA_EXCEEDED](https://developer.pyas.io/errors/RATE_MONTHLY_QUOTA_EXCEEDED): This plan's monthly API request limit has been reached.
- [RESOURCE_CONFLICT](https://developer.pyas.io/errors/RESOURCE_CONFLICT): The resource was modified or already exists.
- [RESOURCE_LIMIT_REACHED](https://developer.pyas.io/errors/RESOURCE_LIMIT_REACHED): The limit for this resource has been reached.
- [RESOURCE_NOT_FOUND](https://developer.pyas.io/errors/RESOURCE_NOT_FOUND): The calendar or event was not found.
- [RESOURCE_SYNC_TOKEN_EXPIRED](https://developer.pyas.io/errors/RESOURCE_SYNC_TOKEN_EXPIRED): The sync token has expired.
- [VALIDATION_ENDPOINT_UNREACHABLE](https://developer.pyas.io/errors/VALIDATION_ENDPOINT_UNREACHABLE): The webhook endpoint did not accept a test delivery.
- [VALIDATION_IDEMPOTENCY_CONFLICT](https://developer.pyas.io/errors/VALIDATION_IDEMPOTENCY_CONFLICT): This idempotency key was already used with a different request.
- [VALIDATION_INVALID_BODY](https://developer.pyas.io/errors/VALIDATION_INVALID_BODY): The request body is not valid.
- [VALIDATION_INVALID_QUERY](https://developer.pyas.io/errors/VALIDATION_INVALID_QUERY): A query parameter is not valid.
- [VALIDATION_INVALID_TIMEZONE](https://developer.pyas.io/errors/VALIDATION_INVALID_TIMEZONE): The time zone is not an IANA time zone name.
- [VALIDATION_PAYLOAD_TOO_LARGE](https://developer.pyas.io/errors/VALIDATION_PAYLOAD_TOO_LARGE): The request body exceeds the size limit for this endpoint.
- [VALIDATION_REJECTED_BY_PROVIDER](https://developer.pyas.io/errors/VALIDATION_REJECTED_BY_PROVIDER): The calendar provider rejected this input.
- [VALIDATION_UNSUPPORTED_OPERATION](https://developer.pyas.io/errors/VALIDATION_UNSUPPORTED_OPERATION): This provider does not support this operation.