Using API v1? See what changes in v2, or the v1 docs
The sandbox
Every app has a sandbox that you access with the app's test keys. The sandbox is ready on your first request and doesn't connect to any real calendar. It returns the same responses and errors as the live API.
What's in the sandbox
The sandbox starts with the people below. Each of them has a Pyas calendar with a week of events, including stand-ups, one-on-ones, a design review, focus time and an offsite. To add your own people, create accounts with:
POST /v2/accounts
| Person | Time zone | subjectId |
|---|---|---|
| Avery Brooks | America/New_York | sandbox_user_1 |
| Sam Patel | Europe/London | sandbox_user_2 |
| Yuki Tanaka | Asia/Tokyo | sandbox_user_3 |
| Jordan Lee | America/Los_Angeles | sandbox_user_4 |
| Riley Chen | UTC | sandbox_user_5 |
The sandbox also includes simulated provider accounts. Avery has a Google account and a Zoom account, and Sam has an Outlook account. These accounts behave like real Google, Outlook and Zoom accounts, with the same features and the same errors, but the API never contacts the providers for them. The following all behave as they would on a real account: Meet and Teams links, Zoom meetings, sharing roles, Outlook categories, calendar groups, invitations to respond to, attachments, reminders and working locations.
To get the ids of the accounts, calendars and events in your sandbox, call:
GET /v2/sandbox
The response lists each id under the same name that the reference examples use, such as account.avery and event.avery.design. The API reference shows the ids from a sample sandbox. Your sandbox has the same people and events, but with its own ids.
Reset the sandbox
To restore the sandbox to the state it was in on your first request, call:
POST /v2/sandbox/reset
You can reset the sandbox between test runs. You can also reset it from the dashboard. In Test mode, go to Accounts and select Reset sandbox.
Simulate changes
On a live account, events change when people update their calendars, reply to invitations or join meetings. In the sandbox, you trigger these changes yourself with the endpoints below. The sandbox then sends the same webhooks that a live account sends.
| Endpoint | What it simulates |
|---|---|
POST /v2/sandbox/simulate-change | An event is created, updated or deleted on the account, as if the person did it in their own calendar app |
POST /v2/sandbox/simulate-meeting | A meeting starts or ends, someone joins or leaves, or a recording becomes available |
POST /v2/sandbox/simulate-reply | An attendee accepts, declines or responds with maybe, and can propose a different time |
curl -X POST https://api.pyas.io/v2/sandbox/simulate-reply \
-H "x-api-key: $PYAS_API_KEY" \
-H "content-type: application/json" \
-d '{ "accountId": "'$ACCOUNT_ID'", "eventId": "'$EVENT_ID'", "email": "sam.patel@example.org", "response": "declined" }'
For a reply, the event must be on one of the sample people's Pyas calendars, not on the simulated Google, Outlook or Zoom account, and email must be one of its attendees. This example replies for the attendee invited in the Quickstart.
Simulate provider errors
To test how your app handles provider failures, add ?simulate= (or a Pyas-Simulate header) to any request made with a test key. The request then fails in the same way it would if a real provider failed:
| Value | Response |
|---|---|
rate_limit | PROVIDER_RATE_LIMITED, with Retry-After |
token_expired | CONNECTION_TOKEN_EXPIRED. The user needs to sign in again. |
revoked | CONNECTION_REVOKED. The user revoked your access. |
provider_error | PROVIDER_UNAVAILABLE |
timeout | PROVIDER_TIMEOUT |
Your error handling code receives the same error codes, hints and HTTP status codes that it receives in production.
Limits
A sandbox can hold up to 25 accounts, 10 calendars per account and 5,000 events. Calendar feeds created in the sandbox work for 7 days. If a sandbox receives no requests for 30 days, it's deleted, and a new one is created on your next request. If you exceed a limit, the API returns RESOURCE_LIMIT_REACHED.
Requests made with a test key don't count toward your plan's monthly request allowance. They have a separate monthly allowance that's large enough for test suites and CI.