Org.OpenAPITools - FastEndpoints ASP.NET Server

Hi, there!

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

The endpoints of this root API are static and useful for reference. To see the live playground with dynamic API endpoints that match up to your own actions, log in first, then go here:

NLA Dynamic API.

Overview <a name="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 <a name="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 <a name="auth">

For Quickly Exploring <a name="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) <a name="server-side">

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) <a name="production">

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 <a name="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 <a name="using-the-api">

Understanding the AI guessing flow <a name="ai-guessing">

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 <a name="common-api-uses">

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 <a name="list-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 <a name="get-hints">

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 <a name="execute-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 <a name="return-data">

The Status Key <a name="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 <a name="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\": \"[email protected]\",
            \"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\": \"[email protected], [email protected]\"
            \"to__email\": \"Mike Knoop\",
        }
    }

Changelog <a name="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

Documentation

This generated project include basic configuration for FastEndpoints ASP.NET Server. For more information regarding FastEndpoints, please visit the FastEndpoints website.

Enabled Features

The following feature have been enabled in this project :

No additional features enabled

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.openapi-generator		.openapi-generator
src/Org.OpenAPITools		src/Org.OpenAPITools
.gitignore		.gitignore
.openapi-generator-ignore		.openapi-generator-ignore
Org.OpenAPITools.sln		Org.OpenAPITools.sln
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Org.OpenAPITools - FastEndpoints ASP.NET Server

Hi, there!

Overview <a name="overview">

Two Usage Modes <a name="usage-modes">

Why Natural Language?

Auth <a name="auth">

For Quickly Exploring <a name="exploring">

For Testing or Production (Server-side only mode) <a name="server-side">

For Production (User-facing mode) <a name="production">

Action Setup Window <a name="action-setup-window">

Using the API <a name="using-the-api">

Understanding the AI guessing flow <a name="ai-guessing">

Common API use cases <a name="common-api-uses">

1. Get a list of the current user's exposed actions <a name="list-exposed-actions">

2. Get a list of an action's optional hint parameters <a name="get-hints">

3. Execute (or preview) an action <a name="execute-action">

Execution Return Data <a name="return-data">

The Status Key <a name="status-key">

The Result Key <a name="result-key">

Changelog <a name="changelog">

Documentation

Enabled Features

About

Uh oh!

Releases

Packages

Languages

sclark-org/zapier-openapi-aspnetfast-server

Folders and files

Latest commit

History

Repository files navigation

Org.OpenAPITools - FastEndpoints ASP.NET Server

Hi, there!

Overview <a name="overview">

Two Usage Modes <a name="usage-modes">

Why Natural Language?

Auth <a name="auth">

For Quickly Exploring <a name="exploring">

For Testing or Production (Server-side only mode) <a name="server-side">

For Production (User-facing mode) <a name="production">

Action Setup Window <a name="action-setup-window">

Using the API <a name="using-the-api">

Understanding the AI guessing flow <a name="ai-guessing">

Common API use cases <a name="common-api-uses">

1. Get a list of the current user's exposed actions <a name="list-exposed-actions">

2. Get a list of an action's optional hint parameters <a name="get-hints">

3. Execute (or preview) an action <a name="execute-action">

Execution Return Data <a name="return-data">

The Status Key <a name="status-key">

The Result Key <a name="result-key">

Changelog <a name="changelog">

Documentation

Enabled Features

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages