> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workato

> Hand legal work to a Wordsmith agent from a Workato recipe, and start a recipe when a task is created or completed.

The Wordsmith connector for Workato lets any recipe send work to Wordsmith and use the result in later steps. A recipe can start from any Workato trigger, such as a new contract in your CLM, a procurement request, a ServiceNow ticket or a Salesforce opportunity. It can also start when a Wordsmith task is created or completed.

> [!NOTE]
>
> The connector is not yet in Workato's community library. Until it is, a Workato admin adds it to your workspace. See [Add the connector](#add-the-connector).

## Actions and triggers

| Action or trigger | What it does |
| - | - |
| **Ask an agent** | Asks an agent a question, with optional files, and waits for the answer. Returns the answer, the decline reason if the agent declined, files the agent created, and a link to the conversation. |
| **Get an answer** | Gets a question you asked an agent, with its answer if it is ready. **Status** `in_progress` means the agent is still working. The step fails if the agent could not answer. |
| **Upload a file** | Stores a file in your private Wordsmith space and returns its file ID, for a question or a task. |
| **Create a task** | Creates a task, with optional files. Assign it to an agent to have the agent start on it, or to a person. With files, the agent starts once they are attached. Returns the task and its link. |
| **Attach files to a task** | Adds uploaded files to a task's inputs. |
| **Get a task** | Gets a task's status, assignees and files. |
| **List agents** | Lists the agents you can ask. The Agent fields use it to offer a dropdown. |
| **Custom action** | Calls any other [Wordsmith API](https://wordsmithai.mintlify.site/introduction.md) route with the connection's key. |
| **New task** (trigger) | Starts the recipe when a task you are involved in is created. |
| **Task status changed** (trigger) | Starts the recipe when a task you can see is completed, or cancelled. |

**Ask an agent** keeps the recipe waiting while the agent works, which usually takes a few minutes. The connector checks for the answer every minute or so. Set **Wait up to (minutes)** for how long to wait; the default is 60. If the agent is still working after that, the step fails with the question ID, so a later **Get an answer** can read the answer.

The step also fails when the agent could not answer, with the agent's message and a link to the conversation. Use an error monitor in the recipe to handle both. When it succeeds, **Status** is `completed`, or `filtered` when the agent declined the question, with the reason in **Decline reason**.

The answer comes in two forms. **Answer** is Markdown. **Answer (HTML)** is the same text formatted for an email body, so use it when you send an email: headings, lists and bold text then show properly.

Both triggers check for tasks every poll interval, 5 minutes by default. Narrow **Task status changed** with **Assignee**, **Source channel** (for example `api`, for tasks a recipe created) or **Tags**, and **New task** with **Agent** or **Assignee**.

## Connect

1. In Wordsmith, open each agent the recipe should hand tasks to, and add **API** as an intake on its configuration page. The **Agent** list in **Create a task** shows only agents with that intake.
2. In Wordsmith, open **Settings → API keys** and create an API key. The connection acts with the access of the person who created the key, so a recipe can do only what that person can do. For recipes that serve a whole team, create the key as a user who can see that team's work. A key limited to some scopes needs `me:read`, `agents:read`, `sessions:read`, `sessions:write`, `files:read`, `files:write`, `tasks:read` and `tasks:write`, plus `directory:read` for the **Assignee** dropdown.
3. In Workato, add a Wordsmith step to a recipe and create a connection. Choose your **Region**: Europe or United States.
4. Paste the API key, then **Connect**.

## Example: review each new contract request

This recipe sends each new request to an agent and posts the answer back.

1. Start the recipe from your request system's **New record** trigger.
2. If the request has a file, download it with that system's download action. Add **Wordsmith → Upload a file** with the file's contents and name.
3. Add **Wordsmith → Ask an agent**:
   * **Agent**: the agent that handles these requests.
   * **Question**: the instruction, with the request's fields inserted. For example: `Review this NDA request from <Requester>. Counterparty: <Counterparty>. Deadline: <Deadline>.`
   * **Files**: the **File ID** from **Upload a file**.
   * **Idempotency key**: the request's record ID, so a rerun of the job does not ask twice.
4. Add an **IF** step: **Status** equals `completed`.
5. Under it, post **Answer (HTML)** and **Conversation link** back to the request, or email them to the requester.
6. Otherwise, send the requester the **Decline reason**, so a declined request is not lost.

To have a person check the work first, use **Create a task** instead of step 3. Assign the task to an agent, put the request's fields in **Description**, and add the files. Then build a second recipe on **Task status changed**, filtered to **Source channel** `api`, that reads **Output files** and posts them back.

## Add the connector

Until the connector is in the community library, a Workato admin adds it to your workspace as a custom connector:

1. Ask [support@wordsmith.ai](mailto:support@wordsmith.ai) for the Workato connector. Support sends a share link or the connector's source code.
2. Open the share link and install the connector. With the source code instead, create a connector under **Tools → Connector SDK** and paste the code in.
3. Release the connector, so recipe builders in the workspace can use it.

## Limits

* **Ask an agent** waits at most as long as **Wait up to (minutes)**. A question that waits on a person's approval can take days, so use **Get an answer** to read it later.
* Files the agent created have two links. **Download URL** expires 5 minutes after the answer arrives, so download it in the next step, and never email it. **Link** does not expire, but needs Wordsmith sign-in.
* **Task status changed** starts the recipe once per task and status, even if the task is reopened and completed again. A task completed before the recipe's start time can start it once if the task changes after that time.
* **New task** reads open tasks in priority order, at most 500 per check. If you are involved in more open tasks than that, a new low-priority task can be missed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.