openpm

Hello, friend!

Welcome to the Zapier Natural Language Actions API docs. You are currently viewing the dynamic API.

The endpoints below are dynamically generated based on your current user session and enabled actions.

These dynamic endpoints provide a playground below for understanding how the API works, its capabilities, and how they match up to the user-facing action setup screens.

The static docs can be found here, though generally the dynamic docs are much better, if you have at least one enabled action.

Overview

Zapier is an integration platform with over 5,000+ apps and 50,000+ actions. You can view the full list here. Zapier is used by millions of users, most of whom are non-technical builders -- but often savvy with software. Zapier offers several no code products to connect together the various apps on our platform. NLA exposes the same integrations Zapier uses to build our products, to you, to plug-in the capabilties of Zapier's platform into your own products.

For example, you can use the NLA API to:

Send messages in Slack
Add a row to a Google Sheet
Draft a new email in Gmail
... and thousands more, with one universal natural language API

The typical use-case for NLA is to expose our ecosystem of thousands of apps/actions within your own product. NLA is optimized for products that receive user input in natural language (eg. chat, assistant, or other large language model based experience) -- that said, it can also be used to power any product that needs integrations. In this case, think of NLA as a more friendly, human API.

NLA contains a decade of experience with API shenanigans, so you don't have to. Common API complexity, automatically handled:

Every type of auth (Basic, Session, API Key, OAuth v1, Oauth v2, Digest, ...), Zapier securely handles and signs requests for you
Support for create, update, and search actions, endpoints optimized for natural language usage
Support for custom fields, Spreadsheet, CRM, and Mailing List friendly!
Reference by name, not ID, humans use natural language names, not IDs, to reference things in their apps, so NLA does too
Smart, human defaults, APIs sometimes have 100 options. Zapier's platform data helps us make NLA simpler for users out of the box

Two Usage Modes

NLA handles all the underlying API auth and translation from natural language --> underlying API call --> return simplified output. The key idea is you (the developer), or your users, expose a set of actions via an oauth-like setup window, which you can then query and execute via a REST API. NLA offers both API Key and OAuth for signing NLA API requests.

Server-side only (API Key): for quickly getting started, testing, and production scenarios where your app will only use actions exposed in the developer's Zapier account (and will use the developer's connected accounts on Zapier.com)
User-facing (Oauth): for production scenarios where you are deploying an end-user facing application and your app needs access to end-user's exposed actions and connected accounts on Zapier.com

Why Natural Language?

Simply, it makes the API easier to use for both developers and users (and also for large language models!)

We designed NLA to expose the power of Zapier's platform without passing along the complexity. A few design choices:

There is a user-facing component to NLA, exposed via a popup window, users set up and enable basic actions which "expose" them to you, the provider.
The default action setup for users is minimal and fast. All required fields are guessed. This guessing is accomplished using an lanuage model on the NLA side.
Users can choose to override any guessed field with a fixed value or choice, increasing trust to use the natural language interface.
Custom fields (ex. spreadsheet columns) can also be dynamically guessed at action run time, or fixed by the user.

Using the API is then simple:

curl -v \
    -d '{"instructions": "Add Bryan Helmig at Zapier to my NLA test sheet, oh and he loves guitars!"}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    'https://nla.zapier.com/api/v1/dynamic/exposed/<ACTION_ID>/execute/'

Or mix in some fixed values:

curl -v \
    -d '{"instructions": "Send a short poem about automation to slack", "channel": "#fun-zapier"}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    'https://nla.zapier.com/api/v1/dynamic/exposed/<ACTION_ID>/execute/'

Auth

For Quickly Exploring

It's best to take advantage of session auth built into the OpenAPI docs.

Log in
Create and enable an action using our demo provider

then all your enabled ("exposed") actions will be available at the bottom of the the dynamic API.

For Testing or Production (Server-side only mode)

For development purposes, or using NLA in a server-side only use case, you can get started quickly using the provider dev. You can generate an API key using this provider and make authenticated requests.

Please follow these steps:

