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, a video.
Before you begin
Decide how you'll bring in your endpoints.
- Import a definition: Import an OpenAPI (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.
Create custom API tools
Start a new API source
In the Risotto dashboard, go to Settings > Integrations. Click New custom integration, then API source, to launch the wizard.
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.
- Display name (required): the name shown for this source, for example
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.
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
curlcommand 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.A command that carries
-uor 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.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.
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.
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, 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.
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 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, 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.
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_caseidentifier (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, orbody), type (string,integer,number,boolean,array, orobject), 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.
- Tool name: a
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
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.
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 for details on referencing tools in your workflows.
Something wrong or missing? Report an issue · View as Markdown