Skip to main content

Superface in 5 minutes

This guide shows you how to pick a provider, generate Comlinks for the use case you want using the CLI, and use Superface OneSDK to run that use case.


This guide assumes you have Node.js version 18.0.0 or newer installed. For Python, version 3.8 or newer is required.

Pick a use case

This one is up to you. What do you want to achieve?

A use case example would be "Send an email and include click tracking", "List all the users in a workspace", or "Add users to a specific group".

Ultimately, your use case is up to you.

Pick a provider

The next step is to pick a provider you would like to use. Again, this is up to you but we recommend you look for API providers that have Open API Specification versions of their documentation, or that host their documentation with

We've created some Quick Start guides for popular APIs such as Notion, Slack and Resend.

Provider authentication

In many cases you also need to set up provider credentials. The Superface CLI will inform you about what tokens to add to your development environment. Learn more about how to handle API credentials in Setting provider API keys.

Install the Superface CLI

The Superface CLI provides all the tooling needed to author the Comlinks for your integration.

Install with Homebrew
brew install superfaceai/cli/superface

If you don't have a Superface account already, you can sign up here. You can use your account to authenticate the CLI via your browser.

superface login

The Superface CLI is used to create Comlinks. They handle use case definition, and the map that is used to create the code you need for your app to communicate correctly with the provider you want to work with.

First, prepare the documentation for the provider you want to use.

superface prepare <URL for provider documentation>

Next, create the Comlink profile for the use case you want to achieve.

superface new <provider-name> "your use case"

Finally, create a Comlink map that you can use in your application.

superface map <provider-name> <scope>/<use-case>

The output from all these commands will be a folder named superface with the following Comlink files:


You now have all the files you need to use these Comlinks in your application. You can run it using the superface execute command from your terminal, but you can also move them over to the app you're developing.

Install OneSDK

In your app directory, install the OneSDK library:

npm install @superfaceai/one-sdk@beta

Add code to your app

Now you can use OneSDK in your app. Create an index.mjs file with the following Node.js code.

Not sure what code to use?

If you want to find the exact code to use here, you can find it in the My Comlinks section of your Superface Dashboard.

import { OneClient } from '@superfaceai/one-sdk';

async function main() {
const client = new OneClient({
assetsPath: './superface',

// Assign our CLI generated profile so it matches
// the 'name' in the .profile file.
// Example: email-communication/email-sending

const profile = await client.getProfile('<profileName>');
const useCase = profile.getUseCase('<usecaseName>'); // The <usecaseName> is also found in the .profile file

try {
const result = await useCase
// Input parameters as defined in profile:
<key>: '<value>',
provider: '<providerName>',
parameters: {
// Provider specific integration parameters:
'<integrationParameterName>': '<integrationParameterValue>',
security: {
// Provider specific security values:
'<securityValueId>': {
// Security values as described in provider or on profile page

// output result on success
console.log("RESULT:", JSON.stringify(result, null, 2));
} catch(e) {
// output result on error
console.log("ERROR:", JSON.stringify(e, null, 2));


Test and confirm

It's time to run your app! Because the Superface OneSDK is built with WebAssembly and uses WASI, it requires that you pass the --experimental-wasi-unstable-preview1 flag when running Node.js version < 18.17.0.

node --experimental-wasi-unstable-preview1 index.mjs

For later versions of Node.js, you can run the command as usual with no flag:

node index.mjs


If you run into errors and need more information about what's happening under the hood, you can set the environment variable ONESDK_LOG to on to see API calls from OneSDK to the API of your chosen provider:


This can print out potentially sensitive information, like API keys and access tokens.

ONESDK_LOG="on" node index.mjs