Using API v1? See what changes in v2, or the v1 docs

SDKs and tools

The Pyas API uses plain HTTPS and JSON, and an OpenAPI document (opens in a new tab) describes every endpoint. The tools on this page make common tasks quicker for you and for your coding agent.

Official libraries

Node.js @pyas/sdk

For Node.js and TypeScript, typed from the API itself, with retries, pagination and webhook verification built in.

Read more

Python

For Django, FastAPI and Flask apps, and for AI agents written in Python.

Coming soon

PHP

For Laravel apps and WordPress plugins, installed with Composer.

Coming soon

Ruby

For Rails apps, as a gem.

Coming soon

Go

For Go services, using the standard library only.

Coming soon

Node.js and TypeScript

The types in @pyas/sdk are generated from the OpenAPI document, so your editor can autocomplete every field. The SDK requires Node 20 or later and has no dependencies.

npm install @pyas/sdk

import { Pyas } from '@pyas/sdk'

const pyas = new Pyas({ apiKey: process.env.PYAS_API_KEY })
const event = await pyas.events.get({ accountId, eventId })

Every operation in the API reference has a method with a matching name, such as pyas.events.list, pyas.calendars.permissions.create and pyas.webhooks.deliveries.replay. Each method accepts a single object that contains the operation's path, query and body parameters. The exception is events.attachments.upload, which takes the file as its second argument. The SDK also does the following:

  • Retries rate-limited requests and network failures when it's safe to do so, and honors the Retry-After header. It sends an Idempotency-Key with every request that creates, changes or deletes something. See Retries and idempotency.
  • Iterates through every page when you use for await, or returns a single page when you await the method.
  • Throws typed errors (such as NotFoundError and RateLimitError) that include the API's error code, hint, documentation link and trace id.
  • Verifies webhook signatures with verifyWebhook.

The CLI

You can use the pyas CLI in your terminal, or let your coding agent use it. Every command accepts --json. The CLI exits with code 2 when the command itself is invalid, and with code 1 when the API rejects the request.

npx @pyas/cli login                                  # signs you in through the dashboard, to set up your apps
npx @pyas/cli apps show <appId>                      # the app's setup checklist and the next step
npx @pyas/cli keys test <appId>                      # a test key, printed once
npx @pyas/cli login --key pyas_sk_test_...           # saves a key for the calendar commands
npx @pyas/cli accounts list
npx @pyas/cli events create --account <id> --title "Intro call" --start 2026-10-21T15:00:00Z --duration 30
npx @pyas/cli errors explain CONNECTION_NOT_FOUND
npx @pyas/cli logs get trc_...                      # what a request did, and why it failed
npx @pyas/cli webhooks listen --forward http://localhost:3000/webhooks

pyas login shows a code in your terminal and opens the dashboard, where you enter the code and approve. Only approve a code from a terminal you're using. The sign-in lasts until you run pyas logout or disconnect it under Connected tools on your dashboard profile. A coding agent that can't wait for a command to finish can run pyas login --no-wait --json, show you the code, then run pyas login --wait.

To call any operation in the reference, use pyas request with the operation's id:

npx @pyas/cli request <operationId> --params '{...}'

Postman

The Pyas API v2 collection has every endpoint, each with the example from the API reference. The examples use your sandbox's sample people and events, so they work as soon as you add your key.

  1. Open Pyas's public Postman workspace, brutforce-tech/pyas-api (opens in a new tab), and fork Pyas API v2 into your own workspace.
  2. In the collection's Variables tab, set apiKey to your test key.
  3. Send any request.

The Scenarios folder runs common tasks step by step, such as finding a time when everyone is free and booking it. Run it with the Collection Runner, and each step passes what the next one needs.

MCP server

To add Pyas to Claude, Cursor, VS Code or another AI tool by its address, with sign-in and nothing to install, see AI tools. The rest of this section runs the server on your own computer, with an API key.

@pyas/mcp provides calendar tools for AI agents, such as tools to find a time, book it and move it. It also provides coding agents with access to the API reference, the error codes and your request logs. With a test key, the server works only in your sandbox.

claude mcp add pyas --env PYAS_API_KEY=pyas_sk_test_... -- npx -y @pyas/mcp

For Claude Desktop, Cursor, Windsurf or VS Code, add the server to the app's MCP settings:

{
  "mcpServers": {
    "pyas": {
      "command": "npx",
      "args": ["-y", "@pyas/mcp"],
      "env": { "PYAS_API_KEY": "pyas_sk_test_..." }
    }
  }
}

To provide only the tools that read data, add --read-only to the arguments.

AI tools for your app

@pyas/ai-tools gives the AI assistant in your own app calendar tools, for the Vercel AI SDK, OpenAI, the Claude API and LangChain. Each person's assistant has access to their calendars only, and asks them before it changes anything. See AI in your app.

npm install @pyas/ai-tools

PyasConnect

PyasConnect is a sign-in dialog for your page. Your users choose a provider and sign in, and the account is saved. Your server needs a single endpoint, which is one line of code with the SDK: pyas.connect.sessionHandler(). See Connecting accounts for the setup. Every option is documented on npm: @pyas/connect-react (opens in a new tab), @pyas/connect-vue (opens in a new tab), @pyas/connect-angular (opens in a new tab) and @pyas/connect (opens in a new tab).

npm install @pyas/connect-react   # or @pyas/connect-vue, @pyas/connect-angular, @pyas/connect

For coding agents

  • llms.txt lists every page of these docs, and llms-full.txt contains all of them in a single file.
  • The error codes endpoint (opens in a new tab) returns every error code with its cause and fix, as structured data.
  • Every error response includes a traceId. To see what the request did and why it failed, run pyas logs get or call:
    GET /v2/logs/{traceId}