Go to the Dev App provider debug page.
Look for "User" -> "Information" -> "API Key". If a key does not exist, follow the instructions to generate one.
Use this key in the header x-api-key to make authenticated requests.

Test that the API key is working:

curl -v \
    -H "Content-Type: application/json" \
    -H "x-api-key: <API_KEY>" \
    'https://nla.zapier.com/api/v1/check/'

For Production (User-facing mode)

The API is authenticated via standard OAuth v2. Submit this form to get access and receive a cliend_id, client_secret, and your provider name (ex. 'acme'). You'll also need to share with us a redirect_uri to receive each code. This API uses both access_token and refresh_token.

Each of your users will get a per-user access token which you'll use to sign requests. The access token both authenticates and authorizes a request to access or run (execute) a given user's actions.

The basic auth flow is:

Send user to our OAuth start URL, ideally in a popup window

var url = https://nla.zapier.com/oauth/authorize/?
    response_type=code&
    client_id=<YOUR_CLIENT_ID>&
    redirect_uri=<YOUR_REDIRECT_URI>&
    scope=nla%3Aexposed_actions%3Aexecute
var nla = window.open(url, 'nla', 'width=650,height=700');

User approves request for access
NLA will redirect user via GET to the redirect_uri you provided us with a ?code= in the query string
Snag the code and POST it to the NLA token endpoint https://nla.zapier.com/oauth/token/

curl -v \
    -d '{ \
        "code": "<CODE>", \
        "grant_type": "authorization_code", \
        "client_id": "<YOUR_CLIENT_ID>", \
        "client_secret": "<YOUR_CLIENT_SECRET>" \
        }' \
    -H "Content-Type: application/json" \
    -X POST 'https://nla.zapier.com/oauth/token/'

Finally, receive refresh_token and access_token in response

Save the refresh token, you'll need to use it to request a new access tokehn when it expires.

Now you can use the access_token to make authenticated requests:

curl -v -H "Authorization: Bearer <ACCESS_TOKEN>" https://nla.zapier.com/api/v1/dynamic/openapi.json

When the access_token expires, refresh it

curl -v \
    -d '{ \
        "refresh_token": "<REFRESH_TOKEN>", \
        "grant_type": "refresh_token", \
        "client_id": "<YOUR_CLIENT_ID>", \
        "client_secret": "<YOUR_CLIENT_SECRET>" \
        }' \
    -H "Content-Type: application/json" \
    -X POST 'https://nla.zapier.com/oauth/token/'

Action Setup Window

Users set up their actions inside a window popup, that looks and feels similar to an OAuth window. The setup URL is the same for all your users: https://nla.zapier.com/<PROVIDER>/start/

You can check the validity of an access/refresh token by checking against the api/v1/check/ endpoint to determine if you should present the oauth/authorize/ or <PROVIDER>/start/ url.

You'd typically include a button or link somewhere inside your product to open the setup window.

var nla = window.open('https://nla.zapier.com/<PROVIDER>/start', 'nla', 'width=650,height=700');

Note: the setup window is optimized for 650px width, 700px height

Using the API

Understanding the AI guessing flow

NLA is optimized for a chat/assistant style usage paradigm where you want to offload as much work to a large language model, as possible. For end users, the action setup flow that takes ~seconds (compared to minutes/hours with traditional, complex integration setup).

An action is then run (executed) via an API call with one single natural language parameter instructions. In the chat/assistant use case, these instructions are likely being generated by your own large language model. However NLA works just as well even in more traditional software paradigm where instructions are perhaps hard-coded into your codebase or supplied by the user directly.

Consider the case where you've built a chat product and your end user wants to expose a "Send Slack Message" action to your product. Their action setup might look like this.

The user only has to pick Slack and authorize their Slack account. By default, all required fields are set to "Have AI guess". In this example there are two required fields: Channel and Message Text.

If a field uses "Have AI guess", two things happen:

When the action is run via the API, NLA will interpret passed instructions (using a language model) to fill in the values for Channel and Message Text. NLA is smart about fields like Channel -- Slack's API requires a Channel ID, not a plain text Channel name. NLA handles all such cases automatically.
The field will be listed as an optional hint parameter in the OpenAPI spec (see "hint parameters" below) which allows you (the developer) to override any instructions guessing.

