@zapier/zapier-sdk

@zapier/zapier-sdk

Table of Contents

• Installation
• Quick Start
• Available Functions
• Accounts
  • getProfile
• Actions
  • getAction
  • listActions
  • listInputFieldChoices
  • listInputFields
  • runAction
• Apps
  • apps.{appKey}
  • apps.{appKey}.{actionType}.{actionKey}
  • getApp
  • listApps
• Authentications
  • findFirstAuthentication
  • findUniqueAuthentication
  • getAuthentication
  • listAuthentications
• HTTP Requests
  • fetch
  • request

Installation

# If starting a new project:
cd your-project-dir
npm init -y
npx tsc --init
# Also, set `"type": "module"` in your package.json for the code examples below.

npm install @zapier/zapier-sdk
npm install -D @zapier/zapier-sdk-cli @types/node typescript

Quick Start

# Authenticates through your browser, automatically handling token management
npx zapier-sdk login

# Generate TypeScript types for actions and fields of any apps you want to use.
npx zapier-sdk add slack google-sheets

# The names of apps are there slugs if available, otherwise internal keys. If
# you don't know the slug or key, just use `list-apps` search to find it.
zapier-sdk list-apps --search "google sheets"

# The output will show you the valid keys next to the app title like this:
# 1. Google Sheets (GoogleSheetsV2CLIAPI, google-sheets, google_sheets)

# By default, types will be generated inside your `src` or `lib` folder if you
# have one or otherwise the root folder. Make sure your `tsconfig.json` file
# includes the generated type files.

# Alternatively, you can specify a custom output directory.
npx zapier-sdk add slack google-sheets --types-output ./types

import { createZapierSdk } from "@zapier/zapier-sdk";

// ######## Initialize Zapier SDK ########
// Running `zapier-sdk login` authenticates through your browser, automatically handling token management
const zapier = createZapierSdk();

// Option 2: Manually provide a token
// const zapier = createZapierSdk({
//   token: "your_zapier_token_here", // or use ZAPIER_TOKEN env var
// });

// ######## Access Apps ########
// List methods return a promise for a page with {data, nextCursor}.
const { data: firstPageApps, nextCursor } = await zapier.listApps();
// Use the cursor to get the next page:
const { data: secondPageApps } = await zapier.listApps({ cursor: nextCursor });

console.log({
  firstPageApps,
  secondPageApps,
});

// List methods also return an iterator for all pages.
// Be careful with lots of pages, note the `search` to filter.
for await (const page of zapier.listApps({ search: "slack" })) {
  const { data: apps } = page;
  console.log({
    apps,
  });
}

// Use `.items()` to iterate over all items of all pages:
// Again, be careful with lots of items. Note the `maxItems` to limit the total items.
for await (const app of zapier.listApps({ maxItems: 100 }).items()) {
  console.log({
    app,
  });
}

// You can collect all results, but this could take a while for long lists!
const allApps = await Array.fromAsync(
  zapier.listApps({ maxItems: 100 }).items(),
);

console.log({
  allApps,
});

// The item methods return a promise for a single item, wrapped with {data}.
// This is just to give us room to add metadata in the future.
const { data: app } = await zapier.getApp({ appKey: "slack" });

console.log({
  app,
});

// ######## Authentication Usage ########
const { data: myAuths } = await zapier.listAuthentications({
  appKey: "slack",
  owner: "me",
});

console.log({
  myAuths,
});

// ######## Find Actions ########
// Option 1: List actions
// Remember, this is just the first page which may not include them all!
// See `.items()` usage above, which can be used to make sure you get all actions.
const { data: actions } = await zapier.listActions({ appKey: "slack" });

console.log({
  actions,
});

const singleAction = await zapier.getAction({
  appKey: "slack",
  actionType: actions[0].action_type,
  actionKey: actions[0].key,
});

console.log({
  singleAction,
});

// Option 2: Access actions via the `apps` proxy
// If you've generated TS types for an app using `zapier-sdk add`, you can access the app's actions like this:

// await zapier.apps.slack.read.channles({});
// await zapier.apps.slack.write.send_message({})

// ######## Run Actions ########
// Option 1:
const { data: channels } = await zapier.runAction({
  appKey: "slack",
  actionType: "read",
  actionKey: "channels",
  authenticationId: myAuths[0].id,
});

