Creating a Tool

Tools in superglue are reusable workflows that you can execute on-demand, schedule, or trigger via webhooks. Each tool consists of sequential steps with built-in data transformations, loops, and error handling. Learn more about how tools fit into the bigger picture in our core concepts page.

Via Agent
Via UI
Via SDK

The fastest way to create a tool is by talking to our agent. Describe what you want to accomplish and the agent will build the tool for you.

Simple example:

"Create a tool that fetches all active customers from Stripe"

superglue will:

Identify which system to use (or create one if needed)
Find the relevant API endpoint from the documentation
Configure the API call with appropriate parameters
Test it and make it available for execution

Complex example:

"Create a tool that loops through all contacts in HubSpot,
filters those with email domains matching @company.com,
and updates their lifecycle stage to 'customer'"

The agent can build multi-step tools with:

Sequential API calls
Data transformations between steps
Loops for batch processing
Error handling and retries

Try it now

Start building tools with our agent

Use the REST SDK to run tools you’ve already created:

npm install @superglue/client

Configure and run a tool:

import { configure, runTool, getTool, listTools } from "@superglue/client";

// Configure the SDK with your API endpoint and token
configure({
  baseUrl: "https://api.superglue.cloud", // or your self-hosted URL
  token: "your_api_token"
});

// List available tools
const { data: tools } = await listTools();
console.log(tools);

// Get a specific tool
const { data: tool } = await getTool("my-tool-id");

// Run a tool with input payload
const { data: run } = await runTool("my-tool-id", {
  inputs: {
    userId: "user_123",
    startDate: "2024-01-01"
  },
  credentials: {
    stripe_api_key: "sk_live_xxx"
  }
});

console.log(run.data); // Tool execution result

The REST SDK is for executing existing tools. To build new tools, use the agent interface or the UI. See the SDK documentation for more details.

Tool anatomy

Every tool consists of:

Steps

Sequential API calls that fetch or modify data. Each step can reference data from previous steps.

Transformations

JavaScript functions that shape the step inputs and the final output. Ensures tool results adhere to response schemas.

Variables

Access data from previous steps, credentials, and input payload using <<variable>> syntax.

Step configuration

Each step in a tool represents a single API call with the following configuration:

Basic structure

{
  id: "stepId",                    // Unique identifier for this step
  instruction: "Fetch customer data from Stripe",  // Human-readable description
  dataSelector: "(sourceData) => { return [\"one\", \"two\"]}",  // The data selector for the current step
  config: {
    systemId: "stripe",            // Which system to use
    method: "POST",                // HTTP method
    url: "https://api.stripe.com/v1/customers",  // Full API endpoint URL
    queryParams: {},               // URL query parameters
    headers: { "Authorization": "Bearer <<stripe_apiKey>>" }, // Custom headers
    body: ""                       // Request body
  }
}

Variable syntax

Use <<variable>> to access dynamic values: Access credentials:

{
  headers: {
    "Authorization": "Bearer <<systemId_access_token>>"
  }
}

Access previous step data:

{
  urlPath: "/customers/<<getCustomer.data.id>>",
  body: {
    email: "<<getCustomer.data.email>>"
  }
}

Access input payload:

{
  queryParams: {
    user_id: "<<userId>>",
    date: "<<startDate>>"
  }
}

Execute JavaScript expressions:

{
  body: {
    ids: "<<(sourceData) => JSON.stringify(sourceData.users.map(u => u.id))>>",
    timestamp: "<<(sourceData) => new Date().toISOString()>>",
    count: "<<(sourceData) => sourceData.items.length>>",
    uppercaseName: "<<(sourceData) => sourceData.name.toUpperCase()>>"
  }
}

JavaScript expressions must use the arrow function syntax (sourceData) => .... Direct property access like <<userId>> works for simple variables, but not for nested properties or transformations.

Data selector

Extract an array to iterate over:

{
  dataSelector: `(sourceData) => {
    const items = sourceData.fetchItems.results || [];
    const excludeIds = sourceData.excludeIds || [];
    return items.filter(item => !excludeIds.includes(item.id));
  }`;
}

Whether a step loops through more than one request is determined by the data selector. If the data selector returns an Array, the request will execute once for each item in that array. The item of the current iteration is available in the config as <<currentItem>> or accessible in code via sourceData.currentItem.

Output transform

Shape the final output of the entire tool:

{
  outputTransform: `(sourceData) => {
    const customers = sourceData.getCustomers.data || [];
    const updated = sourceData.updateCustomers || [];
    
    return {
      success: true,
      total: customers.length,
      updated: updated.length,
      results: updated.map(r => ({
        id: r.currentItem.id,
        status: r.data.status
      }))
    };
  }`;
}

Transform steps

Transform steps allow you to reshape data between API calls without making an external request. Use them when you need complex data transformations that don’t fit in a dataSelector.

Basic structure