Sometimes language models hallucinate or guess wrong. And if this were a particuarly sensitive Slack message, the user may not want to leave the selection of "Channel" up to chance. NLA allows the user to use a specific, fixed value like this.

Now when the action executes, the Message Text will still be automatically guessed but Channel will be fixed to "#testing". This significantly increases user trust and unlocks use cases where the user may have partial but not full trust in an AI guessing.

We call the set of fields the user denoted "Have AI guess" as "hint parameters" -- Message Text above in the above example is one. They are always optional. When running actions via the API, you (the developer) can choose to supply none/any/all hint parameters. Any hint parameters provided are treated exactly like "Use a specific value" at the user layer -- as an override.

One aside: custom fields. Zapier supports custom fields throughout the platform. The degenerate case is a spreadsheet, where every column is a custom field. This introduces complexity because sheet columns are unknowable at action setup time if the user picks "Have AI guess" for which spreadsheet. NLA handles such custom fields using the same pattern as above with one distinction: they are not listed as hint parameters because they are literally unknowable until run time. Also as you may expect, if the user picks a specific spreadsheet during action setup, custom fields act like regular fields and flow through normally.

In the typical chat/assistant product use case, you'll want to expose these hint parameters alongside the exposed action list to your own language model. Your language model is likely to have broader context about the user vs the narrowly constrained instructions string passed to the API and will result in a better guess.

In summary:

[user supplied "Use specific value"] --overrides--> [API call supplied hint parameters] --overrides--> [API call supplied "instructions"]

Common API use cases

There are three common usages:

Get a list of the current user's exposed actions
Get a list of an action's optional hint parameters
Execute an action

Let's go through each, assuming you have a valid access token already.

1. Get a list of the current user's exposed actions

# via the RESTful list endpoint:
curl -v -H "Authorization: Bearer <ACCESS_TOKEN>" https://nla.zapier.com/api/v1/dynamic/exposed/

# via the dynamic openapi.json schema:
curl -v -H "Authorization: Bearer <ACCESS_TOKEN>" https://nla.zapier.com/api/v1/dynamic/openapi.json

Example of full list endpoint response here, snipped below:

