# Cancel a run
Source: https://docs.superglue.cloud/api-reference/runs/cancel-a-run
openapi.yaml post /runs/{runId}/cancel
# Get run status
Source: https://docs.superglue.cloud/api-reference/runs/get-run-status
openapi.yaml get /runs/{runId}
# List runs
Source: https://docs.superglue.cloud/api-reference/runs/list-runs
openapi.yaml get /runs
# Get tool details
Source: https://docs.superglue.cloud/api-reference/tools/get-tool-details
openapi.yaml get /tools/{toolId}
# List tools
Source: https://docs.superglue.cloud/api-reference/tools/list-tools
openapi.yaml get /tools
# Run a tool
Source: https://docs.superglue.cloud/api-reference/tools/run-a-tool
openapi.yaml post /tools/{toolId}/run
# Handle incoming webhook
Source: https://docs.superglue.cloud/api-reference/webhooks/handle-incoming-webhook
openapi.yaml post /hooks/{toolId}
**Enterprise feature.**
Trigger a tool execution from an external webhook (Stripe, GitHub, etc.).
The request body becomes the tool's input payload.
Returns 202 Accepted immediately and executes the tool asynchronously.
# Metrics & Telemetry
Source: https://docs.superglue.cloud/enterprise/metrics
Monitor your Superglue usage with Prometheus-compatible metrics
**Enterprise Feature** — Metrics & telemetry is available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
Superglue exposes **organization-scoped** runtime metrics via a **Prometheus text exposition** endpoint. Use these to build dashboards, SLOs, and alerts for your Superglue usage.
## Endpoint
```
https://api.superglue.cloud/v1/metrics
```
**Auth**: `Authorization: Bearer `\
**Format**: Prometheus text exposition (`text/plain; version=0.0.4`)
**OpenTelemetry users**: Superglue exposes metrics in Prometheus format. To integrate with an
OpenTelemetry stack, use an [OpenTelemetry Collector Prometheus
receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver)
and export via OTLP to your backend.
## Quick Setup
### Option A: Using `authorization` (recommended)
```yaml theme={null}
scrape_configs:
- job_name: superglue
scheme: https
metrics_path: /v1/metrics
static_configs:
- targets: ["api.superglue.cloud"]
authorization:
type: Bearer
credentials: ""
```
### Option B: Using `bearer_token`
```yaml theme={null}
scrape_configs:
- job_name: superglue
scheme: https
metrics_path: /v1/metrics
static_configs:
- targets: ["api.superglue.cloud"]
bearer_token: ""
# or: bearer_token_file: /etc/secrets/superglue_api_key
```
Configure the collector to scrape Superglue via the Prometheus receiver:
```yaml theme={null}
receivers:
prometheus:
config:
scrape_configs:
- job_name: superglue
scheme: https
metrics_path: /v1/metrics
static_configs:
- targets: ["api.superglue.cloud"]
authorization:
type: Bearer
credentials: ""
exporters:
otlp:
endpoint: ""
service:
pipelines:
metrics:
receivers: [prometheus]
exporters: [otlp]
```
## Example Response
```text theme={null}
# HELP superglue_runs_total Total number of finished runs (org-scoped).
# TYPE superglue_runs_total counter
superglue_runs_total{status="success",source="api"} 12
superglue_runs_total{status="failed",source="scheduler"} 3
# HELP superglue_run_duration_seconds_p95 p95 run duration over a trailing window (org-scoped).
# TYPE superglue_run_duration_seconds_p95 gauge
superglue_run_duration_seconds_p95{source="frontend",window="300s"} 1.23
```
***
## Metrics Reference
**Type**: Counter
Total number of finished runs in your org, grouped by outcome and source.
| Label | Values |
| -------- | -------------------------------------------------------------- |
| `status` | `success`, `failed`, `aborted` |
| `source` | `api`, `frontend`, `scheduler`, `mcp`, `tool-chain`, `webhook` |
Best used for **rates and error ratios** over time using `increase()` / `rate()`.
**PromQL Examples**
Total throughput (5m):
```promql theme={null}
sum(increase(superglue_runs_total[5m]))
```
Error rate (5m):
```promql theme={null}
sum(increase(superglue_runs_total{status=~"failed|aborted"}[5m]))
/
clamp_min(sum(increase(superglue_runs_total[5m])), 1)
```
Breakdown by source:
```promql theme={null}
sum by (source) (increase(superglue_runs_total[5m]))
```
**Type**: Gauge
p95 runtime (seconds) for finished runs over a trailing 5-minute window.
| Label | Values |
| -------- | -------------------------------------------------------------- |
| `source` | `api`, `frontend`, `scheduler`, `mcp`, `tool-chain`, `webhook` |
| `window` | `300s` |
This is **end-to-end latency** as Superglue sees it. Good for catching tail latency regressions.
**PromQL Examples**
Alert when API runs get slow:
```promql theme={null}
superglue_run_duration_seconds_p95{source="api"} > 10
```
Dashboard all sources:
```promql theme={null}
superglue_run_duration_seconds_p95
```
***
## Use Cases
Track `superglue_runs_total` filtered by `source="scheduler"` to see successful vs failed runs over time.
```promql theme={null}
sum by (status) (increase(superglue_runs_total{source="scheduler"}[1h]))
```
Set up alerts when scheduled runs fail — catch issues before they pile up.
```promql theme={null}
increase(superglue_runs_total{source="scheduler",status="failed"}[15m]) > 0
```
When an alert fires, jump into the Superglue dashboard or query the REST API to fetch the latest runs and inspect stack traces.
```bash theme={null}
curl -H "Authorization: Bearer $SUPERGLUE_API_KEY" \
"https://api.superglue.cloud/v1/runs?status=failed&limit=10"
```
# Notifications
Source: https://docs.superglue.cloud/enterprise/notifications
Get alerted when tool runs fail
**Enterprise Feature** — Notifications are available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
When tools run on a schedule, failures can go unnoticed. Notifications alert your team immediately when something breaks.
Configure notifications at [app.superglue.cloud/admin?view=notifications](https://app.superglue.cloud/admin?view=notifications).
## How it works
Set up Slack (or another supported channel) to receive alerts
Send a test notification to verify everything works
Define which failures should trigger notifications
## Channel setup
### Authentication
Choose one of two methods:
| Method | Best for |
| -------------------- | -------------------------------------------- |
| **Incoming Webhook** | Quick setup, single channel |
| **Bot Token** | Multiple channels, auto-join public channels |
Both require a Slack Workspace Admin. The setup wizard guides you through each step.
### Message buttons
* **View Details** — Opens the run in the admin dashboard
* **Investigate Failure** — Opens the AI agent with failure context
### Troubleshooting
**Notifications not sending**
* Check that your webhook URL or bot token is valid
* Ensure at least one notification rule is enabled
**Bot can't post to channel**
* Public channels: Bot auto-joins on first message
* Private channels: Invite manually with `/invite @botname`
## Notification rules
Rules determine which failures trigger notifications.
### Trigger sources
| Source | Description |
| ------------- | -------------------------------------- |
| **Scheduler** | Runs triggered by cron schedules |
| **API** | Runs triggered via the REST API or SDK |
| **Webhook** | Runs triggered by incoming webhooks |
Most teams start with **Scheduler** failures only, since scheduled runs happen without human oversight.
### Tool ID patterns
Filter notifications to specific tools using glob patterns:
* `prod-*` — Only tools starting with "prod-"
* `*-sync` — Only tools ending with "-sync"
* Leave empty to match all tools
## Notification content
Each failure notification includes:
* **Tool name** and failure status
* **Error message** (truncated if long)
* **Failed step** with its description
* **Run metadata** — Run ID, source, timestamp
### Investigate Failure
Notifications include an "Investigate Failure" button that opens the superglue agent with the failed run pre-loaded. The agent explains the error, identifies the root cause, and can fix the tool directly.
### Auto-disable
After repeated delivery failures, superglue automatically disables notifications to prevent spam. Fix the underlying issue, then re-enable in the dashboard.
# Permissioning
Source: https://docs.superglue.cloud/enterprise/permissioning
Control tool access with restricted and unrestricted API keys
**Enterprise Feature** — API key permissioning is available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
superglue uses API keys to control access to tools and APIs. You can create keys with full access or restrict them to specific tools.
## API key types
| Type | Access |
| ---------------- | ------------------------------------------------ |
| **Unrestricted** | Full access to GraphQL, REST, MCP, and all tools |
| **Restricted** | REST and MCP only, limited to specific tools |
## Creating API keys
Create and manage API keys from the dashboard:
## Restricted keys
Restricted API keys can only access tools explicitly listed in their `allowedTools` configuration:
| `allowedTools` value | Meaning |
| ---------------------- | ---------------------------- |
| `['*']` | All tools allowed (wildcard) |
| `['tool-1', 'tool-2']` | Only these specific tools |
### What restricted keys can do
* Execute tools via REST API (`/v1/tools/{id}/run`)
* Execute tools via MCP server
* List only their allowed tools
### What restricted keys cannot do
* Access the GraphQL API
* View or execute tools not in their allowed list
* Modify tool configurations
## Use cases
Create restricted keys for AI agents that only allow access to approved tools
Share restricted keys with external services that only need to trigger specific tools
## Example: Creating a restricted key for an agent
1. Navigate to **Settings → API Keys**
2. Click **Create API Key**
3. Enable **Restricted access**
4. Select the tools this key should access
5. Copy the generated key
Use this key in your MCP configuration or REST API calls:
```typescript theme={null}
// MCP server configuration with restricted key
{
"mcpServers": {
"superglue": {
"command": "npx",
"args": ["-y", "superglue-mcp"],
"env": {
"SUPERGLUE_API_KEY": "sg_restricted_xxx",
"SUPERGLUE_API_URL": "https://api.superglue.cloud"
}
}
}
}
```
The agent will only see and execute tools allowed by this key.
# Run History
Source: https://docs.superglue.cloud/enterprise/run-history
Track every tool execution and debug failures with full context
**Enterprise Feature** — Run Results is available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
Every time a tool runs—whether from the API, a schedule, or the dashboard—superglue saves the complete execution history. When something goes wrong, you have everything you need to understand what happened and fix it.
## The Runs tab
Open the **Runs** tab to see all tool executions across your organization.
Each row shows:
* **Started At** — When the run began
* **Tool** — Which tool was executed
* **Status** — Success, failed, or running
* **Trigger** — How it was started (API, schedule, dashboard, or agent)
* **Details** — Duration for successful runs, or the error message for failures
Click any row to expand it and see the full execution details, including the input payload and step-by-step results.
## Debugging a failed run
When a run fails, you have two ways to investigate:
### Load the run in the playground
Click **Load Run** to open the tool with the exact same inputs that caused the failure. You can:
1. See the payload that was sent
2. Re-run the tool to reproduce the issue
3. Make changes and test until it works
4. Save your fix
This is the fastest way to debug when you already have a hunch about what went wrong.
### Ask the agent to investigate
Click **Investigate** to open a conversation with the superglue agent, pre-loaded with the run's context. The agent can:
* Analyze the error and explain what went wrong
* Look at the step results to find where things broke
* Compare with successful runs to spot differences
* Suggest fixes based on the actual data
This is helpful when the error is unclear or you want a second opinion on what might be causing the issue.
## Enabling run results
Run results can be enabled on superglue via the enterprise plan.
Results are compressed before storage and retained according to your organization's data retention settings.
# Scheduled Execution
Source: https://docs.superglue.cloud/enterprise/scheduling
Automate tool execution with cron-based scheduling
**Enterprise Feature** — Tool scheduling is available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
Schedule tools to run automatically at specific times or intervals. Scheduled executions run in the background and log results for later review.
## Creating a schedule
Create schedules from the dashboard:
Navigate to your tool and click "Add Schedule"
Choose from preset intervals (every 5 minutes, hourly, daily, weekly, monthly) or enter a custom cron expression
**Common cron examples:**
* `*/5 * * * *` - Every 5 minutes
* `0 9 * * 1-5` - Weekdays at 9 AM
* `0 0 1 * *` - First day of every month
* `0 */6 * * *` - Every 6 hours
Visit [crontab.guru](https://crontab.guru) to build and validate cron expressions
Choose your timezone to ensure the schedule runs at the correct local time
Provide JSON input data that will be passed to each execution
Click "Add Schedule" to save. The schedule will start running at the next scheduled time. You can pause it anytime by toggling "Enable schedule" off.
## Managing schedules
### Viewing schedules
All schedules for a tool are visible on the tool details page. Each schedule shows:
* Cron expression and human-readable description
* Timezone
* Next scheduled run time
* Last run time and status
* Enable/disable toggle
### Modifying schedules
Click on any schedule to modify:
* Change the cron expression
* Update the timezone
* Modify the input payload
* Enable or disable the schedule
### Deleting schedules
Remove a schedule by clicking the delete button. This stops all future executions but preserves historical run logs.
## Execution behavior
* **Reliability**: Schedules are executed by a dedicated scheduler service with automatic failover
* **Logging**: Every scheduled execution creates a run record with full logs
* **Source tracking**: Scheduled runs are labeled with source `SCHEDULE` in the runs table
* **Error handling**: Failed scheduled runs are logged but don't automatically retry (configure retries in the schedule options)
## Advanced options
When creating a schedule, expand "Advanced Options" to configure:
* **Retries**: Number of retry attempts (0-10) for failed API calls
* **Timeout**: Maximum execution time in milliseconds
* **Webhook**: Send execution results to a URL or trigger another tool when complete
# Tool Versioning
Source: https://docs.superglue.cloud/enterprise/tool-versioning
Track changes and restore previous versions of your tools
**Enterprise Feature** — Tool versioning is available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
Every time you save a tool, superglue automatically archives the previous version. View the full change history and restore any previous version with a single click.
## How it works
* **Automatic versioning**: Each save creates a new version in the history
* **Change tracking**: See exactly what changed between versions with diff highlighting
* **One-click restore**: Restore any previous version instantly
* **User attribution**: Track who made each change and when
## Viewing version history
Click the history icon on any tool to open the version history panel. Each entry shows:
* Version number
* Timestamp and author
* Expandable diff showing what changed
## Restoring a version
Click "Restore" on any historical version to revert the tool to that state. The current version is automatically archived before the restore, so you never lose work.
# Incoming Webhooks
Source: https://docs.superglue.cloud/enterprise/webhooks
Trigger tool execution from external services
**Enterprise Feature** — Incoming webhooks are available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more.
Trigger tools from external services like Stripe, GitHub, Shopify, or any system that can send HTTP webhooks. When an external service sends a webhook, superglue executes your tool with the webhook payload as input.
## How it works
When you enable webhooks for a tool, superglue provides a unique webhook URL:
```
POST https://api.superglue.ai/v1/hooks/{toolId}?token={your_api_key}
```
**Example with real values:**
`https://api.superglue.ai/v1/hooks/`handle-stripe-customer`?token=`a1b2c3d4-e5f6-7890-abcd-ef1234567890
Replace with your actual tool ID (e.g., `handle-stripe-customer`) and with your API key UUID. **Don't include the curly braces `{}`** — they're just placeholders.
External services send HTTP POST requests to this URL. The request body becomes the tool's input payload, and superglue executes the tool asynchronously.
## Setting up a webhook
Your webhook URL follows this pattern:
```
https://api.superglue.ai/v1/hooks/{toolId}?token={your_api_key}
```
Replace `{toolId}` with your tool's ID and `{your_api_key}` with a valid API key. You can create API keys at [https://app.superglue.cloud/api-keys](https://app.superglue.cloud/api-keys).
Add the webhook URL to your external service (Stripe, GitHub, etc.). Most services have a webhooks section in their dashboard.
Your tool receives the raw webhook payload as input. Design your steps to extract the data you need:
```typescript theme={null}
// Example: Stripe webhook payload
{
"id": "evt_1234",
"type": "customer.created",
"data": {
"object": {
"id": "cus_abc123",
"email": "user@example.com"
}
}
}
```
Use template expressions to access nested fields: `<<(sourceData) => sourceData.data.object.email>>`
## Webhook behavior
* **Asynchronous execution**: Returns `202 Accepted` immediately, executes the tool in the background
* **Run tracking**: Each webhook trigger creates a run record you can view in the dashboard
* **Request source**: Runs triggered via webhook are labeled with source `WEBHOOK` in the runs table
## Example: Stripe webhook integration
Build a tool that handles Stripe events and syncs customer data to your CRM:
```typescript theme={null}
// Tool configuration for handling Stripe customer.created events
{
id: "handle-stripe-customer",
steps: [
{
id: "addToMailchimp",
systemId: "mailchimp",
apiConfig: {
method: "POST",
urlPath: "/lists/{list_id}/members",
body: {
email_address: "<<(sourceData) => sourceData.data.object.email>>",
status: "subscribed"
}
}
}
]
}
```
Webhook URL: `https://api.superglue.ai/v1/hooks/handle-stripe-customer?token={your_api_key}`
## Example: GitHub webhook integration
Trigger a deployment tool when code is pushed to your repository:
```typescript theme={null}
// Tool that deploys when code is pushed to main
{
id: "deploy-on-push",
steps: [
{
id: "triggerDeploy",
systemId: "vercel",
apiConfig: {
method: "POST",
urlPath: "/v13/deployments",
body: {
name: "my-app",
gitSource: {
type: "github",
ref: "<<(sourceData) => sourceData.ref>>",
repoId: "<<(sourceData) => sourceData.repository.id>>"
}
}
}
}
]
}
```
## Security considerations
Webhook URLs include your API token. Treat them as secrets.
* **Use HTTPS**: Always use HTTPS webhook URLs
* **Restricted API keys**: Use API keys that only have permission to execute specific tools
* **Validate signatures**: If the source service provides webhook signatures (e.g., Stripe's `stripe-signature` header), validate them in your tool logic
* **Monitor activity**: Regularly review the runs dashboard for unexpected webhook activity
* **Rotate keys**: Periodically rotate API keys used for webhooks
## Filtering webhook events
Many services send multiple event types to the same webhook URL. Filter events in your tool using conditional logic:
```typescript theme={null}
// Only process customer.created events from Stripe
{
finalTransform: `(sourceData) => {
if (sourceData.type !== 'customer.created') {
return { skipped: true, reason: 'Event type not handled' };
}
return sourceData.addToMailchimp;
}`
}
```
# Concepts
Source: https://docs.superglue.cloud/getting-started/core-concepts
Understanding superglue fundamentals
The core idea of superglue is to let users connect their systems via a natural language interface that abstracts away the pain of authentication, structuring requests and mapping data between systems. This page explains key concepts - systems and tools - that are the essential building blocks of everything superglue does.
## Systems
Systems are the reusable building blocks for tools in superglue. A system represents anything that can provide, store, or process data: REST APIs, GraphQL endpoints, SOAP services, SFTP servers, Postgres databases and more.
Instead of maintaining a limited connector library, superglue takes a more general approach. Users can configure any system with custom documentation, URLs, authentication, and instructions tailored to their use case. Think of systems as containers that store all context required to interact with an external service. To learn more about creating systems, check the [systems guide](/guides/creating-a-system).
## Tools
superglue is an AI-powered **tool builder** that builds on top of a user's systems. Tools are built according to user instructions and execute **sequentially**. Every tool takes a number of (optional) inputs, executes a series of tool steps and returns an output.
Tool inputs can include the systems that this tool will use, a payload of tool variables (e.g. a timestamp, a user ID or something similar) or files.
Tools will **execute deterministically** once they are saved, but are built and auto-evaluated using large language models. For more details on tool building, please check out our [tool guide](/guides/creating-a-tool).
## Agents
Definitions of what constitutes an agent vary. When we speak about the superglue agent, we are referring to a chat UI that is powered by an LLM with access to a set of custom tools that it can execute on our user's behalf.
The superglue agent is designed to help you understand what superglue is, how to set up your systems in superglue and how to build tools tailored exactly to your needs and specifications.
Different agents in superglue may have slightly different tool calling capabilities and context about your tools and systems, but the core concept remains the same.
# Introduction
Source: https://docs.superglue.cloud/getting-started/introduction
Sync, migrate, integrate, and manage glue code
superglue is an AI-native integration platform for the glue code holding your systems together.
Build tools to sync, migrate, integrate, and manage legacy systems without writing custom integration code in minutes instead of months.
## Why use superglue?
superglue does not rely on templates and pre-built connectors. It understands documentation, custom auth patterns, rate limiting and misleading HTTP 200 status code errors that plague legacy integrations.
Stop wiring up endpoints, query parameters and auth headers by hand — superglue does this for you. Specify only what your tool and workflow does in natural language, superglue handles the rest.
Set up authentication, upload documentation, or add custom system instructions — all via a chat interface. superglue automates requirements gathering by running web search, reading documentation and testing API endpoints.
***
## How superglue works
Add REST, GraphQL, SOAP, Postgres databases, FTP/SFTP, or local
file systems. Handles OAuth, API
keys, basic auth, custom headers, certificate auth, and session-based flows.
Describe what you need in natural language. The agent understands your systems and generates executable tools that
work across your systems. Handles
JSON, XML, CSV, fixed-width files, and custom formats.
Run tools on-demand, schedule them, or trigger via webhooks. Full execution logs, retry logic, error notifications, and prod observability.
***
## What runs on superglue
Migrate data from legacy ERP, CRM, and custom databases to modern platforms.
Handle complex schema transformations, validate data integrity, and roll
back on failures.
Keep legacy systems in sync with modern platforms during transition periods.
Bi-directional data flows, conflict resolution, and scheduled updates.
Build tools that connect legacy ERP, warehouse management systems, and
legacy SaaS to your modern stack. Upload custom documentation, include system specific instructions and let superglue handle the rest.
Give AI agents the ability to query legacy databases, work with your APIs,
extract data, and map information across disconnected systems.
[Book a demo](https://cal.com/superglue/superglue-demo) to see how superglue
can modernize your legacy systems.
## Support & Community
* [GitHub Repository](https://github.com/superglue-ai/superglue) - Open source and self-hostable
* [Discord Community](https://discord.gg/vUKnuhHtfW) - Get help and share ideas
* [Book a Demo](https://cal.com/superglue/superglue-demo) - Talk to our team
* Email: [founders@superglue.ai](mailto:founders@superglue.ai)
# LLM-driven Development
Source: https://docs.superglue.cloud/getting-started/llm-driven-development
Enhance your AI coding experience with LLM-readable documentation
Like many of you, we love using LLMs during development. To make AI coding assistants more effective when working with superglue, we provide our full documentation in a single markdown file that LLMs can easily consume.
## Available Files
We offer two files:
| File | URL | Purpose |
| ------------- | ----------------------------------------------------------- | -------------------------------------------- |
| **Index** | [llms.txt](https://docs.superglue.cloud/llms.txt) | Lightweight index of all documentation pages |
| **Full docs** | [llms-full.txt](https://docs.superglue.cloud/llms-full.txt) | Complete documentation in one file |
## How to Use
**If your tool can fetch URLs** (Cursor, Claude, etc.) — just give it the URL and let it pull what it needs.
**If your tool requires file uploads** — download [llms-full.txt](https://docs.superglue.cloud/llms-full.txt) and upload it directly.
# Setup
Source: https://docs.superglue.cloud/getting-started/setup
The 5 minute guide to building your first superglue tool
## Hosted Version (Recommended)
Get started in under 5 minutes with no infrastructure setup.
Or [book a demo](https://cal.com/superglue/superglue-demo) to talk to our team first.
Click "Give me an example" to see sample tools, or describe what you need in the agent interface:
The agent will help you set up your systems and tests tools automatically.
Save the tool, run it on-demand, schedule it, or trigger via webhook.
***
## Self-Hosted
Deploy on your infrastructure for complete control and customizability.
### Quick Start
**Prerequisites:** Docker and an LLM API key (OpenAI, Anthropic, or Gemini)
```env theme={null}
AUTH_TOKEN=your-secret-token
LLM_PROVIDER=OPENAI
LLM_FALLBACK_PROVIDER=ANTHROPIC
OPENAI_API_KEY=sk-proj-xxxxx
DATASTORE_TYPE=file
```
For full environment setup instructions, check out the [.env.example](https://github.com/superglue-ai/superglue/blob/main/.env.example).
Run the following command:
```bash theme={null}
docker run -d \
--name superglue \
--env-file .env \
-p 3000:3000 \
-p 3001:3001 \
-p 3002:3002 \
-v superglue_data:/data \
superglueai/superglue:latest
```
Dashboard:
```
http://localhost:3001
```
API:
```
http://localhost:3000?token=your-secret-token
```
### Local Development
```bash theme={null}
git clone https://github.com/superglue-ai/superglue.git
cd superglue
```
Rename the `.env.example` in root to `.env` and populate the required fields, then:
```bash theme={null}
npm install
npm run dev
```
***
### Production Setup
For production deployments, add PostgreSQL and enable credential encryption:
```env theme={null}
AUTH_TOKEN=your-secret-token
LLM_PROVIDER=OPENAI
LLM_FALLBACK_PROVIDER=ANTHROPIC
OPENAI_API_KEY=sk-proj-xxxxx
# PostgreSQL
DATASTORE_TYPE=postgres
POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_USERNAME=superglue
POSTGRES_PASSWORD=secure-password
POSTGRES_DB=superglue
# when using a unsecured postgres db that does not support ssl - like a local docker container, uncomment this:
# POSTGRES_SSL=false
# Credential encryption
MASTER_ENCRYPTION_KEY=generate-with-openssl-rand-hex-32
# Enable scheduled execution
START_SCHEDULER_SERVER=true
```
Start PostgreSQL separately:
```bash theme={null}
docker run -d \
--name postgres \
-e POSTGRES_DB=superglue \
-e POSTGRES_USER=superglue \
-e POSTGRES_PASSWORD=secure-password \
-v postgres_data:/var/lib/postgresql/data \
postgres:15-alpine
```
## Environment Variables
| Variable | Required | Description |
| ------------------------ | --------- | ----------------------------------------------------------------------- |
| `AUTH_TOKEN` | Yes | Secret for API authentication |
| `DATASTORE_TYPE` | Yes | `memory`, `file`, or `postgres` (`postgres` requires additional config) |
| `LLM_PROVIDER` | Yes | `OPENAI`, `ANTHROPIC`, or `GEMINI` (default: `OPENAI`) |
| `LLM_FALLBACK_PROVIDER` | No | Optional fallback provider (`OPENAI`, `ANTHROPIC`, `GEMINI`) |
| `OPENAI_API_KEY` | If active | OpenAI API key |
| `ANTHROPIC_API_KEY` | If active | Anthropic API key |
| `GEMINI_API_KEY` | If active | Gemini API key |
| `MASTER_ENCRYPTION_KEY` | No | Encrypt stored credentials (generate: `openssl rand -hex 32`) |
| `START_SCHEDULER_SERVER` | No | Enable scheduled tools (default: `false`) |
***
## Next Steps
Understand systems, tools, and execution
Build your first tool
Use superglue tools in your internal GPT, Cursor or Claude
# Creating a System
Source: https://docs.superglue.cloud/guides/creating-a-system
Connect superglue to any system
Create a system in superglue to use as reusable building blocks for building tools in superglue. Systems handle authentication and documentation retrieval automatically once configured.
## Getting started
The fastest way to create a system is through the agent interface. Visit [app.superglue.cloud](https://app.superglue.cloud) and start chatting with the agent.
superglue will:
1. Identify the target system
2. Guide you through the authentication flow by collecting all required credentials
3. Create the system and make it available immediately
4. Process and analyze the system's documentation automatically in the background
5. Test system access and verify your credentials are working
Start creating systems with the agent
Systems can also be created manually using the web application:
Click the "Systems" button in the sidebar
Click **Add System** to open the system form
* **Template**: Choose from 100+ prebuilt templates or create a custom system. Templates pre-fill the base URL, documentation URL, and authentication type
* **URL**: Base URL of the system (e.g., `https://api.stripe.com`)
* **Documentation URL**: Optional but recommended link to API documentation
* **Documentation as a file**: Optionally upload a documentation file (PDF, OpenAPI Specs, .zip files, etc.). If you upload a file, superglue will not crawl a doc URL.
* **Credentials**: See [authentication and credential management](/guides/creating-a-system#authentication-and-credential-management) for details
* **OAuth**: For OAuth systems, click **Connect to system** to complete the flow and let superglue handle the token exchange
superglue saves your configuration and processes online documentation in the background if a documentation URL was provided
## Authentication and credential management
superglue supports many different authentication methods. All credentials are encrypted both at rest and in transit.
superglue supports both the client credentials flow and authorization code flow with **automatic token refresh**.
**superglue handles:**
* Scope validation
* Token exchange and storage
* Error handling for token issues
* Automatic token refresh during tool execution
#### Authorization code flow
Used when end users grant access to their account data.
1. User clicks the "connect to provider" button
2. Redirected to the provider’s login page
3. User grants permissions for requested scopes
4. superglue exchanges the authorization code for access tokens
5. Tokens are automatically refreshed on expiration
**Examples:** Slack, Salesforce, Google Services
### Client credentials flow
Used for server-to-server communication with no user interaction.
1. Application requests an access token using client ID and secret
2. Token is automatically refreshed before expiration
3. No user consent required
**Examples:** Twilio, Auth0 Management API, Microsoft Graph
**Required fields:**
* `clientId`, `clientSecret`, `authorizationUrl`, `tokenUrl`
**Optional fields:**
* `scopes`: space-separated OAuth scopes
* `redirectUri`: redirect URL after authorization
Prebuilt OAuth templates are available for 100+ APIs including HubSpot, Google Ads, and Salesforce. Check the templates dropdown in the creation form.
The simplest authentication method. Provide an API key and superglue automatically determines where to include it based on the API’s documentation.
Possible placements:
* Authorization header: `Authorization: Bearer {key}`
* Custom header: `X-API-Key: {key}`
* Query parameter: `?api_key={key}`
### Examples
* **SendGrid**: API key in Authorization header with Bearer prefix
* **Airtable**: Personal access token as Bearer token
* **Zendesk**: Email + API token combined as basic auth (`{email}/token:{apiKey}`)
* **Shopify**: Custom header `X-Shopify-Access-Token`
* **Mailchimp**: Basic auth with `anystring` as username and API key as password
Connect to databases by providing connection details. Supported types include PostgreSQL and FTP/SFTP servers.
### Configuration
**PostgreSQL** requires a connection URL in the format `postgresql://<>:<>@<>:<>/<>` with credentials for `user`, `password`, `host`, `port`, and `database`.
**FTP/SFTP** requires a URL in the format `sftp://<>:<>` with `username` and `password` credentials.
For systems with unique authentication requirements, superglue supports multiple custom patterns.
```typescript theme={null}
credentials: {
username: "your_username",
password: "your_password"
}
```
Used by: Jenkins, Artifactory, legacy APIs
```typescript theme={null}
credentials: {
"X-Custom-Auth": "your_auth_token",
"X-API-Version": "v2",
"X-Tenant-ID": "tenant_123"
}
```
Used by: Internal APIs, multi-tenant systems
```typescript theme={null}
credentials: {
bearerToken: "eyJhbGciOiJIUzI1NiIs..."
}
```
Used by: GitHub (personal access tokens), GitLab, custom auth systems
```typescript theme={null}
credentials: {
botToken: "xoxb-XXXXXX"
}
```
Used by: Slack and Discord
All secrets are encrypted at rest and in transit. The LLM never accesses
real credentials - only placeholders such as `<>` are exposed during
workflow setup and execution.
Systems can be created without credentials and updated later. Credentials
may also be supplied dynamically during tool execution.
The agent can assist with figuring out which credentials are required and where to find them.
e.g., *"I want to connect to my company’s internal API but I'm not sure what authentication it uses."*
## Automatic documentation crawling
superglue automatically crawls and processes documentation upon system creation. This makes it possible for superglue to reason about endpoints, authentication, and data models without manual setup.
When creating a system, the **`documentationUrl`** or uploaded documentation files (like OpenAPI specs, PDFs, or HTML exports) are used as the primary source for this process. The more complete and accurate the provided material, the better superglue’s internal understanding of the system.
### Supported documentation formats
superglue’s fetchers handle most modern and legacy documentation types:
Extracts endpoints, parameters, and schemas from `.json` or `.yaml`
specifications.
Fetches content from popular hosted sites like Mintlify, ReadMe, or
Docusaurus.
Parses legacy or self-hosted documentation, including HTML exports and PDF
manuals.
Automatically analyzes PostgreSQL and MySQL schemas to identify tables,
columns, and relationships.
### Documentation filtering with keywords
Large APIs can have hundreds of endpoints. To improve accuracy and reduce processing time, you can provide specific keywords via the agent that describe what parts of the documentation are most relevant.
The agent automatically adjusts documentation processing based on your instructions:
```
Connect to Stripe and focus on customer and subscription endpoints
```
This ensures that only relevant documentation is processed and saved to the system. Keywords are used to:
* Guide crawling and processing to retain only the most relevant documentation sections
* Improve ranking and retrieval relevance at runtime
## Next steps
Go to superglue and start connecting your APIs, databases, and systems in
minutes.
# Creating a Tool
Source: https://docs.superglue.cloud/guides/creating-a-tool
Create tools to connect your systems and do things
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](/getting-started/core-concepts) page.
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:
1. Identify which system to use (or create one if needed)
2. Find the relevant API endpoint from the documentation
3. Configure the API call with appropriate parameters
4. 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
Start building tools with our agent
Build tools in the UI:
Go to Tools in your superglue dashboard and click "Create Tool"
Choose which systems this tool will use
Describe what the tool should do in natural language. superglue will build the workflow steps automatically.
Run the tool with sample data to verify it works as expected. See [debugging tools](/guides/debugging-a-tool) for troubleshooting.
Use the REST SDK to run tools you've already created:
```bash theme={null}
npm install @superglue/client
```
**Configure and run a tool:**
```typescript theme={null}
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](/sdk/overview) for more details.
## Tool anatomy
Every tool consists of:
Sequential API calls that fetch or modify data. Each step can reference data from previous steps.
JavaScript functions that shape the step inputs and the final output. Ensures tool results adhere to response schemas.
Access data from previous steps, credentials, and input payload using `<>` syntax.
## Step configuration
Each step in a tool represents a single API call with the following configuration:
### Basic structure
```typescript theme={null}
{
id: "stepId", // Unique identifier for this step
systemId: "stripe", // Which system to use
loopSelector: "(sourceData) => { return [\"one\", \"two\"]}", // The data selector for the current step
apiConfig: {
method: "POST", // HTTP method
urlPath: "/v1/customers", // API endpoint path
queryParams: {}, // URL query parameters
headers: { "Authorization": "Bearer <>" }, // Custom headers
body: "" // Request body
}
}
```
### Variable syntax
Use `<>` to access dynamic values:
**Access credentials:**
```typescript theme={null}
{
headers: {
"Authorization": "Bearer <>"
}
}
```
**Access previous step data:**
```typescript theme={null}
{
urlPath: "/customers/<>",
body: {
email: "<>"
}
}
```
**Access input payload:**
```typescript theme={null}
{
queryParams: {
user_id: "<>",
date: "<>"
}
}
```
**Execute JavaScript expressions:**
```typescript theme={null}
{
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 `<>` works for simple variables, but not for nested properties or transformations.
### Data selector
Extract an array to iterate over:
```typescript theme={null}
{
loopSelector: `(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 `<>` or accessible in code via `sourceData.currentItem`.
### Final transform
Shape the final output of the entire tool:
```typescript theme={null}
{
finalTransform: `(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
}))
};
}`;
}
```
## Special systems
### PostgreSQL
Query databases using the postgres\:// URL scheme:
```typescript theme={null}
{
id: "queryDatabase",
systemId: "postgres_db",
apiConfig: {
urlHost: "postgres://<>:<>@<>:5432",
urlPath: "<>",
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.
### FTP/SFTP
Access files on FTP servers:
```typescript theme={null}
{
id: "listFiles",
systemId: "ftp-server",
apiConfig: {
urlHost: "sftp://<>:<>@<>:22",
urlPath: "/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
Failed steps can be automatically retried with exponential backoff
Response data is validated against response schemas if specified
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:
```json theme={null}
{
"type": "object",
"properties": {
"userId": { "type": "string" },
"startDate": { "type": "string", "format": "date" }
},
"required": ["userId"]
}
```
**Response schema** - Validates final output:
```json theme={null}
{
"type": "object",
"properties": {
"success": { "type": "boolean" },
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"email": { "type": "string" }
}
}
}
}
}
```
## Next steps
Test, troubleshoot, and fix issues with your tools
Execute tools on-demand, scheduled, or via webhooks
# Debugging a Tool
Source: https://docs.superglue.cloud/guides/debugging-a-tool
Use the tool playground to debug your tool
The tool playground is a developer-friendly interface for testing, debugging, and refining your tools. It provides granular control over execution and visibility into every step of your workflow.
## Tool Playground Agent
The tool playground includes an AI agent that helps you debug and modify tools through natural language. Access it via the chat interface in the playground.
### Available tools
The playground agent has two specialized tools:
* **`edit_tool`** – Modify the tool configuration, steps, or final transform. Describe what you want to change and the agent updates the tool directly.
* **`edit_payload`** – Update the test payload without manual JSON editing. Ask the agent to add fields, change values, or restructure the input data.
The agent sees the current tool configuration and step results, so it can make targeted edits based on the actual data flowing through your tool.
## Tool Input
The playground starts with a **Tool Input** card where you define the data your tool will process. We refer to this as the tool payload.
### Manual JSON Input
Enter JSON directly in the payload editor. The playground validates your input against the input schema (if defined) and highlights any validation errors.
```json theme={null}
{
"userId": "12345",
"startDate": "2024-01-01"
}
```
If your tool has an input schema, the playground automatically generates a default payload as a starting point. You can edit this to match your test case.
### File Upload
Upload files to use as input data. The playground:
* Parses files automatically and adds them to your payload
* Shows file status (processing, ready, or error)
* Displays total file size
* Allows you to remove files
When you upload a file named `customers.csv`, it becomes available in your payload and subsequent steps as the `customers` variable.
### Schema Validation
The input card shows an amber-colored warning if your current payload doesn't match the input schema. Click "Run Anyway" to proceed despite validation errors, or fix your payload to match the schema requirements.
## Run All Steps
Click **Run All Steps** to execute your entire tool from start to finish. The playground:
* Executes steps sequentially
* Shows progress with a loading indicator on each step
* Marks completed steps with a green checkmark
* Marks failed steps with a red X
* Pauses before the next **critical** step and waits for your confirmation before continuing (for example, a step that writes data or makes changes in a third-party system)
* Navigates to the first failure or final output when done
Click **Stop Execution** to halt the run after the current step completes.
## Inspect a Step
### Step Input
The **Step Input** section shows exactly what data flows into the step and how it is shaped:
* **currentItem**: This is the evaluated result of the data selector showing as a template chip. See [Using Template Expressions](/guides/using-template-expressions) for more.
* **Aggregated Step Data**: All previous step results, payload objects and other input data.
Some data selectors may reference results from previous steps and may not be evaluated yet. Run all previous steps to inspect the evaluated data selector expression.
### Step Config
The **Step Config** tab shows how this step calls the external system:
* **Step Instruction** – natural‑language description of what the step does and what the response should contain
* **System** – which system is used to make the call
* **Safety badge** – a `Step modifies data on system` pill when the step performs write operations, so you can quickly spot calls that change external state
* **API Config** – HTTP method and URL for the request
* **Headers (JSON)** – JSON object with the request headers sent to the server (for example, the `Authorization` header)
* **Query Parameters** – JSON object with the query parameters appended to the request URL
* **Body** – Request body content, which can be JSON, form data, plain text, or any format
* **Pagination** – controls how the step fetches multiple pages (strategy, page size, cursor/offset paths) or shows *No pagination* when pagination is disabled
* **Stop Condition (JavaScript)** – optional JavaScript function that inspects each `response` and pagination state to decide when to stop fetching more pages
### Template Chips
Dynamic values in the config appear as **template chips** – small badges showing a preview of the evaluated expression. Click a chip to open its **the templating popover**, where you can edit the JavaScript expression and see a live preview of your code expression. Note that previews are only available if the previous step has completed successfully.
To insert a new template, type `@` anywhere in a text field to open the **variable picker**. Browse available variables by category (previous step results, credentials, loop context) and drill into nested properties. Selecting a variable inserts a chip with the correct accessor path.
### Step Result
After execution, the **Output** section shows:
* Successful API responses
* Error messages (with full stack traces for debugging)
* Data structure returned by the step
Click on nested objects to expand and inspect their contents. Use this to verify your step is receiving and returning the expected data structure.
### Run Step
Executes just this one step using the current configuration and previous step results. Use this to:
* Test changes to a single step without re-running the entire tool
* Debug a specific failure in isolation
* Verify your instruction changes work
If the **Step Data Selector** returns an array, the step turns into a loop step, running once for each item in the data selector output array. In this case, you can choose to run a single iteration using the dropdown on the **Run Step** button.
## Final Transform
The **Final Transform** card contains JavaScript code that shapes your raw step outputs into the final result structure.
### Edit Transform Code
The transform receives `sourceData` containing all step results:
```javascript theme={null}
(sourceData) => {
return {
users: sourceData.step_1.map((user) => ({
id: user.id,
name: user.full_name,
email: user.email_address,
})),
total: sourceData.step_1.length,
};
};
```
### Test Transform
Click **Run Transform Code** to execute your transform code against the current step results. This shows:
* The final output structure
* Any JavaScript errors in your transform
* Whether the output matches your response schema (if defined)
The transform runs in a sandboxed environment with access to common utilities. If it fails, the error message shows the exact line and issue.
### Response Schema
Define a JSON schema to validate your final output structure. The playground highlights schema violations and prevents invalid outputs from being returned.
# Deploying a Tool
Source: https://docs.superglue.cloud/guides/deploying-a-tool
Execute tools on-demand, schedule them, or trigger via incoming webhooks
Once you've created a tool, you can deploy it in three ways: execute it on-demand, schedule it to run automatically, or trigger it via incoming webhooks from external services.
Execute tools directly from the tool details page:
Go to Tools in your dashboard and select the tool you want to run
Enter any required input parameters in JSON format. If your tool doesn't require input, use `{}`
Click "Run All Steps" to execute immediately. You'll see real-time logs and step-by-step progress
Check the output data and individual step results. All executions are logged for debugging.
For programmatic execution, use the REST SDK:
```bash theme={null}
npm install @superglue/client
```
**Run a saved tool:**
```typescript theme={null}
import { configure, runTool, getRun, listRuns } from "@superglue/client";
// Configure the SDK
configure({
baseUrl: "https://api.superglue.cloud", // or your self-hosted URL
apiKey: "your_api_key"
});
// Run a tool with input payload
const { data: run } = await runTool("sync-customers", {
inputs: {
startDate: "2025-01-01",
userId: "user_123"
}
});
// For synchronous runs, result is available immediately
if (run.status === "success") {
console.log(run.data); // Final output
console.log(run.stepResults); // Step-by-step details
}
```
**Run asynchronously and poll for results:**
```typescript theme={null}
// Start an async run
const { data: run } = await runTool("sync-customers", {
inputs: { startDate: "2025-01-01" },
options: { async: true }
});
// Poll for completion
let status = run.status;
while (status === "running") {
await new Promise(r => setTimeout(r, 1000));
const { data: updated } = await getRun(run.runId);
status = updated.status;
if (status === "success") {
console.log(updated.data);
}
}
```
**List recent runs:**
```typescript theme={null}
const response = await listRuns({
toolId: "sync-customers",
limit: 10
});
response.data.data.forEach(run => {
console.log(`${run.runId}: ${run.status}`);
});
```
**Pass credentials at runtime:**
```typescript theme={null}
const { data: run } = await runTool("sync-customers", {
inputs: { userId: "user_123" },
credentials: {
stripe_api_key: "sk_live_xxx",
hubspot_access_token: "pat-xxx"
}
});
```
## Enterprise deployment options
superglue Enterprise offers additional deployment capabilities for automated and event-driven execution:
Automate tool runs with cron-based scheduling. Run tools at specific times or intervals.
Trigger tools from external services like Stripe, GitHub, or Shopify via HTTP webhooks.
# Using Template Expressions
Source: https://docs.superglue.cloud/guides/using-template-expressions
Understand how template expressions work across systems, tools, and steps.
Most of the time you don't have to write template expressions yourself—the agent generates them for you. Still, understanding how they work helps when you're debugging or tweaking a tool.
At their core, template expressions use the `<>` pattern, where `expression` is evaluated at runtime.
## Where template expressions are used
The same template engine is used across superglue:
* **Systems** – connection strings and URL templates
* **Step configuration** – `urlHost`, `urlPath`, `headers`, `queryParams`, `body`
* **Transforms** – final transforms and data selectors
## Template expression modes
There are two kinds of template expressions: **simple expressions** and **arrow function expressions**.
### Simple expressions (legacy)
Simple expressions resolve values directly from the context (payload, credentials, previous step results) without any JavaScript.
Syntax:
* `<>`
**Examples:**
In the context of a tool step:
```typescript theme={null}
headers: {
"Authorization": "Bearer <>"
},
queryParams: {
user_id: "<>"
}
```
or in a system:
```text theme={null}
postgres://<>:<>@<>:<>/<>
```
### Arrow function expressions (recommended)
Arrow function expressions use JavaScript arrow functions that receive the context as a single parameter (typically named `sourceData`) and return the value to insert. superglue runs these functions in a sandboxed JavaScript VM.
```js theme={null}
<<(sourceData) => {
// read from sourceData and return the value to insert
}>>
```
Arrow function expressions are also used in places that are pure code (for example, the
`finalTransform` field), where you don’t wrap them in `<< >>`. They still receive the same
`sourceData` context object and behave the same way.
**Examples:**
```typescript theme={null}
headers: {
"Authorization": "<<(sourceData) => `Bearer ${sourceData.credentials.apiKey}`>>"
}
```
```typescript theme={null}
body: {
posts: "<<(sourceData) => {
const fromJsonPlaceholder =
(sourceData.fetchJsonPlaceholderPosts ?? []).map(p => ({
id: p.id,
title: p.title,
source: 'jsonplaceholder'
}));
const fromDummyJson =
(sourceData.fetchDummyJsonPosts?.posts ?? []).map(p => ({
id: p.id,
title: p.title,
source: 'dummyjson'
}));
return [...fromJsonPlaceholder, ...fromDummyJson];
}>>"
}
```
## Template context
Template expressions evaluate against a **context object** that depends on where they're used (step config, system, or transform).
* **Arrow function expressions** – context is passed as the function parameter (typically `sourceData`)
* **Simple expressions** – the string inside `<< >>` is resolved against the same context object
The context looks different depending on where the expression is used:
### System context
The context is built from the system credentials (for example, `username`, `password`, `access_token`).
The `sourceData` might look like this:
```json theme={null}
{
"username": "db_user",
"password": "secret123",
"host": "db.example.com",
"port": "5432",
"database": "production"
}
```
System templates are only resolved at tool execution time and get merged
with tool-specific credentials.
### Tool step context
The context is the **aggregated step input**, which includes:
* `payload` – workflow input payload
* `credentials` – resolved credentials for the system
* Previous step results keyed by step ID (for example, `getCustomers`)
* `currentItem` – current iteration data when the step runs in a loop
The `sourceData` object might look like this:
```json theme={null}
{
"payload": { "userId": "12345", "startDate": "2024-01-01" },
"credentials": { "apiKey": "sk_test_..." },
"getCustomers": {
"data": [{ "id": "cus_123", "email": "user@example.com" }]
}
}
```
### Pagination variables
When pagination is configured on a step, the following variables are available in the request configuration (`urlPath`, `queryParams`, `headers`, `body`):
| Variable | Description |
| ---------- | ---------------------------------------------------- |
| `page` | Current page number (starts at 1) |
| `offset` | Current offset (starts at 0, increments by pageSize) |
| `cursor` | Cursor value extracted from the previous response |
| `limit` | Same as pageSize |
| `pageSize` | The configured page size |
**Examples:**
Page-based pagination:
```typescript theme={null}
queryParams: {
"page": "<>",
"per_page": "<>"
}
```
Offset-based pagination:
```typescript theme={null}
queryParams: {
"offset": "<>",
"limit": "<>"
}
```
Cursor-based pagination:
```typescript theme={null}
queryParams: {
"cursor": "<>",
"limit": "<>"
}
```
### Stop condition
The stop condition is a JavaScript function that determines when to stop fetching pages. It receives two arguments:
1. **`response`** – object containing:
* `data` – the parsed response body
* `headers` – response headers
2. **`pageInfo`** – object containing:
* `page` – current page number
* `offset` – current offset
* `cursor` – current cursor value
* `totalFetched` – total number of items fetched so far
The function should return `true` to **stop** pagination, or `false` to continue.
**Examples:**
Stop when no more pages (using response metadata):
```javascript theme={null}
(response, pageInfo) => !response.data.has_more;
```
Stop when data array is empty:
```javascript theme={null}
(response, pageInfo) => response.data.items.length === 0;
```
Stop when cursor is null or missing:
```javascript theme={null}
(response, pageInfo) => !response.data.next_cursor;
```
Stop after fetching a specific number of items:
```javascript theme={null}
(response, pageInfo) => pageInfo.totalFetched >= 1000;
```
Stop when on last page (from total pages header):
```javascript theme={null}
(response, pageInfo) =>
pageInfo.page >= parseInt(response.headers["x-total-pages"] || "1");
```
Combine multiple conditions:
```javascript theme={null}
(response, pageInfo) => {
const items = response.data.results || [];
return (
items.length === 0 || !response.data.next || pageInfo.totalFetched >= 5000
);
};
```
### Final transform context
The context is a combined view of the entire workflow execution:
* All step results keyed by step ID
* The original `payload`
The `sourceData` object might look like this:
```json theme={null}
{
"payload": { "userId": "12345" },
"getCustomers": {
"data": [{ "id": "cus_123", "email": "user@example.com" }]
},
"createPaymentIntent": {
"data": { "id": "pi_456", "status": "succeeded" }
}
}
```
# Using the Agent
Source: https://docs.superglue.cloud/guides/using-the-agent
How to interact with the superglue agent
The superglue agent handles system setup, API discovery, and tool building through a chat interface. Talk to it in natural language — it handles the technical details.
***
## Available superglue agent tools
The agent uses a broad range of tools to help you manage your systems and tools:
**`create_system`** - Create new systems with authentication and documentation
**`modify_system`** - Update existing systems (credentials, docs, configuration)
**`call_endpoint`** - Test API endpoints directly with credential injection
**`authenticate_oauth`** - Complete OAuth authorization flows for systems
**`build_tool`** - Build a new tool from natural language instructions
**`edit_tool`** - Modify an existing tool's configuration or steps
**`run_tool`** - Execute a saved tool with optional input payload
***
## Setting up a system via OAuth
Configure OAuth flows without touching code. The agent walks you through system setup, handles the authorization code flow and stores your credentials securely.
**What this shows:**
* You can set up and run the OAuth 2.0 authorization code flow in the chat with one click
* The agent checks your existing systems to prevent duplicate setup
* The agent automatically stores your credentials and automatically verifies your setup
Start creating systems with the agent
***
## Talk to your APIs
Point the agent at your custom APIs. It can test endpoints, authentication, and build working tools based on exploration.
**What this shows:**
* You can upload documentation as files directly in the chat
* The agent can extract endpoint information from uploaded docs
* The agent automates endpoint discovery and parameter inference and enables API interaction through conversation
Start talking to your APIs
***
## Next steps
Connect your first API, database, or file system
Build executable tools that work across your systems
# Using the MCP
Source: https://docs.superglue.cloud/mcp/using-the-mcp
Use superglue tools in Cursor, Claude, and other MCP-compatible clients
superglue exposes your tools through [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), giving AI agents direct access to execute pre-built superglue tools.
The MCP interface provides **discovery and execution** of pre-built superglue
tools. It does **not** support ad-hoc system creation or tool building.
Use MCP in production for agentic use cases and internal GPTs.
## When to use MCP
Execute only pre-approved, tested tools. No ad-hoc code generation or system
modification.
Execute saved tools from your custom GPTs with full observability and error
handling.
Give AI agents the ability to discover and execute complex multi-system
workflows without manual API wiring.
Expose business logic as AI-accessible tools for customer support, ops
teams, or automated workflows.
***
## Installation
### Cursor
Add to your Cursor MCP settings (`.cursor/config.json` or via Settings → MCP):
```json theme={null}
{
"mcpServers": {
"superglue": {
"command": "npx",
"args": [
"mcp-remote",
"https://app.superglue.cloud/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
```
### Claude Desktop
Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json theme={null}
{
"mcpServers": {
"superglue": {
"command": "npx",
"args": [
"mcp-remote",
"https://app.superglue.cloud/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
```
### Self-Hosted
Point to your self-hosted instance:
```json theme={null}
{
"mcpServers": {
"superglue": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:3000/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
```
Get your API key from the superglue web application sidebar under **API
Keys**.
***
## Available Tools
The MCP server exposes two core tools for discovery and execution:
### `find_relevant_tools`
Search for pre-built tools using natural language queries.
**Input Schema:**
```typescript theme={null}
{
searchTerms: string; // Space separated search terms
}
```
**Returns:**
```typescript theme={null}
{
success: boolean;
tools: Array<{
id: string;
instruction: string;
inputSchema?: Record;
responseSchema?: Record;
steps: Array<{
systemId?: string;
stepId: string;
}>;
}>;
}
```
**Use Cases:**
* Discover available tools for a specific task
* Browse all tools (use `*` as wildcard)
* Find tools by system type or capability
**Example:**
```json theme={null}
{
"searchTerms": "sync shopify orders to postgres"
}
```
***
### `execute_tool`
Execute a saved tool by its ID.
**Input Schema:**
```typescript theme={null}
{
id: string // Tool ID to execute
payload?: Record // Optional JSON payload
}
```
**Returns:**
```typescript theme={null}
{
success: boolean
data?: any // Execution result (truncated if > 20KB)
error?: string // Error message if failed
suggestion?: string
}
```
**Behavior:**
* Executes with saved credentials from systems used during build
* Full execution logs available in superglue dashboard
**Example:**
```json theme={null}
{
"id": "tool_abc123",
"payload": {
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}
}
```
***
## Usage Patterns
### Discovery → Execution Flow
```typescript theme={null}
// 1. Find relevant tools
find_relevant_tools({
searchTerms: "customer data from salesforce",
});
// 2. Execute the tool
execute_tool({
id: "tool_xyz789",
payload: { accountId: "001..." },
});
```
## Troubleshooting
### Connection Issues
```bash theme={null}
# Test MCP endpoint
curl https://app.superglue.cloud/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```
### Tool Not Found
```
Error: "Tool ID does not exist"
```
**Solution:** Use `find_relevant_tools` to get valid tool IDs or check the dashboard.
***
## Next Steps
Build tools to expose via MCP
Build systems and tools with the agent
Direct REST API access
Deploy self-hosted MCP server
# Methods
Source: https://docs.superglue.cloud/sdk/methods
Complete reference for all SDK methods
## Installation
```bash npm theme={null}
npm install @superglue/client
```
```bash pip theme={null}
pip install superglue-client
```
## Initialization
```typescript TypeScript theme={null}
import {
configure,
listTools,
getTool,
runTool,
getRun,
cancelRun,
listRuns,
} from "@superglue/client";
// Configure before making any API calls
configure({
baseUrl: "http://localhost:4000/api/v1",
apiKey: "your-api-key",
});
```
```python Python theme={null}
from superglue_client import SuperglueClient
client = SuperglueClient(
base_url="http://localhost:4000/api/v1",
token="your-api-key"
)
```
## Tools
### listTools
List all available tools with pagination.
```typescript TypeScript theme={null}
import { listTools } from "@superglue/client";
const response = await listTools({
page: 1,
limit: 50,
});
if (response.status === 200) {
const { data, page, total, hasMore } = response.data;
for (const tool of data) {
console.log(`${tool.id}: ${tool.name || tool.instruction}`);
}
console.log(`Page ${page}, Total: ${total}, Has more: ${hasMore}`);
}
```
```python Python theme={null}
from superglue_client.api.tools import list_tools
response = list_tools.sync(
client=client,
page=1,
limit=50
)
if response:
for tool in response.data:
print(f"{tool.id}: {tool.name or tool.instruction}")
print(f"Page {response.page}, Total: {response.total}, Has more: {response.has_more}")
```
**Parameters:**
* `page` - Page number (default: `1`)
* `limit` - Items per page (default: `50`)
**Returns:** List of `Tool` objects with pagination metadata
***
### getTool
Get detailed information about a specific tool.
```typescript TypeScript theme={null}
import { getTool } from "@superglue/client";
const response = await getTool("my-tool-id");
if (response.status === 200) {
const tool = response.data;
console.log(`Tool: ${tool.name}`);
console.log(`Steps: ${tool.steps.length}`);
console.log(`Version: ${tool.version}`);
console.log(`Instruction: ${tool.instruction}`);
}
```
```python Python theme={null}
from superglue_client.api.tools import get_tool
tool = get_tool.sync(
tool_id="my-tool-id",
client=client
)
if tool:
print(f"Tool: {tool.name}")
print(f"Steps: {len(tool.steps)}")
print(f"Version: {tool.version}")
print(f"Instruction: {tool.instruction}")
```
**Parameters:**
* `toolId` - Unique tool identifier
**Returns:** `Tool` object with full configuration
***
### runTool
Execute a tool with inputs and options.
```typescript TypeScript theme={null}
import { runTool } from "@superglue/client";
const response = await runTool("my-tool-id", {
inputs: {
userId: "user_123",
startDate: "2025-01-01",
},
options: {
async: false,
timeout: 60,
webhookUrl: "https://your-app.com/webhook",
},
credentials: {
stripeApiKey: "sk_test_...",
slackToken: "xoxb-...",
},
});
if (response.status === 200 || response.status === 202) {
const run = response.data;
console.log(`Run ID: ${run.runId}`);
console.log(`Status: ${run.status}`);
if (run.status === "success" && run.data) {
console.log("Result:", run.data);
} else if (run.status === "running") {
console.log("Run in progress...");
}
}
```
```python Python theme={null}
from superglue_client.api.tools import run_tool
from superglue_client.models import (
RunRequest,
RunRequestInputs,
RunRequestCredentials,
RunRequestOptions
)
# Create typed input/credential objects
inputs = RunRequestInputs.from_dict({
"user_id": "user_123",
"start_date": "2025-01-01"
})
credentials = RunRequestCredentials.from_dict({
"stripe_api_key": "sk_test_...",
"slack_token": "xoxb-..."
})
body = RunRequest(
inputs=inputs,
options=RunRequestOptions(
async_=False,
timeout=60,
webhook_url="https://your-app.com/webhook"
),
credentials=credentials
)
run = run_tool.sync(
tool_id="my-tool-id",
client=client,
body=body
)
if run:
print(f"Run ID: {run.run_id}")
print(f"Status: {run.status.value}")
if run.status.value == "success" and run.data:
print("Result:", run.data)
elif run.status.value == "running":
print("Run in progress...")
```
**Parameters:**
* `toolId` - Tool to execute
* `runRequest` - Execution configuration:
* `inputs` - Input data accessible in tool steps
* `options` - Execution options:
* `async` - If `true`, return 202 immediately and execute asynchronously
* `timeout` - Request timeout in seconds (sync only)
* `webhookUrl` - URL to POST results when complete
* `traceId` - Custom trace ID for log tracking
* `credentials` - Runtime credentials to override defaults
**Returns:** `Run` object with execution status and results
**Status Codes:**
* `200` - Tool executed synchronously (completed)
* `202` - Tool executing asynchronously (in progress)
* `400` - Invalid request
* `409` - Concurrent execution limit reached
* `410` - Tool deleted
* `429` - Rate limit exceeded
***
## Runs
### getRun
Get the status and results of a tool execution.
```typescript TypeScript theme={null}
import { getRun } from "@superglue/client";
const response = await getRun("run_abc123");
if (response.status === 200) {
const run = response.data;
console.log(`Status: ${run.status}`);
console.log(`Tool: ${run.toolId}`);
if (run.status === "success") {
console.log("Result:", run.data);
console.log("Steps:", run.stepResults);
} else if (run.status === "failed") {
console.error("Error:", run.error);
}
console.log(`Duration: ${run.metadata.durationMs}ms`);
}
```
```python Python theme={null}
from superglue_client.api.runs import get_run
run = get_run.sync(
run_id="run_abc123",
client=client
)
if run:
print(f"Status: {run.status.value}")
print(f"Tool: {run.tool_id}")
if run.status.value == "success":
print("Result:", run.data)
print("Steps:", run.step_results)
elif run.status.value == "failed":
print("Error:", run.error)
print(f"Duration: {run.metadata.duration_ms}ms")
```
**Parameters:**
* `runId` - Unique run identifier
**Returns:** `Run` object with status, results, and metadata
**Run Statuses:**
* `running` - Execution in progress
* `success` - Completed successfully
* `failed` - Failed due to error
* `aborted` - Cancelled by user or system
***
### cancelRun
Cancel a running tool execution.
```typescript TypeScript theme={null}
import { cancelRun } from "@superglue/client";
const response = await cancelRun("run_abc123");
if (response.status === 200) {
console.log("Run cancelled successfully");
console.log("Status:", response.data.status); // "aborted"
}
```
```python Python theme={null}
from superglue_client.api.runs import cancel_run
run = cancel_run.sync(
run_id="run_abc123",
client=client
)
if run:
print("Run cancelled successfully")
print(f"Status: {run.status.value}") # "aborted"
```
**Parameters:**
* `runId` - Run to cancel
**Returns:** Updated `Run` object with `aborted` status
***
### listRuns
List tool execution runs with filtering and pagination.
```typescript TypeScript theme={null}
import { listRuns } from "@superglue/client";
// List all runs
const response = await listRuns({
page: 1,
limit: 50,
});
// Filter by tool
const toolRuns = await listRuns({
toolId: "my-tool-id",
page: 1,
limit: 50,
});
// Filter by status
const failedRuns = await listRuns({
status: "failed",
page: 1,
limit: 50,
});
if (response.status === 200) {
const { data, page, total, hasMore } = response.data;
for (const run of data) {
const status = run.status === "success" ? "✓" : "✗";
console.log(`${run.runId}: ${status} - ${run.metadata.startedAt}`);
}
}
```
```python Python theme={null}
from superglue_client.api.runs import list_runs
from superglue_client.models.list_runs_status import ListRunsStatus
# List all runs
response = list_runs.sync(
client=client,
page=1,
limit=50
)
# Filter by tool
tool_runs = list_runs.sync(
client=client,
tool_id="my-tool-id",
page=1,
limit=50
)
# Filter by status
failed_runs = list_runs.sync(
client=client,
status=ListRunsStatus.FAILED,
page=1,
limit=50
)
if response:
for run in response.data:
status = "✓" if run.status.value == "success" else "✗"
print(f"{run.run_id}: {status} - {run.metadata.started_at}")
```
**Parameters:**
* `page` - Page number (default: `1`)
* `limit` - Items per page (default: `50`)
* `toolId` - Filter by tool ID (optional)
* `status` - Filter by status: `running`, `success`, `failed`, `aborted` (optional)
**Returns:** List of `Run` objects with pagination metadata
# Overview
Source: https://docs.superglue.cloud/sdk/overview
Quick start with the superglue SDK
The superglue SDK provides programmatic access to the superglue API for executing and managing tools. Available in TypeScript/JavaScript and Python.
## Installation
```bash npm theme={null}
npm install @superglue/client
```
```bash pip theme={null}
pip install superglue-client
```
## Quick start
```typescript TypeScript theme={null}
import { configure, listTools, runTool, getRun } from "@superglue/client";
// Configure before making any API calls
configure({
baseUrl: "http://localhost:4000/api/v1",
apiKey: "your-api-key",
});
// List available tools
const response = await listTools({ limit: 10 });
console.log(response.data.data);
// Run a tool
const runResponse = await runTool("my-tool-id", {
inputs: {
userId: "user_123",
},
});
console.log(`Run ID: ${runResponse.data.runId}`);
console.log(`Status: ${runResponse.data.status}`);
// Get run results
const resultResponse = await getRun(runResponse.data.runId);
if (resultResponse.data.status === "success") {
console.log("Result:", resultResponse.data.data);
}
```
```python Python theme={null}
from superglue_client import SuperglueClient
from superglue_client.api.tools import list_tools, run_tool
from superglue_client.api.runs import get_run
from superglue_client.models import RunRequest, RunRequestInputs
# Initialize client
client = SuperglueClient(
base_url="http://localhost:4000/api/v1",
token="your-api-key"
)
# List available tools
tools = list_tools.sync(client=client, limit=10)
print(tools.data)
# Run a tool
inputs = RunRequestInputs.from_dict({"user_id": "user_123"})
body = RunRequest(inputs=inputs)
run = run_tool.sync(
tool_id="my-tool-id",
client=client,
body=body
)
print(f"Run ID: {run.run_id}")
print(f"Status: {run.status.value}")
# Get run results
result = get_run.sync(run_id=run.run_id, client=client)
if result.status.value == "success":
print("Result:", result.data)
```
## Authentication
Get your API key from the superglue dashboard under Settings → API Keys.
```typescript TypeScript theme={null}
import { configure } from '@superglue/client';
configure({
baseUrl: 'https://api.superglue.com/v1',
apiKey: 'your-api-key'
});
```
```python Python theme={null}
client = SuperglueClient(
base_url="https://api.superglue.com/v1",
token="your-api-key"
)
```
Use the `AUTH_TOKEN` environment variable from your `.env` file.
```typescript TypeScript theme={null}
import { configure } from '@superglue/client';
configure({
baseUrl: 'https://your-instance.com/api/v1',
apiKey: process.env.AUTH_TOKEN
});
```
```python Python theme={null}
import os
client = SuperglueClient(
base_url="https://your-instance.com/api/v1",
token=os.getenv("AUTH_TOKEN")
)
```
## TypeScript support
The SDK is fully typed with TypeScript. All types are auto-generated from the OpenAPI specification.
```typescript TypeScript theme={null}
import { getTool } from "@superglue/client";
import type { Tool, Run, RunRequest } from "@superglue/client";
// Assumes configure() has been called (see Quick start above)
const response = await getTool("my-tool-id");
const tool: Tool = response.data;
```
```python Python theme={null}
from superglue_client.api.tools import get_tool
from superglue_client.models import Tool, Run, RunRequest
tool: Tool = get_tool.sync(tool_id="my-tool-id", client=client)
```
## Next steps
Complete API reference for all SDK methods
TypeScript and Python type definitions
# Types
Source: https://docs.superglue.cloud/sdk/types
TypeScript and Python type definitions for the superglue SDK
All types are auto-generated from the OpenAPI specification. This reference covers the most commonly used types.
## Tool types
### Tool
A multi-step workflow tool that executes protocol-specific operations.
```typescript TypeScript theme={null}
interface Tool {
id: string;
name?: string;
version?: string;
instruction?: string;
inputSchema?: Record;
outputSchema?: Record;
steps: ToolStep[];
outputTransform?: string;
createdAt?: string;
updatedAt?: string;
}
```
```python Python theme={null}
from superglue_client.models import Tool
class Tool:
id: str
steps: list[ToolStep]
name: str | None
version: str | None
instruction: str | None
input_schema: dict[str, Any] | None
output_schema: dict[str, Any] | None
output_transform: str | None
created_at: str | None
updated_at: str | None
```
**Fields:**
* `id` - Unique identifier
* `steps` - Ordered execution steps (min: 1)
* `name` - Display name
* `version` - Semantic version (major.minor.patch)
* `instruction` - Human-readable description
* `inputSchema` - JSON Schema for tool inputs
* `outputSchema` - JSON Schema for tool outputs
* `outputTransform` - JavaScript function for final transformation: `(sourceData) => expression`
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
***
### ToolStep
A single execution step supporting multiple protocols (HTTP/HTTPS, Postgres, FTP/SFTP).
```typescript TypeScript theme={null}
interface ToolStep {
id: string;
url: string;
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
systemId: string;
instruction?: string;
queryParams?: Record;
headers?: Record;
body?: string;
dataSelector?: string;
modify?: boolean;
failureBehavior?: "fail" | "continue";
pagination?: Pagination;
}
```
```python Python theme={null}
from superglue_client.models import ToolStep, ToolStepMethod
class ToolStep:
id: str
url: str
method: ToolStepMethod
system_id: str
instruction: str | None
query_params: dict[str, str] | None
headers: dict[str, str] | None
body: str | None
data_selector: str | None
modify: bool | None
failure_behavior: ToolStepFailureBehavior | None
pagination: Pagination | None
```
**Fields:**
* `id` - Unique identifier
* `url` - Full URL with protocol (e.g., `https://api.example.com`, `postgres://host:5432/db`, `ftp://host/path`)
* `method` - HTTP method (use `POST` for non-HTTP protocols)
* `systemId` - System to use for credentials and documentation
* `instruction` - What this step does
* `queryParams` - URL query params (HTTP only), supports template expressions
* `headers` - HTTP headers (HTTP only), supports template expressions
* `body` - Request body (protocol-specific), supports template expressions
* `dataSelector` - JavaScript function to select data: `(sourceData) => expression`
* `modify` - Whether this step modifies data on the system it operates on
* `failureBehavior` - `"fail"` stops execution, `"continue"` proceeds to next step
* `pagination` - Pagination configuration (HTTP only)
**Template Expressions:**
Use `<<(sourceData) => ...>>` syntax to reference previous step outputs:
```json theme={null}
{
"query": "<<(sourceData) => sourceData.step1.userId>>",
"limit": "<<(sourceData) => sourceData.inputs.limit>>"
}
```
***
## Run types
### Run
Represents a tool execution with status, results, and metadata.
```typescript TypeScript theme={null}
interface Run {
runId: string;
toolId: string;
status: "running" | "success" | "failed" | "aborted";
tool?: {
id: string;
name?: string;
version?: string;
};
toolPayload?: {
inputs?: Record;
credentials?: Record;
options?: Record;
};
data?: any;
error?: string;
stepResults?: RunStepResultsItem[];
options?: Record;
requestSource?: string;
traceId?: string;
metadata: RunMetadata;
}
```
```python Python theme={null}
from superglue_client.models import Run, RunStatus
class Run:
run_id: str
tool_id: str
status: RunStatus
metadata: RunMetadata
tool: RunTool | None
tool_payload: RunToolPayload | None
data: Any | None
error: str | None
step_results: list[RunStepResultsItem] | None
options: RunOptions | None
request_source: str | None
trace_id: str | None
```
**Fields:**
* `runId` - Unique run identifier
* `toolId` - ID of executed tool
* `status` - Execution status: `running`, `success`, `failed`, `aborted`
* `tool` - Tool metadata (not full config)
* `toolPayload` - Inputs/credentials/options provided at runtime
* `data` - Tool execution results (only when `status` is `success`)
* `error` - Error message (only when `status` is `failed` or `aborted`)
* `stepResults` - Results from each execution step
* `options` - Execution options used
* `requestSource` - Where run was initiated
* `traceId` - Trace ID for debugging
* `metadata` - Timing and duration info (see `RunMetadata`)
***
### RunMetadata
Timing information for a run.
```typescript TypeScript theme={null}
interface RunMetadata {
startedAt?: string;
completedAt?: string;
durationMs?: number;
}
```
```python Python theme={null}
from superglue_client.models import RunMetadata
class RunMetadata:
started_at: str | Unset
completed_at: str | Unset
duration_ms: int | Unset
```
**Fields:**
* `startedAt` - ISO timestamp when run started
* `completedAt` - ISO timestamp when run finished (only present when status is `success`, `failed`, or `aborted`)
* `durationMs` - Execution duration in milliseconds
***
### RunRequest
Configuration for executing a tool.
```typescript TypeScript theme={null}
interface RunRequest {
runId?: string;
inputs?: Record;
credentials?: Record;
options?: {
async?: boolean;
timeout?: number;
webhookUrl?: string;
traceId?: string;
};
}
```
```python Python theme={null}
from superglue_client.models import (
RunRequest,
RunRequestInputs,
RunRequestCredentials,
RunRequestOptions
)
from superglue_client.types import Unset
class RunRequest:
run_id: str | Unset
inputs: RunRequestInputs | Unset
credentials: RunRequestCredentials | Unset
options: RunRequestOptions | Unset
```
**Fields:**
* `runId` - Pre-generated run ID (optional, for idempotency)
* `inputs` - Tool-specific input parameters
* `credentials` - Runtime credentials (not persisted, overrides stored credentials)
* `options` - Execution options:
* `async` - If `true`, return immediately (202) and execute async. If `false`, wait for completion (200)
* `timeout` - Request timeout in seconds (sync only)
* `webhookUrl` - URL to POST completion notification, or `tool:toolId` to chain tools
* `traceId` - Custom trace ID for log tracking
***
### RunStepResultsItem
Result from a single step execution.
```typescript TypeScript theme={null}
interface RunStepResultsItem {
stepId: string;
success: boolean;
data?: any;
error?: string;
}
```
```python Python theme={null}
from superglue_client.models import RunStepResultsItem
class RunStepResultsItem:
step_id: str
success: bool
data: RunStepResultsItemData | None
error: str | None
```
**Fields:**
* `stepId` - Which step this result is for
* `success` - Whether the step completed successfully
* `data` - API response data (if successful)
* `error` - Error message (if failed)
***
## Pagination
### Pagination
Pagination configuration for HTTP/HTTPS requests.
```typescript TypeScript theme={null}
interface Pagination {
type: "offset" | "cursor";
pageSize?: string;
cursorPath?: string;
stopCondition?: string;
}
```
```python Python theme={null}
from superglue_client.models import Pagination, PaginationType
class Pagination:
type: PaginationType
page_size: str | None
cursor_path: str | None
stop_condition: str | None
```
**Fields:**
* `type` - Pagination type: `"offset"` or `"cursor"`
* `pageSize` - Items per page (available as `<<(sourceData) => sourceData.limit>>`)
* `cursorPath` - JSONPath to extract next page cursor (e.g., `"meta.next_cursor"`)
* `stopCondition` - JavaScript function to determine when to stop: `(response, pageInfo) => boolean`
* `response` - Object with `{data: ..., headers: ...}`
* `pageInfo` - Object with `{page, offset, cursor, totalFetched}`
* Return `true` to STOP, `false` to continue
***
## Response types
### ListTools200
Response from `listTools()`.
```typescript TypeScript theme={null}
interface ListTools200 {
data?: Tool[];
page?: number;
limit?: number;
total?: number;
hasMore?: boolean;
}
```
```python Python theme={null}
from superglue_client.models import ListToolsResponse200
class ListToolsResponse200:
data: list[Tool] | Unset
page: int | Unset
limit: int | Unset
total: int | Unset
has_more: bool | Unset
```
**Fields:**
* `data` - Array of Tool objects
* `page` - Current page number
* `limit` - Items per page
* `total` - Total number of items
* `hasMore` - Whether more pages exist
***
### ListRuns200
Response from `listRuns()`.
```typescript TypeScript theme={null}
interface ListRuns200 {
data?: Run[];
page?: number;
limit?: number;
total?: number;
hasMore?: boolean;
}
```
```python Python theme={null}
from superglue_client.models import ListRunsResponse200
class ListRunsResponse200:
data: list[Run] | Unset
page: int | Unset
limit: int | Unset
total: int | Unset
has_more: bool | Unset
```
**Fields:**
* `data` - Array of Run objects
* `page` - Current page number
* `limit` - Items per page
* `total` - Total number of items
* `hasMore` - Whether more pages exist
***
## Enums
### RunStatus
```typescript TypeScript theme={null}
type RunStatus = "running" | "success" | "failed" | "aborted";
```
```python Python theme={null}
from enum import Enum
class RunStatus(str, Enum):
RUNNING = "running"
SUCCESS = "success"
FAILED = "failed"
ABORTED = "aborted"
```
***
### ToolStepMethod
```typescript TypeScript theme={null}
type ToolStepMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
```
```python Python theme={null}
from enum import Enum
class ToolStepMethod(str, Enum):
GET = "GET"
POST = "POST"
PUT = "PUT"
PATCH = "PATCH"
DELETE = "DELETE"
```
***
### ToolStepFailureBehavior
```typescript TypeScript theme={null}
type ToolStepFailureBehavior = "fail" | "continue";
```
```python Python theme={null}
from enum import Enum
class ToolStepFailureBehavior(str, Enum):
FAIL = "fail"
CONTINUE = "continue"
```