console.log({
  channels,
});

const { data: profile } = await zapier.getProfile();

// Option 2:
// Create an app binding to your authentication.
const mySlack = zapier.apps.slack({
  authenticationId: myAuths[0].id,
});

// Use your app binding to run the action.
const { data: users } = await mySlack.search.user_by_email({
  inputs: {
    email: profile.email,
  },
});

console.log({
  users,
});

// You can also skip the app binding and pass the auth into the action.
const { data: sameUsers } = await zapier.apps.slack.search.user_by_email({
  inputs: {
    email: profile.email,
  },
  authenticationId: myAuths[0].id,
});

console.log({
  sameUsers,
});

// If the slug for an app has dashes, you can also use a snake_cased app key.
// For example, either of the following are valid:
// zapier.apps["google-sheets"]
// zapier.apps.google_sheets

Available Functions

Accounts

getProfile

Get current user's profile information

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	❌	—	—

Returns: Promise<ProfileItem>

Example:

const { data: profile } = await sdk.getProfile();

Actions

getAction

Get detailed information about a specific action

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	✅	—	—	App key (e.g., 'SlackCLIAPI' or slug like 'github')
↳ actionType	string	✅	—	read, read_bulk, write, run, search, search_or_write, search_and_write, filter	Action type that matches the action's defined type
↳ actionKey	string	✅	—	—	Action key to execute

Returns: Promise<ActionItem>

Example:

const { data: action } = await sdk.getAction({
  appKey: "example-key",
  actionType: "read",
  actionKey: "example-key",
});

listActions

List all actions for a specific app

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	✅	—	—	App key of actions to list (e.g., 'SlackCLIAPI' or slug like 'github')
↳ actionType	string	❌	—	read, read_bulk, write, run, search, search_or_write, search_and_write, filter	Filter actions by type
↳ pageSize	number	❌	—	—	Number of actions per page
↳ maxItems	number	❌	—	—	Maximum total items to return across all pages
↳ cursor	string	❌	—	—	Cursor to start from

Returns: Promise<PaginatedResult<ActionItem>>

Example:

// Get first page and a cursor for the second page
const { data: actions, nextCursor } = await sdk.listActions({
  appKey: "example-key",
});

// Or iterate over all pages
for await (const page of sdk.listActions({
  appKey: "example-key",
})) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const action of sdk
  .listActions({
    appKey: "example-key",
  })
  .items()) {
  // Do something with each action
}

listInputFieldChoices

Get the available choices for a dynamic dropdown input field

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	✅	—	—	App key (e.g., 'SlackCLIAPI' or slug like 'github')
↳ actionType	string	✅	—	read, read_bulk, write, run, search, search_or_write, search_and_write, filter	Action type that matches the action's defined type
↳ actionKey	string	✅	—	—	Action key to execute
↳ inputFieldKey	string	✅	—	—	Input field key to get choices for.
↳ authenticationId	string	❌	—	—	Authentication ID to use for this action
↳ inputs	object	❌	—	—	Current input values that may affect available choices
↳ page	number	❌	—	—	Page number for paginated results
↳ pageSize	number	❌	—	—	Number of choices per page
↳ maxItems	number	❌	—	—	Maximum total items to return across all pages
↳ cursor	string	❌	—	—	Cursor to start from

Returns: Promise<PaginatedResult<InputFieldChoiceItem>>

Example:

// Get first page and a cursor for the second page
const { data: inputFieldChoices, nextCursor } = await sdk.listInputFieldChoices(
  {
    appKey: "example-key",
    actionType: "read",
    actionKey: "example-key",
    inputFieldKey: "example-key",
  },
);

// Or iterate over all pages
for await (const page of sdk.listInputFieldChoices({
  appKey: "example-key",
  actionType: "read",
  actionKey: "example-key",
  inputFieldKey: "example-key",
})) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const inputFieldChoice of sdk
  .listInputFieldChoices({
    appKey: "example-key",
    actionType: "read",
    actionKey: "example-key",
    inputFieldKey: "example-key",
  })
  .items()) {
  // Do something with each inputFieldChoice
}

listInputFields