{
    "results": [
        {
            "id": "01GTB1KMX72QTJEXXXXXXXXXX",
            "description": "Slack: Send Channel Message",
            ...

Example of full openapi.json response here, snipped below:

{
    ...
    "paths": {
        ...
        "/api/v1/dynamic/exposed/01GTB1KMX72QTJEXXXXXXXXXX/execute/": {
            "post": {
                "operationId": "exposed_01GTB1KMX72QTJEXXXXXXXXXX_execute",
                "summary": "Slack: Send Channel Message (execute)",
                ...

2. Get a list of an action's optional hint parameters

As a reminder, hint parameters are always optional. By default, all parameters are filled in via guessing based on a provided instructions parameter. If a hint parameter is supplied in an API request along with instructions, the hint parameter will override the guess.

# via the RESTful list endpoint:
curl -v -H "Authorization: Bearer <ACCESS_TOKEN>" https://nla.zapier.com/api/v1/dynamic/exposed/

# via the dynamic openapi.json schema:
curl -v -H "Authorization: Bearer <ACCESS_TOKEN>" https://nla.zapier.com/api/v1/dynamic/openapi.json

Example of full list endpoint response here, snipped below:

{
    "results": [
        {
            "id": "01GTB1KMX72QTJEXXXXXXXXXX",
            "description": "Slack: Send Channel Message",
            "input_params": {
                "instructions": "str",
                "Message_Text": "str",
                "Channel": "str",
                ...

Example of full openapi.json response here, snipped below:

{
    ...
    "components": {
        "schemas": {
            ...
            "PreviewExecuteRequest_01GTB1KMX72QTJEXXXXXXXXXX": {
                "title": "PreviewExecuteRequest_01GTB1KMX72QTJEXXXXXXXXXX",
                "type": "object",
                "properties": {
                    "instructions": {
                        ...
                    },
                    "Message_Text": {
                        ...
                    },
                    "Channel_Name": {
                        ...
                    }

Note: Every list of input_params will contain instructions, the only required parameter for execution.

3. Execute (or preview) an action

Finally, with an action ID and any desired, optional, hint parameters in hand, we can run (execute) an action. The parameter instructions is the only required parameter run an action.

curl -v \
    -d '{"instructions": "send a short poem about automation and robots to slack", "Channel_Name": "#fun-zapier"}' \
    -H "Content-Type: application/json" \
    -X POST 'https://nla.zapier.com/api/v1/dynamic/exposed/01GTB1KMX72QTJEXXXXXXXXXX/execute/'

Another example, this time an action to retrieve data:

curl -v \
    -d '{"instructions": "grab the latest email from bryan helmig"}' \
    -H "Content-Type: application/json" \
    -X POST 'https://nla.zapier.com/api/v1/dynamic/exposed/01GTA3G1WD49GN1XXXXXXXXX/execute/'

One more example, this time requesting a preview of the action:

curl -v \
    -d '{"instructions": "say Hello World to #fun-zapier", "preview_only": true}' \
    -H "Content-Type: application/json" \
    -X POST 'https://nla.zapier.com/api/v1/dynamic/exposed/01GTB1KMX72QTJEXXXXXXXXXX/execute/'

Execution Return Data

The Status Key

All actions will contain a status. The status can be one of four values:

success

The action executed successfully and found results.

error

The action failed to execute. An error key will have its value populated.

Example:

    {
        ...
        "action_used": "Gmail: Send Email",
        "result": null,
        "status": "error",
        "error": "Error from app: Required field "subject" (subject) is missing. Required field "Body" (body) is missing."
    }

empty

The action executed successfully, but no results were found. This status exists to be explicit that having an empty result is correct.

preview

The action is a preview and not a real execution. A review_url key will contain a URL to optionally execute the action from a browser, or just rerun without the preview_only input parameter.

Example:

    {
        ...
        "action_used": "Slack: Send Channel Message",
        "input_params": {
            "Channel": "fun-zapier",
            "Message_Text": "Hello World"
        },
        "review_url": "https://nla.zapier.com/execution/01GW2E2ZNE5W07D32E41HFT5GJ/?needs_confirmation=true",
        "status": "preview",
    }

The Result Key

All actions will return trimmed result data. result is ideal for humans and language models alike! By default, full_results is not included but can be useful for machines (contact us if you'd like access to full results). The trimmed version is created using some AI and heuristics:

selects for data that is plain text and human readable
discards machine data like IDs, headers, etc.
prioritizes data that is very popular on Zapier
reduces final result into about ~500 words

Trimmed results are ideal for inserting directly back into the prompt context of a large language models without blowing up context token window limits.

Example of a trimmed results payload from "Gmail: Find Email":

    {
        "result": {
            "from__email": "mike@zapier.com",
            "from__name": "Mike Knoop",
            "subject": "Re: Getting setup",
            "body_plain": "Hi Karla, thanks for following up. I can confirm I got access to everything! ... Thanks! Mike",
            "cc__emails": "bryan@zapier.com, wade@zapier.com"
            "to__email": "Mike Knoop",
        }
    }

Changelog

Mar 20, 2023 Shipped two minor but breaking changes, and one other minor change to the API's response data:

Route: /api/v1/configuration-link/
- Key url is now configuration_link (breaking change)
Route: /api/v1/exposed/{exposed_app_action_id}/execute/
- Key rating_url is now review_url (breaking change)
Route: /api/v1/exposed/
- Added configuration_link key

openpm.ai

zapier

Hello, friend!

Overview

Two Usage Modes

Why Natural Language?

Auth

For Quickly Exploring

For Testing or Production (Server-side only mode)

For Production (User-facing mode)

Action Setup Window

Using the API

Understanding the AI guessing flow

Common API use cases

1. Get a list of the current user's exposed actions

2. Get a list of an action's optional hint parameters

3. Execute (or preview) an action

Execution Return Data

The Status Key

The Result Key

Changelog