​
core concepts

superglue simplifies API integrations by understanding how to interact with data sources, transform their data into your target schema, and handle the complexities of extraction, validation, and transformation.

Key components include:

  • API Configs (ApiConfig): These are definitions that tell superglue how to interact with a specific API Endpoint. You provide an instruction (e.g., “fetch user data”), the API’s URL, and optionally, documentation or a response schema. Superglue uses this to understand and call the API, handling aspects like pagination and authentication.
  • Workflows (Workflow): Workflows allow you to chain multiple API calls and transformations together. A workflow consists of a series of ExecutionSteps. Each step typically uses an ApiConfig to fetch or send data, and you can map and transform data between steps. This is powerful for orchestrating complex data flows.
  • Transformations (JSONata): Data transformations and mappings within API Configs and Workflows are often defined using JSONata, a flexible query and transformation language for JSON.

​
getting Started

  1. Get Access

  2. Install the SDK

    npm install @superglue/client

​
example 1: Executing a Simple Workflow

Let’s create a workflow that:

  1. Fetches a list of todos from JSONPlaceholder.
  2. For the first todo in the list, fetches the details of the user who created it.
  3. Combines the todo title and the user’s name.
import { SuperglueClient, HttpMethod } from "@superglue/client"; // Assuming HttpMethod is exported

const superglue = new SuperglueClient({
  apiKey: "YOUR_API_KEY", // Replace with your actual API key or remove if self-hosting with no auth
});

async function runMyWorkflow() {
  try {
      const workflowResult = await superglue.executeWorkflow({
        // input can be an ID of a pre-saved workflow or a WorkflowInput object
          workflow: {
            id: "myTodoUserWorkflow",
            steps: [
              {
                id: "fetchTodos", // Unique ID for this step
                apiConfig: {
                  id: "jsonplaceholderTodos",
                  urlHost: "https://jsonplaceholder.typicode.com",
                  urlPath: "/todos",
                  method: HttpMethod.GET,
                  instruction: "Fetch a list of todos. We only need the first one for this example.",
                },
              },
              {
                id: "fetchUser",
                apiConfig: {
                  id: "jsonplaceholderUsers",
                  urlHost: "https://jsonplaceholder.typicode.com",
                  urlPath: "/users/<<$.fetchTodos[0].userId>>", // JSONata path parameter for first userId
                  method: HttpMethod.GET,
                  instruction: "Fetch user details by user ID for the first todo."
                },
              },
            ],
            // Transform the results of the steps into the final desired output. If not given, this will be generated from the reponse schema
            // finalTransform: `{
            //  "todoTitle": $steps.fetchTodos.data[0].title,
            //  "userName": $steps.fetchUser.data.name
            //}`,
            finalTransform: "$",
            responseSchema: { // define the expected final output structure
              type: "object",
              description: "first todo",
              properties: {
                  todoTitle: { type: "string" },
                  userName: { type: "string" }
              }
            }
        },
        // `payload` could be used to pass initial data to the first step if needed. E.g. IDs to fetch, filters, etc. In short, things that can change across calls.
        // payload: { userId: 1 },
        // `credentials` can be used to authenticate requests. They need to be referenced in the api config (e.g. "headers": {"Authorization": "Bearer <<hubspot_api_key>>"})
        // credentials: { hubspot_api_key: "pa_xxx" },      
    });

    console.log("Workflow Succeeded:", workflowResult.success);
    console.log("Workflow Data:", workflowResult.data);
  } catch (error) {
    console.error("Workflow failed:", error);
  }
}

runMyWorkflow();

​
next steps

​
requirements

  • Node.js 16+ for the client SDK.
  • For self-hosting:
    • Docker 20.10.0+
    • A Gemini or OpenAI API key (or compatible LLM provider).

​
support & resources

Ready to simplify your API integrations? Get started with superglue now!