> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get up and running with the Zapier SDK in 5 minutes
export const appCount = "9,000+";
## Set up with your AI
**Your agent runs the commands for you**
**Your agent walks you through the process**
Using another IDE agent (Cline, Windsurf, etc.)? Copy this prompt.
```text expandable theme={null}
Set up the Zapier SDK for me. Before installing anything:
- Run `pwd` and tell me the current folder.
- Ask whether to install here or somewhere else.
End with: "Should I set up here, or do you want to point me at a different directory?" Then STOP and wait. If I name a different directory, `cd` there first, creating it with `mkdir -p` if needed. If my reply is ambiguous, use the current directory.
After I confirm the directory, work through these steps one at a time. Run each command in the terminal, report what happened, then continue.
1. Detect the package manager.
Check for pnpm-lock.yaml, yarn.lock, bun.lockb, or package-lock.json. If one exists, use that manager for every install command. If none exist, use npm.
2. Ensure a project exists.
- If package.json exists, use the project as-is and remember this for step 9.
- If package.json is missing, create one: npm init -y
3. Check Node.js is installed at version 20 or higher: node -v
- If Node is missing, tell me to install it from https://nodejs.org or run brew install node, then stop.
- If Node is older than 20, tell me to upgrade it, then stop.
4. Install the SDK: npm install @zapier/zapier-sdk
- An EPERM error on ~/.npm/_cacache usually means the command sandbox is blocking npm cache writes, not that file permissions are broken.
5. Install dev dependencies: npm install -D @zapier/zapier-sdk-cli @types/node typescript tsx
6. Ask whether to install the optional Zapier SDK skill for agent context.
Say: "Do you want me to install the optional Zapier SDK skill for extra agent context? It is not required for SDK setup." Then STOP and wait.
- If I clearly say yes, run: npx skills add zapier/sdk -y
- Otherwise, skip this step and continue.
7. Authenticate with Zapier.
First ask: "Are you signing up or logging in? Am I running on your local machine with a browser, or in a remote/headless environment like Telegram or Discord?" Then STOP and wait. Do not infer the environment.
- If I do not have a Zapier account and we are in a remote environment like Telegram or Discord, run: npx zapier-sdk signup --non-interactive --headless
- If I do not have a Zapier account and you are running on my machine, run: npx zapier-sdk signup --non-interactive
- If I already have a Zapier account and we are in a remote environment like Telegram or Discord, run: npx zapier-sdk login --non-interactive --headless
- If I already have a Zapier account and you are running on my machine, run: npx zapier-sdk login --non-interactive
- If unsure, ask whether to sign up or log in, and whether you are local or remote, before running any auth command.
- Use --headless when auth must happen through a browser outside this terminal. Show me the printed URL and pass the final OAuth callback URL back to the waiting command when I provide it.
- Browser signup/login opens a browser. A permissions or sandbox error usually means credentials could not be written to disk.
- If authentication fails for another reason, try once more.
- After authentication succeeds, confirm the email from the CLI output.
8. List my connected apps: npx zapier-sdk list-connections --owner me --json 2>/dev/null | head -n 1000
- Show only the first 10 results as a markdown table with columns: ID, App Key, Expired. Do not show Title.
- Tell me how many total connections there are. If there are more than 10, say you are only showing the first 10.
- The page size is 100. If exactly 100 connections return, note that more may exist, but do not fetch more pages.
- If the list is empty, tell me to connect at least one app at https://zapier.com/app/assets/connections and come back.
9. If this was an existing project from step 2, scan the codebase and suggest 2-3 concrete ways to integrate the Zapier SDK. Reference real files and patterns you find, for example an API route, tool registry, backend service, or sync script. If this is a fresh project, skip this step.
When setup is done, tell me I am ready and explain:
Zapier has pre-built connectors for 9,000+ apps, including Slack, Google Sheets, Salesforce, GitHub, and thousands more. The SDK and CLI expose that integration layer to code, so you do not have to build OAuth, token refresh, retries, or each app API yourself. My existing Zapier connections are authenticated and ready to use.
- **TypeScript SDK:** for production integrations, backend services, scheduled workflows, and agent tools. It is type-safe, handles token refresh and retries, and uses the same app keys, action keys, and input shapes discovered through the CLI. SDK reference: https://docs.zapier.com/sdk/reference
- **CLI:** for exploration and ad-hoc actions. Use it to inspect apps, fields, and actions, then run one-offs from a terminal or agent. CLI reference: https://docs.zapier.com/sdk/cli-reference
**Want to run a quick test?**
If I have a Slack connection, offer to send me a DM on Slack using the SDK. Describe what will happen and end with: "Want to run this quick test?" Then STOP and wait. Do not output anything else. If I do not have a Slack connection, skip the test.
Only proceed with the test if my reply is clearly affirmative, such as "yes" or "go ahead". If ambiguous, skip the test and continue.
When I say yes, create src/zapier-slack-test.ts with code that:
1. Looks up my Slack user by email using sdk.runAction("slack", "search", "user_by_email", { connectionId: ID, inputs: { email: "ZAPIER_EMAIL" } }).
2. Sends a DM to myself using sdk.runAction("slack", "write", "direct_message", { connectionId: ID, inputs: { channel: "USERNAME", text: "Hello via Zapier SDK" } }).
Replace ID, ZAPIER_EMAIL, and USERNAME with real values from earlier steps. Run it with npx tsx src/zapier-slack-test.ts. If user_by_email fails, ask for my Slack email and try again.
After the test completes, is skipped, or there is no Slack connection:
- Pick 1-3 apps from the connections table and show commands I can use to explore their actions, such as: npx zapier-sdk list-actions APP_KEY
- Do not run those commands.
- Suggest 3 specific ideas based on my connected apps. Each idea should read from one app, optionally process data, and write to another. Do not suggest event-driven workflows. Keep each idea to one sentence. Example: "pull in-progress Jira issues and DM yourself a summary on Slack".
```
***
## Prerequisites
* Node.js 20+ installed
* A [Zapier account](https://zapier.com/sign-up) (free tier works). Or create one using the CLI in Step 3
* At least one app connected to your Zapier account
## Step 1: Install the SDK
Create a new project (or use an existing one) and install the required packages:
```bash theme={null}
# Create a new project (optional)
mkdir my-zapier-project && cd my-zapier-project
npm init -y && npm pkg set type=module
# Install the SDK and CLI
npm install @zapier/zapier-sdk
npm install -D @zapier/zapier-sdk-cli @types/node typescript
# Initialize TypeScript (if starting fresh)
npx tsc --init
```
The examples in this guide assume you have `"type": "module"` in your
`package.json` so that you're using ES modules with support for top-level
`await`. We do that above with `npm pkg set type=module`.
## Step 2: Install the SDK skill
Install the Zapier SDK skill so your coding agent knows how to use the SDK across every future session:
```bash theme={null}
npx skills add zapier/sdk -y
```
Works with Claude Code, Cursor, Codex, OpenCode, Windsurf, and 50+ other coding agents.
## Step 3: Authenticate
The SDK CLI can create a Zapier account or log into an existing one, then
provision local SDK credentials:
New to Zapier? Start with `signup`:
```bash theme={null}
npx zapier-sdk signup
```
This opens your browser to create an account, authorize the SDK CLI, and store a
local SDK credential.
Already have a Zapier account? Use `login` instead:
```bash theme={null}
npx zapier-sdk login
```
As long as the CLI package is installed as a development dependency, the SDK will automatically use your CLI authentication.
**Building for production or deploying to a server?** CLI authentication is
for development terminals. For any server-side deployment, [client
credentials](/sdk/deploy) are the recommended approach.
**Want approvals on these credentials?** Pass `--use-approvals` to `signup`
or `login` to provision the credential with an empty permission policy. Every
request will prompt you to approve (or deny) the action until you've built the
policy up. See [Permissions](/sdk/permissions) for the full flow.
```bash theme={null}
npx zapier-sdk signup --use-approvals
# or, if you already have an account:
npx zapier-sdk login --use-approvals
```
Use headless authentication when your terminal cannot open a browser, like
an SSH session or remote dev box. The CLI prints a signup or login URL; open
it somewhere with a browser, finish authentication, then paste the final
callback URL back into the terminal.
```bash theme={null}
npx zapier-sdk signup --headless
# or, if you already have an account:
npx zapier-sdk login --headless
```
If an agent is running the command and should never stop for prompts,
combine it with `--non-interactive`:
```bash theme={null}
npx zapier-sdk signup --non-interactive --headless
# or, if you already have an account:
npx zapier-sdk login --non-interactive --headless
```
The [client credentials guide](/sdk/deploy) covers creation, secure storage, and how to use them across platforms.
```typescript theme={null}
const zapier = createZapierSdk({
credentials: {
clientId: process.env.ZAPIER_CREDENTIALS_CLIENT_ID,
clientSecret: process.env.ZAPIER_CREDENTIALS_CLIENT_SECRET,
},
});
```
You can also provide a token directly:
```typescript theme={null}
const zapier = createZapierSdk({
credentials: process.env.ZAPIER_CREDENTIALS,
});
```
## Step 4: Generate Types for Your Apps
The SDK can generate TypeScript types for any app, giving you full autocomplete and type safety:
```bash theme={null}
# Add types for the apps you want to use
npx zapier-sdk add slack google-sheets
# Don't know the app key? Search for it
npx zapier-sdk list-apps --search "google sheets"
```
Types are generated in your `src` or `lib` folder by default. You can customize the output location:
```bash theme={null}
npx zapier-sdk add slack --types-output ./types
```
## Step 5: Initialize the SDK
Create a new file (e.g., `index.ts`) and initialize the SDK:
```typescript theme={null}
import { createZapierSdk } from "@zapier/zapier-sdk";
// Initialize with browser-based auth (from `zapier-sdk signup` or `zapier-sdk login`).
const zapier = createZapierSdk();
```
## Step 6: List Your Connected Apps
Let's verify everything works by listing available apps:
```typescript theme={null}
// List the first page of apps
const { data: apps } = await zapier.listApps();
console.log(
"Available apps:",
apps.map((app) => app.title)
);
```
This returns the first page of results. For large datasets, use `.items()` to
iterate over all results or `maxItems` to limit the total. See the [API
Reference](/sdk/reference) for pagination patterns.
Run your script:
```bash theme={null}
npx tsx index.ts
```
## Step 7: Run Your First Action
Now let's execute an action. First, you'll need a connection for the app you want to use:
```typescript theme={null}
// Get Slack connection
// Option 1: Use listConnections when you need to filter or
// work with multiple connections.
const { data: allSlackConnections } = await zapier.listConnections({
appKey: "slack",
owner: "me",
isExpired: false,
});
const acmeSlackConnection = allSlackConnections.find(c => c?.title?.toLowerCase().includes("acme"))
if (!acmeSlackConnection) {
console.log(
"Slack connection matching filter not found. Connect Slack at https://zapier.com/app/assets/connections"
);
}
// Option 2: Use findFirstConnection when you just need the first
// available connection and let any errors bubble up
const { data: firstSlackConnection } = await zapier.findFirstConnection({
appKey: "slack",
owner: "me",
});
// List Slack channels using your connection
const { data: channels } = await zapier.runAction({
appKey: "slack",
actionType: "read",
actionKey: "channels",
connectionId: firstSlackConnection.id,
});
console.log("Your Slack channels:", channels);
```
## Step 8: Use the Proxy Pattern (Optional)
For a cleaner syntax, use the app proxy pattern:
```typescript theme={null}
const { data: firstSlackConnection } = await zapier.findFirstConnection({
appKey: "slack",
owner: "me",
isExpired: false,
});
// Create a bound Slack instance
const mySlack = zapier.apps.slack({
connectionId: firstSlackConnection.id,
});
// Now use it with a clean syntax
const { data: channels } = await mySlack.read.channels({});
console.log("Channels:", channels);
// Or pass auth inline without binding
const { data: users } = await zapier.apps.slack.search.user_by_email({
inputs: { email: "colleague@company.com" },
connectionId: firstSlackConnection.id,
});
```
## Step 9: Make Custom API Calls with `fetch` (Optional)
**Note on governance:** The `.fetch()` method makes authenticated API calls
directly, giving you access to any supported endpoint. Unlike pre-built
actions, these direct API calls are not currently subject to your org's app or
action restriction policies. If your org has governance requirements, use
pre-built actions where possible. Direct API governance is on the roadmap.
When you need to call an API that doesn't have a built-in action, use `fetch` to make authenticated requests through the Zapier SDK:
```typescript theme={null}
// Get your Slack connection
const { data: slackConnection } = await zapier.findFirstConnection({
appKey: "slack",
owner: "me",
isExpired: false,
});
if (!slackConnection) {
console.log(
"No Slack connection found. Connect Slack at https://zapier.com/app/assets/connections"
);
process.exit(1);
}
// Make a custom API call—Zapier injects the user's credentials
const response = await zapier.fetch("https://slack.com/api/users.list", {
method: "GET",
connectionId: slackConnection.id,
});
const users = await response.json();
```
## Complete Example
Here's a full example that sends a Slack message:
```typescript theme={null}
import { createZapierSdk } from "@zapier/zapier-sdk";
async function main() {
const zapier = createZapierSdk();
// Get Slack connection
const { data: firstSlackConnection } = await zapier.findFirstConnection({
appKey: "slack",
owner: "me",
isExpired: false,
});
// Create bound Slack instance
const slack = zapier.apps.slack({
connectionId: firstSlackConnection.id,
});
// Get available channels
const { data: channels } = (await slack.read.channels({})) as {
data: Array<{ id: string; name: string }>;
};
const testChannel = channels.find((c) => c.name === "testing");
if (!testChannel) {
throw new Error("Could not find #testing channel");
}
// Send a message
const { data: result } = await slack.write.channel_message({
inputs: {
channel: testChannel.id,
text: "Hello from the Zapier SDK!",
},
});
console.log("Message sent!", result);
}
main().catch(console.error);
```
## Next Steps
* [API Reference](/sdk/reference) — full documentation of all SDK methods and patterns
* [CLI Reference](/sdk/cli-reference) — command-line tools including list-apps, add, and view-policy
* [Browse integrations](https://zapier.com/apps) — {appCount} apps you can connect
* [Try the demo use case](/sdk) — the meeting reschedule example on the overview page is a confirmed working end-to-end scenario, good for testing your setup
* [Hit a problem?](https://npsup.zapier.app/contact-us?product=Zapier%20SDK) — tell us what broke via the feedback form