{
  id: "formatCustomerData",
  instruction: "Format customer data for the next API call",
  config: {
    type: "transform",
    transformCode: "(sourceData) => sourceData.getCustomers.data.map(c => ({ id: c.id, name: c.fullName, email: c.contactEmail }))"
  }
}

When to use transform steps

Complex data reshaping between API calls
Aggregating data from multiple previous steps
Filtering or sorting data before the next request
Preparing payloads in a specific format

Accessing transform results

Transform step results are wrapped in the same { currentItem, data, success } envelope as request steps:

// In a subsequent step — access the transformed data via .data
{
  body: "<<(sourceData) => JSON.stringify(sourceData.formatCustomerData.data)>>"
}

Transform steps do NOT have systemId, url, method, headers, body, or pagination fields. They only have type: "transform" and transformCode.

Special systems

PostgreSQL

Query databases using the postgres:// URL scheme:

{
  id: "queryDatabase",
  config: {
    systemId: "postgres_db",
    url: "postgres://<<postgres_db_username>>:<<postgres_db_password>>@<<postgres_db_hostname>>:5432/<<postgres_db_database>>",
    body: {
      query: "SELECT * FROM users WHERE status = $1 AND created_at > $2",
      params: ["active", "<<(sourceData) => sourceData.startDate>>"]
    }
  }
}

Always use parameterized queries with $1, $2, etc. placeholders to prevent SQL injection. Provide values in the params array, which can include static values or <<>> expressions.

Redis

Execute Redis commands using the redis:// (or rediss:// for TLS) URL scheme:

{
  id: "getUserProfile",
  config: {
    systemId: "redis_cache",
    url: "redis://<<redis_cache_username>>:<<redis_cache_password>>@<<redis_cache_host>>:6379/0",
    body: {
      command: "HGETALL",
      args: ["<<(sourceData) => `user:${sourceData.userId}`>>"]
    }
  }
}

The body takes a command string and optional args array. You can also pass an array of commands to execute them as a pipeline in a single round-trip:

body: [
  { command: "GET", args: ["user:123:name"] },
  { command: "HGETALL", args: ["user:123"] }
]

FTP/SFTP

Access files on FTP servers:

{
  id: "listFiles",
  config: {
    systemId: "ftp-server",
    url: "sftp://<<ftp-server_username>>:<<ftp-server_password>>@<<ftp-server_hostname>>:22/data",
    body: {
      operation: "list",
      path: "/reports"
    }
  }
}

Supported operations:

list - List directory contents
get - Download file (auto-parses CSV/JSON/XML)
put - Upload file
delete - Delete file
rename - Rename/move file
mkdir - Create directory
rmdir - Remove directory
exists - Check if file exists
stat - Get file metadata

Error handling

Automatic retries

Failed steps can be automatically retried with exponential backoff

Validation

Response data is validated against response schemas if specified

Graceful degradation

Handle missing data with optional chaining and defaults in transformations

Keep steps focused - Each step should make a single API call. Use transformations to prepare data, not as additional steps.Use descriptive IDs - Step IDs are used to reference data in later steps. Use clear names like getCustomers, updateOrder, sendEmail.Avoid unnecessary loops - Don’t loop over thousands of items if the API supports batch operations. Check the documentation first.Test with real data - Test each step incrementally with production-like data before deploying.

Input and output schemas

Define schemas to make your tools more robust: Input schema - Validates payload before execution:

{
  "type": "object",
  "properties": {
    "userId": { "type": "string" },
    "startDate": { "type": "string", "format": "date" }
  },
  "required": ["userId"]
}

Response schema - Validates final output:

{
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "email": { "type": "string" }
        }
      }
    }
  }
}

Getting Started

Guides

SDK Reference

CLI Reference

API Reference

Enterprise

Try it now

Tool anatomy

Steps

Transformations

Variables

Step configuration

Basic structure

Variable syntax

Data selector

Output transform

Transform steps

Basic structure

When to use transform steps

Accessing transform results

Special systems

PostgreSQL

Redis

FTP/SFTP

Error handling

Automatic retries

Validation

Graceful degradation

Input and output schemas

Next steps

Debug your tool

Deploy to production

Getting Started

Guides

SDK Reference

CLI Reference

API Reference

Enterprise

Documentation Index

Try it now

​Tool anatomy

Steps

Transformations

Variables

​Step configuration

​Basic structure

​Variable syntax

​Data selector

​Output transform

​Transform steps

​Basic structure

​When to use transform steps

​Accessing transform results

​Special systems

​PostgreSQL

​Redis

​FTP/SFTP

​Error handling

Automatic retries

Validation

Graceful degradation

​Input and output schemas

​Next steps

Debug your tool

Deploy to production

Tool anatomy

Step configuration

Basic structure

Variable syntax

Data selector

Output transform

Transform steps

Basic structure

When to use transform steps

Accessing transform results

Special systems

PostgreSQL

Redis

FTP/SFTP

Error handling

Input and output schemas

Next steps