langchain/tests/unit_tests/tools/openapi/test_specs/zapier/apispec.json

{
   "openapi": "3.0.2",
   "info": {
      "title": "Zapier Natural Language Actions (NLA) API (Dynamic) - Beta",
      "version": "1.0.0",
      "description": "<img src=\"https://cdn.zappy.app/945f9bf9e44126873952ec5113949c3f.png\" width=\"100\" />\n\n## Hello, friend!\nWelcome to the **Zapier Natural Language Actions API docs**. You are currently viewing the **dynamic** API.\n\nThe endpoints below are dynamically generated based on your [current user session](/login/zapier/) and [enabled actions](/demo/).\n\nThese *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.\n\nThe static docs can be [found here](/api/v1/docs), though generally the dynamic docs are much better, if you have at least one [enabled action](/demo/).\n\n\n## Overview <a name=\"overview\"></a>\n\nZapier is an integration platform with over 5,000+ apps and 50,000+ actions. You can view the [full list here](https://zapier.com/apps). 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. \n\nFor example, you can use the NLA API to:\n* Send messages in [Slack](https://zapier.com/apps/slack/integrations)\n* Add a row to a [Google Sheet](https://zapier.com/apps/google-sheets/integrations)\n* Draft a new email in [Gmail](https://zapier.com/apps/gmail/integrations)\n* ... and thousands more, with one universal natural language API\n\nThe 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.\n\nNLA contains a decade of experience with API shenanigans, so you don't have to. Common API complexity, automatically handled:\n* **Every type of auth** (Basic, Session, API Key, OAuth v1, Oauth v2, Digest, ...), Zapier securely handles and signs requests for you\n* **Support for create, update, and search actions**, endpoints optimized for natural language usage\n* **Support for custom fields**, Spreadsheet, CRM, and Mailing List friendly!\n* **Reference by name, not ID**, humans use natural language names, not IDs, to reference things in their apps, so NLA does too\n* **Smart, human defaults**, APIs sometimes have 100 options. Zapier's platform data helps us make NLA simpler for users out of the box\n\n#### Two Usage Modes <a name=\"usage-modes\"></a>\n\nNLA 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.\n\n1. **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)\n\n2. **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\n\n#### Why Natural Language? \n\nSimply, it makes the API easier to use for both developers and users (and also for [large language models](https://en.wikipedia.org/wiki/Wikipedia:Large_language_models)!)\n\nWe designed NLA to expose the power of Zapier's platform without passing along the complexity. A few design choices:\n* There is a [user-facing component](https://cdn.zappy.app/83728f684b91c0afe7d435445fe4ac90.png) to NLA, exposed via a popup window, users set up and enable basic actions which \"expose\" them to you, the `provider`.\n* The default action setup for users is minimal and fast. [All required fields are guessed](https://cdn.zappy.app/20afede9be56bf4e30d31986bc5325f8.png). This guessing is accomplished using an lanuage model on the NLA side.\n* Users can [choose to override any guessed field](https://cdn.zappy.app/e07f6eabfe7512e9decf01cba0c9e847.png) with a fixed value or choice, increasing trust to use the natural language interface.\n* Custom fields (ex. spreadsheet columns) can also be [dynamically guessed at action run time](https://cdn.zappy.app/9061499b4b973200fc345f695b33e3c7.png), or fixed by the user.\n\nUsing the API is then simple:\n\n```\ncurl -v \\\n    -d '{\"instructions\": \"Add Bryan Helmig at Zapier to my NLA test sheet, oh and he loves guitars!\"}' \\\n    -H \"Authorization: Bearer <ACCESS_TOKEN>\" \\\n    -H \"Content-Type: application/json\" \\\n    'https://nla.zapier.com/api/v1/dynamic/exposed/<ACTION_ID>/execute/'\n```\n\nOr mix in some fixed values:\n\n```\ncurl -v \\\n    -d '{\"instructions\": \"Send a short poem about automation to slack\", \"channel\": \"#fun-zapier\"}' \\\n    -H \"Authorization: Bearer <ACCESS_TOKEN>\" \\\n    -H \"Content-Type: application/json\" \\\n    'https://nla.zapier.com/api/v1/dynamic/exposed/<ACTION_ID>/execute/'\n```\n\n## Auth <a name=\"auth\"></a>\n\n#### For Quickly Exploring <a name=\"exploring\"></a>\n\nIt's best to take advantage of session auth built into the OpenAPI docs.\n\n1. [Log in](/login/zapier/)\n2. [Create and enable an action](/demo/) using our `demo` provider\n\nthen all your enabled (\"exposed\") actions will be available at the bottom of the the **[dynamic API](/api/v1/dynamic/docs)**.\n\n#### For Testing or Production (Server-side only mode) <a name=\"server-side\"></a>\n\nFor 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.\n\nPlease follow these steps:\n\n1. Go to the [Dev App provider](/dev/provider/debug/) debug page.\n2. Look for \"User\" -> \"Information\" -> \"API Key\". If a key does not exist, follow the instructions to generate one.\n3. Use this key in the header `x-api-key` to make authenticated requests.\n\nTest that the API key is working:\n\n```\ncurl -v \\\n    -H \"Content-Type: application/json\" \\\n    -H \"x-api-key: <API_KEY>\" \\\n    'https://nla.zapier.com/api/v1/check/'\n```\n\n#### For Production (User-facing mode) <a name=\"production\"></a>\n\nThe API is authenticated via [standard OAuth v2](https://oauth.net/2/). Submit [this form](https://share.hsforms.com/1DWkLQ7SpSZCuZbTxcBB98gck10t) 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`.\n\nEach 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.\n\nThe basic auth flow is:\n\n1. **Send user to our OAuth start URL, ideally in a popup window**\n\n```javascript\nvar url = https://nla.zapier.com/oauth/authorize/?\n    response_type=code&\n    client_id=<YOUR_CLIENT_ID>&\n    redirect_uri=<YOUR_REDIRECT_URI>&\n    scope=nla%3Aexposed_actions%3Aexecute\nvar nla = window.open(url, 'nla', 'width=650,height=700');\n```\n\n2. **User approves request for access**\n\n3. **NLA will redirect user via `GET` to the `redirect_uri` you provided us with a `?code=` in the query string**\n\n4. **Snag the `code` and `POST` it to the NLA token endpoint `https://nla.zapier.com/oauth/token/`**\n\n```\ncurl -v \\\n    -d '{ \\\n        \"code\": \"<CODE>\", \\\n        \"grant_type\": \"authorization_code\", \\\n        \"client_id\": \"<YOUR_CLIENT_ID>\", \\\n        \"client_secret\": \"<YOUR_CLIENT_SECRET>\" \\\n        }' \\\n    -H \"Content-Type: application/json\" \\\n    -X POST 'https://nla.zapier.com/oauth/token/'\n```\n\n5. **Finally, receive `refresh_token` and `access_token` in response**\n\nSave the refresh token, you'll need to use it to request a new access tokehn when it expires.\n\nNow you can use the `access_token` to make authenticated requests:\n\n```\ncurl -v -H \"Authorization: Bearer <ACCESS_TOKEN>\" https://nla.zapier.com/api/v1/dynamic/openapi.json\n```\n\n6. **When the `access_token` expires, refresh it**\n\n```\ncurl -v \\\n    -d '{ \\\n        \"refresh_token\": \"<REFRESH_TOKEN>\", \\\n        \"grant_type\": \"refresh_token\", \\\n        \"client_id\": \"<YOUR_CLIENT_ID>\", \\\n        \"client_secret\": \"<YOUR_CLIENT_SECRET>\" \\\n        }' \\\n    -H \"Content-Type: application/json\" \\\n    -X POST 'https://nla.zapier.com/oauth/token/'\n```\n\n## Action Setup Window <a name=\"action-setup-window\"></a>\n\nUsers 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/`\n\nYou 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.\n\nYou'd typically include a button or link somewhere inside your product to open the setup window.\n\n```javascript\nvar nla = window.open('https://nla.zapier.com/<PROVIDER>/start', 'nla', 'width=650,height=700');\n```\n\n_Note: the setup window is optimized for 650px width, 700px height_\n\n## Using the API <a name=\"using-the-api\"></a>\n\n#### Understanding the AI guessing flow <a name=\"ai-guessing\"></a>\n\nNLA 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).\n\nAn 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.\n\nConsider 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](https://cdn.zappy.app/d19215e5a2fb3896f6cddf435dfcbe27.png).\n\nThe 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.\n\nIf a field uses \"Have AI guess\", two things happen:\n1. 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.\n2. 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.\n\nSometimes 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](https://cdn.zappy.app/dc4976635259b4889f8412d231fb3be4.png).\n\nNow 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.\n\nWe 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. \n\nOne 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.\n\nIn 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.\n\nIn summary:\n\n```\n[user supplied \"Use specific value\"] --overrides--> [API call supplied hint parameters] --overrides--> [API call supplied \"instructions\"]\n```\n\n\n#### Common API use cases <a name=\"common-api-uses\"></a>\n\nThere are three common usages:\n1. Get a list of the current user's exposed actions\n2. Get a list of an action's optional hint parameters\n3. Execute an action\n\nLet's go through each, assuming you have a valid access token already.\n\n### 1. Get a list of the current user's exposed actions <a name=\"list-exposed-actions\"></a>\n\n```\n# via the RESTful list endpoint:\ncurl -v -H \"Authorization: Bearer <ACCESS_TOKEN>\" https://nla.zapier.com/api/v1/dynamic/exposed/\n\n# via the dynamic openapi.json schema:\ncurl -v -H \"Authorization: Bearer <ACCESS_TOKEN>\" https://nla.zapier.com/api/v1/dynamic/openapi.json\n```\n\nExample of [full list endpoint response here](https://nla.zapier.com/api/v1/dynamic/exposed/), snipped below:\n\n```\n{\n    \"results\": [\n        {\n            \"id\": \"01GTB1KMX72QTJEXXXXXXXXXX\",\n            \"description\": \"Slack: Send Channel Message\",\n            ...\n```\n\nExample of [full openapi.json response here](https://nla.zapier.com/api/v1/dynamic/openapi.json), snipped below:\n\n```\n{\n    ...\n    \"paths\": {\n        ...\n        \"/api/v1/dynamic/exposed/01GTB1KMX72QTJEXXXXXXXXXX/execute/\": {\n            \"post\": {\n                \"operationId\": \"exposed_01GTB1KMX72QTJEXXXXXXXXXX_execute\",\n                \"summary\": \"Slack: Send Channel Message (execute)\",\n                ...\n\n```\n\n### 2. Get a list of an action's optional hint parameters <a name=\"get-hints\"></a>\n\nAs 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.\n\n```\n# via the RESTful list endpoint:\ncurl -v -H \"Authorization: Bearer <ACCESS_TOKEN>\" https://nla.zapier.com/api/v1/dynamic/exposed/\n\n# via the dynamic openapi.json schema:\ncurl -v -H \"Authorization: Bearer <ACCESS_TOKEN>\" https://nla.zapier.com/api/v1/dynamic/openapi.json\n```\n\nExample of [full list endpoint response here](https://nla.zapier.com/api/v1/dynamic/exposed/), snipped below:\n\n```\n{\n    \"results\": [\n        {\n            \"id\": \"01GTB1KMX72QTJEXXXXXXXXXX\",\n            \"description\": \"Slack: Send Channel Message\",\n            \"input_params\": {\n                \"instructions\": \"str\",\n                \"Message_Text\": \"str\",\n                \"Channel\": \"str\",\n                ...\n```\n\nExample of [full openapi.json response here](https://nla.zapier.com/api/v1/dynamic/openapi.json), snipped below:\n\n```\n{\n    ...\n    \"components\": {\n        \"schemas\": {\n            ...\n            \"PreviewExecuteRequest_01GTB1KMX72QTJEXXXXXXXXXX\": {\n                \"title\": \"PreviewExecuteRequest_01GTB1KMX72QTJEXXXXXXXXXX\",\n                \"type\": \"object\",\n                \"properties\": {\n                    \"instructions\": {\n                        ...\n                    },\n                    \"Message_Text\": {\n                        ...\n                    },\n                    \"Channel_Name\": {\n                        ...\n                    }\n\n```\n\n_Note: Every list of input_params will contain `instructions`, the only required parameter for execution._ \n\n### 3. Execute (or preview) an action <a name=\"execute-action\"></a>\n\nFinally, 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.\n\n```\ncurl -v \\\n    -d '{\"instructions\": \"send a short poem about automation and robots to slack\", \"Channel_Name\": \"#fun-zapier\"}' \\\n    -H \"Content-Type: application/json\" \\\n    -X POST 'https://nla.zapier.com/api/v1/dynamic/exposed/01GTB1KMX72QTJEXXXXXXXXXX/execute/'\n```\n\nAnother example, this time an action to retrieve data:\n\n```\ncurl -v \\\n    -d '{\"instructions\": \"grab the latest email from bryan helmig\"}' \\\n    -H \"Content-Type: application/json\" \\\n    -X POST 'https://nla.zapier.com/api/v1/dynamic/exposed/01GTA3G1WD49GN1XXXXXXXXX/execute/'\n```\n\nOne more example, this time requesting a preview of the action:\n\n```\ncurl -v \\\n    -d '{\"instructions\": \"say Hello World to #fun-zapier\", \"preview_only\": true}' \\\n    -H \"Content-Type: application/json\" \\\n    -X POST 'https://nla.zapier.com/api/v1/dynamic/exposed/01GTB1KMX72QTJEXXXXXXXXXX/execute/'\n```\n\n\n#### Execution Return Data <a name=\"return-data\"></a>\n\n##### The Status Key <a name=\"status-key\"></a>\n\nAll actions will contain a `status`. The status can be one of four values:\n\n`success`\n\nThe action executed successfully and found results.\n\n`error`\n\nThe action failed to execute. An `error` key will have its value populated.\n\nExample:\n\n```\n    {\n        ...\n        \"action_used\": \"Gmail: Send Email\",\n        \"result\": null,\n        \"status\": \"error\",\n        \"error\": \"Error from app: Required field \"subject\" (subject) is missing. Required field \"Body\" (body) is missing.\"\n    }\n```\n\n`empty`\n\nThe action executed successfully, but no results were found. This status exists to be explicit that having an empty `result` is correct.\n\n`preview`\n\nThe 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,\nor just rerun without the `preview_only` input parameter.\n\nExample:\n\n```\n    {\n        ...\n        \"action_used\": \"Slack: Send Channel Message\",\n        \"input_params\": {\n            \"Channel\": \"fun-zapier\",\n            \"Message_Text\": \"Hello World\"\n        },\n        \"review_url\": \"https://nla.zapier.com/execution/01GW2E2ZNE5W07D32E41HFT5GJ/?needs_confirmation=true\",\n        \"status\": \"preview\",\n    }\n```\n\n##### The Result Key <a name=\"result-key\"></a>\n\nAll 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:\n\n* selects for data that is plain text and human readable\n* discards machine data like IDs, headers, etc.\n* prioritizes data that is very popular on Zapier\n* reduces final result into about ~500 words\n\nTrimmed results are ideal for inserting directly back into the prompt context of a large language models without blowing up context token window limits.\n\nExample of a trimmed results payload from \"Gmail: Find Email\":\n\n```\n    {\n        \"result\": {\n            \"from__email\": \"mike@zapier.com\",\n            \"from__name\": \"Mike Knoop\",\n            \"subject\": \"Re: Getting setup\",\n            \"body_plain\": \"Hi Karla, thanks for following up. I can confirm I got access to everything! ... Thanks! Mike\",\n            \"cc__emails\": \"bryan@zapier.com, wade@zapier.com\"\n            \"to__email\": \"Mike Knoop\",\n        }\n    }\n```\n## Changelog <a name=\"changelog\"></a>\n\n**Mar 20, 2023**\nShipped two minor but breaking changes, and one other minor change to the API's response data:\n\n* Route: `/api/v1/configuration-link/`\n  * Key `url` is now `configuration_link` **(breaking change)**\n* Route: `/api/v1/exposed/{exposed_app_action_id}/execute/`\n  * Key `rating_url` is now `review_url` **(breaking change)**\n* Route: `/api/v1/exposed/`\n  * Added `configuration_link` key"
   },
   "servers": [
      {
         "url": "https://nla.zapier.com"
      }
   ],
   "paths": {
      "/api/v1/configuration-link/": {
         "get": {
            "operationId": "get_configuration_link",
            "summary": "Get Configuration Link",
            "parameters": [],
            "responses": {
               "200": {
                  "description": "OK"
               }
            },
            "description": "If the user wants to execute actions that are not exposed, they can\ngo here to configure and expose more.",
            "security": [
               {
                  "SessionAuth": []
               },
               {
                  "AccessPointApiKeyHeader": []
               },
               {
                  "AccessPointApiKeyQuery": []
               },
               {
                  "AccessPointOAuth": []
               }
            ]
         }
      },
      "/api/v1/exposed/": {
         "get": {
            "operationId": "list_exposed_actions",
            "summary": "List Exposed Actions",
            "parameters": [],
            "responses": {
               "200": {
                  "description": "OK",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/ExposedActionResponseSchema"
                        }
                     }
                  }
               }
            },
            "description": "List all the currently exposed actions for the given account.",
            "security": [
               {
                  "SessionAuth": []
               },
               {
                  "AccessPointApiKeyHeader": []
               },
               {
                  "AccessPointApiKeyQuery": []
               },
               {
                  "AccessPointOAuth": []
               }
            ]
         }
      }
   },
   "components": {
      "schemas": {
         "ExposedActionSchema": {
            "title": "ExposedActionSchema",
            "type": "object",
            "properties": {
               "id": {
                  "title": "Id",
                  "description": "The unique ID of the exposed action.",
                  "type": "string"
               },
               "operation_id": {
                  "title": "Operation Id",
                  "description": "The operation ID of the exposed action.",
                  "type": "string"
               },
               "description": {
                  "title": "Description",
                  "description": "Description of the action.",
                  "type": "string"
               },
               "params": {
                  "title": "Params",
                  "description": "Available hint fields for the action.",
                  "type": "object"
               }
            },
            "required": [
               "id",
               "operation_id",
               "description",
               "params"
            ]
         },
         "ExposedActionResponseSchema": {
            "title": "ExposedActionResponseSchema",
            "type": "object",
            "properties": {
               "results": {
                  "title": "Results",
                  "type": "array",
                  "items": {
                     "$ref": "#/components/schemas/ExposedActionSchema"
                  }
               },
               "configuration_link": {
                  "title": "Configuration Link",
                  "description": "URL to configure and expose more actions.",
                  "type": "string"
               }
            },
            "required": [
               "results",
               "configuration_link"
            ]
         }
      },
      "securitySchemes": {
         "SessionAuth": {
            "type": "apiKey",
            "in": "cookie",
            "name": "sessionid"
         },
         "AccessPointApiKeyHeader": {
            "type": "apiKey",
            "in": "header",
            "name": "X-API-Key"
         },
         "AccessPointApiKeyQuery": {
            "type": "apiKey",
            "in": "query",
            "name": "api_key"
         },
         "AccessPointOAuth": {
            "type": "oauth2",
            "flows": {
               "authorizationCode": {
                  "authorizationUrl": "/oauth/authorize/",
                  "tokenUrl": "/oauth/token/",
                  "scopes": {
                     "nla:exposed_actions:execute": "Execute exposed actions"
                  }
               }
            }
         }
      }
   }
}