Get the input fields required for a specific action

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	✅	—	—	App key (e.g., 'SlackCLIAPI' or slug like 'github')
↳ actionType	string	✅	—	read, read_bulk, write, run, search, search_or_write, search_and_write, filter	Action type that matches the action's defined type
↳ actionKey	string	✅	—	—	Action key to execute
↳ authenticationId	string	❌	—	—	Authentication ID to use for this action
↳ inputs	object	❌	—	—	Current input values that may affect available fields
↳ pageSize	number	❌	—	—	Number of input fields per page
↳ maxItems	number	❌	—	—	Maximum total items to return across all pages
↳ cursor	string	❌	—	—	Cursor to start from

Returns: Promise<PaginatedResult<RootFieldItemItem>>

Example:

// Get first page and a cursor for the second page
const { data: rootFieldItems, nextCursor } = await sdk.listInputFields({
  appKey: "example-key",
  actionType: "read",
  actionKey: "example-key",
});

// Or iterate over all pages
for await (const page of sdk.listInputFields({
  appKey: "example-key",
  actionType: "read",
  actionKey: "example-key",
})) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const rootFieldItem of sdk
  .listInputFields({
    appKey: "example-key",
    actionType: "read",
    actionKey: "example-key",
  })
  .items()) {
  // Do something with each rootFieldItem
}

runAction

Execute an action with the given inputs

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	✅	—	—	App key (e.g., 'SlackCLIAPI' or slug like 'github')
↳ actionType	string	✅	—	read, read_bulk, write, run, search, search_or_write, search_and_write, filter	Action type that matches the action's defined type
↳ actionKey	string	✅	—	—	Action key to execute
↳ authenticationId	string	❌	—	—	Authentication ID to use for this action
↳ inputs	object	❌	—	—	Input parameters for the action
↳ pageSize	number	❌	—	—	Number of results per page
↳ maxItems	number	❌	—	—	Maximum total items to return across all pages
↳ cursor	string	❌	—	—	Cursor to start from

Returns: Promise<PaginatedResult<ActionResultItem>>

Example:

// Get first page and a cursor for the second page
const { data: actionResults, nextCursor } = await sdk.runAction({
  appKey: "example-key",
  actionType: "read",
  actionKey: "example-key",
});

// Or iterate over all pages
for await (const page of sdk.runAction({
  appKey: "example-key",
  actionType: "read",
  actionKey: "example-key",
})) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const actionResult of sdk
  .runAction({
    appKey: "example-key",
    actionType: "read",
    actionKey: "example-key",
  })
  .items()) {
  // Do something with each actionResult
}

Apps

apps.{appKey}

Bind an authentication ID to an app

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ authenticationId	number	✅	—	—

Returns: Promise<AppProxy>

Example:

const result = await sdk.apps.appKey({
  authenticationId: 12345,
});

apps.{appKey}.{actionType}.{actionKey}

Execute an action with the given inputs for the bound app, as an alternative to runAction

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ inputs	object	❌	—	—
↳ authenticationId	number	❌	—	—

Returns: Promise<PaginatedResult<ActionResultItem>>

Example:

// Get first page and a cursor for the second page
const { data: actionResults, nextCursor } =
  await sdk.apps.appKey.actionType.actionKey();

// Or iterate over all pages
for await (const page of sdk.apps.appKey.actionType.actionKey()) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const actionResult of sdk.apps.appKey.actionType
  .actionKey()
  .items()) {
  // Do something with each actionResult
}

getApp

Get detailed information about a specific app

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	✅	—	—	App key of app to fetch (e.g., 'SlackCLIAPI' or slug like 'github')

Returns: Promise<AppItem>

Example:

const { data: app } = await sdk.getApp({
  appKey: "example-key",
});

listApps

List all available apps with optional filtering

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKeys	array	❌	—	—	Filter apps by app keys (e.g., 'SlackCLIAPI' or slug like 'github')
↳ search	string	❌	—	—	Search for apps by name
↳ pageSize	number	❌	—	—	Number of apps per page
↳ maxItems	number	❌	—	—	Maximum total items to return across all pages
↳ cursor	string	❌	—	—	Cursor to start from

Returns: Promise<PaginatedResult<AppItem>>

Example:

