# Custom API Tools

Turn any REST API into runbook tools using the custom tool wizard

The custom tool wizard turns any REST API into runbook tools. Add the endpoints you want by importing an API definition, pasting a cURL command, or building one manually. Configure the authentication once, then Risotto promotes each endpoint into a tool you can use in any runbook. No code required!

To watch custom API tools imported from a vendor's API spec, next to a script tool for the same system, see [Build your own tools](https://www.tryrisotto.com/docs/guides/build-tools-video), a video.

## Before you begin

Decide how you'll bring in your endpoints.

- **Import a definition**: Import an [OpenAPI](https://www.openapis.org/) (Swagger) JSON or YAML file, a Postman Collection (v2.x) export (up to 15 MB), or a public HTTPS URL. Risotto detects the format and imports every operation or request in the file at once.
- **Paste a cURL command**: Paste in a single request cURL request.
- **Build manually**: Manually define the endpoint when you don't have a definition or sample request handy.

A source uses a single import method. Pick the on-ramp that fits the endpoints you're adding—you can't mix methods on the same source.

> **Note:** Risotto calls only hosts that resolve to a public IP address. If the API is on a private address or is only reachable over a VPN, Risotto refuses the call with the error `Host '<host>' resolves to a private or reserved address.` Put the API behind a public hostname, for example a reverse proxy or an API gateway.

## Create custom API tools

1. **Start a new API source**

   In the Risotto dashboard, go to **Settings** > **Integrations**. Click **New custom integration**, then **API source**, to launch the wizard.

2. **Name your API source**

   The **Custom API source** dialog opens on a **Name your API source** form with three fields:

   - **Display name** (required): the name shown for this source, for example `GitHub`.
   - **Base URL (optional)**: the root URL of the API. Leave it blank to fill it from the imported definition or cURL command.
   - **Description (optional)**: a note that helps runbooks understand when to use these tools, for example "Used by the IT runbooks to look up assets."

   Click **Create and continue**.

3. **Add endpoints**

   The wizard now shows a four-step progress bar across the top: **Add endpoints**, **Endpoints**, **Authentication**, and **Review**. On the **Add endpoints** step, a segmented control offers three tabs: **Import a definition**, **Paste a cURL command**, and **Build manually**. Bring in the API calls you want to turn into tools using whichever on-ramp fits. Each method produces draft endpoints you'll review and refine in the next steps.

   ### Import a definition

   Choose **Upload file** to drag a JSON or YAML OpenAPI (Swagger) document or a Postman Collection export onto the **Drop here** area (max 15 MB), or choose **Link URL** to paste a public HTTPS URL and click **Fetch**. Risotto detects the format, parses the definition, and surfaces every operation or request as a candidate tool. Risotto stores the document so it can re-parse it if your API grows new endpoints.

   For a Postman collection, a path placeholder such as `{id}` becomes a required path parameter, and a disabled query parameter or form field becomes an optional parameter. Risotto skips a request whose path has a placeholder it cannot fill.

   When ingestion succeeds, you'll see the definition title, version, base URL, and the number of endpoints ready to review.

   ### Paste a cURL command

   Paste a `curl` command from your API docs or your browser's "Copy as cURL." Risotto infers the method, URL, and query and body parameters, all of which you can adjust in the next steps. Click **Add endpoint**.

   > **Warning:** Don't include real credentials (API keys, tokens, passwords) in the command—remove them before pasting. You'll set up authentication securely in a later step.

   A command that carries `-u` or a user name in the URL sets the source's scheme to **Basic auth** for you, so the authentication step opens on the right option. Neither half of the pasted pair is kept.

   ### Build manually

   Choose the HTTP **method** and enter a **path** relative to the source base URL (for example, `/v1/widgets/{id}`). Use `{name}` for path parameters. Click **Add endpoint**, then set the name, description, and parameters in the next steps.

   Once the source has at least one endpoint ready to review, click **Continue**.

4. **Pick the endpoints**

   The **Pick the endpoints** step lists every endpoint in a table with a checkbox, **Tool name**, **Method**, **Path**, and **Params** (the number of parameters) for each row. Each endpoint becomes one tool. Use the **Filter by name, path, or description** box to narrow the list, then select the endpoints you want to import. All endpoints are selected by default, and a counter in the top right (for example, "65 of 65 selected") shows how many are checked. The header checkbox selects or clears all rows at once. You can refine each tool's name, description, and parameters in the review step.

   Click **Continue to Authentication**.

5. **Configure authentication**

   On the **Configure authentication** step, pick the scheme your API expects from the **Authentication type** dropdown. The fields below the dropdown change to match the scheme. Credentials are encrypted and only sent to the source's base URL, and they're shared by every tool created from this source.

   - **No auth**: requests go out without credentials. Use only for publicly accessible APIs.
   - **Bearer token**: Risotto sends the token as `Authorization: Bearer <token>`.
   - **API key (header)**: provide a **Header name** (for example, `X-API-Key`) and **Header value**.
   - **Basic auth**: provide a **Username** and a **Password**. Both halves are credentials picked from the [Credential Vault](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault), and either half may be left empty. Some APIs carry the whole secret in one half, such as Dropbox Sign, which sends the API key as the username with no password.

   Click **Save and continue**. Use **Back to endpoints** if you need to change your endpoint selection first.

   > **Note:** Credentials are write-only and never displayed again. When you return to rotate a credential, leave a field blank to keep the existing value, or enter a new value to replace it. Changing the auth type requires entering fresh credentials.

   > **Note:** For Basic auth, rotate one half at a time only while the other half is a vault credential. When both halves were typed in before the vault, Risotto asks you to re-enter the half you are not changing rather than overwrite it with an empty value.

   ### What about APIs that use OAuth?

   Custom API sources don't run an OAuth flow themselves. Pick the path that matches the kind of OAuth the API expects:

   - **Long-lived token or API key.** Most APIs let you mint a token in their admin console. Store it as a **Bearer token** or **API key (header)** here; no OAuth handshake is needed at request time.
   - **OAuth client credentials (machine-to-machine, expiring tokens).** Use a [script tool](https://www.tryrisotto.com/docs/integrations/tools/script-tools) instead: the script exchanges the client ID and secret for an access token and makes the API call in one run, with the secret stored as an `env.*` secret.
   - **The vendor exposes an MCP server.** Connect it as an [external MCP server](https://www.tryrisotto.com/docs/integrations/tools/external-mcp-servers), which supports OAuth 2.1 natively.
   - **User-delegated OAuth** (the "sign in with…" redirect on behalf of each requester) is not supported on custom API tools today.

6. **Review and publish**

   The **Review and save** step opens with the **Source name** and **Base URL** you set earlier, along with a reminder of which authentication scheme is shared by every tool from this source. Below that, each selected operation appears as a collapsible tool draft labeled with its tool name, method, and path (for example, `alerts_query GET /alerts`). Expand a draft to refine:

   - **Tool name**: a `snake_case` identifier (lowercase letters, digits, and underscores; must start with a letter).
   - **Requires approval**: a toggle next to the tool name. When on, the agent must get approval before running the tool. On by default.
   - **Description (agent-facing)**: explains what the tool does and when to use it.
   - **Request**: the HTTP **method** (GET, POST, PUT, PATCH, DELETE) and **path**. Use `{name}` for path parameters; the path is relative to the source base URL.
   - **Parameters**: for each parameter, set its **name**, **location** (`path`, `query`, `header`, or `body`), **type** (`string`, `integer`, `number`, `boolean`, `array`, or `object`), **description**, and whether it's **required**.

   Select the tools to include and click **Publish**. The button shows the count, for example **Publish 3 tools**. Risotto validates each draft and reports which tools published successfully and which need fixes. You can correct any failed drafts and publish again. Re-publishing won't create duplicates.

## Test a tool

After publishing, open a tool from the **Tools** page and click **Run tool** to run it with custom parameters. Risotto executes the request and shows the result (or any error), so you can confirm the tool works before referencing it in a runbook.

## Manage your API sources

Each API source has its own card, with the description **Custom API**, in the **Custom** group of **Settings** > **Integrations**. Click the card to open the source.

To add another source, click **New custom integration** > **API source** on the same page. Use one source per upstream service. Old links to the **Tool Connectors** page open **Settings** > **Integrations**.

A source whose wizard has not published a tool yet is a draft. Its page shows "Setup not finished", with **Continue setup** to reopen the wizard and **Delete draft** to remove it.

### Source detail page

Opening a published source shows the source name with a **Published** badge and a **From API spec** tag, plus its base URL, spec version, and when the definition was last refreshed. Three summary cards report **Tools imported** (a count), **Authentication** (the scheme and whether credentials are configured), and **Spec source** (for example, "OpenAPI spec" and the definition title).

The **Tools from this source** table lists each tool's name and description, **Method**, **Path**, and **Number of runbooks** that reference it. Side panels show the **Spec source** details (OpenAPI URL, version, and checksum) and the **Authentication** scheme with a **Configured** indicator for the credentials.

The top right of the page has an **Add tools** button and a **⋮** menu with **Edit source** and **Delete source**. From here you can:

- **Edit source**: update the display name, base URL, authentication, and default headers. Default headers are sent on every request the source's tools make.
- **Add tools**: promote additional endpoints that haven't been published yet. This reopens the pick-endpoints and review steps without re-running authentication.
- **Delete source**: remove the source, its draft endpoints, and all of its tools in one action. See [Delete a source](#delete-a-source).

### Delete a source

You can delete a source from its detail page (**⋮** > **Delete source**). To delete a draft, click **Delete draft** on its page. Only Admins and Managers can delete a source.

- If the source has no tools, the dialog asks you to confirm. Click **Delete source**.
- If the source has tools, the dialog lists each tool that Risotto deletes with the source. Click **Delete source and N tools**. You cannot undo the delete.
- If an automation uses one of the tools, the dialog warns you. The automation keeps running without the deleted tools.

An enabled runbook or a published script tool that uses one of the source's tools blocks the delete. The **Can't delete this source yet** dialog lists each **Active runbook** and **Published script tool** with a link. Remove the tools from them, then delete the source. A disabled runbook does not block the delete.

To remove only some tools of a source, use the bulk actions on the **Tools** page. See [Enable, disable, or delete many tools](https://www.tryrisotto.com/docs/dashboard/tools#enable-disable-or-delete-many-tools).

## Use custom API tools in runbooks

Published custom API tools appear in the runbook editor alongside Risotto's native tools. Add them to any runbook with the same approval, logging, and configuration controls. See [Runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks) for details on referencing tools in your workflows.

Source: https://www.tryrisotto.com/docs/integrations/tools/custom-api-tools
