Skip to main content

Creating tools

Superface offers a web based tool builder that allows you to:

  • Create new tools and use cases you require using Open API Specifications.

Access the Authoring Hub by clicking on Create Tools in your Account menu, or by heading to

The authoring hub for tools will be empty until a tool has been started.

Add a new use case/tool


To add a new tool to Superface you will need the a URL for, or a copy of, the Open API Specification for the API of the service you want to connect to.

Step 1: Upload documentation

Start by clicking on + Add tool, a popup will appear and you can either paste an Open API Specification, or provide a URL for it (URLs for documentation hosted by will also be accepted here).

Remember, only Open API Specification documentation is supported at this time. URLs for standard API documentation pages will not work.

The connect new provider modal

You don't have to provide a name, however if you want control over the naming you can provide one. Typically the name should be for the service you are creating a tool for (eg. electricity-maps, hubspot, my-company-api).

Clicking Connect tool will index the Open API Specification and get it ready for you to make a tool with. You will see the progress on your screen as well as any errors that may occur.

Step 2: Check the provider

Once indexing is complete you will be redirected to a page similar to the one below.

The provider setup

You can check the setup for the Provider by looking at the JSON output. It outlines:

  • The name of the service
  • The base URL of the API to connect to
  • The security scheme required to connect to the API
  • Any additional parameters that are required

If you think anything is missing, you can add the elements you need by using the shortcut templates above the box.

Shortcut templates are available to help make your provider correct

If everything looks correct, it's time to create your use case by clicking Create use case.

Video Overview

Step 3: Create a use case

Before defining your use case, you must install the provider for the tool. You can do this by clicking on Install. Once complete, you can proceed with writing your use case prompt.

First you must install the provider

Next, define what the action for your tool should take by writing it out as natural language. For example, with this dbt tool, we want to invite new users to our account:

Write your use case prompt as a natural language input

Click Create new use case to continue.

Superface will then determine how to achieve your use case using the documentation you provided earlier.

Superface determines how to achieve a use case and shows you progress

Video Overview

Step 4: Test and edit

After Superface determines what is required by the API to achieve your use case, you will see a page that looks similar to the one below.

The profile tester

There are three areas on this page:

The use case interface defines the expected inputs that are needed to make your use case possible, as well as what a successful response will look like. This is determined from the documentation you provided.

The chat window on the right is pre-populated with your requested use case prompt. You can test it directly from here to see if you get the response you are looking for.

First, test your prompt to see what you get.

Missing configuration

In order to complete requests with your tool, Superface needs the correct authorization. If this is not already set up, you will be asked to configure it. Click on Configure to enter the API credentials.

If you are happy with the output from your prompt, you can move on to installing it.

If you think your prompt can do better, you can choose to Change the inital prompt and provide greater specificity.

Video Overview

Step 5: Install your tool

To install your tool click on Install use case. A modal will appear with the files that are going to be installed on your account. This is for information only.

The installation modal

Superface now has everything it needs to provide the capability you requested.

Click on Install use case again to add it to your list of tools.