// Get first page and a cursor for the second page
const { data: apps, nextCursor } = await sdk.listApps();

// Or iterate over all pages
for await (const page of sdk.listApps()) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const app of sdk.listApps().items()) {
  // Do something with each app
}

Authentications

findFirstAuthentication

Find the first authentication matching the criteria

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	❌	—	—	App key of authentication to find (e.g., 'SlackCLIAPI' or slug like 'github')
↳ search	string	❌	—	—	Search term to filter authentications by title
↳ title	string	❌	—	—	Filter authentications by exact title match
↳ accountId	string	❌	—	—	Filter by account ID
↳ owner	string	❌	—	—	Filter by owner

Returns: Promise<AuthenticationItem>

Example:

const { data: authentication } = await sdk.findFirstAuthentication();

findUniqueAuthentication

Find a unique authentication matching the criteria

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	❌	—	—	App key of authentication to find (e.g., 'SlackCLIAPI' or slug like 'github')
↳ search	string	❌	—	—	Search term to filter authentications by title
↳ title	string	❌	—	—	Filter authentications by exact title match
↳ accountId	string	❌	—	—	Filter by account ID
↳ owner	string	❌	—	—	Filter by owner

Returns: Promise<AuthenticationItem>

Example:

const { data: authentication } = await sdk.findUniqueAuthentication();

getAuthentication

Get a specific authentication by ID

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ authenticationId	number	✅	—	—	Authentication ID to retrieve

Returns: Promise<AuthenticationItem>

Example:

const { data: authentication } = await sdk.getAuthentication({
  authenticationId: 12345,
});

listAuthentications

List available authentications with optional filtering

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ appKey	string	❌	—	—	App key of authentications to list (e.g., 'SlackCLIAPI' or slug like 'github')
↳ authenticationIds	array	❌	—	—	List of authentication IDs to filter by
↳ search	string	❌	—	—	Search term to filter authentications by title
↳ title	string	❌	—	—	Filter authentications by exact title match
↳ accountId	string	❌	—	—	Filter by account ID
↳ owner	string	❌	—	—	Filter by owner, 'me' for your own authentications or a specific user ID
↳ pageSize	number	❌	—	—	Number of authentications per page
↳ maxItems	number	❌	—	—	Maximum total items to return across all pages
↳ cursor	string	❌	—	—	Cursor to start from

Returns: Promise<PaginatedResult<AuthenticationItem>>

Example:

// Get first page and a cursor for the second page
const { data: authentications, nextCursor } = await sdk.listAuthentications();

// Or iterate over all pages
for await (const page of sdk.listAuthentications()) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const authentication of sdk.listAuthentications().items()) {
  // Do something with each authentication
}

HTTP Requests

fetch

Execute fetch

Parameters:

Name	Type	Required	Default	Possible Values	Description
url	string	✅	—	—	The URL to fetch
init	object	❌	—	—	Fetch options including authentication
↳ method	string	❌	—	GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
↳ headers	object	❌	—	—
↳ body	string	❌	—	—
↳ authenticationId	number	❌	—	—	Zapier authentication ID to use for the request
↳ callbackUrl	string	❌	—	—	URL to send async response to (makes request async)
↳ authenticationTemplate	string	❌	—	—	Optional JSON string authentication template to bypass Notary lookup

Returns: Promise<Response>

Example:

const result = await sdk.fetch("https://example.com", { key: "value" });

request

Make authenticated HTTP requests through Zapier's Relay service

Parameters:

Name	Type	Required	Default	Possible Values	Description
options	object	✅	—	—
↳ url	string	✅	—	—	The URL to request (will be proxied through Relay)
↳ method	string	❌	—	GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS	HTTP method
↳ body	string	❌	—	—	Request body as a string
↳ authenticationId	number	❌	—	—	Zapier authentication ID to use for the request
↳ callbackUrl	string	❌	—	—	URL to send async response to (makes request async)
↳ authenticationTemplate	string	❌	—	—	Optional JSON string authentication template to bypass Notary lookup
↳ headers	string	❌	—	—	Request headers
↳ relayBaseUrl	string	❌	—	—	Base URL for Relay service

Returns: Promise<Response>

Example:

const result = await sdk.request({
  url: "https://example.com",
});