Quickstart

In this guide, you send your first requests to your app's sandbox, where sample people already have a week of events. The sandbox doesn't connect to any real calendar. When your integration works, you can connect a real one.

Get a test key

Sign in to the dashboard (opens in a new tab), open your app (or create one), and copy a test key from API keys. Test keys start with pyas_sk_test_ and work only in your app's sandbox, so you can test anything without affecting real calendars.

export PYAS_API_KEY=pyas_sk_test_...

Install the SDK

The SDK is optional. Every request is a plain HTTPS request with your key in the x-api-key header. Each example on this page shows both the SDK and cURL. To send them from Postman instead, see Postman.

npm install @pyas/sdk

List the connected accounts

Your sandbox includes sample people, and each one has a connected account with a Pyas calendar. Every request that reads or writes calendar data must include an accountId, so start by listing the accounts.

import { Pyas } from '@pyas/sdk'

const pyas = new Pyas({ apiKey: process.env.PYAS_API_KEY })

for await (const account of pyas.accounts.list()) {
  console.log(account.accountId, account.name, account.provider)
}

Read a week of events

Pass an accountId from the previous step and a time window in from and to. With expand=true, each occurrence of a recurring event is returned separately.

const from = new Date()
const to = new Date(Date.now() + 7 * 86_400_000)

const page = await pyas.events.list({ accountId, from: from.toISOString(), to: to.toISOString(), expand: true })
for (const event of page.data) {
  console.log(event.startsAt, event.title)
}

Events have the same structure on Google Calendar, Microsoft Outlook and Pyas calendars. Every event includes:

• startsAt and endsAt in UTC.
• The same times in the calendar's own time zone (startsAtLocal, endsAtLocal and timezone).
• Attendees and conferencing details.
• Your own metadata.

Create an event

const event = await pyas.events.create({
  accountId,
  title: 'Intro call',
  startsAt: '2026-10-21T15:00:00Z',
  endsAt: '2026-10-21T15:30:00Z',
  attendees: [{ email: 'sam.patel@example.org' }],
})
console.log(event.id, event.startsAtLocal)

The SDK sends an Idempotency-Key with every request that creates, changes or deletes something. If it retries the request after a dropped connection, the event isn't created twice. If you call the API with plain HTTP, send your own Idempotency-Key header. See Retries and idempotency.

See it in the dashboard

To see the event you created, switch your app to Test mode in the dashboard, open Accounts, select the person and open their Calendar tab. When you select the event, the dashboard shows the request that last updated it.

Connect a real calendar

When your integration works in the sandbox, switch to a live key and let your users connect their own Google, Microsoft Outlook or Zoom accounts with PyasConnect. The code you wrote for the sandbox works without changes, because the requests, the event structure and the errors are the same.

npx @pyas/cli webhooks listen --forward http://localhost:3000/webhooks