@zapier/zapier-sdk

Table of Contents

• Installation
• Quick Start
• Available Functions
• Accounts
  • getProfile
• Actions
  • getAction
  • getInputFieldsSchema
  • 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",
});

getInputFieldsSchema

Get the JSON Schema representation of input fields for an action. Returns a JSON Schema object describing the structure, types, and validation rules for the action's input parameters.

Parameters:

| Name | Type | Required | Default | Possible Values | Description | | -------------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | options | object | ✅ | — | — | | | ↳ appKey | string | ✅ | — | — | App key (e.g., 'SlackCLIAPI' or slug like 'github') to get the input schema for | | ↳ 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 get the input schema for | | ↳ authenticationId | string | ❌ | — | — | Authentication ID to use when fetching the schema. Required if the action needs authentication to determine available fields. | | ↳ inputs | object | ❌ | — | — | Current input values that may affect the schema (e.g., when fields depend on other field values) |

Returns: Promise<InputSchemaItem>

Example:

const { data: inputSchema } = await sdk.getInputFieldsSchema({
  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",
});